For Claude Code, split a large project reference by where each instruction applies: keep repository-wide essentials in the root CLAUDE.md, put directory-specific guidance in nested CLAUDE.md files, and use path-scoped rules in .claude/rules/ for constraints that should apply only to matching files. A 500-line ceiling can be a useful project target, but Anthropic does not prescribe it; its Help Center recommends keeping each CLAUDE.md short and signal-dense, “under roughly 200 lines.”
Choose a file structure by instruction scope
CLAUDE.md is a plain Markdown file that gives Claude Code project context. The root file is read at session start; a nested CLAUDE.md is loaded when Claude reads files under that file’s directory. Rules in .claude/rules/ can hold focused constraints and conventions, with optional path patterns to limit when they apply. Anthropic describes these structures in its CLAUDE.md guidance and Claude Code steering overview.
![Claude Code for Beginners: [All in 1] The Ultimate Step-by-Step Guide to Set Up Safely, Build Real Projects, and Automate Your Work with AI – No Tech Background and No Terminal Experience Needed](https://m.media-amazon.com/images/I/41IO6Hnt6vL._SL160_.jpg)
| Structure | Use it for | When it applies |
|---|---|---|
Root CLAUDE.md |
Shared project orientation and repository-wide instructions | Read at session start |
Nested CLAUDE.md |
Guidance specific to a directory or module | When Claude reads files under that directory |
.claude/rules/ |
Focused conventions or constraints; add path patterns when they should be selective | When applicable to the specified paths, or more broadly if not path-scoped |
Splitting content into imported or linked files can make it easier to maintain, but it does not automatically make that material selectively loaded. If an instruction should apply only to a directory or set of files, use the corresponding nested file or a path-scoped rule rather than assuming that a separate file alone limits its scope.
Keep the root file short and useful
Use the root CLAUDE.md as a compact map of what Claude needs across the repository. Keep instructions that are genuinely shared, and move detailed local guidance to the place it governs. Anthropic’s Help Center, in guidance published April 15, 2026, says: “Aim for a file that is short and signal-dense — under roughly 200 lines.” This is guidance, not a hard technical maximum or a measured guarantee about task performance. An Anthropic presentation dated March 24, 2026 likewise says longer files consume more context and can negatively affect instruction adherence, but gives no measured effect size. Read the presentation.
Free tools Windows power users keep installed
One-click scans. No signup required.
- Build, test, lint, and run commands people need to use the project.
- Conventions the team actually follows, such as naming and error handling.
- A short architecture overview and hard constraints.
- Recurring gotchas that would otherwise cost time or cause mistakes.
Remove changelogs, information obvious from the file tree, and aspirational rules the team does not consistently follow. Move exhaustive API documentation elsewhere when the code itself provides the needed detail.
Move instructions to the narrowest useful scope
Use nested CLAUDE.md files for directory-specific guidance
Put a nested CLAUDE.md inside a directory when its instructions belong to that part of the repository—for example, module-specific conventions or local commands. Claude Code loads it when it reads files under that directory, so unrelated parts of the project do not need to carry the same local detail.
Use path-scoped rules for selected files
Use .claude/rules/ for a focused constraint or convention that applies across matching paths, including when those paths do not neatly share one directory. Add YAML frontmatter with a paths list of glob patterns to scope the rule. This example shows the syntax; its instruction is illustrative:
---
paths:
- "src/api/**"
- "**/*.handler.ts"
---
All API handlers must validate input before processing.Anthropic’s published rules example demonstrates path patterns in frontmatter. Match the mechanism to the scope: a directory’s own guidance belongs in a nested file; a cross-cutting rule for selected file types or locations belongs in a path-scoped rule.
A practical split, step by step
- Set the ceiling. Treat 500 lines as your chosen maximum, not an Anthropic requirement. Since Anthropic recommends under roughly 200 lines for a
CLAUDE.md, aim for a smaller, more signal-dense root file where practical. - Sort each instruction by scope. Mark whether it applies repository-wide, to a directory or module, or only to specific matching paths.
- Keep shared essentials in the root. Retain the project’s common commands, conventions, architecture summary, constraints, and recurring gotchas.
- Create nested files for local guidance. Move instructions that apply only when working in a particular directory into that directory’s
CLAUDE.md. - Create rules for selective cross-cutting guidance. Place focused constraints in
.claude/rules/and addpathsglobs when they should activate only for matching files. - Remove material that is not useful context. Cut stale history, obvious file-tree descriptions, inconsistent aspirations, and documentation better maintained elsewhere.
- Review the result as the project changes. Revisit guidance after
/init, when Claude repeats a mistake, when conventions change, and during periodic cleanup.
What a 500-line target does—and does not—mean
Keeping each file under 500 lines is an organizational choice, not a published technical limit for Claude Code. Anthropic’s stated guidance is more conservative for CLAUDE.md: under roughly 200 lines. Its rationale is qualitative—longer files consume more context and may negatively affect instruction adherence. The available guidance does not establish an empirically optimal line count or quantify how much splitting improves accuracy.
The practical goal is not to distribute text merely to satisfy a counter. Make every file easier to maintain and ensure each instruction appears where its scope is clear. A short root file plus appropriately scoped local files is more useful than a collection of fragmented files whose contents still apply everywhere.
Quick Recap
Best Value
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.
