Enji GuardCLAUDE.md best practices: what it is and how to write one
CLAUDE.md is the instructions file Claude Code reads before it works in your repo. This is a practical guide to what belongs in it, how to structure it, and how to keep it true as the code changes.
1 repo · setup in about 5 minutes · no card, no commitment
01
What is CLAUDE.md?
CLAUDE.md is a Markdown file in your repository that gives Claude Code the context it needs to work safely: how to build and test, conventions to follow, boundaries to respect, and where the important pieces live. Without it, the agent works from whatever it can infer and fills the gaps by guessing.
02
What to put in it
Keep it short, specific, and verifiable:
- How to install, build, run, and test the project
- Conventions: structure, naming, and patterns to match
- What not to do, files to leave alone, commands to avoid
- Security and review rules: no secrets, no auto-merge, human review required
- Where domain logic lives and how the main pieces fit together
03
Best practices that keep it useful
Write it like onboarding notes for a new engineer. Be concise so Claude Code does not burn its context budget reading rules instead of doing the task; prefer concrete commands over vague guidance; put narrow rules close to the code they govern; and link rather than duplicate. If you also use Cursor or other agents, keep CLAUDE.md, AGENTS.md, and .cursorrules consistent so they do not contradict each other.
04
Common mistakes
The big one is drift: a CLAUDE.md written on day one stops matching the code by month two, and Claude Code keeps trusting rules that are no longer true. Watch for bloat (so much context the agent never reaches the task), conflicts with other rules files, and secrets accidentally pasted into the file.
05
Keep CLAUDE.md honest with Guard
The hard part is keeping it accurate. Enji Guard audits CLAUDE.md, AGENTS.md, and Cursor rules against the real repo on a schedule, flags drift, and can open a pull request that updates them to match the code.
Quick questions
Is CLAUDE.md the same as AGENTS.md?
They do the same job, instructions for a coding agent, but CLAUDE.md targets Claude Code specifically, while AGENTS.md is a tool-agnostic convention. Many repos keep both, which is exactly why they can drift out of sync.
How do I stop CLAUDE.md from going stale?
Treat it like code: review it when the project changes, and audit it on a schedule. Guard can do the second part automatically, flagging where your rules no longer match the repo.
Keep your CLAUDE.md true to the code.
Connect a repo and Guard audits your agent rules against the real codebase. No card.