Scoping Rules: Global, Project, Path-Glob | by Ian Johnson | Jun, 2026 | MediumSitemapOpen in appSign up<br>Sign in
Medium Logo
Get app<br>Write
Search
Sign up<br>Sign in
Scoping Rules: Global, Project, Path-Glob
Ian Johnson
4 min read·<br>Just now
Listen
Share
A rule that fires on every file is a tax. A rule that never fires is dead code. The cost of getting scope wrong is paid every session, on every task, by every contributor and almost nobody talks about it.<br>I want to talk about it.<br>The three scopes in Claude Code are global (~/.claude/CLAUDE.md), project (./CLAUDE.md), and path-scoped (subdirectory CLAUDE.md, or feature docs loaded by path match). They look like a hierarchy. They behave like three different tools.<br>The default mistake is to put everything in the project CLAUDE.md and call it done. The file grows. It crosses 500 lines. It crosses 1,000. The agent reads it on every task, including the ones where 90% of the file is irrelevant. The team stops reading it because it is too long to absorb. The new contributor never reads it at all.<br>Tokens are the easy half of the cost. Attention is the harder one. Every line of CLAUDE.md is a line the agent has to weigh against every other line, and a line the human has to skip past when they are looking for the one rule they actually need.<br>Global: the rules that follow you<br>Global rules apply to every project on your machine. The bar is very high. If a rule does not survive the test would I want this in a Python repo, a TypeScript repo, and a shell-script repo, it does not belong in global.<br>What I keep there are personal preferences about how the agent should communicate. Be terse. Do not narrate intermediate reasoning. Do not add commentary to commit messages. Do not write documentation files unless I ask. None of those depend on the language, the framework, or the project. They are about the working relationship, not the code.<br>What does not belong in global: anything about a specific language, framework, library, or convention. Use functional components in React is a fine rule. It does not belong in global. The moment I open a backend repo, the rule is firing against code that does not have React in it. The agent has to either ignore it (wasted tokens) or get confused (worse).<br>If you cannot phrase the rule in language that applies equally to any repo, the rule is not global.<br>Project: the rules that define the codebase<br>Project rules apply to every file in the project. They are for conventions true everywhere in this codebase. Naming. Layout. Build commands. The library you use for X. The framework’s pitfalls.<br>The bar for a project rule is does this apply to most of the files in the repo. If the rule only applies to the frontend, or only the database layer, or only one feature, it does not belong at the project root. It belongs in a path-scoped file.<br>A good project rule: Use pnpm, not npm. Applies everywhere. Cheap for the agent to honor, cheap for a human to verify. Tests live in tests/, not __tests__/. Same shape. All public exports go through index.ts. Same shape.<br>A bad project rule, the one I see most often: When working in the API module, make sure the validation schema is updated to match. Applies to maybe 10% of the files. The agent reads it on every other task. It earns its keep one out of ten sessions; the other nine, it is noise.<br>Get Ian Johnson’s stories in your inbox
Join Medium for free to get updates from this writer.
Subscribe
Subscribe
Remember me for faster sign in
That rule belongs in a subdirectory CLAUDE.md inside the API module, where it loads when the agent is touching files in that module and stays silent when it is not.<br>Path-scoped: the rules that earn their keep<br>Path-scoped rules are the underused primitive. Most teams know they exist and do not use them, because the project root is the path of least resistance and I will move it later is the path of I will never move it.<br>The mental model is simple. The agent loads context based on what it is looking at. Edit a file in src/components/, the CLAUDE.md in src/components/ loads. Edit a file in src/api/, the CLAUDE.md in src/api/ loads. Rules that are only true for that subtree go there.<br>The discipline pays off three ways.<br>The agent’s context window is smaller on every task. The rules it loads are the rules that apply. Nothing else.<br>The rules themselves can be specific. A rule that only fires inside src/api/ does not have to caveat itself. It does not have to say in the API module, do X. It just says do X, because the file location is doing the scoping. The rule reads more directly. The agent applies it more reliably.<br>The rules are colocated with the code they constrain. A new contributor opening src/api/ sees the rules for that module right there. The convention is documented where the convention lives.<br>The test for moving a rule down<br>The quick check I run on every rule in the project root: would this rule still apply if I deleted half the repo? If the answer is no, the rule is...