CLAUDE.md is a markdown file that Claude Code automatically loads at the start of each session; it is not executed as a config, but simply inserted into the prompt as text.
The main technical mistake almost everyone makes: breaking the file into @imports, thinking it saves context. In reality, imports are loaded entirely at once — only path-scoped rules in .claude/rules/ truly save context.
Size guideline: up to 200 lines for a project CLAUDE.md, up to 30 lines for a personal ~/.claude/CLAUDE.md — models reliably hold about 150-200 instructions in mind simultaneously, and Claude Code's system prompt already occupies about 50 of them.
CLAUDE.md, AGENTS.md, and Cursor Rules are not interchangeable: Claude Code only reads CLAUDE.md, Cursor reads .cursor/rules/ and AGENTS.md, and AGENTS.md itself as an open standard is currently in over 60,000 repositories.
The article includes a working example of CLAUDE.md for a Spring Boot project, an analysis of common mistakes, and two documented bugs that most guides remain silent about.
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 a persistent memory of the project: commands, architecture, conventions — everything that the model cannot infer from the code itself (official Claude Code documentation). I would formulate the essence of the file 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 for a week I had to repeat the same architectural pattern remark for the project every session — and as soon as this line moved to CLAUDE.md, the need to repeat disappeared (a similar experience is described in the maketocreate.com analysis using a Laravel project with the "repository instead of Eloquent in controllers" pattern as an example).
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 a model that 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-instrument standard read by Codex, Cursor, Copilot, Gemini CLI, and others. Claude Code does not read it natively — only CLAUDE.md (TECHSY, verified on a live repository). More on this in the comparison section below.
Difference from Cursor Rules: Cursor Rules is a format specific to Cursor (.cursor/rules/*.mdc), with its own YAML-frontmatter system and activation modes. This is a parallel system, incompatible with CLAUDE.md: put CLAUDE.md in a Cursor project — and Cursor will simply ignore it.
How Claude uses CLAUDE.md
Claude Code searches for CLAUDE.md files hierarchically and loads them with different behavior depending on the level:
Global (~/.claude/CLAUDE.md) — personal settings that apply to every project on your machine.
Project root (./CLAUDE.md) — the main file committed to git and used by the entire team.
Nested CLAUDE.md in subdirectories — are not loaded immediately, but only when Claude actually accesses files in the corresponding subdirectory. This is an intentional design: a monorepo with 50 subdirectories will not bloat the context with instructions that are not needed right now (Serenities AI).
When instructions from different levels conflict, a simple rule applies: a more specific instruction overrides a more general one. If the organizational policy says "4 spaces for indentation," and the project CLAUDE.md says "2 spaces" — for this project, the project instruction wins (Serenities AI). This rule is worth keeping in mind when deciding at which level to write something — something truly common to all your projects is better placed in the global file immediately, rather than duplicated in each project file.
How Claude Code technically loads CLAUDE.md: imports vs rules vs compaction
This is the section for which I sat down to write this article at all — because almost all the guides I reviewed before writing give the advice "keep the file short," but none explain properly why some context reduction techniques work, and others only seem to work.
@imports are loaded eagerly. If you break down a 500-line CLAUDE.md into five 100-line imports, you'll get a more maintainable set of files — but the context actually loaded into the model will remain the same 500-line volume. An import is expanded entirely at the start of the session, as if you pasted the file content directly (Claude Certification Guide). This is a trap I almost fell into myself: it seemed logical that breaking into files would reduce the load, but in reality, it only reduces the chaos in your editor.
`.claude/rules/*.md` with `paths:` frontmatter are loaded on-demand. Unlike imports, rule files in .claude/rules/ are loaded only when Claude is actually working with a file that matches the specified glob pattern. This is the only mechanism in this system that truly, not conditionally, reduces context (official documentation). If your goal is to reduce context volume, not just organize files, you need rules, not imports.
Session compaction. The root CLAUDE.md survives /compact — after compressing the conversation history, Claude re-reads it from disk and re-injects it into the session. However, nested CLAUDE.md and path-scoped rules do not automatically return after compaction — they are reloaded only when Claude next accesses the corresponding subdirectory or file (official documentation).
Built-in trimming. Starting with Claude Code v2.1.206, there is a /doctor command that analyzes your committed CLAUDE.md and suggests what to remove: anything the model can infer directly from the code (folder structure, dependency list, architecture overview) — to be removed; pitfalls, justifications for decisions, and non-standard conventions that the code itself doesn't show — to be kept (official documentation). I consider this criterion — "can it be inferred from the code" — the best practical test for any line in your file, and I will return to it later in the best practices section.
What must be in CLAUDE.md
I approach this list not as an arbitrary set of categories, but through one criterion I've already mentioned: only what the model cannot reliably infer from the code itself goes here. If the architecture can be understood 90% by just opening three files — it's not worth describing. But there are categories where without an explicit instruction, the model almost always guesses incorrectly or spends steps clarifying — and these are what make up this list from my practical experience.
Technology stack — language, framework, versions, which are not always unambiguously visible from package.json or pom.xml. This is especially true for transition periods: if the project is partly on Java 17, partly already on 21, or uses Spring Boot 3.x with separate modules on an older version — the model won't guess this, and an incorrectly applied API from a newer version will lead to a compilation error that will have to be fixed manually.
Architecture — how the application layers are organized, where new code should go. Without this point, I regularly saw the model put business logic directly into the controller because it's the easiest working path — technically the code works, but it breaks the layered structure adopted in the project.
Naming conventions — conventions that differ from the defaults for the language or framework. The model will default to generally accepted Java or Spring standards; if your team has its own deviation (e.g., a Dto suffix instead of Request/Response), you need to state it directly — it won't guess this agreement on its own.
Build commands — your project's actual commands (make build, ./gradlew build), not general assumptions. Without this, the model often suggests a generic command like mvn install, even if your project has been on Gradle for a long time — and you waste time on a trivial fix.
Testing — which framework, how to run, whether to write tests before or after a feature. This is the point that most affects whether the model checks its own work before saying "done," or just submits code on faith.
Restrictions — directories or files that Claude should not touch without explicit permission. I would highlight this separately as the only item on the list that works not for code quality, but for security: without an explicit prohibition, the model might change a migration file that has already been applied in production, simply because it's technically the "easiest" solution to the task.
Definition of Done — when a task is considered complete: tests passed, linter clean, documentation updated. Without this point, the line between "code written" and "task completed" becomes blurred, and this is where the expectation gap most often arises between what the model produced and what was actually needed to be delivered.
What should never be written in CLAUDE.md
This, in my opinion, is the most important section of the entire article — and precisely where most competitors limit themselves to general words. I will deliberately explain not just "what not to write," but what specifically breaks when you do write it — because "unnecessary" sounds like a matter of taste, but in reality, each point has a specific mechanism of harm.
Large code snippets. CLAUDE.md is not a place for implementation examples; refer to a specific file, don't paste content. The problem is not just the volume: pasted code becomes outdated faster than a text description. An architecture description "the service does not directly access the repository of another module" remains true after a year. A pasted code example that has long been refactored will actively mislead the model — it will focus on the example, not on how the code actually looks today.
API documentation. It changes more often than CLAUDE.md and quickly becomes outdated; a link to the real documentation lives longer than a copy. The problem here is worse than just "outdated" — an outdated copy of API documentation in CLAUDE.md is actively harmful because the model trusts it as much as the rest of the file. It will confidently suggest an endpoint that no longer exists, or a field that was renamed two sprints ago, and you will get not a compilation error, but a silent logical error that is easy to miss during review.
README. Duplicating README in CLAUDE.md means double maintenance of the same content — sooner or later they will diverge. I've seen firsthand how a team updates README with each release because new developers look at it, but forgets the copy in CLAUDE.md — simply because it's a file that is opened less often by eyes, although read more often by the model.
Changelog. Change history does not affect how to write new code today — it's ballast that eats context every session. Here the argument is purely economic: every line about what happened in February competes for the model's attention with a line about how to write code now — and the model cannot automatically weigh "this is history" against "this is an active rule," it simply reads the entire file as equivalent context.
One-time instructions. "Update dependency X today" is a task for the chat, not for a file that is loaded constantly. If this instruction is not removed after completion, it will continue to be loaded in every subsequent session and may even confuse the model when the task is long done, but the file still says "update X" — the model will either try to do it again, or spend a step clarifying whether it's already done.
Obvious things. "Write clean code," "add comments where necessary" — give the model nothing it doesn't already do by default, and simply take up lines from the limit of 150-200 instructions I wrote about above. This is the most expensive type of ballast of all listed: it's not just useless, but displaces space that could be occupied by a line with a real effect — for example, the same DTO naming convention that the model really couldn't guess on its own.
Optimal CLAUDE.md structure
Based on what I've seen in working production files and community recommendations, the optimal structure looks like this:
Project overview
Architecture
Coding conventions
Directory structure
Commands
Testing
Security
Definition of Done
Agent behaviour
Useful references
The order here is not accidental: first — the context in which the model should understand what kind of project it is (overview, architecture), then — the rules for writing code (conventions, structure), then — how to check 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 short — specifically. Guideline: up to 200 lines for a project CLAUDE.md, up to 30 lines for a personal ~/.claude/CLAUDE.md. This is not an arbitrary number — frontier models reliably follow about 150-200 instructions simultaneously, and Claude Code's system prompt already occupies about 50 of them (HumanLayer, via maketocreate.com). That is, each extra line in your file is real competition for the model's attention with other instructions, not a free bonus.
Use absolute rules. "Try to use named exports" is worse than "Use named exports, not default exports" — the model better follows a clear, unambiguous instruction than a soft wish.
Avoid contradictions — and understand how the system resolves conflicts if they arise. I've written this above, but I'll repeat it here intentionally: a more specific instruction overrides a more general one. Knowing this rule means you can consciously place an exception at a lower level (e.g., in the CLAUDE.md of a specific subdirectory), rather than trying to maintain one giant, consistent rule for the entire project.
Separate general and local instructions. General personal preferences (favorite diff format, timezone) — in the global file. Team conventions — in the project file, under git.
Update the file regularly. A CLAUDE.md that hasn't been edited for three months on an actively developing project is almost certainly a file with outdated commands.
Do not store project history. "We used to use Redux, now we've switched to Zustand" — interesting for a person, useless for a model that only needs the current state.
Refer to documentation instead of copying. One line with a link lives longer than a copied paragraph that no one will synchronize manually.
Add actual project commands. Not "run tests," but literally ./gradlew test or npm run test:unit — the model shouldn't guess.
The main test for any line: can it be inferred from the code? If yes — it's a candidate for removal. This is precisely the logic used by the built-in /doctor, and I recommend applying it consciously even before writing turns into a 300-line file that will have to be trimmed retroactively.
Good CLAUDE.md Example
# Project overview
Backend API for room booking system. Spring Boot 3.5, Java 21, PostgreSQL.
# Architecture
Layered architecture: controller → service → repository.
DTOs for input/output data, entities do not leave the service layer.
Business logic only in service, controllers are thin.
# Coding conventions
- Named parameters in constructors via Lombok @RequiredArgsConstructor
- Exceptions — custom unchecked, inherit from ApiException
- DTOs via record, not class
- Dates — only java.time, never java.util.Date
# Directory structure
src/main/java/com/company/booking/
controller/ — REST controllers, only delegation to service
service/ — business logic
repository/ — Spring Data JPA
dto/ — record classes for API
entity/ — JPA entities
config/ — Spring configuration
# Commands
Build: ./gradlew build
Run tests: ./gradlew test
Run integration tests: ./gradlew integrationTest (requires Docker for Testcontainers)
Local run: ./gradlew bootRun --args='--spring.profiles.active=local'
# Testing
JUnit 5 + Mockito for unit, Testcontainers + PostgreSQL for integration.
Each new service method with business logic — at least one unit test.
Do not mock what can be tested via Testcontainers.
# Security
Never log passwords, tokens, or customer personal data.
All endpoints under /admin/** — only ADMIN role, check at @PreAuthorize level.
# Definition of Done
- Tests passed (./gradlew test)
- No new warnings from Checkstyle
- DTOs documented with Javadoc, if public API
# Agent behaviour
Before a major refactoring — first, a plan, without file modifications.
Do not delete existing tests without explicit permission, even if they "look redundant".
# Useful references
Architectural decisions: docs/adr/
Domain model description: docs/domain-model.md
Note: there is no actual code snippet here, no copy of README, no changelog. Each section gives the model something it couldn't confidently infer from the code itself — which is why the file works.
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 switched to 3.
In February 2025, we rewrote the payment module (see PR #482).
In April, we added Kafka, and in June 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 almost a textbook collection of anti-patterns: project history instead of current state, obvious advice like "write clean code", embedded implementation code instead of a file reference, a complete copy of API documentation that is guaranteed to diverge from the actual code within the first sprint, and a changelog that doesn't influence any decisions about new code. A file of this size and content will consume context every session, giving the model minimal useful signal.
CLAUDE.md for Spring Boot
For Java/Spring projects, I would highlight a separate block for the stack specific to the ecosystem:
Maven or Gradle — and specific commands for building/testing your version, not both "just in case".
Spring Boot version and key starters that are actually used (web, data-jpa, security, actuator).
Spring AI, if the project works with it — it's worth noting separately which provider (Ollama, OpenAI, Anthropic) is used by default in the dev profile.
Docker — commands for locally raising infrastructure (docker-compose up -d), not just a mention that Docker is used.
PostgreSQL — version, whether Postgres-specific types (jsonb, arrays) are used, which may not have a direct equivalent in other RDBMS.
Flyway — migration numbering rule, whether an applied migration can be edited (almost always — no).
Testcontainers — which specific containers are used for integration tests, so Claude doesn't suggest mocking what is already tested via a real DB.
CLAUDE.md for Monorepo
For a monorepo with multiple packages in one repository ("root", "frontend/", "backend/", "shared/") the mechanism of nested CLAUDE.md files described in the technical loading section works: the root file carries what is common to the entire repository (general conventions, CI commands), and each subdirectory has its own CLAUDE.md with what is specific to it.
Practical advice: do not duplicate in a subdirectory what is already in the root file — a nested CLAUDE.md complements the root file, it does not completely replace it. And remember the priority rule: if the root file says one thing, and frontend/CLAUDE.md says another for frontend code, the more specific instruction wins for work within frontend/.
CLAUDE.md for Microservices
Here the task is fundamentally different from a monorepo. In a monorepo, the question is "where to store nested files within one repository". In a microservice architecture, each service lives in its own repository with its own CLAUDE.md — and the real question is not about nesting, but about synchronizing common conventions between repositories that are not physically linked by a single directory tree.
Two practical approaches I've seen: first — keep common conventions (commit style, logging approach, common security rules) in a separate internal repository and include them via @import in each service (remember — import is fully expanded, so keep this common file compact). Second — accept that a small duplication of a few key lines in each service's CLAUDE.md is cheaper than infrastructure for synchronization, especially if there are few services and they don't change weekly.
CLAUDE.md vs AGENTS.md
Parameter
CLAUDE.md
AGENTS.md
Who reads
Claude Code only
Codex, Cursor, Copilot, Gemini CLI, Windsurf, and others
Who manages the standard
Anthropic
Agentic AI Foundation (Linux Foundation)
Memory model
Multi-level: global / project / nested + rules with path-scoping
Simpler: file in root, override by directory depth
Distribution
Specific to Claude Code
60,000+ public repositories as of mid-2026
The key fact that is most often confused: Claude Code does not natively read AGENTS.md, and other tools (Cursor, Copilot, Gemini CLI) do not read CLAUDE.md — this is confirmed by a direct test on a live repository: placing CLAUDE.md in a Cursor project, and Cursor simply ignores it (TECHSY). If your team uses more than one AI tool, the most practical approach is to keep AGENTS.md as the base cross-tool file and CLAUDE.md separately for what is specific to Claude Code (nested structure, path-scoped rules).
CLAUDE.md vs Cursor Rules
Parameter
CLAUDE.md
Cursor Rules
Format
One or several .md files
.mdc files in .cursor/rules/ with YAML frontmatter
Activation modes
Always when entering the scope (global/project/nested)
Four modes: Always Apply, Apply Intelligently, Apply to Specific Files, and legacy .cursorrules
Path-scoping
Through separate .claude/rules/ with paths: frontmatter
Built into the format itself via the globs field
Priority on conflict
By directory depth (more specific overrides more general)
Team → Project → User, earlier source wins
Objectively speaking, Cursor's rule activation system is more structured "out of the box" — four explicit modes versus Claude Code's simpler model. However, Claude Code's deeper hierarchy (global/project/nested + rules) offers more flexibility for large monorepos. If your team works exclusively in Cursor, I wouldn't try to artificially replicate Claude Code's system — just use the native capabilities of .mdc files.
CLAUDE.md vs Codex Instructions
It's worth clarifying the inaccuracy in the comparison title right away: OpenAI Codex does not have a separate proprietary format called "Codex Instructions" — Codex CLI reads the same open AGENTS.md that other tools use (The Prompt Shelf). This means the "CLAUDE.md vs Codex" comparison in practice is the same case as "CLAUDE.md vs AGENTS.md" above, with one difference: Codex CLI has a convenient diagnostic command --print-instructions, which shows exactly which merged AGENTS.md content is actually loaded into the current session — useful when you suspect a file is being truncated or skipped.
Practical conclusion: if your team uses both Claude Code and Codex, be prepared to maintain two files — CLAUDE.md for one tool, AGENTS.md for the other — and move truly common things into a format that can be imported or copied into both without discrepancies.
Common Developer Mistakes
Most points in this section are not just "bad practice," but a specific cause-and-effect chain that I've observed either in my own projects or in community descriptions. I'll detail each one so that not only "what's wrong" is visible, but also what exactly it causes next.
A 1000-line file. A classic mistake is trying to describe the project exhaustively instead of giving the model only what it cannot infer itself. The consequence is direct, and I've already explained the mechanism above: the model reliably keeps about 150-200 instructions in mind simultaneously, and Claude Code's system prompt already occupies about 50 of them. A 1000-line file is not "more context about the project," it's an overloaded attention budget where the important Definition of Done rule gets lost among hundreds of obvious statements, and the model effectively starts ignoring some instructions not out of malice, but because it physically cannot hold them all with equal weight.
Contradictory instructions. This is especially common between global and project files, when personal habits contradict team conventions. The consequence here is not that the "model gets confused" abstractly — since the specificity rule applies (project overrides global), the model will actually always follow the project rule, and your personal habit from the global file will simply be silently ignored every time. If you don't know this rule, it will look like Claude is "forgetting" your settings — when in reality, it's correctly applying the priority, you just weren't aware that the global line never had a chance to work in this project.
Outdated commands. A file that hasn't been updated since switching from npm to pnpm or changing the CI pipeline. The consequence is specific: the model will execute exactly the command written in the file, get a "command not found" error or lock file conflicts, and spend a step figuring out what went wrong on its own, instead of immediately running the correct command. This is a minor issue that subtly eats up time in every session until someone updates one line.
Lack of architecture. A model without a description of application layers tends to create new files in places not conventional for the project. The reason is simple: without an explicit rule, the model relies on the simplest working path for a specific task, not on the team's architectural agreement — technically, the code will work even if the business logic ends up directly in the controller instead of the service layer, and you'll get technically correct but architecturally incorrect code that will need to be refactored during review.
Mixing documentation and instructions. When CLAUDE.md tries to be a README, an API reference, and an instruction file all at once, it performs all three roles poorly. The reason is the same one I've already explained in the "what you should never write" section: documentation and references change at a different frequency than instructions for the model, and sooner or later diverge from reality — only here the consequence is broader, as the file loses focus for three different audiences (new developers, those looking for the API, and the model itself), satisfying none of them completely.
Buggy documentation: user-level rules with paths: frontmatter in ~/.claude/rules/ as of early 2026 are not loaded, even if the file matches the pattern — this is a confirmed bug (GitHub issue #21858). Practical consequence: if you've written a personal path-scoped rule at your profile level and it silently doesn't work, it looks exactly like an error in your glob pattern — and you can spend hours looking for an error where the bug is actually in the tool itself. A workaround is to move path-scoped rules to the project level, not the personal profile.
Headings from imported files are not automatically demoted. If the main file has \# Code conventions, and an imported file starts with its own \# Heading, the result is not a subsection, but a sibling of the same heading level. The consequence is subtle but real: the file structure that looks logical in your editor (the import is seemingly "nested" under a section) actually unfolds in the model as two independent headings of the same level — this confuses the hierarchy of instruction importance when you expected nesting itself to signal something to the model. The GitHub issue regarding this was closed as "not planned," so no fix is expected — monitor heading levels manually (HackerNoon).
Glob patterns starting with { or * must be quoted in YAML frontmatter — without quotes, this is not a Claude Code limitation, but a standard YAML syntax requirement that regularly catches developers off guard (Medium, Frontend Master). The consequence here is the harshest of all: it's not a silent behavioral error, but a syntax parsing error — the entire rules file might not load at all, and you'll lose not one rule, but the entire set of path-scoped rules from that file until you find and fix the quotes.
FAQ
Can I have multiple CLAUDE.md files?
Yes, and I would even say that for any project larger than a single service, it's not an option but the norm. I usually have three levels active at once: global with personal settings, project-specific under git for the whole team, and several nested in subdirectories with specifics for a particular module. They don't compete — each level complements a more general one based on the specificity rule I've already explained above: a more local instruction overrides a more general one where they intersect.
Where is the best place to store the file?
Here, I follow a simple division by purpose. I always put the project CLAUDE.md in the repository root and commit it to git — otherwise, the whole team works with different instructions for the same model, which defeats the purpose of the file. The personal file (~/.claude/CLAUDE.md), on the contrary, is outside the repository because these are my personal work habits that should not be imposed on other team members.
What is the optimal size?
The guideline I follow myself is up to 200 lines for a project file and up to 30 lines for a personal global file. This is not an arbitrary number for the sake of it: I've already explained in the best practices section that models reliably keep about 150-200 instructions in focus simultaneously, and Claude Code's system prompt itself already occupies about 50 of them. Therefore, exceeding this limit is not an aesthetic problem, but a direct loss of efficiency: some of your instructions will simply stop working reliably.
Can I use Markdown?
Yes, this is its native file format, and I would recommend not neglecting the structure — headings and lists don't just "look nice," they help group related instructions into logical blocks, making it easier to read both for me when reviewing the file and for the model when processing context.
Does CLAUDE.md work in subdirectories?
Yes, and this is where I consider Claude Code's memory model to be stronger than simpler alternatives. A nested CLAUDE.md is not loaded immediately at the start of a session, but on-demand — only when Claude actually accesses files in the corresponding subdirectory. For monorepos, which I regularly work with, this means that instructions specific to the frontend module do not occupy context when Claude is working exclusively with backend code.
Do I need to store it in Git?
The project file, absolutely yes, I insist on this in every team I work with: if CLAUDE.md is not in git, each developer accumulates their own, gradually diverging version of instructions, and you lose the main value of the file — consistency. However, I always add personal override files to .gitignore — they are specific to my work environment, not to the project.
How is it different from README?
I formulate this difference through the audience, not the format. README is written for a person who opens the repository for the first time and knows nothing about the project — it's a showcase. CLAUDE.md is written for a model that already knows general development patterns and only needs what specifically differentiates your project from default assumptions. When I tried to combine both roles in one file, both audiences suffered immediately — I wrote about this in more detail in the common mistakes section above.
Can it be used with AGENTS.md?
Yes, and in my practice, it's more of a rule than an exception — few teams today rely solely on one AI tool. Claude Code only reads CLAUDE.md, while Cursor, Copilot, or Gemini CLI primarily rely on AGENTS.md. If your team is mixed, I would immediately plan for support of both files, rather than trying to force one tool to read the format of another — it simply won't work.
Does @import really reduce context?
No, and this is precisely the mistaken intuition I myself had before I understood the mechanism in more detail. Imports are loaded entirely at the start of the session — splitting the file into several imported parts makes it easier for you to maintain the code, but does not reduce the amount that actually goes into the model. If the goal is context saving, not editing convenience, only path-scoped rules in .claude/rules/ work, which I detailed in the section on technical file loading above.
What happens to CLAUDE.md after /compact?
The root file is reinjected from disk — I've personally verified this, and the behavior is stable. However, nested CLAUDE.md and rules do not automatically return after compaction: they are reloaded only when Claude next accesses the corresponding subdirectory or file. If you expect a nested instruction to be "remembered" for the entire session after compaction, this is a dangerous assumption — it's better to assume it's only loaded when needed.
What is the minimum Claude Code version required for /doctor trimming?
v2.1.206 or newer. I recommend checking your current version before relying on this command in the best practices description above — on older versions, the command is simply missing, and you'll get an error instead of a hint about file trimming.
Conclusions
If I were to take one thought away from this article, I would choose this: CLAUDE.md is not documentation or configuration, but text that competes for the model's limited attention with everything else loaded into context every time. Every extra line is not a free "just in case" insurance, but a real cost that the model pays each session.
My practical advice, which I apply to every new CLAUDE.md: don't try to write the perfect file immediately. Start with the basic minimum — stack, commands, key conventions — and add one line at a time whenever Claude makes a mistake that a single clear rule could have prevented. And before adding a new line, apply the same test that underlies /doctor: can this be inferred from the code? If yes — don't write it, the model will figure it out itself.
