Agentic Docs Templates

A language-agnostic, framework-agnostic repository template for document-driven AI coding agent development.

AI coding agents are powerful but undisciplined by default. This template gives agents a durable context system: read docs before changing code, plan before executing, write tests before implementation, keep documentation synchronized, and use admission, budget, deletion, and archive rules to prevent state snapshots, decision logs, technical debt, and backlogs from becoming dumping grounds.

Table of Contents

• Quick Start
• Adopting in Existing Projects
• Repository Structure
• Core Concepts
• Documentation Integrity Check
• Customization
• Compatibility
• Inspiration
• License

Quick Start

1. Click "Use this template" on GitHub to create a new repo
2. Edit AGENTS.md and fill in the <!-- CUSTOMIZE --> sections with your tech stack, commands, and coding rules
3. Edit ARCHITECTURE.md, docs/STATE.md, docs/TESTING.md, and product specs with real project facts
4. Run python3 scripts/check-docs.py
5. Start developing. The agent will follow the workflow defined in AGENTS.md

Adopting in Existing Projects

Use the bootstrap prompt. An AI agent will analyze your project and generate the documentation files with project-specific content.

# Claude Code
claude "Read https://raw.githubusercontent.com/Sukitly/agentic-docs-templates/main/bootstrap.md and follow the instructions to set up agentic docs for this project."

Or download first:

curl -sO https://raw.githubusercontent.com/Sukitly/agentic-docs-templates/main/bootstrap.md
claude "Read bootstrap.md and follow the instructions to set up agentic docs for this project."

The bootstrap prompt works with any AI coding agent. It analyzes the project, confirms findings with the user, generates docs with real content, and verifies documentation integrity.

Repository Structure

├── AGENTS.md                      # Agent instructions (rules, workflow, checklists)
├── ARCHITECTURE.md                # Architecture map (customize per project)
├── bootstrap.md                   # Bootstrap prompt for existing projects
├── docs/
│   ├── STATE.md                   # Current-state snapshot (no changelog)
│   ├── DECISIONS.md               # Still-binding technical decisions
│   ├── DEPLOYMENT.md              # Deploy targets, env, smoke tests, rollback notes
│   ├── TESTING.md                 # Testing strategy
│   ├── TECH_DEBT.md               # Implementation deviations with repayment paths
│   ├── BACKLOG.md                 # Product gaps, deferred decisions, ops follow-ups
│   ├── archive/
│   │   └── README.md              # Read-only archive boundary and catalog
│   ├── product-specs/
│   │   ├── knowledge-base.md      # Feature descriptions, file paths, data model
│   │   └── glossary.md            # Canonical terms and definitions
│   ├── design-docs/
│   │   └── index.md               # Design document index
│   ├── exec-plans/
│   │   ├── index.md               # Execution plan index
│   │   ├── active/                # In-progress plans (empty in this template)
│   │   └── completed/             # Completed plans (empty in this template)
│   ├── templates/
│   │   ├── design-doc.md          # Template for design documents
│   │   └── exec-plan.md           # Template for execution plans
│   └── references/                # External guides and references
├── scripts/
│   └── check-docs.py              # Documentation integrity checker
└── .gitignore

Core Concepts

Core Rules

1. Read docs first. Understand current state and architecture before touching code.
2. Create docs only when the criteria are met. Design Docs and Exec Plans are durable carriers for significant design and multi-step work, not bureaucracy for every small change.
3. Plan before execute. Present planned file changes and wait for explicit approval.
4. Tests first for core logic. Use TDD for behavior that matters.
5. Self-review and sync docs. A task is not complete until checks pass and affected docs are updated.
6. Documentation is a budgeted current-state system. Rewrite snapshots in place, delete stale queue entries, and physically separate history from current authority.
7. No minimum-diff shortcuts. Choose the right abstraction over the smallest patch.
8. No silent decisions. Non-trivial choices must be explicit; do not fabricate alternatives just to fill a table.
9. No unrequested actions. Report out-of-scope findings instead of modifying them opportunistically.

Document Types

Type	When to Create	Location
Current-state snapshot	Always present; stores current conclusions by domain	docs/STATE.md
Product knowledge snapshot	Always present; stores current behavior and entry points by feature	docs/product-specs/knowledge-base.md
Design Doc	Significant architecture/product design change with real competing approaches	docs/templates/design-doc.md
Exec Plan	Cross-package/service cutover, irreversible migration, or multi-PR/multi-session work	docs/templates/exec-plan.md
Decision Log	Still-binding cross-cutting decision without a carrying doc	docs/DECISIONS.md
Tech Debt	Implementation deviation with evidence, engineering impact, and a repayment path	docs/TECH_DEBT.md
Backlog	Product gap, deferred decision, or ops/security follow-up with explicit value or restart conditions	docs/BACKLOG.md
Historical Archive	Document has completed its purpose but retains historical research value	docs/archive/

Documentation Freshness Boundaries

• STATE.md and knowledge-base.md entries are no more than five lines (roughly 300 words) and contain only current conclusions and authoritative links; push excess detail into a Design Doc or Exec Plan.
• DECISIONS.md entries are no more than 15 lines and retain only decisions that still constrain future work.
• TECH_DEBT.md and BACKLOG.md are active queues, not historical ledgers. Delete entries when repaid, started, abandoned, invalidated, or superseded; do not maintain completed tables or duplicate active Exec Plan tracking.
• Durable documents do not track whether a specific migration is pending or applied; transient state belongs in the deployment system or an active Exec Plan.
• archive/ is read-only and not current authority; delete obsolete content with no historical value.

Workflow

Task received
  → Read relevant docs
  → Decide whether a Design Doc or Exec Plan is required
  → Present plan and get approval
  → Write tests first for core logic
  → Implement final path
  → Run checks
  → Run self-review
  → Update docs
  → Done

Documentation Integrity Check

python3 scripts/check-docs.py

# or via uv
uv run scripts/check-docs.py

The script checks relative Markdown links, index coverage, Exec Plan structure, and ARCHITECTURE.md path references. It has no external dependencies beyond Python 3.

Customization

Search for <!-- CUSTOMIZE --> comments across Markdown files:

• AGENTS.md: commands, tech stack, coding rules, testing rules
• ARCHITECTURE.md: directory structure, layering rules, conventions
• docs/STATE.md: deployment/runtime, infrastructure, current domain state
• docs/DEPLOYMENT.md: deploy targets, env vars, smoke tests, rollback notes
• docs/TESTING.md: test categories, directories, commands, coverage goals
• docs/product-specs/knowledge-base.md: features, data model, file paths
• docs/product-specs/glossary.md: project-specific terminology

Compatibility

AGENTS.md is supported by many AI coding agents, including Codex, Cursor, Gemini CLI, pi, and others.

Note: Claude Code uses CLAUDE.md by default. Rename, copy, or symlink AGENTS.md to CLAUDE.md if needed.

Inspiration

This template is inspired by OpenAI's Harness Engineering approach to AI-assisted development and practical lessons from real-world agent-driven projects.

License

MIT