Your CLAUDE.md Should Explain What Done Means
ZarifThe most useful line in a project instruction file may be the least impressive one: run the build before committing.
It does not promise to turn an assistant into a staff engineer. It gives the assistant a specific condition it can check. That is the standard I want from the rest of the file.
This site's own project instructions contain that rule, alongside instructions to preserve existing work, investigate reported problems, and keep editorial links in the right format. Those are concrete constraints from an actual project. They are a better starting point than a universal prompt promising extraordinary productivity.
Editorial correction, September 5, 2026: the earlier version claimed a 10x improvement and specific reductions in bugs, output time, and wasted context. Those measurements were not substantiated in the article. They have been removed, along with unsupported claims about Anthropic's internal workflow. This is a practical guide, not a controlled productivity study.
Start with the decisions you keep repeating
My preference is for an agent to investigate and complete the work I have authorized. A routine implementation question should not become another task for me. But the agent still needs to know the boundary of that authorization and what counts as finished.
For this site, that means understanding the content format, checking the existing implementation, making the change, and verifying the result. A polished explanation of a proposed fix is not the same deliverable.
Write those expectations in terms the agent can act on:
| Vague instruction | More useful instruction |
|---|---|
| Be careful | Preserve unrelated local changes and inspect the diff before committing. |
| Write good content | Substantiate numerical claims; do not invent personal testing or client results. |
| Make it work | Run the relevant validation and report any remaining failure. |
| Remember this | Record the decision in the project notes and link to the source. |
The right instructions depend on the project. A writing workspace needs different checks from a billing service.
Understand what the file can do
Claude Code's documentation distinguishes instructions written in CLAUDE.md from auto-memory notes the agent saves. These mechanisms supply context; they are not an enforcement boundary. A written rule can guide an action without technically preventing a violation. Claude Code memory documentation.
Keep durable project facts in the main instruction file: where things live, how to validate a change, and which constraints apply repeatedly. A long procedure that only matters occasionally can live in a linked document instead. Review saved instructions when the project changes; an obsolete deployment command is worse than a missing one.
A small template to adapt
The following is a suggested adaptation of the working principles in this repository, not a claim that this exact template has been benchmarked.
# Project instructions
## Outcome
Complete the requested change through the relevant verification.
Report the result, the evidence, and anything still unresolved.
## Before editing
Read the current implementation and project instructions.
Preserve unrelated local work.
Use the project's existing conventions.
## Decisions
Proceed with routine choices inside the authorized task.
Ask when a missing decision materially changes the outcome.
Do not assume permission to contact people or publish private data.
## Verification
Use checks appropriate to the change.
For content, verify claims, links, and the production build.
Do not describe a check as passed unless it actually ran and passed.
## Handoff
Record what changed, where it lives, and the next unresolved decision.
Keep durable lessons separate from temporary progress.
The important editing step is replacing the generic verification section with your actual commands and conditions. The file becomes useful when it describes your environment.
Keep progress separate from project knowledge
A record of everything the agent did is difficult to reuse. A short record of what changed and why is more useful.
I would keep three kinds of information distinct:
- Instructions: how work should be performed.
- Current state: what exists, what shipped, and what remains unfinished.
- Lessons: specific corrections worth applying again.
A useful lesson names the mistake and the replacement behavior. “Be more accurate” is not enough. “Do not describe a prototype as deployed; check its release state first” can guide a future task.
Saved notes still need to be found and read. Do not confuse a file existing on disk with every future session automatically receiving it.
Give the agent room to work, then inspect the result
Autonomy works best when the assignment has a finish line. For a content change, that might be an updated article, working links, and a successful build. For a product change, it may include a deployed version and a checked user flow.
The practical question is whether the agent delivered that result. A larger instruction file is not proof that it did.
Related Guides
- Claude Code Features That Matter After the First Demo
- Claude Code vs GitHub Copilot: AI Coding Compared
- Enterprise AI Agent Platforms: How an FDE Should Evaluate the Shortlist
- How to Create AI-Powered SOPs for Your Entire Business
Does CLAUDE.md guarantee that Claude follows every instruction?
No. It supplies context. Enforced permissions and technical controls are separate from prose instructions.
Do I need a large template?
Start with repeated project decisions and real validation commands. Add a rule when it addresses a recurring problem, and remove rules that are obsolete or contradictory.