Keep CLAUDE.md short and move detailed rules into separate docs
For long s, a very large CLAUDE.md or AGENTS.md can make the assistant read instructions that do not matter for the current task. These files are useful because they tell how a project works, but putting every rule into one file adds each time. Important rules can get buried inside the long file.
Old can keep affecting new work for too long. Task-specific instructions can also interfere with unrelated tasks. A thinner base file works better when it only includes shared project rules, source-of-truth documents, areas not to touch, when to ask for clarification, and where to find task-specific docs.
Heavier material such as rules, README editing rules, test rules, handoff rules, release checklists, and phase reports can live in separate documents.
Key points
- A huge CLAUDE.md or AGENTS.md can make every session carry irrelevant instructions.
- Long base files can raise and hide the most important rules.
- Old and task-specific rules may keep steering unrelated work.
- The base file should stay short and point to the right task-specific documents.
- Detailed rules for , tests, handoff, and releases can be split into separate docs.