40 lines of CLAUDE.md beats defaults: direct the agent, don't describe the project
techpotions · reddit · 2026-09-22
A Reddit user shares hard-won lessons on writing CLAUDE.md: most files fail because they describe the project instead of directing the agent. Concrete before/after examples — "We use pnpm" becomes "Package manager is pnpm. Never use npm or yarn"; vague type-safety wishes become explicit pnpm typecheck commands; noting tests need a local Postgres via docker compose up -d saves 60s hangs.
Key takeaways:
- If Claude makes the same mistake twice, it's a missing CLAUDE.md line, not a prompting problem
- Write hard non-negotiables: don't start the dev server, never touch .env, no migrations without asking
- Use nested CLAUDE.md files (Claude reads the nearest one plus the root) to separate workspace and package rules
The author also released 5 free MIT templates (Next.js, Python, monorepo, API service, lean starter), with a warning not to paste them in unedited.
More from coding & agent
- Google's RRSI regularizes recursive self-improvement of agent harnesses, +4.7 OOD points — google · 2026-09-22
- 53 harness bugs: an engineering team's field notes on building eval harnesses — DrDatta_AIIMS · 2026-09-22
- atuin 18.23 ships infinite searchable scrollback — shell history now keeps command output — aronchick · 2026-09-22
- Kev: open-source 0.8B/4B/9B judge models on Qwen3.5, the 9B fits a 32GB Mac — khiladi1729 · 2026-09-22
- Open-source coding-agent skills for Google ADK on Google Cloud, distilled from real engineering lessons — Difficult_Design6676 · 2026-09-22
- After trimming his Claude Code harness, a Max 20x user now has 9 spare hours of quota a week — carlito_17 · 2026-09-22