CLAUDE.md Best Practices: How to Properly Configure Claude

In brief:

• CLAUDE.md is a markdown file that Claude Code automatically loads at the start of each session. It's not executed as a config but inserted into the context as text, making it a suggestion to the model rather than a strict rule.
• The main technical pitfall: splitting the file into @imports to save context. Imports are loaded entirely at once. Only path-scoped rules in .claude/rules/ truly save context.
• A good size guideline is up to 200 lines for a project's CLAUDE.md. This isn't a hard limit; the density of useful instructions is more important than the line count.
• Since version 2.1.277, Claude Code also reads AGENTS.md, but by default, only when CLAUDE.md is absent in the project. Cursor has its own .cursor/rules/ system.
• When CLAUDE.md becomes insufficient — rules, skills, hooks, and permissions: what goes where.
• The article includes a working example for Spring Boot, common mistakes, and a simple way to check if a file actually affects the outcome.

Contents

• What is CLAUDE.md and why is it needed
• How Claude uses CLAUDE.md
• How Claude Code technically loads CLAUDE.md: imports vs rules vs compaction
• What must be in CLAUDE.md
• What should never be written in CLAUDE.md
• Optimal CLAUDE.md structure
• Best practices for writing CLAUDE.md
• CLAUDE.md vs rules vs skills vs hooks: what goes where
• Good CLAUDE.md example
• Bad CLAUDE.md example
• CLAUDE.md for Spring Boot
• CLAUDE.md for a monorepo
• CLAUDE.md for microservices
• CLAUDE.md vs AGENTS.md
• CLAUDE.md vs Cursor Rules
• CLAUDE.md vs Codex Instructions
• Common developer mistakes
• FAQ
• Conclusion

What is CLAUDE.md and why is it needed

CLAUDE.md is a regular markdown file that Claude Code automatically loads at the start of each session, giving the model what can be called persistent memory about the project: commands, architecture, conventions — everything the model cannot infer from the code itself (official Claude Code documentation). I'd phrase the file's purpose as simply as possible: CLAUDE.md doesn't make Claude smarter — it makes Claude stop forgetting.

This is not hyperbole. I personally encountered a situation where I had to repeat the same architectural pattern remark every session for a week. As soon as this line moved to CLAUDE.md, the need to repeat disappeared (a similar experience is described in maketocreate.com's analysis using a Laravel project with the "repository instead of Eloquent in controllers" pattern).

Difference from README.md: README is written for people opening a repository for the first time — it's the project's showcase. CLAUDE.md is written for the model, which already "knows" what typical code looks like and only needs what distinguishes your specific project from default assumptions.

Difference from AGENTS.md: AGENTS.md is an open, cross-tool standard read by Codex, Cursor, Copilot, Gemini CLI, OpenCode, and others. Claude Code, since version 2.1.277, also reads it, but by default, only as a fallback when CLAUDE.md is absent in the project. Details and modes are in the comparison section.

Difference from Cursor Rules: Cursor Rules is a format specific to Cursor (.cursor/rules/*.mdc), with its own YAML frontmatter system and activation modes. It's a parallel system, incompatible with CLAUDE.md: putting CLAUDE.md in a Cursor project will simply be ignored by Cursor.

How Claude uses CLAUDE.md

Claude Code searches for CLAUDE.md hierarchically by directory, and its behavior depends on the level:

• Global (~/.claude/CLAUDE.md) — personal settings for all projects on your machine.
• Project root (./CLAUDE.md or ./.claude/CLAUDE.md) — the main file, committed to git, and works for the entire team.
• Local (./CLAUDE.local.md) — your personal notes for this project (local URL, test accounts). Add it to .gitignore.
• Nested CLAUDE.md in subdirectories — only loaded when Claude reads files from that subdirectory. A monorepo with 50 modules doesn't bloat the context with what's not needed right now.
• Managed policy — a file that an administrator rolls out to all organization machines. Not relevant for solo developers, but important for companies to know this level exists.

Separate from these files is auto memory — notes that Claude keeps itself in ~/.claude/projects/<project>/memory/MEMORY.md. The first 200 lines or 25 KB are loaded at startup. You can view and edit them via /memory. You write CLAUDE.md, Claude writes MEMORY.md.

All found files go into the context together. When instructions conflict, the more specific one usually wins (project overrides global), but this isn't guaranteed: the model sees both versions. Therefore, the rule is simple: avoid contradictions, and explicitly mark exceptions at the lower level.

How Claude Code technically loads CLAUDE.md: imports vs rules vs compaction

Almost all guides say "keep the file short" but don't explain which shortening techniques actually work and which only seem to. The difference lies in the loading mechanism.

@imports are loaded immediately and entirely. Split a 500-line CLAUDE.md into five 100-line imports — you get more manageable files, but the same amount of context. An import is expanded at the start of the session as if the content were inserted directly. Nesting is up to 5 levels deep. Inside `code` and code blocks, `@path` is not processed, so you can mention a path without importing the file.

Rules in .claude/rules/*.md behave differently:

⚠️ Personal rules in ~/.claude/rules/ with paths: didn't work for a long time (issue #21858, closed in March 2026), and later reports indicate the problem recurs. Path-scoped rules work reliably at the project level. After changes, verify via /memory that the file was indeed loaded.

What survives /compact:

Practical takeaway: an instruction given only in chat might disappear after compaction. If a rule is important, it belongs in a file.

HTML comments don't cost context. Block comments <!-- ... --> are removed before loading. Useful for notes to colleagues: "why this rule is here."

Built-in trimming. Since v2.1.206, the /doctor command (alias /checkup) analyzes the committed CLAUDE.md and suggests removing things the model can infer from the code: folder structure, dependency list, general overview. It leaves pitfalls, justifications for decisions, and non-standard conventions. It also finds duplicates between CLAUDE.md and CLAUDE.local.md and suggests moving some instructions to skills or nested CLAUDE.mds. The criterion "can this be inferred from the code?" is the best test for any line.

What must be in CLAUDE.md

The same criterion applies: only what the model cannot confidently infer from the code. Here are categories where it most often guesses wrong without explicit instruction:

• Stack and versions — especially during transition periods (part of modules on Java 17, part on 21). Otherwise, the model will use APIs from a newer version, and the build will fail.
• Architecture — where new code should go. Without this, business logic regularly ends up in the controller: it works, but breaks layers.
• Non-standard naming conventions — e.g., the suffix Dto instead of Request/Response. The model knows default Java conventions, but not your team's agreements.
• Build commands — literally ./gradlew build, not "build the project." Otherwise, you'll get mvn install in a Gradle project.
• Testing — framework, run command, when to write tests. This determines whether the model checks its work before saying "done."
• Restrictions — what not to touch without permission (e.g., already applied migrations). Important: a textual prohibition is a request, not a lock. For critical items, use permissions and hooks (see below).
• Definition of Done — tests passed, linter clean, documentation updated. Without this, "code written" and "task completed" are different things.

What should never be written in CLAUDE.md

Behind each point is a specific mechanism of harm, not just a matter of taste:

• Secrets, keys, passwords. CLAUDE.md is committed to git and included in the context of every session. Keys belong in environment variables or a secret manager, and access to .env should be restricted via permissions.
• Large code snippets. An embedded example becomes outdated faster than a description. After refactoring, the model will rely on the old example instead of the actual code. Refer to the file.
• API documentation. An outdated copy is worse than no documentation: the model will confidently suggest an endpoint that no longer exists. This results not in a compilation error, but a silent logical error.
• Copying README. READMEs are updated at releases because people look at them. The copy in CLAUDE.md is forgotten, and the files diverge.
• Changelog and decision history. "Previously Redux, now Zustand" — the model doesn't distinguish history from current rules; it reads everything as equally important.
• One-off instructions. "Update dependency X" is a task for the chat. Forgotten in the file, it will cause the model to repeat or re-check already completed actions.
• Obvious things. "Write clean code," "add comments" — the model does this anyway. Such lines only dilute those that truly affect the outcome.

Optimal CLAUDE.md structure

Based on what I've seen in production files and community recommendations, the optimal structure looks like this:

1. Project overview
2. Architecture
3. Coding conventions
4. Directory structure
5. Commands
6. Testing
7. Security
8. Definition of Done
9. Agent behaviour
10. Useful references

The order here is not accidental: first, the context in which the model should understand what the project is about (overview, architecture), then the rules for writing code (conventions, structure), then how to verify its own work (commands, testing, security, DoD), and finally, behavioral instructions and references to additional materials.

Best practices for writing CLAUDE.md

Keep the file concise. A practical guideline from Anthropic is up to 200 lines per CLAUDE.md, and a few dozen for a personal ~/.claude/CLAUDE.md. This isn't a hard limit: every line consumes context in every session, and the longer the file, the less consistently Claude executes it. Density is more important than length.

Write unambiguously. "Use named exports, not default" is better than "try to use named exports."

Avoid contradictions. An exception for a module should be in its nested CLAUDE.md or a rule with paths:, not a second rule right next to the first.

Separate levels. Personal preferences go in ~/.claude/CLAUDE.md, project-specific personal notes in CLAUDE.local.md, and team conventions in the project's CLAUDE.md under git.

Maintain only the current state. No history, no outdated commands. A file that hasn't been edited for three months on a live project is almost certainly lying.

Refer, don't copy. A single line with a reference lasts longer than a copied paragraph.

Add a rule after a repeated mistake. Don't try to anticipate everything. The model put logic in the controller twice — that's a candidate for CLAUDE.md. A hypothetical problem is not.

The main test: can this be inferred from the code? If yes, delete it. /doctor uses this same logic; apply it before the file grows to 300 lines.

How to verify that CLAUDE.md is actually working

1. Take 3–5 typical project tasks (new endpoint, bug fix, test).
2. Complete them with CLAUDE.md and without it (temporarily rename the file).
3. Compare how many manual edits were needed and whether the architecture and conventions were followed.
4. Rules that didn't change the outcome are for deletion.
5. Periodically run /doctor prompt-audit — it finds contradictions between instruction files.

💡 This is not overkill. A study by ETH Zurich (138 repositories, 5,694 PRs) showed that instruction files written like READMEs slightly worsen agent performance and increase token usage. A long file does not equal a useful file.

CLAUDE.md vs rules vs skills vs hooks: what goes where

When CLAUDE.md grows, the problem usually isn't that it's long. It simply contains things that belong in other mechanisms:

Key difference: CLAUDE.md, rules, and skills are text that the model *can* violate. Hooks and permissions are deterministic: they trigger regardless of what the model "decided." Therefore, the rule "never push to main" in CLAUDE.md is a suggestion, while deny in permissions is a guarantee:

// .claude/settings.json
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(git push:*)"
    ]
  }
}

A simple rule for choosing: if violating the instruction is an inconvenience, write it in CLAUDE.md. If violating it is an incident, use permissions or a hook.

Good CLAUDE.md Example

# Project overview
Backend API for a room booking system. Spring Boot 4, Java 21, PostgreSQL 17.

# Architecture
Layered architecture: controller → service → repository.
Entities do not leave the service layer; only DTOs go outside.
Business logic is exclusively in the service layer; controllers are thin.

# Coding conventions
- Constructor injection (@RequiredArgsConstructor), no field injection with @Autowired
- Exceptions are custom unchecked exceptions, inheriting from ApiException
- DTOs are records only
- Dates are java.time only, never java.util.Date
- JSON is handled by Jackson 3 (tools.jackson package), not com.fasterxml.jackson

# Commands
Build: ./gradlew build
Unit tests: ./gradlew test
Integration tests: ./gradlew integrationTest (requires Docker for Testcontainers)
Local run: ./gradlew bootRun --args='--spring.profiles.active=local'

# Testing
JUnit 5 + Mockito for unit tests, Testcontainers + PostgreSQL for integration tests.
Each new service method with business logic requires at least one unit test.
Do not mock what can be tested with Testcontainers.

# Security
Never log passwords, tokens, or customer personal data.
Endpoints /admin/** are accessible only to users with the ADMIN role via @PreAuthorize.

# Definition of Done
- ./gradlew build completes without new warnings from Checkstyle
- Public DTOs have Javadoc

# Agent behaviour
Before a major refactoring, create a plan first, without modifying files.
Do not delete existing tests without explicit permission.

# References
Architectural decisions: docs/adr/
Domain model: docs/domain-model.md

<!-- Rules for migrations are in .claude/rules/migrations.md -->

There's no code, README copies, or changelog here—only what the model wouldn't infer on its own. Pay attention to two things. The "Directory structure" section is absent: Claude can infer the standard Spring project structure from the code, and these are the types of /doctor blocks it suggests removing first. The line about Jackson 3 is an example of a perfect instruction: in Spring Boot 4, the package changed, and without a hint, the model would habitually import the old com.fasterxml.

Bad CLAUDE.md Example

# About the project
This is our great project, which we started developing in 2023.
Initially, we used Spring Boot 2, then we moved to 3.
In February 2025, we rewrote the payment module (see PR #482).
In April, we added Kafka, and in June, we removed it because it didn't work out.

# Code style
Write clean, readable code. Follow best practices.
Comments should be meaningful.

# Controller example
```java
@RestController
@RequestMapping("/api/v1/bookings")
public class BookingController {
    // ... 150 lines of controller implementation ...
}
```

# API documentation
GET /api/v1/bookings — returns a list of bookings
  Parameters: page, size, sort
  Response: { "content": [...], "totalElements": 42, ... }
[... 40 more endpoints with full field descriptions ...]

# Changelog
- v1.2.0: added filtering by date
- v1.1.0: fixed bug with timezones
- v1.0.0: first release

This is a collection of anti-patterns: history instead of current state, vague advice like "write clean code," embedded code instead of a reference, a copy of API documentation that will diverge from the code within the first sprint, and a changelog that doesn't influence any decisions. Such a file consumes session context and offers almost no value. Compare: "write clean code" → zero effect; "entities do not leave the service layer" → specific behavior that's easy to verify.

CLAUDE.md for Spring Boot

For Java/Spring projects, it's worth specifically documenting what's unique to the ecosystem:

• Maven or Gradle—and the exact commands for your specific choice, not both "just in case."
• Spring Boot version and key starters. This is especially important now: free support for Boot 3.5 ended in June 2026, and many projects are in the process of migrating to Boot 4 (Jackson 3, Spring Framework 7). The model needs to know which version you are *currently* on.
• Spring AI—the version (1.x and 2.x differ significantly; 2.0 requires Boot 4) and the default provider in the dev profile (Ollama, OpenAI, Anthropic).
• Docker—the command to bring up infrastructure (docker compose up -d), not just "we use Docker."
• PostgreSQL—the version and specific types (jsonb, arrays, pgvector) that don't have a direct equivalent in other databases.
• Flyway—migration numbering and the prohibition of editing applied migrations.
• Testcontainers—which containers are used, so Claude doesn't suggest mocking things that are tested against a real database.

Migration rules are an ideal candidate for a path-scoped rule: they are only needed when Claude interacts with the migrations folder.

# .claude/rules/migrations.md
---
paths:
  - "src/main/resources/db/migration/**"
---
- New migration means a new file V{N}__short_description.sql, N = last number + 1
- Never edit existing migrations—they have been applied to production
- To change the schema, create a new migration with ALTER, do not edit the old one

And if an error here could cost an incident, add a prohibition on editing via permissions (see where to put what).

CLAUDE.md for Monorepos

For monorepos (frontend/, backend/, shared/), the mechanism of nested CLAUDE.md files works: the root file contains shared information (conventions, CI commands), and each subdirectory contains only its specific details. A nested file *supplements* the root file, not replaces it, so don't duplicate what's already present above.

Two practical tips:

• Rules tied to file types rather than folders (e.g., all *.test.ts in any package) are more conveniently kept as rules with paths: than scattered across nested CLAUDE.md files.
• In large monorepos, CLAUDE.md files from other teams might be pulled in, which you don't need. These can be excluded by configuring claudeMdExcludes in .claude/settings.local.json.

CLAUDE.md for Microservices

Here, the task is different: each service lives in its own repository, and the issue isn't nesting but how to synchronize common conventions across repositories.

For 3–5 services, I'd opt for duplication: a few lines are cheaper than infrastructure. When there are more than a dozen services or conventions change frequently—use a plugin. Importing from the home directory is an intermediate option for personal rules, but not for team-wide ones.

CLAUDE.md vs AGENTS.md

For a long time, Claude Code was an exception and only read CLAUDE.md. Since version 2.1.277 (September 18, 2026), it also reads AGENTS.md, but by default, only as a fallback.

⚠️ Important: If a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md file exists in the working directory or any parent directory, Claude Code will ignore AGENTS.md by default. No error will occur—the file simply won't be included in the context.

Four "Project instructions" modes

The mode is switched via the /config command → Project instructions:

💡 This setting is personal: Claude Code ignores it in project settings, so you can't commit it. To ensure the whole team gets the same instructions, use import.

Recommended approach for a team

Common rules go into AGENTS.md. In CLAUDE.md, the first line is an import, followed only by Claude-specifics:

# CLAUDE.md
@AGENTS.md

## Only for Claude Code
- Use plan mode for changes in src/billing/
- Run ./gradlew build before committing

The @AGENTS.md line is committed with the repository and works for everyone, regardless of their personal mode. If someone enables claude-md-and-agents-md, AGENTS.md won't be duplicated.

How to check what was loaded

• /memory—shows loaded files (AGENTS.md is visible there starting from version 2.1.280).
• /doctor prompt-audit—finds contradictions between CLAUDE.md and AGENTS.md.
• If the Project instructions option is missing from /config, AGENTS.md support is unavailable for this session (old version, first session after an update, or the built-in agents-md plugin is disabled). In that case, use the @AGENTS.md import.

CLAUDE.md vs Cursor Rules

Cursor's activation system is more flexible out-of-the-box: the "Apply Intelligently" mode, where the agent itself decides based on the description whether a rule is needed, is conceptually closest to skills in Claude Code, rather than rules. The old .cursorrules file is deprecated; in new projects, use only .cursor/rules/.

⚠️ If a large CLAUDE.md file is present in a Cursor project, Cursor loads it entirely into every chat. For mixed teams, this is another argument for keeping CLAUDE.md concise and putting shared information in AGENTS.md.

CLAUDE.md vs Codex Instructions

There isn't a separate "Codex Instructions" format: the Codex CLI reads the same AGENTS.md. The differences lie in the mechanics:

• Global instructions—in ~/.codex/AGENTS.md (analogous to ~/.claude/CLAUDE.md).
• AGENTS.override.md—if placed next to AGENTS.md, Codex reads only the override file. This is convenient for temporary local changes but is also a frequent reason why edits to AGENTS.md "don't work."
• Order—Codex concatenates files from the root down to the current directory, with files closer to the work being loaded last.

The practical takeaway has changed: previously, you had to maintain two separate files for Claude Code and Codex. Now, AGENTS.md as a single source of truth and a short CLAUDE.md with @AGENTS.md plus Claude-specifics is sufficient (see above). To verify in Codex, the simplest method is to add a unique marker to AGENTS.md and ask the agent to repeat it.

Common Developer Mistakes

Each point represents a specific chain of "cause → effect," not an abstract "bad practice."

• 1000-Line File. An attempt to describe the project exhaustively instead of providing only what the model won't infer. Every line consumes context in every session, and the important Definition of Done rule gets lost among a hundred obvious statements. The model doesn't ignore it intentionally—it's just that the longer the file, the less consistently it's followed.
• Contradictory Instructions. Most often between a global and a project file. The model sees both versions simultaneously and usually picks the more specific one, but this isn't guaranteed: behavior can "float" from session to session. It seems like Claude "forgets" settings, when in reality, it's been given two mutually exclusive instructions. Fix this with /doctor prompt-audit and explicit exclusion at a lower level.
• Outdated Commands. Switched from npm to pnpm or changed CI, but didn't update the file. The model will execute what's written, get "command not found," and spend a step figuring it out—in every session, until someone fixes one line.
• Lack of Architecture. Without a description of layers, the model takes the simplest working path: the code will run, but the business logic will end up in the controller, requiring refactoring during review.
• Mixing Documentation and Instructions. A CLAUDE.md that tries to be a README, API reference, and instructions simultaneously performs all three roles poorly: documentation changes at a different rate and diverges from reality.
• Both CLAUDE.md and AGENTS.md — and expecting both to work. By default, Claude Code only reads CLAUDE.md and silently skips AGENTS.md. Half of the team's rules simply don't reach the model. The solution: put @AGENTS.md as the first line of CLAUDE.md (see comparison section).
• Prohibitions Only in Text. "Never push to main" in CLAUDE.md is a suggestion the model might ignore. For critical items, use permissions.deny or a hook (see what goes where).
• Important Rules Only in Chat. After /compact, the history is compressed, and what was said in conversation might disappear. If you repeat the same thing twice, it belongs in a file.
• Personal path-scoped rules in ~/.claude/rules/. Rules with paths: at the profile level failed to load for a long time (GitHub issue #21858, closed in March 2026), and later reports indicate the issue recurs. This looks exactly like an error in your glob pattern—you could spend hours searching in the wrong place. Keep path-scoped rules at the project level and verify them using /memory.
• Headings from imported files are not demoted. If the main file has # Code conventions, and an imported file starts with its own # Heading, the model will see them as sibling headings of the same level, not a subsection. The nesting you see in your editor isn't passed to the model—monitor heading levels manually (HackerNoon).
• Glob without quotes in YAML frontmatter. Patterns starting with * or { must be quoted—this is a YAML syntax requirement, not a Claude Code one. Without quotes, the frontmatter won't parse, and the entire rules file might fail to load, not just a single rule.

FAQ

Can I have multiple CLAUDE.md files?

Yes, and for any project larger than a single service, it's standard. I typically use three levels: global with personal settings, project-specific under git for the team, and several nested within modules. They complement each other; the key is to avoid contradictions between them.

Where is the best place to store the file?

Project CLAUDE.md goes in the repository root (or .claude/CLAUDE.md) under git. Personal settings for all projects go in ~/.claude/CLAUDE.md. Personal settings for a specific project (local URLs, test accounts) go in CLAUDE.local.md, added to .gitignore.

What's the optimal size?

Anthropic's practical guideline is up to 200 lines per file; for my personal global file, I keep it to a few dozen. This isn't a hard limit: every line consumes context in every session, and the longer the file, the less consistently Claude executes it. The density of useful instructions is more important than the line count.

Can I use Markdown?

Yes, it's the native format. Headings and lists group related instructions and make file reviews easier. Block HTML comments <!-- --> are stripped before loading—they're useful for explaining to colleagues why a rule is needed without consuming context.

Does CLAUDE.md work in subdirectories?

Yes. A nested CLAUDE.md isn't loaded at startup but only when Claude reads files from that subdirectory. In a monorepo, frontend instructions don't consume context while Claude is working with the backend.

Do I need to store it in Git?

The project-specific one—absolutely: otherwise, each developer accumulates their own version of instructions, and the file's main value—consistency—is lost. Conversely, CLAUDE.local.md and personal settings go into .gitignore.

How is it different from README?

By audience. README is for a human opening the repository for the first time. CLAUDE.md is for the model, which already knows general patterns and only needs what makes your project different from default assumptions. Combining both roles in one file harms both.

Does Claude Code read AGENTS.md?

Yes, starting with version 2.1.277 (September 2026). By default, only when the project lacks CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md. To load both, add @AGENTS.md as the first line of CLAUDE.md (works for the whole team) or select the claude-md-and-agents-md mode in /config → Project instructions (works only for you).

Does @import really reduce context?

No. Imports are fully expanded at the start of the session—splitting into files makes maintenance easier but doesn't reduce the context size. Only rules in .claude/rules/ with paths: save context.

What happens to CLAUDE.md after /compact?

The root CLAUDE.md, rules without paths:, and auto memory are reloaded. Nested CLAUDE.md and rules with paths: are restored only when Claude reads the relevant files again. Instructions given only in chat may disappear after compaction.

How does CLAUDE.md differ from MEMORY.md?

You write CLAUDE.md—these are instructions. MEMORY.md (auto memory) is maintained by Claude itself—these are its notes from previous sessions; the first 200 lines or 25 KB are loaded at startup. You can view and edit both via /memory.

What's the minimum Claude Code version required for /doctor trimming?

v2.1.206 or newer. On older versions, the command doesn't offer CLAUDE.md truncation. Alias: /checkup.

Conclusion

If I had to distill this article down to one takeaway, it would be this: CLAUDE.md is neither documentation nor configuration, but text that competes for the model's attention with everything else in the context every session. And this is advice to the model, not a guarantee.

Here's what I recommend based on my own experience with Claude Code:

• Start with the minimum. Stack, commands, architecture, a few non-standard conventions—30–50 lines. Don't try to write the perfect file from the start.
• Add a line only after a repeated mistake. Claude did the same thing wrong twice—that's a rule for the file. A hypothetical problem is not.
• Before each new line, ask: can this be inferred from the code? If yes, don't write it. Run /doctor once a month.
• Move narrow concerns to rules with paths:, and procedures to skills. CLAUDE.md should only contain what's needed in every session.
• Secure critical items with permissions and hooks, not text. Access to .env, pushing to main, production—these aren't things to trust to a markdown suggestion.
• If your team uses multiple AI tools, have one source of truth. Shared items in AGENTS.md, Claude-specifics in CLAUDE.md via @AGENTS.md.
• Verify, don't just believe. Run 3–5 typical tasks with and without the file. Rules that made no difference—delete them.