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
- Boubou: open-source CLI turns your laptop into a fully local voice AI hub — alexcovo_eth · 2026-11-12
- User automates entire video clipping workflow with Nous Research's Hermes agent — Teknium · 2026-11-12
- As models improve, writing good evals gets harder and more important — amankhan · 2026-11-12
- Prime agent ships with day-one multi-agent communication, runs in Minecraft unmodified — sarahcat21 · 2026-11-12
- Autonomous agent edits just 1,024 weights to lift Qwen3.5 0.8B from 7.4% to 37.4% on MATH-500 — VictorSanh · 2026-11-12
- Omarchy 4.6 lets you share local AI models across your tailnet, says DHH — alexcovo_eth · 2026-11-12