A contract-based, agent-first documentation system for AI-assisted application development
Humans steer. Agents execute.
Documentation exists so coding agents can operate autonomously within defined boundaries. Every doc artifact is written for agents as the primary consumer and humans as reviewers.
- Repository-local knowledge is the only truth — if the agent can't read it in-repo, it doesn't exist
- Docs are contracts, not explanations
- Structure over prose; bullets over paragraphs
- Durable truth lives in predictable locations
- Temporary thinking never becomes documentation
- Documentation must use progressive disclosure: short entrypoints point to deep docs
- Tests are the executable contract for behavior
- Agents must always know: what to read, where to write, what to update
- DRY docs: define every fact once, in one canonical location, and link everywhere else — if information appears in two places, one of them is wrong (or will be soon)
- Token budgets matter — every doc has a size target; agent performance degrades as context fills, so keep docs within their budgets
- Don't document what tools enforce — if linters, type checkers, or frameworks already enforce it, don't repeat it in docs
Primary goal: minimum tokens, maximum correctness, zero drift.
# === Required (always create) ===
README.md # Product contract + entry point
ARCHITECTURE.md # System layout, boundaries, data flows
AGENTS.md # Agent table of contents (~120 lines)
docs/
app-workflows.md # User journeys
dev-workflows.md # Engineering workflows
features/
_template.md
<feature>.md
exec-plans/
active/
<plan>.md
completed/
<plan>.md
tech-debt-tracker.md
# === Create-on-need (only when you have concrete content) ===
agent-tools.md # MCP / tool access
QUALITY_SCORE.md # Golden principles + quality tracking
RELIABILITY.md # SLOs, fragile areas, reliability constraints
SECURITY.md # Trust boundaries, auth, data policies
product-specs/ # Cross-cutting product specs
<spec>.md
design-docs/ # Architecture decisions (lightweight ADRs)
<decision>.md
references/ # Pinned external knowledge
<topic>.md
# === Agent-specific config (create only for the agent in use) ===
CLAUDE.md # Claude Code only
.cursorrules # Cursor (legacy)
.cursor/rules/*.mdc # Cursor (current)
.github/copilot-instructions.md # GitHub Copilot
Hard Rule: Agents MUST NOT create new documentation files unless explicitly instructed.
Agent Config Rule: Only create the agent-specific config file for the agent currently being used. Codex CLI uses
AGENTS.mddirectly — no separate config file needed.
For repositories with multiple packages, services, or distinct modules, subdirectory-scoped docs are allowed:
- Each package/service MAY have its own
AGENTS.md,ARCHITECTURE.md, or agent config file - Subdirectory docs supplement the root docs — they add specificity, not replace shared rules
- When root and subdirectory docs conflict, the most-specific doc wins and the conflict should be flagged for resolution
- Keep the root-level docs as the canonical entry point; subdirectory docs handle local concerns only
Agents MUST read AGENTS.md before making any change. It is the table of contents and the only forced read.
Every other doc is pulled on demand, based on the task:
| Task | Pull |
|---|---|
| Understand the product | README.md |
| Touch system boundaries, deployments, or data flow | ARCHITECTURE.md |
| Change a feature's behavior, inputs, outputs, or tests | docs/features/<feature>.md |
| Work that spans multiple features | docs/product-specs/<spec>.md |
| Change a user journey | docs/app-workflows.md |
| Change engineering or testing process | docs/dev-workflows.md |
| Behavioral or structural change | docs/QUALITY_SCORE.md |
| Touch reliability or security domains | docs/RELIABILITY.md, docs/SECURITY.md |
| Tool or MCP access needed | docs/agent-tools.md |
| Agent-specific operating rules apply | Agent config file (if present) |
AGENTS.md lists every doc path so agents can find them without guessing.
When two docs contradict each other:
- Most-specific doc wins — a feature doc overrides ARCHITECTURE.md for that feature's behavior
- Subdirectory docs override root docs for their scope (see section 2)
- Agent MUST flag the conflict in its PR so humans can reconcile the source docs
All knowledge agents need must live in-repo as versioned markdown.
Rules:
- Never rely on Slack, Google Docs, Confluence, Jira, or tribal knowledge
- If information exists only in an external system, it must be pinned into
docs/references/as a markdown summary before agents can use it - External links are allowed as citations but never as the source of truth
- Every doc file must be self-contained enough that an agent can act on it without additional context
Test: If a fresh agent session cannot find and act on the information, the documentation has failed.
Purpose: product contract + GitHub-quality entry point
Size target: ~150 lines max
- Product overview and target user
- Core features list (links to feature docs)
- Short architecture summary (link to ARCHITECTURE.md)
- Tech stack (surface-level only)
- Setup instructions
- Environment variable names (no values)
- Run commands
- Test commands (quick subset + full suite)
- Documentation map (links to all core docs)
- Contribution basics (reference AGENTS.md)
Allowed: languages, frameworks, platforms, services, hosting, datastores by type
Disallowed: DB schemas, deployment topology, secrets, infrastructure scripts
- Bullets where possible
- No implementation detail
Purpose: system layout, deployments, and data flows
Size target: ~200 lines max
- Components and responsibilities
- Deployment locations (what runs where)
- Data stores and ownership
- External services
- Trust boundaries
- Data flows
- Core features list (links to feature docs)
- Canonical file references — pointer to one exemplar file per major pattern (e.g., "Canonical API handler:
src/handlers/users.ts") - References to relevant design docs in
docs/design-docs/
Allowed: hosting targets, service boundaries, logical data entities, event and request flows
Disallowed: table-level schemas, ORM field lists, SQL, migration detail
- Lists only
- No rationale unless required for correctness
Purpose: the ~120-line entry point that tells agents how to operate in this repo
AGENTS.md is a table of contents, not a manual. It should be concise enough for an agent to read in a single pass and know exactly where to go next.
Note: This file is also used directly by Codex CLI as its configuration file.
Quick verify: <exact command to run the fast test subset>- The single highest-frequency command agents will run. Keep it at the top so it's visible without scrolling.
- What this repo is and what it produces
- Key system boundaries agents must respect
- Link to
ARCHITECTURE.mdfor full detail
- Rules agents must never break (testing, doc updates, PR structure)
- Testing requirements (TDD guidance, when to run tests)
- Doc update rules (same-PR requirement)
- Pointer to every canonical doc location
- One line per doc: file path + purpose
- Where plans live (
docs/exec-plans/active/) - When plans are required
- Link to
docs/dev-workflows.mdfor full process
- PR structure requirements
- What agents must verify before submitting
- Target ~120 lines total
- Every line is actionable or a pointer
- No prose blocks
- No duplicated rules — point to the source doc instead
Purpose: source of truth for a core feature
Size target: ~80 lines max per feature doc
# Feature: <name>
## Purpose
One sentence describing the problem this feature solves.
## Used By
- UI: <screen or flow>
- API: <endpoint>
- Job: <worker or cron> (if any)
## Core Functions
- function_or_module_a
- function_or_module_b
## Canonical Files
- Pattern exemplar: `path/to/canonical/implementation`
## Inputs
- name: type (source)
## Outputs
- name: type
- side effects (DB write, event, notification)
## Flow
- Step 1
- Step 2
- Step 3
## Edge Cases
- Case -> expected behavior
## UX States (if applicable)
- Empty
- Loading
- Error
## Verification
- Test files: `path/to/tests`
- Required cases: happy path + 2-5 edge cases
- Quick verify command: `<exact command to run this feature's tests>`
- Full verify command: `<exact command to run full suite>`
- Pass criteria: what "green" looks like for this feature
## Related Docs
- README.md
- ARCHITECTURE.md
- docs/app-workflows.mdAllowed: logical data usage ("writes to primary database"), side effects
Disallowed: table names, field names, indexes
- Bullets only
- Every line constrains behavior
Purpose: cross-cutting product behavior that spans multiple features
Use docs/product-specs/ when documentation spans multiple features, describes cross-cutting product behavior, or captures product requirements that don't fit a single feature doc.
Size target: ~120 lines max per spec
# Spec: <name>
## Scope
Which features and systems this spec covers.
## Features Involved
- [Feature A](../features/feature-a.md)
- [Feature B](../features/feature-b.md)
## User Personas Affected
- Persona -> how they're impacted
## Cross-Cutting Behaviors
- Behavior description -> which features implement it
- Shared constraints that apply across features
## Business Rules
- Rule -> enforcement mechanism
## Constraints
- Performance, compliance, or UX constraints that span features
## Verification
- How to validate cross-feature behavior end-to-end
- Exact commands if applicable- Bullets only
- Must link to related feature docs — never duplicate feature-level detail
- One spec per product area
Purpose: user journeys inside the product
Size target: ~150 lines max
- One section per core user workflow
- Step-by-step user actions
- High-level system responses
- Links to relevant feature docs
- No component names
- No backend detail
Purpose: how engineering work is done in this repo
Size target: ~150 lines max
- New feature workflow
- Bugfix workflow
- Refactor workflow
- Documentation update workflow
- Pull request workflow
- Testing workflow (required)
- Checklists only
Test types:
- Unit: pure logic
- Integration: boundaries (HTTP handlers, DB writes, queue jobs)
- E2E: only highest-value user workflows (few, stable)
Test placement: explicit repo paths
Commands: quick (relevant subset), full (full suite)
When to run:
- After behavior change: run relevant subset
- Before PR: run full suite (or document why not)
Bugfix rule:
- Add failing test first
- Confirm failure
- Implement fix
- Rerun tests until green
Purpose: tool and context access contract (MCP-friendly)
- Tool list and purpose
- Local vs CI access
- Security boundaries
- MCP usage notes
Most coding agents support reusable skills or custom commands (e.g., Claude Code's .claude/commands/, Codex's .agents/skills/, Cursor's .cursor/plans/). These are agent-specific features — use each agent's native format and directory structure rather than defining a shared location. If skills are in use, document their existence and purpose in this file so other agents or humans know they're available.
Purpose: versioned planning artifacts that track work from intent to completion
Plans are not throwaway notes. They are versioned artifacts with goals, decisions, progress, and validation criteria.
docs/exec-plans/active/— plans currently in progressdocs/exec-plans/completed/— plans that have been executed and validateddocs/exec-plans/tech-debt-tracker.md— continuous tracking of known tech debt
- Goal: what this plan achieves
- Decisions: key choices made and why
- Steps: ordered execution checklist
- Validation: how to verify the plan succeeded
- Progress log: updated as work proceeds
- New features
- Data model changes
- User explicitly requests a plan
Plans are optional for small multi-file edits, bugfixes, and routine refactors. Use judgment — a plan should clarify work, not add ceremony.
- Create in
active/ - Update progress as work proceeds
- Move to
completed/after validation - Reference in PR
- Continuous log of known tech debt
- Each entry: description, impact, proposed resolution, priority
- Agents update this when they discover or create tech debt
- Review during planning to avoid compounding debt
Purpose: encode the project's golden principles and track quality over time
- Shared utilities and abstraction rules
- Data boundary validation requirements
- Test coverage expectations
- Architectural layering rules
- Quality checklist agents must verify before PR
Agents update this doc when quality standards change or new patterns are established.
Purpose: reliability constraints and operational awareness
- SLOs and performance targets (if defined)
- Known fragile areas and mitigation strategies
- Graceful degradation requirements
- Monitoring and alerting expectations
Purpose: security policies agents must follow
- Trust boundaries (what talks to what, with what permissions)
- Authentication and authorization model
- Data handling policies (PII, encryption, retention)
- Security-sensitive code paths
- Dependency security requirements
Purpose: record architecture decisions and significant design choices
# Decision: <title>
## Context
What problem or situation prompted this decision.
## Decision
What was decided.
## Consequences
- What this enables
- What this constrains
- Trade-offs accepted- One doc per significant decision
- Referenced from ARCHITECTURE.md
- Not retroactive — only create for new decisions going forward
- Agents create design docs when making architectural choices that affect system boundaries
Purpose: pinned external knowledge that agents need
- External API documentation that agents must reference
- Third-party service constraints or configuration
- Standards or specifications the project must comply with
- Each file is a markdown summary of external knowledge
- Include source URL as a citation
- Keep concise — only what's needed for agent execution
- Update when external sources change
Purpose: tool-specific operating constraints for a particular coding agent
Rule: Only create the config file for the agent currently in use.
| Agent | Config File | Notes |
|---|---|---|
| Claude Code | CLAUDE.md |
Project root; supports nested CLAUDE.md in subdirectories |
| Codex CLI | AGENTS.md |
Uses the shared AGENTS.md file directly; supports AGENTS.override.md per directory |
| Cursor | .cursor/rules/*.mdc |
.mdc files scoped by glob; .cursorrules is legacy |
| Gemini CLI | GEMINI.md or AGENT.md |
Project root; supports nested files in subdirectories |
| GitHub Copilot | .github/copilot-instructions.md |
Inside .github/ directory |
All major agents support hierarchical config discovery — subdirectory configs supplement or override root configs:
- Claude Code: nested
CLAUDE.mdfiles add scoped context per directory - Codex CLI: walks from git root to CWD, merging
AGENTS.mdat each level;AGENTS.override.mdtakes precedence at the same level - Cursor:
.mdcrules can be scoped to specific file patterns via globs - Gemini: nested
GEMINI.mdfiles override general context with specific context
Use nested configs when distinct modules, services, or packages need different conventions. Keep root-level config for repo-wide rules.
- "Follow AGENTS.md" — single line
- Quick verify command (copy from AGENTS.md)
- Plan location (
docs/exec-plans/active/)
- ≤10 lines — pointer only, not a manual
- No policy, no rules, no duplication of AGENTS.md
- If you need to add rules, add them to AGENTS.md instead
When code changes, agents MUST update:
| Change Type | Update Location |
|---|---|
| Feature logic, inputs, outputs, tests | docs/features/<feature>.md |
| Cross-cutting product behavior | docs/product-specs/<spec>.md |
| User journeys | docs/app-workflows.md |
| System layout, deployments, integrations | ARCHITECTURE.md |
| Dev or testing process | docs/dev-workflows.md |
| Architecture decisions | docs/design-docs/<decision>.md |
| Quality standards or patterns | docs/QUALITY_SCORE.md |
| Reliability constraints or SLOs | docs/RELIABILITY.md |
| Security policies or trust boundaries | docs/SECURITY.md |
| Setup or tech stack summary | README.md |
| Active work plans | docs/exec-plans/active/ |
| Known tech debt | docs/exec-plans/tech-debt-tracker.md |
Docs drift when code changes but docs don't. Use one or more of these mechanisms to catch it:
- Header timestamp: add
<!-- last_verified: YYYY-MM-DD -->to the top of each doc; agents update this when they verify or modify the doc - CI check (recommended): compare modification dates of doc files against their related source files; flag docs that haven't been updated since related code changed
- Agent pre-task check: before starting work, agents should verify that the docs they read are consistent with the code they see; if not, flag the drift before proceeding
- References are highest-risk:
docs/references/files summarize external sources that change independently — review these on a regular cadence
All docs MUST follow:
- Bullets over sentences
- Only update affected sections
- No rewording unchanged content
- No rationale unless required for correctness
- Define every fact once — link, don't repeat
- Reference canonical files instead of copying code into docs — keeps docs short and prevents staleness
Golden Rule: Define once, link everywhere. As short as possible, but precise enough to prevent ambiguity. If a fact lives in two files, delete one and replace it with a link.
- Linter/formatter rules — if ESLint, Prettier, Ruff, etc. enforce it, don't restate it in docs
- Type system guarantees — if TypeScript, Go, or Rust enforce a constraint, the types are the doc
- Framework defaults — don't document behavior that's standard for the framework in use
- Obvious conventions — if the codebase consistently follows a pattern, agents will infer it from code; only document deviations or non-obvious choices
- Historical context — don't explain why old decisions were made unless it constrains future decisions (use
docs/design-docs/for that) - Edge cases that can't happen — don't document impossible states or scenarios the type system prevents