This repo outlines an approach to coding in the era of AI agents. It maximizes the value of strategic decisions and maintains clear documentation for optimal context efficiency when working with AI coding assistants.
This framework encourages building with a product and project focused mindset from the outset, ensuring technical decisions align with strategic goals.
The Problem: AI coding agents require context to work effectively. Traditional documentation approaches either:
- Provide too much context (overwhelming, slow to parse)
- Provide too little context (agents make wrong assumptions)
- Lack strategic clarity (agents can't align with long-term vision)
- Force agents to rebuild context from scratch on every interaction
The Solution: A hierarchical documentation system that enables rapid context rebuilding at any altitude:
-
Multi-level context access: Agents can quickly rebuild context from either:
- Higher level (strategic): "Why are we building this? What's the vision?" → ROADMAP.md
- Lower level (implementation): "How does this module work? What patterns do we use?" → CLAUDE.md
-
Right-sized context: Makes it easier and quicker for agents to find exactly what they need, at the right level of detail
-
Strategic alignment: Clear separation between vision (ROADMAP) and execution (PROJECT_PLAN) ensures agents understand both what to build and why
-
Workflow-aware design: Aims to reduce documentation friction through focused context and batch updates, minimising the cost of finding and maintaining documentation
This framework is working when:
- ✅ Developers can quickly find the correct documentation from any entry point
- ✅ AI agents receive exactly the context they need without excess
- ✅ Documentation updates have minimal workflow disruption
- ✅ Strategic decisions are preserved and discoverable months later
your-project/
├── README.md # Public-facing overview
├── CLAUDE.md # 🎯 Main entry point for AI agents
├── ROADMAP.md # Strategic vision (quarters/years)
├── PROJECT_PLAN.md # Tactical execution (weeks/months)
├── CHANGELOG.md # Feature and change history
├── CONTRIBUTING.md # Contributor guidelines
│
└── src/
└── your-module/
└── CLAUDE.md # Module-specific architecture & patterns
| Content Type | Root CLAUDE.md | Subfolder CLAUDE.md | Code Comments |
|---|---|---|---|
| Setup & installation | ✓ Primary | ||
| High-level architecture | ✓ Overview | Detailed design | |
| Design patterns | Mention | Explain + examples | Reference |
| API contracts | Link | Full specification | Implementation notes |
| Why decisions made | Strategic context | Technical rationale | Edge cases |
| How to extend | General guidance | Specific steps | Implementation details |
| Document | Timeframe | Purpose | Example Content |
|---|---|---|---|
| ROADMAP.md | Quarters/Years | Strategic vision - the "destination" | "Q2 2024: Multi-tenancy support" |
| PROJECT_PLAN.md | Weeks/Months | Tactical execution - the "route" | "Sprint 3: Implement OAuth middleware" |
| CLAUDE.md (root) | Always current | Navigation hub + setup | Task routing, env setup, common commands |
| CLAUDE.md (subfolder) | Always current | Architecture + patterns | Component design, integration guides |
| CHANGELOG.md | Historical | Feature history | "v2.1.0: Added rate limiting" |
# Clone this template
git clone https://github.com/your-username/agentic-coding-framework.git
# Copy core files to your project
cp agentic-coding-framework/CLAUDE.md your-project/
cp agentic-coding-framework/ROADMAP.md your-project/
cp agentic-coding-framework/PROJECT_PLAN.md your-project/
cp agentic-coding-framework/CHANGELOG.md your-project/
# Copy example subfolder CLAUDE.md
cp agentic-coding-framework/examples/ml-workflow/CLAUDE.md your-project/src/your-module/- Edit
CLAUDE.md: Replace placeholder content with your project structure, setup steps, and task navigation - Edit
ROADMAP.md: Add your strategic goals and milestones - Edit
PROJECT_PLAN.md: Add current sprint/iteration plans - Edit
CHANGELOG.md: Document your first version
When working with Claude Code or other AI assistants:
- Point them to
CLAUDE.mdas the main entry point - Reference specific sections for focused context
- Update docs as you make changes (see
PROJECT_PLAN.mdfor documentation debt tracking)
Once you're comfortable with the core framework, explore these optional patterns:
When to use: Projects with 10+ documented folders
- Creates an ASCII navigation tree
- Quick reference for complex codebases
- See: docs/ADVANCED_FEATURES.md#docs-index
When to use: Team collaboration starts
- Automated reminders to update docs in PRs
- Reduces documentation drift
- See: .github/PULL_REQUEST_TEMPLATE/documentation.md
When to use: Fast iteration creates doc gaps
- Track TODOs in
PROJECT_PLAN.md - Prioritize doc updates alongside features
- See: docs/ADVANCED_FEATURES.md#doc-debt-tracking
When to use: Multiple people editing docs
- Severity levels (🔴 Critical, 🟡 Moderate, 🟢 Minor)
- Manual checklist for spotting contradictions
- See: docs/ADVANCED_FEATURES.md#conflict-detection
When to use: Project structure evolves
- Heuristics for when to split CLAUDE.md into subfolders
- Examples of folder size thresholds
- See: docs/ADVANCED_FEATURES.md#multi-folder-strategy
When to use: Continuous improvement culture
- Every 2-3 months review template
- Questions about doc effectiveness
- See: docs/ADVANCED_FEATURES.md#retrospectives
See the examples/ml-workflow/ folder for a minimal working example showing:
- Task-based navigation in root
CLAUDE.md - Subfolder
CLAUDE.mdfor a data science/ML module - Breadcrumb navigation between docs
- Strategic vs tactical separation (ROADMAP vs PROJECT_PLAN)
Documentation exists at different altitudes:
- Strategic (ROADMAP): Where are we going and why?
- Tactical (PROJECT_PLAN): What are we doing right now?
- Architectural (CLAUDE.md): How does the system work?
- Implementation (Code): What does this specific function do?
The "What Goes Where" table is a guide, not a law. Use your judgment:
- If repetition aids clarity, repeat
- If a detail feels important at multiple levels, include it at both
- Optimize for findability, not purity
AI agents work best with:
- Focused context: 2-5KB of targeted docs beats 50KB of comprehensive docs
- Task-oriented navigation: "What are you trying to do?" not "Here's everything"
- Breadcrumbs: Clear paths between related documents
Documentation should:
- ✅ Be updated after completing a task (batch at task end)
- ✅ Use severity levels for conflicts (only critical ones interrupt)
- ❌ Never pause development mid-task for doc updates
- ❌ Never enforce strict rules that slow down iteration
This framework is designed to evolve based on real-world usage. Contributions welcome:
- Share your adaptations and improvements
- Report what works (and what doesn't) in your projects
- Suggest new advanced patterns based on your experience
See CONTRIBUTING.md for guidelines.
MIT License - see LICENSE file for details.
Use this framework freely in your projects, commercial or personal.
This framework is designed to evolve. Potential enhancements being considered:
Concept: Documentation patterns for teams using different LLMs for different purposes
Examples:
- Gemini for code reviews
- Claude Code for coding and implementation
- OpenAI for brainstorming and ideation
- Specialized models for data science workflows
Value: Guide teams on how to document when different AI agents handle different aspects of development
Resource: Compound Engineering Plugin
Concept: Integrate compound engineering principles into the documentation framework
Value: Enhanced patterns for building complex systems with clear documentation boundaries
Validation Script (scripts/check_docs.sh):
- Detect broken internal links
- Find inconsistent terminology
- Verify hierarchical structure
- Check documentation debt items
GitHub Actions Workflow:
- Automated doc checks on pull requests
- Link validation in CI/CD
- Documentation coverage reporting
Pre-commit Hooks:
- Remind developers to update relevant docs
- Validate markdown formatting
- Check for placeholder text
Status: Focus is on establishing manual patterns first, then automate when pain points are clear.
Concept: Integrate Model Context Protocol to enable AI agents to access contextual information more efficiently
Potential Features:
- MCP servers for documentation navigation
- Context-aware documentation retrieval
- Standardized interfaces for AI agents to query project structure
- Dynamic context loading based on agent tasks
Value: Reduces token usage and improves AI agent performance by providing only relevant context when needed
Concept: Develop custom Claude skills that understand and leverage this documentation framework
Potential Skills:
/docs-search- Intelligent search across hierarchical documentation/update-roadmap- Guided roadmap updates with validation/plan-feature- Feature planning that auto-generates PROJECT_PLAN entries/sync-docs- Detect and fix documentation inconsistencies
Value: Seamless workflow for maintaining and using the documentation framework within Claude Code
Concept: Create a standalone plugin that scaffolds and maintains this documentation structure
Features:
- One-command project initialization with templates
- Automatic detection of documentation drift
- Interactive documentation update wizard
- Integration with popular IDEs and editors
- Documentation health metrics and dashboards
Value: Lower barrier to entry and easier maintenance for teams adopting the framework
This framework emerged from practical experience using AI coding assistants for coding and optimising documentation during onboarding, particularly when using Claude Code.
Inspired by the need to maintain clarity and strategic alignment in fast-moving AI-assisted development environments.
Research: The philosophy of this framework is supported by research from MIT, notably: Meng, E. and Jackson, D. (2025). What You See Is What It Does: A Structural Pattern for Legible Software. Available at: https://arxiv.org/abs/2508.14511.
Contributors: Thanks to James Algers for contributing.
Last Updated: 2025-01-31 Status: Template v1.0 - Ready for use Feedback: GitHub Issues