CLAUDE.md: cut to gotchas; drop code-derivable content and duplicates

[millsmillsymills]

Source

The new rules of context engineering for Claude 5 generation models — the guidance on keeping CLAUDE.md lightweight and gotcha-focused, and on consolidating instructions into a single source.

What to build

CLAUDE.md is the longest in the workspace (~179 lines) and most of it restates what the code already says. Trim it to the non-obvious:

• Drop the ~33-line Commands block — standard uv/ruff/ty/pytest/bandit invocations derivable from pyproject.toml. (Note: the Makefile targets that are genuinely non-obvious — cassette refresh/drift — aren't in this file today; the workspace CLAUDE.md covers them.)
• Drop the ~19-line src/ architecture tree — recoverable with ls/find.
• Replace the three inline code templates ("Adding a read tool" / "write tool" / "purchase tool") with pointers to one representative real handler per tier — the real code can't drift from itself.
• Drop the standards/audit stanza and the Conventions block; both duplicate workspace-level guidance that local agents already load (the Conventions bullets are shared verbatim with unifi/unraid/shortcut). This also stops publishing the ~/Desktop/Projects/... absolute path, which names a checkout that isn't part of this repo.

Keep intact: the v5 API gaps section ("so an LLM doesn't waste a turn searching for a tool that cannot exist"), the non-obvious invariants list, the purchase-gating tier table, and the no-retry-on-timeout-for-non-idempotent-methods rule.

Acceptance criteria

• Commands block and architecture tree removed
• Inline tool templates replaced with pointers to representative real handlers
• Standards stanza and shared Conventions block removed (a one-line note that workspace-level conventions apply is enough); no local absolute paths remain
• v5 API gaps, invariants, gating table, and retry semantics retained

Blocked by

• The shared "Python server conventions" section landing in the workspace-level CLAUDE.md (tracked separately). Only the shared-Conventions removal depends on it; the rest can proceed independently.