I've found that keeping my CLAUDE.md minimal (under 100 lines) yields the best results. I focus mainly on these areas:
- Essential project context and purpose
- A minimal project structure to help locate types, interfaces, and helpers
- Common commands to avoid parsing package.json repeatedly.
Regarding the specific practices mentioned:
Implementation Flow: I've noticed Claude Code often tries to write all tests at once, then implements everything when import fails (not true TDD). To address this, I created a TDD-Guard hook that enforces one test at a time, test fail for the right reason, only implement the minimal code to make the test pass.
Code quality: I've had good success automating these with husky, lint-staged, and commitlint. This gives deterministic results and frees up the context for more important information.
When Stuck: I agree that developer intervention is often the best path. I'm just afraid the specific guidance here might be too generic.
- Essential project context and purpose
- A minimal project structure to help locate types, interfaces, and helpers
- Common commands to avoid parsing package.json repeatedly.
Regarding the specific practices mentioned:
Implementation Flow: I've noticed Claude Code often tries to write all tests at once, then implements everything when import fails (not true TDD). To address this, I created a TDD-Guard hook that enforces one test at a time, test fail for the right reason, only implement the minimal code to make the test pass.
Code quality: I've had good success automating these with husky, lint-staged, and commitlint. This gives deterministic results and frees up the context for more important information.
When Stuck: I agree that developer intervention is often the best path. I'm just afraid the specific guidance here might be too generic.
For anyone interested in this automated approach:
https://github.com/nizos/tdd-guard (includes example configuration)
https://github.com/typicode/husky
https://github.com/conventional-changelog/commitlint
https://github.com/lint-staged/lint-staged