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
├── SYNCHRONIZATIONS.md # Cross-concept event flows
├── 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 |
| SYNCHRONIZATIONS.md | Always current | Cross-concept event flows | "When user.delete fires → post.deleteAll follows" |
| 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/
cp agentic-coding-framework/SYNCHRONIZATIONS.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)
The framework changes the order of operations for building with an agent, not just how things are documented. The key shift: design your concepts before writing any code. This gives the agent tight boundaries to work within and surfaces coordination decisions early — when they're cheap to change.
1. Define your concepts first
Before touching code, ask the agent to draft the concepts your project needs:
"I'm building a project that [brief description]. Using the concept spec format in
examples/ml-workflow/CLAUDE.md, draft the concepts we need and their state/actions/invariants. Don't write any code yet."
Review what it proposes. Maybe two concepts collapse into one, or a concept is too thin to justify its own module. This conversation is fast — getting it wrong in a spec is a 5-minute fix; getting it wrong in code is a refactor.
2. Write the specs and SYNCHRONIZATIONS.md
Once you've agreed on concepts, ask the agent to create the subfolder CLAUDE.md files and populate SYNCHRONIZATIONS.md:
"Create a CLAUDE.md for each concept using the format in
examples/ml-workflow/CLAUDE.md. Then populateSYNCHRONIZATIONS.mdwith the cross-concept flows."
Review the sync entries. If a coordination feels wrong, fix the spec now. This is your coordination map before any implementation exists.
3. Implement one concept at a time
Scope each coding task strictly to one concept:
"Implement the
[Concept]concept. Follow the spec in[path]/CLAUDE.mdexactly. Do not import from any other concept. Write unit tests that verify the invariants."
Repeat for each concept. Each task is self-contained — the agent has a tight spec and a clear rule about what it must not touch.
4. Implement the coordinator last
Once all concepts are implemented and tested in isolation:
"Read
SYNCHRONIZATIONS.md. Createcoordinator.pywith one function per SYNC entry. This is the only file allowed to import from multiple concepts."
The agent translates each SYNC entry directly into a function. If an entry is ambiguous, it surfaces now — not mid-implementation.
Keep prompts scoped to one concept or one sync at a time. The instinct is to say "build the whole pipeline" — resist it. The framework only pays off if the agent operates within concept boundaries, and it will as long as your prompts respect them too.
- Smaller agent tasks: Each prompt has a clear boundary. The agent isn't holding the whole system in context at once.
- Invariants as a safety net: The agent knows from the spec what must hold after each action. You don't have to restate constraints in every prompt.
- Easier debugging: If something breaks, the concept boundaries tell you exactly where to look.
- Safe iteration: Changing a threshold or adding a downstream effect means updating one SYNC entry and the coordinator — neither concept doc changes.
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/ folder for a two-concept worked example showing the full framework in action:
| File | What it demonstrates |
|---|---|
examples/ml-workflow/CLAUDE.md |
Concept spec (state, actions, invariants) for a self-contained MLWorkflow concept |
examples/deployment/CLAUDE.md |
Concept spec for a self-contained Deployment concept |
examples/SYNCHRONIZATIONS.md |
How the two concepts coordinate — without either knowing about the other |
The SYNCHRONIZATIONS.md is the key file to read: it shows what a real sync entry looks like and explains why the coordination lives here instead of in either concept's doc.
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