A good CLAUDE.md is a short, versioned briefing for Claude Code: it records the project facts, commands, conventions and completion checks you would otherwise have to repeat. Put shared rules in the repository, keep personal preferences in your user file, move narrow guidance into .claude/rules/, and verify the result with /context or /memory. Treat the file as context—not as a security control that can guarantee an action is blocked.
What a CLAUDE.md file is—and what it is not
Claude Code reads applicable Markdown memory files when it starts working in a project. Those files give the agent durable background: what the product does, where important code lives, which commands are authoritative, and which conventions a change must follow. The value is practical: instead of correcting the same mistake in every session, you encode the correction once.
As an Amazon Associate I earn from qualifying purchases.
Anthropic’s documentation describes these files as context, not enforced configuration. That distinction matters. A sentence such as “never access production” may guide the model, but it cannot reliably prevent a tool call. If an action must be blocked regardless of Claude’s decision, use an appropriate permission setting or a PreToolUse hook. Keep safety controls outside the Markdown file.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsThe best file is not a complete handbook. It is a compact set of facts and repeatable instructions that Claude cannot infer reliably from the repository or that people repeatedly need to explain.
#1 Best Overall
Choose the right location before writing rules
Claude Code loads applicable files in the directory hierarchy above the working directory at launch. When work reaches a subdirectory, applicable files there can also be loaded. Use that hierarchy to put each instruction where its audience can maintain it.
| Location | Use it for | Source-control guidance |
|---|---|---|
./CLAUDE.md |
Project-wide instructions shared by the team | Usually commit it with the repository |
./.claude/CLAUDE.md |
The same project-wide role, kept with other Claude configuration | Commit when the team should share it |
~/.claude/CLAUDE.md |
Your preferences across projects | Keep in your home configuration, not the repository |
./CLAUDE.local.md |
Personal instructions for one project | Keep it out of source control, normally through .gitignore |
.claude/rules/ |
Modular or path-specific rules for larger projects | Commit shared rules; ignore private ones |
Do not put a team rule in a user-level file: your colleagues will not receive it. Conversely, do not commit an editor preference or a local machine path that only helps one developer. A useful test is ownership: the people who need to update a rule should be able to find it without asking who owns a hidden setting.
Collect facts Claude should not have to guess
Before drafting, list the information you have explained more than once or that is easy to misread from the code. Prioritize facts that change an implementation decision.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11- Project map: one sentence describing the product, followed by the important top-level directories and what each owns.
- Architecture: boundaries between services, packages, clients, generated code and data-access layers; record decisions that are not obvious from filenames.
- Commands: the real build, test, lint, type-check, formatting and development commands, including required working directories.
- Conventions: naming, error handling, logging, dependency choices, API patterns, test placement and formatting rules that the existing code consistently follows.
- Workflow: checks required before a change is complete, migration steps, code-generation steps and review expectations.
- Known traps: commands that are destructive, files that are generated, compatibility constraints and areas where a seemingly small change has wider consequences.
Use repository evidence rather than guesses. If a command varies by package, state the package path and command together. If a value is unknown, leave it out until you can verify it; a confident but false instruction is worse than no instruction.
Start with a compact, project-specific outline
A maintainable starter file can use this shape. Replace every bracketed description with facts from the actual repository; do not copy generic commands that the project does not run.
# Project instructions
## Project map
- [What this product does]
- [Important directories and their responsibilities]
## Commands
- Build: `actual build command`
- Test: `actual test command`
- Lint: `actual lint command`
- Type-check: `actual type-check command`
## Conventions
- [Specific naming and formatting rules]
- [Established architectural patterns]
## Workflow
- [Checks required before a change is complete]
- [Migration, generation or review steps]This is an editorial structure, not a required schema. Claude Code does not need a special frontmatter block for an ordinary project file. Clear Markdown headings and bullets make the rules easier for people to review and for the agent to apply.
Turn vague preferences into executable instructions
Write each rule so a reviewer can answer three questions: what action is required, where does it apply, and how can someone check it? Anthropic’s examples contrast “Use 2-space indentation” with “Format code properly,” and “API handlers live in src/api/handlers/” with “Keep files organized.” The first version of each pair gives Claude a concrete decision.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
State the action and scope
- Prefer “Use 2-space indentation in JavaScript and TypeScript files” to “Format code properly.”
- Prefer “Put HTTP handlers in
src/api/handlers/” to “Keep the API organized.” - Prefer “Add unit tests beside the module under test; use the existing test runner” to “Add tests.”
- Prefer “Run
npm testfrom the repository root before committing” to “Test your changes.”
Include exceptions only when they are real. A long list of hypothetical caveats makes the primary rule harder to notice. If a rule applies to only one area, move it to a path-scoped file instead of weakening a global instruction.
Use the repository’s actual vocabulary
Match package names, directory names, scripts and service names exactly. If the repository uses “controller” for one layer and “handler” for another, preserve that distinction. Mention whether a command is expected to modify files, contact a network service or require an environment variable. The instruction should help Claude choose the next safe step, not merely describe an aspiration.
Separate required checks from helpful suggestions
Mark blocking checks clearly: “Before considering a change complete, run the unit suite and type-check.” Put optional advice under a separate heading. Mixing “must” and “consider” in one undifferentiated list makes priorities ambiguous.
Document commands as a workflow, not a shopping list
Commands are among the highest-value entries because they prevent Claude from inventing scripts. Group them by purpose and include the expected location.
## Commands
Run these from the repository root unless noted otherwise.
- Install dependencies: `...`
- Start development: `...`
- Build production artifacts: `...`
- Run all tests: `...`
- Run one test file: `...`
- Lint: `...`
- Type-check: `...`
## Completion checks
1. Run the focused test for the changed area.
2. Run the full test command.
3. Run lint and type-check.
4. Review generated files and the final diff.Use the exact scripts already defined by the project. If a command is destructive or expensive, say so and identify a safer alternative. For a monorepo, name the package and whether the command should run from the root or a workspace directory. For generated code, state both the generator command and whether generated output belongs in a commit.
Rank #3
Describe architecture and conventions that affect decisions
Claude can inspect source, but a short explanation prevents it from inferring the wrong pattern from an unusual or legacy file. Explain boundaries rather than narrating every directory.
- Identify the canonical layer for business logic, persistence, validation and presentation.
- Say which module owns shared types or schemas.
- Record whether API changes require a migration, a schema update, a client regeneration or a compatibility period.
- State naming and file-placement conventions that are not enforced by tooling.
- Explain the project’s error, logging and observability patterns when consistency matters.
- Call out generated, vendored or read-only directories so Claude does not edit them directly.
Do not copy an entire style guide into CLAUDE.md if the repository already has one. Link or point to the canonical local document by path, then summarize only the decisions Claude must apply routinely. This keeps the always-loaded context focused and prevents two documents from drifting apart.
Use .claude/rules/ for modular and path-specific guidance
Large projects rarely need every rule for every task. Put one topic per file—such as testing.md, api-design.md or database.md—under .claude/rules/. Rules without a paths field load unconditionally. Add YAML frontmatter when a rule should activate only for matching files.
---
paths:
- 'src/api/**/*.ts'
- 'tests/api/**/*.ts'
---
# API rules
- Validate request data at the boundary.
- Keep handlers thin; put business logic in the service layer.
- Update the API tests when response shapes change.Choose path patterns that match the repository’s real layout. A rule that is too broad adds irrelevant context; one that is too narrow silently misses files. Review nested CLAUDE.md files and rule files together so the same topic does not have contradictory instructions in multiple places.
Split files without hiding the context cost
A CLAUDE.md can import another file with @path/to/file syntax. Relative and absolute paths are supported, imports can nest up to five levels, and imports inside Markdown code blocks are not interpreted. Imports are useful when ownership or organization improves—for example, when a testing team maintains a testing guide separately.
Splitting a document does not make its contents free. Imported material still consumes context when it loads. Use imports for maintainability, and use path-scoped rules when guidance is relevant only to particular files. Do not create a maze of tiny files that makes it unclear which rule applies.
# Project instructions
@docs/engineering/testing.md
@docs/engineering/release-workflow.mdAfter adding an import, inspect the loaded context rather than assuming the path was resolved as intended. Keep imported files in locations that new contributors can discover and update.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Keep the always-loaded file short
Anthropic recommends targeting fewer than 200 lines per CLAUDE.md. This is product guidance, not a measured performance threshold. Concise, specific instructions are easier to follow, while a long file consumes context and can reduce adherence.
Trim rules that duplicate tooling, describe obvious code, or apply only to one directory. Move specialized material into path-scoped rules. Replace paragraphs with a precise bullet when the meaning is unchanged. Keep a short explanation for an unusual architectural decision, but remove historical narrative that does not change what Claude should do now.
Do not confuse this recommendation with auto-memory behavior. Anthropic’s documentation says auto memory loads up to its first 200 lines or 25 KB; that is a loading limit for auto memory, not a recommendation that every CLAUDE.md should be that size.
Use /init as a starting point, then edit it
The /init command can analyze a codebase and generate a starting file containing discovered build commands, test instructions and conventions. Treat that output as an inventory, not an authority. It may miss unwritten decisions, include a command that is no longer canonical, or describe a pattern that exists only in one legacy area.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →- Run
/initfrom the project context where you want the file created. - Read every generated line and verify commands, paths and directory names against the repository.
- Delete generic observations that do not help an implementation decision.
- Add the team’s unwritten rules, completion checks and known traps.
- Move area-specific rules into
.claude/rules/when they do not apply globally. - Commit the shared file only after a teammate can understand and maintain it.
A generated file is valuable because it accelerates discovery; it is not guaranteed to be complete or correct.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Verify what Claude Code actually loaded
Use /context to inspect the context available in the session. Use /memory where appropriate to inspect memory-related information. These checks catch wrong locations, malformed imports, overly broad path rules and unexpectedly large files.
- Start Claude Code in the repository root, or in the directory where the work will begin.
- Run
/contextand confirm that the intended project instructions appear. - If you use memory or imports, run
/memoryand inspect the relevant entries. - Ask Claude to identify the command and conventions it will follow for a small, low-risk task.
- Compare its answer with the file and correct ambiguous or missing rules.
Verification is especially important after moving a file or adding a nested rule. A rule that exists on disk but is outside the applicable directory hierarchy is not helping the session you care about.
Understand the limits of instruction files
They guide behavior; they do not enforce permissions
“Claude treats them as context, not enforced configuration,” Anthropic’s documentation states. Do not rely on a sentence in Markdown to prevent a prohibited tool call, bypass a permission prompt or protect a secret. Use the product’s permission mechanisms and a PreToolUse hook when an action must be denied independently of the model.
Recommended Free Tools
They do not replace source-of-truth documentation
Keep detailed API contracts, deployment runbooks and legal or security policies in their canonical documents. Point Claude to those local paths and summarize the decisions it must apply during coding. Otherwise, the same rule will eventually diverge in two places.
They do not make a longer prompt better
Anthropic also says, “The more specific and concise your instructions, the more consistently Claude follows them.” Add a rule after a recurring mistake or correction, then test whether it prevents that mistake. Do not add prose merely because the file looks short.
Maintain the file as the project changes
A CLAUDE.md is part of the project’s developer interface. Review it when scripts, package boundaries or workflows change.
- When a command changes: update the command and its working directory in the same change that updates the build configuration.
- When a directory moves: update path-scoped rules and any examples that name the old path.
- When a correction repeats: add the smallest concrete rule that would have prevented it.
- When rules conflict: remove or relocate one; do not rely on Claude to resolve contradictory copies.
- When a rule becomes automatic: let the formatter, linter, test runner or hook enforce it and shorten the prose.
- During review: check that every command still works and that no private path, token or local preference is committed.
Use version control history to explain why a non-obvious rule exists, but keep the live file focused on what Claude should do now.
Common failure modes and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Claude repeats a known mistake | The rule is vague, buried or absent | Write one concrete action with a path or command, then verify it in /context |
| A project rule works for one developer only | It is in ~/.claude/CLAUDE.md or a local file |
Move the shared instruction to the repository and keep personal details local |
| Unrelated tasks receive irrelevant instructions | A specialized rule loads globally | Move it to .claude/rules/ and add matching paths |
| An imported rule seems ignored | The path is wrong, nested too deeply or placed inside a code block | Use a valid relative or absolute path, stay within five import levels, and verify with /memory or /context |
| The file keeps growing but behavior does not improve | Duplicate, historical or aspirational prose is consuming context | Delete non-actionable text and retain only specific, checkable rules |
| A rule is treated as a security barrier | Context instructions are being mistaken for enforcement | Use permissions or a PreToolUse hook for actions that must be blocked |
A practical review checklist
- Is the file in the location that matches its audience?
- Can a new contributor identify the project’s important directories in under a minute?
- Are build, test, lint and type-check commands real and runnable from the stated directory?
- Does every “must” rule name an action, scope or check?
- Are generated, vendored and sensitive files clearly identified?
- Would a path-specific rule be better than adding another global paragraph?
- Are imports valid, discoverable and no more than five levels deep?
- Is the always-loaded file targeted at fewer than 200 lines?
- Have you checked
/contextand, where relevant,/memoryafter changes? - Are security requirements enforced by permissions or hooks rather than prose?
The simplest reliable pattern
Keep one concise project file for shared facts and completion checks. Add a user-level file only for your cross-project preferences, a gitignored local file for private project details, and path-scoped rules for specialized areas. Write rules as concrete actions using the repository’s real commands and paths. Then inspect the loaded context and prune anything that does not improve a decision.
That pattern gives Claude Code the context it needs without pretending that Markdown can enforce permissions or that more instructions automatically produce better work.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
