CLAUDE.md · Free worked guide
CLAUDE.md Examples for Real Repositories
See practical CLAUDE.md examples for a web app, monorepo, and API, then test whether each instruction improves a real Claude Code task.
By ClaudeQuest · Reviewed · Independent learning material
What does a useful CLAUDE.md look like?
A useful CLAUDE.md contains stable repository facts: where important code lives, verified commands, change boundaries, and the evidence required before handoff. It should not become a diary of one-off tasks or a substitute for permissions.
Decision rule: Keep a rule only when it is stable, specific to this repository, and testable on a second task.
Use it in a real situation
A Next.js repository has separate billing and UI tests. The agent repeatedly runs the full suite even when the billing service is unavailable.
- Name the observable outcome and the constraint that changes the decision.
- Choose the smallest action that can produce useful evidence.
- Keep permissions, uncertainty, and side effects visible before execution.
- Run a check that could disprove the approach, then record what remains unknown.
Original ClaudeQuest worked example
From vague request to reviewable result
Task or input
Add a Verification section naming the focused UI test, the command that needs the billing service, and what must be reported when that service is unavailable.
Better result
Verification: run the focused component test for UI-only changes. Run billing integration tests only when the local billing service is available. Never report billing as verified when that check was skipped.
How to verify it
Give Claude Code a harmless UI task. Confirm it selects the focused test and explicitly preserves the unverified billing risk.
Three mistakes to avoid
Copying without adaptation. Replace repository, data, user, and authority assumptions with facts from your environment.
Treating prose as enforcement. Use permissions, validation, tests, and human approval for boundaries that must hold.
Calling one success proof. Re-test the decision with a different input or context before treating it as a durable skill.
Related CLAUDE.md guides
Source and scope
Primary technical reference: Claude Code memory documentation. Source reviewed September 13, 2026. Product capabilities can change; verify time-sensitive details against the current primary documentation.
The scenario and worked example are original ClaudeQuest learning material. ClaudeQuest is independent of Anthropic and does not guarantee tool performance, certification results, or professional outcomes.
Read the editorial and evidence method →