From 1439bdd20975a176bc509d8376be85ee181536ae Mon Sep 17 00:00:00 2001 From: Madhura68 Date: Sun, 3 May 2026 01:11:15 +0200 Subject: [PATCH] docs(adr): add 0008-agent-instructions-in-claude-md + update README index --- .../0008-agent-instructions-in-claude-md.md | 41 +++++++++++++++++++ docs/adr/README.md | 8 ++++ 2 files changed, 49 insertions(+) create mode 100644 docs/adr/0008-agent-instructions-in-claude-md.md diff --git a/docs/adr/0008-agent-instructions-in-claude-md.md b/docs/adr/0008-agent-instructions-in-claude-md.md new file mode 100644 index 0000000..904d09a --- /dev/null +++ b/docs/adr/0008-agent-instructions-in-claude-md.md @@ -0,0 +1,41 @@ +--- +title: "ADR-0008: Agent instructions in CLAUDE.md + topical runbooks" +status: accepted +date: 2026-05-03 +--- + +# ADR-0008: Agent instructions in CLAUDE.md + topical runbooks + +## Status + +Accepted + +## Context + +Claude Code reads `CLAUDE.md` at session start and injects it verbatim into the system prompt. As the project grew, the file expanded to ~350 lines covering stack, patterns, MCP tools, commit strategy, branch policy, Vercel deployment, and demo-user rules. At that length the token cost was significant and the file was hard to navigate — both for humans and for AI agents skimming for a specific rule. + +A separate `docs/agent-instruction-audit.md` tracked *why* each rule existed, but that meta-history was buried and rarely consulted. The result: rules were added but never removed, and the file drifted toward being a reference dump rather than a decision-forcing instrument. + +## Decision + +Split `CLAUDE.md` into a short ≤150-line orientation hub that hard-links to topical runbooks: + +- `docs/runbooks/branch-and-commit.md` — branch policy, plan mode, commit strategy +- `docs/runbooks/mcp-integration.md` — all 18 MCP tools + batch-loop invariants +- `docs/runbooks/deploy-vercel.md` — Sharp, cron, env-var, preflight rules + +`CLAUDE.md` retains only the rules an agent **must** have in active context on every turn: the orientation table, the 8 hardstop rules, stack table, patterns quickref, and env vars. Everything else is a hyperlink. + +`AGENTS.md` (Codex entry-point) becomes a 10-line redirect stub pointing at `CLAUDE.md`. + +## Consequences + +**Positive** +- Active-context token cost drops ~60 % — the hub is ~114 lines vs 350. +- Each runbook is standalone and audience-tagged (`audience: [ai-agent]` etc.), so a future agent can fetch exactly the doc it needs. +- The split gives a natural place to add rules without polluting the root file. +- `docs/decisions/agent-instructions-history.md` (renamed from `agent-instruction-audit.md`) documents the *why* behind each rule as persistent institutional memory. + +**Negative** +- An agent that reads only `CLAUDE.md` will miss branch/MCP/deploy rules unless it follows the links. Mitigation: critical one-liners (e.g., "PR only after user test") are kept as hardstops in the hub. +- The split increases the number of files to maintain; runbooks can drift from `CLAUDE.md` if authors forget to update both. Mitigation: docs-sync convention in `CLAUDE.md` Conventions section. diff --git a/docs/adr/README.md b/docs/adr/README.md index 6ffcb6c..44b3b71 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -86,6 +86,14 @@ typo fixes. Course corrections always create a new ADR. | # | Title | Status | Template | |---|---|---|---| | [0000](./0000-record-architecture-decisions.md) | Record architecture decisions | accepted | Nygard | +| [0001](./0001-base-ui-over-radix.md) | @base-ui/react over Radix UI | accepted | Nygard | +| [0002](./0002-float-sort-order.md) | Float sort_order for drag-and-drop reorder | accepted | Nygard | +| [0003](./0003-one-branch-per-milestone.md) | One branch per milestone (Hobby plan) | accepted | MADR | +| [0004](./0004-status-enum-mapping.md) | Status enum mapping via lib/task-status.ts | accepted | Nygard | +| [0005](./0005-iron-session-over-nextauth.md) | iron-session over NextAuth/Clerk | accepted | MADR | +| [0006](./0006-demo-user-three-layer-policy.md) | Demo-user three-layer write guard | accepted | Nygard | +| [0007](./0007-claude-question-channel-design.md) | Agent ↔ user question channel via persistent table + LISTEN/NOTIFY | accepted | MADR | +| [0008](./0008-agent-instructions-in-claude-md.md) | Agent instructions in CLAUDE.md + topical runbooks | accepted | Nygard | When new ADRs are added, the docs index generator (`npm run docs:index`) will list them in [`../INDEX.md`](../INDEX.md). Update this table by hand