Letting Claude read my repo before it writes

Most of the friction with coding agents is not the model. It is that the model starts every task blind to the things everyone on the team already knows. A short CLAUDE.md at the repo root fixes most of it.

What goes in it

Keep it to the things you would tell a new contributor on their first day, and nothing they can infer from the code:

• The commands that actually run the project and the tests.
• Conventions that are not obvious from a single file — branching, commit style, where shared code lives.
• The two or three traps that have bitten people before.

What to leave out

Do not restate the framework docs or describe the folder structure the agent can see for itself. Every line it does not need is a line diluting the ones it does.

Rule of thumb: if grepping the repo would answer it, leave it out. If only a person could tell you, write it down.

Why it pays off

One good CLAUDE.md is worth about ten prompts of pasted context, and it never goes stale in a chat window. The agent reads the repo the way you wish every reviewer would — before touching anything.