Where to Put Team and Personal Rules in CLAUDE.md

A monorepo holds two projects, frontend/ and backend/, and each has its own CLAUDE.md. You start Claude Code inside frontend/ and ask it to tweak a backend endpoint along the way. The rule in backend/CLAUDE.md, "update the OpenAPI file whenever an endpoint changes," never kicks in.

The same week, someone puts their local test URL in the root CLAUDE.md and commits it, and now the whole team reads it.

Neither problem has anything to do with how well the rules are written. Both are about location. A CLAUDE.md can live in several places, and each location decides two things:

• who sees it: just you, the whole team, or you in this one repository;
• when it loads: at startup, or only once Claude touches a particular directory.

These two are controlled by different things. Where you store the file decides who it's shared with. The startup directory and the files Claude touches decide what loads this time. If you only look at where a file sits, it's easy to assume that anything committed to the repo gets read on every run.

The fix is to pick the file by who should see it, then work out what loads from the startup directory. When the root file grows long, move rules that only matter for part of the codebase into a subdirectory file or a path-scoped rule, so they load only when needed.

01 Four Locations, Chosen by Who Should See Them

Four locations cover most everyday projects:

Both the project root and .claude/ can hold project-level instructions. Pick one as the primary location so related rules don't drift across files. That local test URL from the opening belongs in CLAUDE.local.md, with the file added to .gitignore.

This matches the Claude Code memory documentation: project instructions go in ./CLAUDE.md or ./.claude/CLAUDE.md, and personal project preferences go in ./CLAUDE.local.md, which loads alongside CLAUDE.md and is treated the same way.

02 The Startup Directory Decides What Loads

At startup, Claude Code searches upward from the current directory for instruction files, and several may load. The docs explain that these files are concatenated into context rather than overriding each other. They're ordered from the filesystem root down to your working directory, so the file closest to where you launched is read last. Within each directory, CLAUDE.local.md comes after CLAUDE.md.

Being read last doesn't mean a nearer file reliably overrides an earlier written requirement. When two rules conflict, go back to the source files and resolve the conflict there.

A monorepo holds several projects in one repository. Subdirectory instructions load according to the area being accessed:

shop-platform/
├── CLAUDE.md
├── frontend/
│   └── CLAUDE.md
└── backend/
    └── CLAUDE.md

Starting in frontend/ loads the root and frontend instructions, without the sibling backend/CLAUDE.md. Starting at the root loads root rules first, and subdirectory instructions load as Claude reads files in those areas. The docs are more specific: a CLAUDE.md in a subdirectory under your working directory loads once Claude reads, writes, or edits another file in that subdirectory.

Back to the opening example. backend/ isn't under frontend/, so a session started in frontend/ never reads it. When a task spans both front end and back end, start from the root.

Where a file is stored decides who it's shared with; the startup directory and the files Claude touches decide what loads for this task. Committing a subdirectory file doesn't make every sibling's instructions load together. To confirm exactly which files loaded, check /context first, as described in why Claude Code ignores your CLAUDE.md rules.

03 When the File Grows, Move Rules Where They Belong

As a file grows, look for material that's rarely needed. Official guidance suggests keeping each CLAUDE.md under 200 lines. Going over doesn't break anything right away; treat the number as a prompt to review. The memory docs give the reason: longer files consume more context and reduce adherence.

Moving long sections into @path imports can tidy the file, but imported content still loads, so it doesn't reduce context use. For example:

# Additional Rules

- Git workflow: see @docs/git-workflow.md
- Release constraints: see @docs/release-rules.md

When the file grows, work through these steps in order:

1. Delete information that's easy to find in code, configuration, and lockfiles.
2. Move subproject-specific rules to the matching directory.
3. Turn requirements that only apply to certain files into path-scoped rules.
4. Move long methods used only for specific tasks into a Skill.

What to delete in step 1 depends on what deserves a permanent place, which is covered in how to write a CLAUDE.md that Claude actually uses.

04 Load Path-Scoped Rules Only When Needed

For example, save the following as .claude/rules/api.md to give API files their own requirements. The YAML between the two --- lines is metadata, and paths sets the matching scope:

---
paths:
  - "src/api/**/*.ts"
---

# API Rules

- Call `requirePermission()` before every write operation.
- External error responses must not include database exceptions or stack traces.

A rule like this loads only when Claude works with matching files, which is easier to maintain than stuffing front-end, back-end, database, and release details into the root file. One catch: a file in .claude/rules/ without paths loads at startup with the same priority as .claude/CLAUDE.md. If you want it to appear only when needed, give it a matching scope.

The Claude Code best practices make the same recommendation: scope rules that only concern one part of the codebase to that part, so they don't take up room on every task.

When placing a rule, keep two questions apart. Which file it lives in decides who sees it. Which directory you start from and which files Claude touches decide what loads this time. Answer both, and that backend rule and that local URL each end up where they should be.