janpeter/Scrum4Me
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 10
Scrum4Me/docs/adr/0008-agent-instructions-in-claude-md.md

2.4 KiB
Raw Blame History

title status date
ADR-0008: Agent instructions in CLAUDE.md + topical runbooks accepted 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.