Context-Driven Documentation (CDD)
🌐 Português: Leia em Português (PT-BR)
Transform how you build software with AI pair programming
CDD is an AI-first development framework that makes human-AI collaboration feel natural, powerful, and productive. Create meaningful specifications through conversation, generate detailed implementation plans autonomously, and let AI write high-quality code - all while maintaining perfect context across your entire project.
🎯 What Makes CDD Different
Traditional development with AI requires constantly re-explaining your project. CDD eliminates this friction:
- Create meaningful specs in a conversational way - Socrates, your intelligent documentation assistant, asks the right questions and structures your engineering thought process
- Break down specs into actionable plans - AI generates detailed, step-by-step implementation plans autonomously
- Automatically generate high-quality code from plans - Execute implementations with full project context
- Eliminate repeated context-sharing with AI - Capture your project's context once, AI understands it forever
- Documentation never goes out of date - Living documentation that evolves with your codebase
💡 The Core Principle
Context captured once. AI understands forever.
Instead of manually managing context or repeatedly explaining your project, CDD maintains a living knowledge base that provides perfect context automatically. Your AI partner knows your architecture, patterns, and conventions - making every conversation start from shared understanding instead of zero.
🧠 The Mental Model
CLAUDE.md = "My project's constitution - always loaded"
specs/ = "Current sprint work - tickets with plans"
docs/ = "Living feature documentation - stays synchronized"
AI Agents = "Intelligent assistants that know my project"
The workflow: Conversational requirements → Autonomous planning → AI implementation → Self-maintaining docs
⚡ Quick Start
Installation
pip install cdd-claude
Initialize Your Project
cd my-project
cdd init
This creates:
CLAUDE.md- Your project's constitutionspecs/tickets/- Where your sprint work livesdocs/features/anddocs/guides/- Living documentation that stays synchronized- Framework AI agents for intelligent collaboration
Your First Feature (5-Step Workflow)
# 1. Create a ticket
cdd new feature user-authentication
# 2. Open in Claude Code and have a conversation with Socrates
/socrates feature-user-authentication
# Socrates asks intelligent questions:
# - "What problem are you solving?"
# - "Who are your users?"
# - "What are the acceptance criteria?"
# Your spec.yaml gets built through natural conversation
# 3. Generate an implementation plan
/plan feature-user-authentication
# AI reads your spec, understands your project (CLAUDE.md),
# and creates a detailed step-by-step plan
# 4. Implement with full context
/exec feature-user-authentication
# (Or use /exec-auto for fully automatic, hands-free implementation)
# AI writes code following your plan, architecture, and conventions
# 5. Your living docs update automatically
# docs/features/authentication.md reflects what was built
That's it. Conversational requirements → Autonomous planning → AI implementation.
Create Documentation (Simpler Workflow)
Documentation has a simpler workflow - no spec/plan/exec phases:
# Create a guide or feature doc
cdd new documentation guide getting-started
cdd new documentation feature authentication
# Fill it with Socrates
/socrates docs/guides/getting-started.md
# Socrates helps you build comprehensive docs through conversation
# - What is this guide about?
# - Who is the audience?
# - What examples would help?
# Your documentation gets built naturally
# Keep it updated as your code evolves - it's living documentation!
Key difference: Documentation is meant to evolve continuously with your codebase. Create it once, refine it often with Socrates.
🏗️ How It Works
Directory Structure
When you run cdd init, you get a simple, git-friendly structure:
my-project/
├── CLAUDE.md # Project constitution (always loaded by AI)
├── specs/
│ ├── tickets/ # Active sprint work
│ │ └── feature-auth/
│ │ ├── spec.yaml # Requirements from conversation
│ │ ├── plan.md # AI-generated implementation plan
│ │ └── progress.yaml # Implementation progress (created by /exec)
│ └── archive/ # Completed tickets (auto-archived by /exec)
└── docs/
├── features/ # Living feature documentation
│ └── authentication.md
└── guides/ # User guides and how-tos
└── getting-started.md
CLAUDE.md - Your Project's Constitution
This file is automatically loaded in every Claude Code session, providing foundational context:
# Project Constitution
## Architecture & Patterns
- System design and core patterns
- Data flow and component relationships
## Tech Stack & Constraints
- Languages, frameworks, and versions
- Infrastructure and deployment requirements
## Development Standards
- Code style and formatting rules
- Testing requirements and conventions
Once you fill this out, AI knows your project fundamentals forever.
Specs - Structured Tickets with Plans
Each ticket is a folder containing:
- spec.yaml - Requirements gathered through conversation with Socrates
- plan.md - Detailed implementation plan generated by AI
Ticket types:
cdd new feature- New functionality with user stories and acceptance criteriacdd new bug- Bug reports with reproduction steps and impact assessmentcdd new spike- Research tasks with questions and success criteriacdd new enhancement- Improvements to existing features
Docs - Living Documentation
Feature documentation that stays synchronized with your code:
# Feature: User Authentication
## Current Implementation
- OAuth 2.0 with Google
- Session-based auth
- JWT tokens for API access
## Technical Details
- Endpoints: /auth/google, /auth/logout
- Database: users, sessions tables
- Security: bcrypt hashing, secure cookies
🤖 Meet Socrates - Your Intelligent Documentation Assistant
Socrates transforms scattered thoughts into comprehensive specifications through guided conversation.
Traditional approach:
What's the feature name? ___
What does it do? ___
Who are the users? ___
Feels like filling out a form. No intelligence.
Socrates approach:
You: /socrates
Socrates: I'll help you create a comprehensive spec.
What problem are you trying to solve?
You: Users can't access their personal data
Socrates: What kind of personal data? Why can't it be public?
Who are these users exactly?
You: It's a SaaS project management tool. Users create private
projects and tasks.
Socrates: Perfect! So you need authentication to separate user data.
Let's think about the authentication method - what feels right
for your users?
Socrates:
- Asks the right questions based on context
- Probes deeper when answers are vague
- Suggests edge cases you might miss
- Structures your thoughts into proper spec format
- Saves progress as you go
✨ Current Features
✅ Conversational Specification Creation
Create comprehensive specs through natural dialogue with Socrates. No forms, no templates - just conversation that builds understanding.
✅ Autonomous Implementation Planning
AI reads your spec, understands your project architecture, and generates detailed step-by-step implementation plans with time estimates and risk assessment.
✅ Context-Aware Code Generation
Execute implementations with full project context - architecture, patterns, conventions, and business rules all automatically available.
✅ Living Documentation
Documentation that evolves with your codebase, capturing what actually exists rather than what was planned.
✅ File-Based & Git-Friendly
Everything lives in files you can version control, review, and share. No databases, no lock-in.
📍 Current Workflow
1. cdd new feature-name → Creates ticket structure
2. /socrates feature-name → Conversational spec creation
3. /plan feature-name → AI generates implementation plan
4. /exec feature-name → AI implements with full context
(or /exec-auto for hands-free automatic implementation)
5. /sync-docs feature-name → Sync living documentation with implementation
🗺️ Roadmap
Coming Soon
Skills - Auto-Activation 📅
- Technical knowledge that activates automatically based on conversation
- Example: Mention "OAuth" → Security patterns auto-load
- Example: Mention "slow query" → Database optimization patterns auto-load
Agents - Domain Specialists 📅
- Independent specialists with focused expertise
@business-analyst- Validate requirements and edge cases@security-auditor- Review security implications@api-architect- Design API patterns and structure
Auto-Documentation 📅
/completecommand that analyzes implementations- Automatically updates living docs based on actual code
- Captures institutional knowledge and lessons learned
Team Collaboration 📅
- Shared knowledge bases across teams
- Project templates for different domains
- Team onboarding automation
🎓 Learn More
- Getting Started Guide (Coming Soon)
- Socrates Guide - Master conversational spec creation
- Examples - See example specs and workflows
🤝 Contributing
CDD is open source and welcomes contributions! See CONTRIBUTING.md (Coming Soon) for:
- Development setup
- Architecture overview
- Contribution guidelines
- Roadmap and priorities
📄 License
MIT License - see LICENSE for details
🌟 Why CDD?
Before CDD:
Every conversation with AI starts from zero
→ Constantly re-explaining architecture
→ AI makes suggestions that don't fit your patterns
→ Documentation gets stale immediately
→ Context lives in developers' heads
With CDD:
Context captured once, understood forever
→ AI knows your project intimately
→ Suggestions align with your architecture
→ Documentation evolves automatically
→ Knowledge is shared and accessible
The result: Development teams that think faster, build better, and maintain perfect context without cognitive overhead.
Transform your development workflow. Start with pip install cdd-claude
Built for the AI-first development era. Made with ❤️ by developers who believe human-AI collaboration should feel natural.
Metadata
Release files for cdd-claude 0.1.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cdd_claude-0.1.5.tar.gz | 92.6 kB | Without provenance | Details for cdd_claude-0.1.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cdd_claude-0.1.5-py3-none-any.whl | Python 3 | none | any | Details for cdd_claude-0.1.5-py3-none-any.whl |
Total release size: 222.3 kB
Release files / cdd_claude-0.1.5.tar.gz
| Download URL | cdd_claude-0.1.5.tar.gz |
|---|---|
| Size | 92.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
08e9494d0a6c90cffeb9b10593d1e6bfbc4aa8548894f8b0005154ba7876e5a1
|
|
BLAKE2b-256 checksum How to use checksums |
3a0b970914fe84b2e4770ac04a3fdb1bd35ce39d14dd03319147b71774a257c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.11.12 Linux/5.15.167.4-microsoft-standard-WSL2
|
Release files / cdd_claude-0.1.5-py3-none-any.whl
| Download URL | cdd_claude-0.1.5-py3-none-any.whl |
|---|---|
| Size | 129.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9c7a66453df75edc22ba68398e80d1bffe91d5b4534ce30b65f16052cb6bcb90
|
|
BLAKE2b-256 checksum How to use checksums |
406dcd338b0d5d8e4329040de1e386807eb1194fbf0ccad6b10757c8b019f875
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.11.12 Linux/5.15.167.4-microsoft-standard-WSL2
|
Security for cdd-claude 0.1.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.