Split standing conventions into focused rule files

Learning objective

Organize shared conventions into topic-specific .claude/rules/ files rather than one large CLAUDE.md.

Core idea

Give each standing convention an identifiable topic and maintained home. Claude Code discovers Markdown files under .claude/rules/, so a project can keep concise main instructions and separate testing, API, and deployment rules without listing an import for every rule file.

This organization improves review and ownership. It reduces loaded context only when you also remove unnecessary instructions or make rules conditional. Splitting one long instruction into several unconditional files preserves the text Claude must read. A tidy directory tree is not evidence that a session’s instruction budget became smaller.

How it works

Replace the monolith with topic files

Place shared Markdown rules in the project’s .claude/rules/ directory and commit them with the repository. Use descriptive filenames, such as testing.md, api-conventions.md, and deployment.md. Each file should cover one topic, so a change to testing policy has an obvious document to update.

A project can organize its instructions as follows:

.claude/
  CLAUDE.md
  rules/
    testing.md
    api-conventions.md
    deployment.md

Keep .claude/CLAUDE.md focused on the essentials that orient every session. Move the detailed standing conventions into the relevant topic files. Claude Code discovers all .md files recursively, including files inside subdirectories such as .claude/rules/backend/ or .claude/rules/frontend/. A subfolder groups topics for maintainers; its name alone does not make the contained rules conditional.

Rules without paths frontmatter load at launch with the same priority as .claude/CLAUDE.md. You do not need an explicit @path reference to activate each discovered rule. Adding imports for the same collection is not the mechanism that gives this directory its automatic discovery.

The directory also does not make contradictory instructions safe. If the main file says to use one test runner and testing.md says to use another, both can enter context. Anthropic warns that conflicting instruction text can produce arbitrary choices. Moving the same contradiction into smaller files preserves the contradiction.

Make the content concrete and concise

Anthropic recommends targeting under 200 lines per CLAUDE.md. This is an adherence and context recommendation, not a 200-line cutoff beyond which a file becomes unreadable. The memory page documents a separate hard boundary: Claude Code skips an instruction file over 4 MiB.

A rule file earns its place by preserving information Claude cannot reliably derive from the code. Include a project-specific test command, a convention that differs from language defaults, or a recurring pitfall. Remove generic statements such as “write clean code” and inventories that a repository read already supplies. The best-practices page recommends asking whether deleting a line would cause Claude to make mistakes.

Write verifiable instructions rather than broad aspirations. “Use 2-space indentation” gives a concrete expectation; “format code properly” leaves interpretation open. Topic files make it easier to review such wording because related instructions appear together. They still supply guidance, so mandatory execution belongs in the hook mechanism described in 3.1.1.

Do not measure success only by the length of the main file. After the split, examine the main file plus every unconditional rule. If all the same prose remains, the context cost remains. Shortening a file by relocating paragraphs improves organization; deleting redundant text improves the amount and clarity of guidance delivered.

Separate topic organization from conditional scope

A rule’s paths field in YAML frontmatter makes it conditional on matching files. Without that field, a file named api-conventions.md is an unconditional rule even if every sentence concerns the API. Naming communicates the topic to people; frontmatter carries the documented loading condition.

For this unit, recognize that distinction rather than copying every glob into the main file. Task statement 3.3 owns path-specific selection; see 3.3.1. If all sessions need the testing convention, leave testing.md unconditional. If a framework rule applies only to a subset of files, conditional scope is the mechanism for keeping that text out of unrelated work.

Project rules also depend on the launch’s settings sources. Excluding project from --setting-sources skips project rules. If an entire rule collection is absent, check whether the invocation excluded that source before diagnosing every Markdown file separately.

Personal topic rules belong in ~/.claude/rules/. They apply to your projects and load before project rules. A project rule appearing later does not override contradictory personal text; Claude might follow either. A personal topic directory is therefore inappropriate for delivering conventions to teammates, just as a home CLAUDE.md is.

Key distinctions and trade-offs

Rules versus imports: .claude/rules/ discovers its Markdown files automatically. @path imports explicitly compose selected documents into a CLAUDE.md; 3.1.2 owns their path and approval semantics. Choose automatic topic organization when the convention belongs to the project’s rule collection.

Topic versus loading scope: A filename or subfolder identifies subject matter. The paths frontmatter field conditions loading. Do not claim a folder named frontend scopes its files to frontend code.

Standing rule versus task procedure: Rules load every session or when matching files are opened. Anthropic recommends skills for task-specific instructions that need not always occupy context; see 3.2.1. A deployment naming convention can be standing guidance, while a multi-step deployment procedure belongs in a task-oriented mechanism.

More files make topic ownership easier but can spread duplicates and conflicts across the collection. Keep one authoritative statement of each convention, and review the collection as a whole when reorganizing it.

Architecture / decision scenario

A developer-productivity team has a root instruction file mixing testing standards, API error conventions, deployment naming, and a lengthy deployment procedure. Changes to any topic require scanning the entire document, and Claude sometimes misses a test requirement buried among unrelated details.

The team keeps a short .claude/CLAUDE.md and moves standing conventions to testing.md, api-conventions.md, and deployment.md under .claude/rules/. Each maintainer removes redundant wording and checks for a conflicting copy in the main file. The testing rule states the precise project command instead of asking Claude to “test thoroughly.”

Initially the three files have no paths field, so all load at launch. The team makes no claim that splitting alone saves context. It identifies API-only guidance for conditional scope under 3.3.1 and gives the multi-step deployment procedure a skill under 3.2.1. The deployment rule retains only the convention needed as standing context.

A teammate still lacks every project rule. Their launch excludes the project settings source with --setting-sources; restoring that source addresses collection loading. Copying the rules into ~/.claude/rules/ would disguise the launch issue and make the shared design personal. The team checks launch-loaded files with /context, following 3.1.4.

Common exam traps

• Assuming every topic file needs an explicit import from the main instruction file.
• Treating a frontend/ subfolder as a path-matching condition.
• Claiming that splitting unchanged prose reduces loaded context.
• Treating the 200-line recommendation as the hard file-size boundary.
• Moving a shared convention into ~/.claude/rules/ and expecting teammate delivery.
• Leaving contradictory copies of the same convention in the main file and topic rules.

What to remember

Use .claude/rules/ for automatically discovered, focused Markdown conventions. Recursion organizes topics; paths frontmatter controls conditional loading. Unconditional files still load at launch, so prune text as well as split it. Keep shared guidance in project files, check project settings-source inclusion, and reserve task procedures for skills.

Knowledge check

References

• Anthropic, How Claude remembers your project
• Anthropic, Best practices for Claude Code