Writing a good Claude.md

What CLAUDE.md Is and When It Helps

• Commenters define CLAUDE.md as a repo-level “prompt/config file” that is deterministically injected into Claude Code’s context, unlike ordinary docs it may or may not read.
• Many find it most useful for: project-specific norms (e.g., “no new Mocha tests, only Jest”), workflows (“how to run tests, migrations, builds”), and quirks (“use our S3 Terraform modules,” “prefer getOne() wrapper over findOne()”).
• Some report large gains in complex brownfield codebases or “hands-off” agent workflows; others say for simple, well-understood projects it’s marginal.

CLAUDE.md vs Regular Documentation and Linters

• One camp argues you mostly just need good code comments, READMEs, and tests; LLMs should learn from that like humans do.
• The opposing camp stresses that LLMs are stateless and re-onboard every session, so they need compact, always-injected instructions beyond human-oriented docs.
• Several insist that linters, type-checkers, and tests should enforce many rules (e.g., safe DB queries) rather than relying on prompts alone; CLAUDE.md is for preferences and conventions, not hard guarantees.

Context Limits, Ignored Instructions, and “Ritual Magic”

• Multiple reports say Claude frequently ignores parts of long CLAUDE.md files, especially mid-session or under token pressure; people use “canary” rules like special honorifics or emojis to detect when it’s drifting.
• There’s debate over information density: some advocate minimal, highly relevant instructions; others claim long but tightly focused guidance works well.
• Several observe that comments and excess context can degrade performance on hard problems; others say rich documentation is essential for understanding.

Patterns: Multiple Files, Skills, and Tools

• Many split guidance into multiple files: root CLAUDE.md as high-level hub plus task- or directory-specific markdown (or AGENTS.md/skills) referenced via a “table of contents” section.
• Some prefer hooks, tools, and scripts (e.g., enforcing index-safe queries, linting, schema inspection) over trying to “prompt away” bad behavior.
• A recurring tactic is to have Claude draft or refactor CLAUDE.md itself, then humans trim verbosity.

Productivity and Skepticism

• Experiences diverge sharply: some claim ~2× productivity, others cite studies and personal experience suggesting experienced devs can be slower with agents.
• Skeptics see CLAUDE.md/AGENTS.md as fragile, non-portable “prompt magic” that will age poorly as models gain memory and better state handling; enthusiasts see them as today’s highest-leverage configuration point.