Question 1

What distinguishes a good CLAUDE.md from a bad one?

Accepted Answer

Offer one criterion: every line should close a recurring question. A good file: Is short (under 200 lines), concrete, checkable. "2-space indent" is good; "write tidy code" is meaningless. Records what the agent can't find on its own: why something is the way it is, what the pitfall is, which command to run. Is free of contradictions. When two rules clash the model picks one arbitrarily. A bad file: Repeats the directory tree and the dependency list — the agent sees those anyway. Contains a general Android tutorial. Holds multi-step procedures — those belong in skills, because a skill loads only when needed. End with an operational rule: if you type the same correction a second time, it belongs in CLAUDE.md.

Question 2

A monorepo has several teams, each with its own rules. How would you organise CLAUDE.md?

Accepted Answer

Build on hierarchy and narrow loading: 1. At the repo root — only what applies to everyone: the build system, shared conventions, prohibitions. Keep it short. 2. Inside each module/folder — a CLAUDE.md for that team. These load only when the agent works with files in that folder, so other teams' context doesn't land in yours. 3. .claude/rules/ — cross-cutting topics (testing, security) scoped narrowly with paths:. Add that the main risk is contradiction: the root file says one thing, the module file another. So keep the root file small and principled — detail belongs lower down. If other teams' files get in your way, they can be excluded through configuration.

Question 3

How do you resolve the complaint "the agent isn't following the rule in CLAUDE.md"?

Accepted Answer

Work through it in order of likelihood: 1. Is the file loading? Check with /context. A file in the wrong place never loads. 2. Is the rule concrete? "Keep the code clean" isn't checkable. "Don't add new XML layouts" is. 3. Is there a contradiction? Another CLAUDE.md or rules file may say the opposite. 4. Is the file too long? A specific rule gets lost in 800 lines. Then make the key point: CLAUDE.md is context, not configuration — guidance, not enforcement. If a rule really must hold, move it to the technical layer: permissions.deny for blocking. A hook to run format/lint after a file edit. CI as a mandatory gate on the PR.

PUT in CLAUDE.md	DON'T put in CLAUDE.md
Build and test commands (exact, at module level)	A listing of the directory tree — the agent can see it
Conventions: naming, package structure, DI rules	The dependency list — it is in `libs.versions.toml`
Pitfalls: "X doesn't work in this module because…"	General Kotlin/Android tutorials
Prohibitions: "don't touch this folder", "don't use this library"	Multi-step procedures — those belong in a skill
Architectural decisions and their rationale	Anything derivable from git history

CLAUDE.md and context engineering

📚 Sources and documentation