---
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.