One rule set, four places: inline +3,330 tokens, @import +3,442, paths +0 until read
Claude Code experiments show that placing a large rule set in a path‑scoped file keeps it out of the initial prompt until a matching file is read, saving up to 3,000 tokens. The study compares inline, imported, and scoped rule placements, revealing that scoped rules load only on demand and remain i…
Claude Code, the AI coding assistant from Anthropic, has introduced a feature that lets developers scope rule files to specific file patterns. A recent experiment measured how this feature affects the number of tokens sent in the first request of a fresh session. By placing the same 2,004‑word rule set in four different locations—inline, imported, unscoped file, and path‑scoped file—researchers quantified the token savings and clarified when the rules actually enter the model’s context.
How the Test Was Set Up
The experiment ran on Claude Code v2. Each configuration started with a minimal Claude.md file that only contained a heading and a passphrase. The rule set itself was a 2,004‑word document with 40 numbered bullet points about API handlers. Two small source files, src/api/handler.ts and src/ui/button.ts, were included to trigger the path‑scoped rule in one of the setups.
The four placements were:
- Inline in
Claude.md– the rules were pasted directly into the main file. - Imported via
@import– the rules lived in a separate file referenced fromClaude.md. - Unscoped file – the rules were stored in
claude/rules/api.mdwithout any path pattern. - Path‑scoped file – the rules were in
claude/rules/api.mdwith a front‑matter fieldpaths: ["src/api/**"].
Token Counts and What They Reveal
For each setup, the first request’s total input tokens were measured. The baseline, with only the three‑line Claude.md, used 20,617 tokens. Adding the rules inline raised the count to 23,947 (+3,330 tokens). Importing the rules increased the count to 24,059 (+3,442 tokens). The unscoped file produced 24,055 (+3,438 tokens), virtually identical to the imported version. The path‑scoped file, however, matched the baseline at 20,617 tokens—no extra tokens were sent until a file matching the pattern was read.
When the session read src/api/handler.ts, the rule set was loaded into context, costing an additional 2,987 tokens. Reading src/ui/button.ts, which does not match the pattern, produced no rule load and saved those tokens. The difference between the two runs—2,987 tokens—matches the size of the rule set minus the surrounding file wrapper.
What This Means for Developers
For projects with large rule sets that only apply to certain directories, path‑scoped rules can dramatically reduce the token footprint of early turns. In the author’s own repository, a 34 KB Claude.md and two rule files (8.9 KB and 0.8 KB) were split so that coding conventions only load when a source file is read. This means that turns focused on documentation or other non‑code tasks incur no cost for the coding rules.
However, the savings only apply to the first request that triggers a matching file. Once the rule set is loaded, it remains in context for subsequent turns, so the overall token cost over a long session is similar to an inline rule set that starts later. The benefit is greatest for agents that run many short, isolated jobs or for unattended scripts that rarely touch the relevant files.
Limitations and Next Steps
The experiment measured token usage, not rule adherence. The documentation warns that files over 200 lines may reduce adherence, but this was not tested. Additionally, the trigger was the Read tool; other file‑access methods such as grep or shell commands may behave differently. Future work will explore these scenarios and confirm whether path‑scoped rules reload after compaction when a matching file is read again.
Developers can reproduce the test by cloning the provided repository and running the same prompts. The results will vary based on the size of the rule set, but the zero‑token baseline for the first request should hold.
For more details, check the author’s blog post on the AI Shop and the RuleStack product page.
Why it matters
By loading rules only when needed, developers can keep Claude Code’s prompt lean, reduce token costs, and improve performance for short, focused tasks.
Key points
- Path‑scoped rules add no tokens until a matching file is read
- Inline and imported rules increase the first request token count by ~3,300 tokens
- Unscoped files behave like imported files, adding ~3,400 tokens
- Once loaded, path‑scoped rules stay in context for subsequent turns
- Savings are most noticeable for agents that rarely touch the scoped files
- Future tests should examine other file‑access methods and adherence impact
Frequently asked questions
What is a path‑scoped rule in Claude Code?
A rule file with a <code>paths</code> front‑matter field that only loads into context when the assistant reads a file matching the specified pattern.
Do path‑scoped rules affect token usage after they are loaded?
No, once a path‑scoped rule is loaded it remains in context for the rest of the session, so subsequent turns incur the same cost as an inline rule that starts later.
Can I use path‑scoped rules with shell commands?
The experiment used the <code>Read</code> tool; other methods like <code>grep</code> or shell commands may trigger rules differently, so you should test your specific workflow.
