Free templates · Independent Claude learning
CLAUDE.md Template: Project Instructions You Can Test
A useful CLAUDE.md answers the questions a developer would otherwise repeat: where to look, how to check a change, and when to stop. Start with the small template below, replace every placeholder with repository facts, and remove any rule you cannot explain.
Leave with a project instruction file and a repeatable check—not a promise that an agent will always obey it.
By ClaudeQuest · Updated
Go to the free templates ↓Copy, adapt, and check
No registration is required to read or copy these templates. Replace placeholders and check the result against your own input.
Minimal CLAUDE.md template
Original ClaudeQuest starter. Save as CLAUDE.md or .claude/CLAUDE.md at your repository root. The placeholders are deliberately not runnable commands: discover and verify your actual scripts first.
# Project purpose
[What this repository does and who uses it.]
## Find the right code
- Main implementation: [path and responsibility]
- Relevant tests: [path]
- Architecture notes: [path, if maintained]
## Verification
- Focused test command: [verified command]
- Type/lint check: [verified command]
- Before editing, read nearby code and its tests.
- After editing, run relevant checks and report actual results.
- If a check cannot run, say what is unverified and why.
## Change boundaries
- Preserve unrelated work and existing public behavior.
- Ask before changing dependencies, public interfaces, or database structure.
- Do not deploy or make external changes without explicit authorization.
## Handoff
- Summarize changed behavior and tests performed.
- Name remaining risks and any human decision needed.How to check the result
Ask Claude Code to explain where it would make one small change, without editing. Compare its chosen paths and test command with the repository. Correct one inaccurate instruction before attempting implementation.
A task brief that should stay outside permanent instructions
Use this separately for today's work. Temporary bug details should not become permanent rules for every future task.
Task: [one observable behavior to fix]
Reproduction: [input and steps]
Expected: [observable result]
Observed: [actual result]
Scope: [files or subsystem allowed to change]
Non-goals: [related things we are not changing]
Evidence required: [focused test and review check]
Stop if: [new risk or missing decision]
First, explain the likely investigation steps. Do not edit yet.How to check the result
A good response separates the reported symptom from a proven cause. It names an investigation and verification path without claiming that a fix already works.
What belongs in CLAUDE.md?
Keep stable, shared conventions and verified repository commands in project guidance. Anthropic supports both root CLAUDE.md and .claude/CLAUDE.md; user guidance has a different scope. These files provide model context, not enforced security controls. Permissions, sandboxing, tests, and human approvals must enforce consequential boundaries independently.
Adapt it to a real repository
Suppose a small web application has separate UI and billing tests. A generic instruction to run all tests gives little help when the local billing service is unavailable. Write which checks can run locally and what their limits are. Do not insert an invented npm command simply because another template uses it. If the repository has no test for the changed behavior, record that gap instead of calling the task verified.
A ten-minute instruction audit
Choose a harmless change such as a validation message. First ask for a read-only investigation and record the chosen files. Then compare the proposed checks with existing scripts. Finally inspect whether the response identifies approval boundaries and missing evidence. Repeat on a second, different task. If guidance helps only with the original example, it is probably too specific for the project file.
Keep a correction log, not an expanding rulebook
When a repeated failure appears, record the symptom, the instruction changed, and the next task used to test it. For example: the agent skipped a neighboring test, so the rule now asks it to inspect tests beside the module before proposing an edit. A later task either supplies evidence that the correction helped or exposes a different cause. Remove obsolete path references when files move.
Common mistakes and better alternatives
Weak approach: Be careful and write clean code.
Improve it: Name the existing convention to follow and the check that would reveal a regression.
Weak approach: Run npm test, copied without checking the repository.
Improve it: Replace it with an actual script verified in this project; report missing dependencies separately.
Weak approach: Never deploy, written only in a prompt.
Improve it: Keep the instruction, but also restrict deployment permissions. Text is not an access-control mechanism.
Questions before you start
Is CLAUDE.md the same as auto memory?
No. CLAUDE.md is guidance you maintain; auto memory is knowledge Claude Code may record. Review both for correctness. Neither should be treated as an authorization boundary.
Should I put secrets in the file?
No. Do not include API keys, passwords, customer records, or confidential examples. Describe how authorized configuration is accessed without copying its values.
Do I need a large template?
Start with the facts needed for the next task. Add a rule when a real failure demonstrates a need, then test it. A longer file is not evidence of a better workflow.
Sources and scope
Anthropic Claude Code documentation: How Claude remembers your project. Technical source checked September 7, 2026. Templates and audit examples are original ClaudeQuest learning material.
ClaudeQuest is independent of Anthropic. These templates are not official exam material, certification, or a guarantee of output quality.
How we review learning material