optimize-agents-md

Write lean, high-compliance AGENTS.md files and wire CLAUDE.md to them via @AGENTS.md so every AI coding tool reads the same source of truth.

Core philosophy

Frontier LLMs reliably follow only ~150-200 instructions per session, and Claude Code's system prompt already consumes about 50 of those slots. Every line added to AGENTS.md dilutes compliance across all rules, not just the newest ones. Ruthless curation is the foundational practice: a focused 60-80 line file Claude actually follows beats a 300-line file it mostly ignores.

Compliance also decays over long conversations — from 95%+ at messages 1-2 to 20-60% by messages 6-10. This is why the file should encode preferences, not hard requirements. Hard requirements belong in hooks, formatters, or CI. AGENTS.md is for the stuff that's hard to enforce mechanically.

The litmus test for every line: "Would removing this line cause Claude to make a mistake it wouldn't otherwise make?" If no, cut it.

Workflow

Run these stages in order. Stages 1-2 are autonomous discovery. Stage 3 is interactive but adaptive — don't pepper the user with questions if the answers are obvious from the code.

1. Survey the existing state

Read whatever exists in the project: