authoring-agent-docs

Keep the file under 200 lines with only facts the agent cannot infer from code, such as build commands and repo etiquette. Write concrete verifiable rules, state the motivation behind each, and give the agent a check it can run like a test suite or linter.

Include build and test commands, style rules differing from language defaults, branch and PR conventions, architecture decisions, required env vars, and non-obvious gotchas. Exclude standard conventions, file-by-file codebase descriptions, and frequently changing facts.

The file is likely too long, so the rule is lost in the noise, or the rule is placed in a file the agent never opens when it applies. Prune low-value lines and move the rule into the file the reader is actually using.

Target under 200 lines per CLAUDE.md. Longer files consume more context and reduce adherence, and splitting into imports does not save context because imports still load at session start.

Anything that must happen every time, such as blocking a write or running a linter before commit, belongs in a deterministic hook. Instruction files are context the agent tries to follow, with no guarantee of strict compliance.