Claude Code / project instruction field notes
Claude Code Rules: CLAUDE.md, path scopes, and conflicts
CLAUDE.md or .claude/CLAUDE.md. Split focused guidance into Markdown files under .claude/rules/. A rule without paths applies broadly; a rule with paths is documented to load when Claude reads a matching file. Keep rules concrete, non-contradictory, and small enough to audit. Do not claim a rule was applied unless a session shows it.We created an isolated rule with marker RULES-LOCAL-9274 and path scope src/**/*.js. The file exists and the CLI reached the authentication boundary, but no InstructionsLoaded event was recorded and no model response was produced. Rule discovery and application are therefore marked untested, not inferred from the file structure.
Choose the instruction surface by scope
| Surface | Best use | Loading boundary |
|---|---|---|
Project CLAUDE.md | Repository-wide commands, architecture facts, and safety rules | Loaded as project instructions for the session |
.claude/rules/*.md without paths | Modular guidance that applies across the project | Documented to load at launch with project instructions |
.claude/rules/*.md with paths | Language, package, or directory-specific guidance | Documented to load when matching files are read |
Nested CLAUDE.md | Guidance local to a subtree | Loaded when Claude works in or reads through that subtree |
~/.claude/CLAUDE.md and ~/.claude/rules/ | Personal preferences across projects | User scope; keep project facts out of it |
A path-scoped rule
---
paths:
- "src/**/*.js"
---
# Evidence boundary
Marker: RULES-LOCAL-9274
Never describe documentation-derived behavior as a local
runtime result. If a model-backed step was not run, label it untested.The marker is deliberately not repeated in the prompt. If an authenticated session later quotes it after reading src/example.js, the output can help show that the matching rule entered context. Even then, quoting a marker proves discovery more directly than it proves faithful execution of every rule.
Official documentation warns that invalid YAML frontmatter causes Claude Code to treat a rule as if it had no paths field. A typo can therefore broaden a rule rather than merely disabling it. Use debug output and an InstructionsLoaded hook when auditing path-specific behavior.
What the local attempt actually returned
The session command targeted project settings and asked Claude to read src/example.js. It stopped before model processing:
"terminal_reason":"api_error"
"result":"Not logged in · Please run /login"
"total_cost_usd":0
"input_tokens":0
"output_tokens":0The configured InstructionsLoaded hook did not create instruction-events.jsonl. That absence does not prove the rule is invalid; it proves only that this unauthenticated attempt produced no captured loading event.
What was tested, and what remains untested
| Claim | Verdict | Evidence |
|---|---|---|
| The rule fixture exists at the documented project path | Tested | Local file inspection found .claude/rules/evidence-boundary.md and its unique marker. |
| The session attempted to start with project settings | Tested | The CLI produced a structured result and stopped at login. |
| The path-scoped rule loaded | Untested | No InstructionsLoaded record was created. |
| The model followed the rule | Untested | No model response occurred. |
| A conflicting rule resolved in a predictable order | Untested | No conflict experiment was run. |
A conflict audit that can be run later
- Put one unique marker and one harmless formatting instruction in the root
CLAUDE.md. - Put a different marker and the opposite formatting instruction in a path-scoped rule.
- Start a fresh authenticated session and read one matching file and one nonmatching file.
- Capture
InstructionsLoadedevents, the model's stated active instructions, and the produced edit separately. - Repeat after
/compact, because root instructions and lazily loaded rules have different reload timing.
Do not put marker values in the prompt, and do not use a production repository for deliberate conflicts. A disposable fixture keeps the result reversible.
FAQ
Are Claude Code rules the same as skills?
No. Rules are persistent project instructions. Skills are reusable task packages invoked when their description or name matches the work.
Does a valid paths glob prove the rule was loaded?
No. The glob describes intended scope. Verify loading with session evidence such as an InstructionsLoaded record and then verify behavior separately.
Why not upgrade just to complete this test?
The owner chose not to purchase a Claude subscription or add an API key. The missing model-backed steps are therefore labeled untested rather than filled with assumptions.