Repo Doc Templates

These files are the agent's durable memory. Keep each one short, factual, and versioned. Put standing orders in CLAUDE.md / AGENTS.md; put arguments and diagrams in ARCHITECTURE.md and ADRs. See Docs as Agent Memory and CLAUDE.md & AGENTS.md.

CLAUDE.md

Use for every Claude Code repo. Standing orders only — under ~60 lines. No essays, no aspirational values, nothing a linter already enforces.

# <Project name> — Claude Code instructions

## Commands
- Install: `<pkg manager install>`
- Dev: `<dev command>`
- Test: `<test command that exits — not watch mode>`
- Typecheck / lint: `<commands>`
- Build: `<build command>`

## Hard constraints
- Never edit `<generated paths>` — regenerate with `<codegen command>`
- Never commit secrets; use `<env mechanism>`
- <Domain rule agents invent around, e.g. money = integer cents>

## Conventions (non-obvious only)
- <API naming / serialization rule>
- <Where new code goes: e.g. features under src/features/<name>/>
- Before adding a utility, check: <capabilities index or path>

## Pointers
- Architecture: `docs/ARCHITECTURE.md`
- Specs: `docs/specs/`
- ADRs: `docs/adr/`
- Testing: `docs/TESTING.md`

## Done means
- `<typecheck>` and `<tests>` pass
- Update `TASKS.md` / changelog in the same PR when applicable

AGENTS.md

Use when multiple tools (Claude Code, Codex, Cursor, Copilot) share the repo. Prefer one source of truth; make CLAUDE.md a pointer or symlink if both exist.

# <Project name> — Agent instructions

> Tool-agnostic standing orders. Claude Code: also see CLAUDE.md if present (should match this file).

## Commands
- Install / test / typecheck / build: same as CLAUDE.md section

## Hard constraints
- <Same never-dos as CLAUDE.md>

## Repo map (pointers only)
- Architecture: `docs/ARCHITECTURE.md`
- Specs: `docs/specs/`
- Decisions: `docs/adr/` or `DECISIONS.md`

## Working rules
- Prefer smallest diff that satisfies the spec
- Do not expand scope beyond the current task / spec
- Ask before changing public APIs, auth, or data migrations

README.md

Use for human onboarding. Agents should not need this file for constraints — put those in CLAUDE.md. Keep README honest about how to run and where truth lives.

# <Project name>

<One sentence: what it does and for whom.>

## Quick start
```bash
<clone / install / env setup>
<dev command>
```

## Docs that matter
| Doc | Purpose |
|---|---|
| `CLAUDE.md` / `AGENTS.md` | Agent standing orders |
| `docs/ARCHITECTURE.md` | System shape |
| `docs/specs/` | Feature specs |
| `docs/adr/` | Architecture decisions |

## Stack
- Runtime: `<Node / Python / …>`
- Framework: `<…>`
- Data: `<…>`
- Deploy: `<…>` — see `docs/DEPLOYMENT.md`

## Contributing
- Spec before large features: see `docs/specs/`
- PRs must pass `<CI checks>`

ARCHITECTURE.md

Use when agents invent structure, duplicate modules, or ignore existing boundaries. Describe current reality, not the roadmap.

# Architecture — <Project name>

## Purpose
<What the system does in 2–3 sentences.>

## Context diagram
<!-- Prefer a mermaid flowchart in the real file -->
- External actors: `<users, webhooks, third parties>`
- Trust boundaries: `<auth edge, admin, public API>`

## Major components
| Component | Path | Responsibility | Owns data? |
|---|---|---|---|
| `<name>` | `<path>` | `<one line>` | `<yes/no + store>` |

## Boundaries (do not cross casually)
- `<e.g. payments must not import from UI>`
- `<e.g. only src/api may talk to Stripe>`

## Data & consistency
- Source of truth: `<DB / service>`
- Idempotency: `<where / how>`
- Migrations: `<tool + rule>`

## Key ADRs
- ADR-<nn>: `<title>` — `<one-line decision>`

## Non-goals (architecture)
- `<what we explicitly will not build into this system>`

TASKS.md

Use as a living queue the agent updates in the same PR. Prefer checkboxes and owners over narrative status reports.

# Tasks — <Project / milestone>

Last updated: `<YYYY-MM-DD>` · Owner: `<name>`

## In progress
- [ ] `<task>` — owner `<name>` — spec: `docs/specs/<file>` — branch `<name>`

## Up next
- [ ] `<task>` — blocked by: `<none | dependency>`
- [ ] `<task>`

## Done (recent)
- [x] `<task>` — merged `<PR / date>`

## Parking lot
- `<idea not scheduled>` — reason parked: `<…>`

DECISIONS.md

Use for lightweight decisions that don't deserve a full ADR. Promote to ADR when consequences are cross-cutting or agents keep re-opening the choice.

# Decision log — <Project>

Format: date · decision · why · alternatives rejected · supersedes

## <YYYY-MM-DD> — <Short decision title>
- **Decision:** `<what we chose>`
- **Why:** `<1–3 lines>`
- **Rejected:** `<option>` — `<why not>`
- **Applies to:** `<paths / services>`
- **Supersedes:** `<none | prior entry>`

CODING_STANDARDS.md

Use only for conventions a linter cannot enforce and agents repeatedly violate. If it's lintable, lint it and delete the prose.

# Coding standards — <Project> (non-lintable)

## Must
- `<e.g. all money as integer cents; format only at edges>`
- `<e.g. errors: typed AppError subclasses, never string throws in src/domain>`
- `<e.g. new HTTP handlers go through src/api/middleware/auth.ts>`

## Must not
- `<e.g. no ORM in src/payments — see ADR-0002>`
- `<e.g. no new shared utils without checking src/lib/ first>`

## Naming
- `<API: snake_case; internal: camelCase; map in serialize.ts>`

## PR expectations
- Diff stays inside the spec's blast radius
- Tests for new behavior live next to code under `<convention>`

TESTING.md

Use so agents stop inventing test runners, skipping integration setup, or declaring "done" without the right suite.

# Testing — <Project>

## How to run
| Suite | Command | Notes |
|---|---|---|
| Unit | `<cmd>` | Fast; default for most PRs |
| Integration | `<cmd>` | Needs `<Docker / services>` |
| E2E | `<cmd>` | Run before release / auth changes |

## What "tested" means
- New behavior: at least one failing-then-passing test that asserts the acceptance criterion
- Bugfix: regression test that fails on main without the fix
- Do not add tests that only assert mocks were called

## Fixtures & data
- Factories: `<path>`
- Never hit production credentials in tests
- `<seed / reset procedure>`

## Known flaky / skip rules
- `<test or area>` — reason — owner

DEPLOYMENT.md

Use before agents "helpfully" invent deploy scripts or change infra. Document the real path and rollback.

# Deployment — <Project>

## Environments
| Env | URL / cluster | Who deploys | Auto? |
|---|---|---|---|
| Preview | `<…>` | CI on PR | yes |
| Staging | `<…>` | `<role>` | `<yes/no>` |
| Production | `<…>` | `<role>` | `<yes/no>` |

## Pipeline
1. `<build>`
2. `<migrate — expand/contract rules>`
3. `<deploy>`
4. `<smoke checks>`

## Required secrets / config
- `<VAR>` — purpose — where set
- Never commit `.env*`; local: `<direnv / 1password / …>`

## Rollback
- Procedure: `<revert deploy / previous image>`
- DB: `<forward-only | down migrations allowed when…>`
- On-call: `<rotation / channel>`

SECURITY.md

Use for threat-relevant never-dos and pointers. Not a compliance binder — agents need actionable constraints.

# Security — <Project>

## Trust boundaries
- Public: `<routes>`
- Authenticated: `<…>`
- Admin / privileged: `<…>`

## AuthN / AuthZ
- Mechanism: `<sessions / JWT / …>` — code: `<path>`
- Authorization checks live in `<path>`; never only in the UI
- Tenancy: `<how tenant_id is enforced>`

## Secrets
- Store: `<vault / platform env>`
- Rotation: `<cadence / owner>`
- Agents must never print secrets into logs, commits, or PR descriptions

## High-risk surfaces
- `<payments, file upload, SSRF-prone fetch, raw SQL>` — review required

## Reporting
- Internal: `<channel>`
- External: `<security@…>`

PROJECT_CONTEXT.md

Use for product/domain facts that bloat CLAUDE.md but agents still need. Point to it from CLAUDE.md; don't duplicate standing orders here.

# Project context — <Product name>

## Users & jobs
- Primary user: `<who>` — job: `<what they hire the product to do>`
- Secondary: `<…>`

## Domain glossary
| Term | Meaning in this product |
|---|---|
| `<Invoice>` | `<definition agents misuse>` |
| `<Workspace>` | `<tenancy unit>` |

## Current priorities
1. `<this quarter's bet>`
2. `<…>`

## Explicit non-goals
- `<what sales keeps asking for that we will not build>`

## Constraints from the business
- Compliance: `<SOC2 / HIPAA / none>`
- Latency / SLOs that affect design: `<…>`
- Third-party contracts that constrain APIs: `<…>`

Related

• CLAUDE.md & AGENTS.md — inclusion rules and hierarchy
• Docs as Agent Memory — what belongs where
• Repository Structure — layout that agents can navigate
• Navigability — making the repo searchable for agents
• Templates index — all templates