CLAUDE.md is the file Claude Code reads automatically at the start of every session in a project. Think of it as onboarding notes for an AI teammate instead of a human one. Anything you'd tell a new hire before their first PR belongs here: what the project does, how to run it, where the load-bearing code lives, and the mistakes people (or agents) keep making.
Why bother
Without it, an agent re-derives your stack, your conventions, and your build commands from scratch every session. That costs time, and it sometimes guesses wrong. With it, that context loads once, up front, and stays consistent across every conversation and every teammate who also has Claude Code.
What makes a good one
A minimal CLAUDE.md has six sections, no filler:
- Project Overview: the one paragraph an agent should never have to re-derive
- Commands: the exact install/dev/test/build commands, copy-pasteable
- Implementation Principles: the decision order for whether new code should even be written (YAGNI, reuse before rewrite, standard library before custom code)
- Architecture: the load-bearing structure, not a full file tree
- Coding Standards: the rules a linter can't catch
- What NOT to do: the project's actual, specific failure modes, not generic advice
Keep it short and specific. A CLAUDE.md that repeats what a linter or package.json already enforces adds noise, not signal. The parts worth writing down are the ones nobody could guess from reading the code alone.
How to get it
A minimal template is maintained in Agentry Labs. Copy it into your project root and customize the sections:
curl -sSL https://raw.githubusercontent.com/ersanyamarya/agentry-labs/main/scripts/install.sh | bash -s -- claude-md-files/BASIC_CLAUDE.mdThis installs the template under .claude/skills/ in your project so it's available for any new Claude Code session: