How to Write CLAUDE.md?

Start with the three basics: one sentence explaining what the project does, which package manager to use, and which few key commands exist. Move everything else out and let the agent look it up on its own when needed.

Don't use /init to auto-generate it, because it stuffs in the project structure, tech stack, and code paths. Most of this can be discovered on its own, and it easily goes out of date.

Keep only the pitfalls in the repo that are truly special and hard to discover directly from the code. Too many rules easily conflict with each other, and Claude then has to first decide which one to follow.

You can directly copy ready-made rules, such as OpenCode's 4 rules: validate external data only once at the entry point, and don't extract logic used only once into a function early.

Adding an on-demand search rule is also effective: don't write unfamiliar features from scratch. First search open-source projects on GitHub to compare approaches before starting. The author says coding became smoother.

When a team uses multiple agents at the same time, note that Claude Code currently mainly reads CLAUDE.md, not AGENTS.md, so the two sets of rules need to be kept in sync.