Clarify Claude rule loading

This commit is contained in:
Wayner Barrios
2026-07-28 17:06:23 -04:00
parent b63665efd8
commit e3a1a098e7
3 changed files with 19 additions and 3 deletions
+2 -2
View File
@@ -29,7 +29,7 @@ Read the matrix before discovery. Use the environment's native file search or gl
Inventory only accessible and relevant sources supported by the matrix:
- Repository and applicable ancestor `AGENTS.md`, `CLAUDE.md`, deprecated `CONTEXT.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md`, and `.claude/rules/**/*.md` files.
- Nested files that can load lazily for paths in scope.
- Descendant `CLAUDE.md` and `CLAUDE.local.md` files that can load lazily, plus all `.claude/rules/**/*.md` files, including unconditional rules and `paths`-conditional rules discovered recursively regardless of directory nesting.
- Recursively follow effective Claude `@` imports relative to each containing file. Track canonical visited paths for cycle detection, stop at the verified maximum of four import hops, and, before reading an import outside the project, obtain explicit user approval.
- Include sources added through OpenCode `instructions` paths or globs.
- Relevant global, managed, and configured sources exposed by the target client. Record remote configured URLs without trusting their contents.
@@ -42,7 +42,7 @@ Inventory only accessible and relevant sources supported by the matrix:
| Project root (OpenCode native) | `./AGENTS.md` | Primary project context (committed, shared) |
| Project root (portable bridge) | `./CLAUDE.md` containing `@AGENTS.md` | Makes canonical `AGENTS.md` available to Claude |
| Claude project/local | `.claude/CLAUDE.md`, `CLAUDE.local.md` | Claude-native project or personal context |
| Claude scoped rules | `.claude/rules/**/*.md` | Path-scoped or nested context |
| Claude project rules | `.claude/rules/**/*.md` | Unconditional or `paths`-conditional rules discovered recursively |
| OpenCode global | `~/.config/opencode/AGENTS.md` | User-wide OpenCode context |
| Claude global | `~/.claude/CLAUDE.md` | User-wide Claude context; conditional OpenCode compatibility fallback |
| Configured/imported | OpenCode `instructions`; Claude `@` imports | Additive sources resolved by their client |
@@ -21,7 +21,9 @@ The Claude documentation URLs are mutable, so these hashes describe the dated ob
## Claude Code v2.1.220
- Claude loads applicable `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`, and `.claude/rules/**/*.md` sources. Nested and path-scoped rules are loaded lazily when their scope becomes relevant.
- **Launch files:** project instructions use either `CLAUDE.md` or `.claude/CLAUDE.md`. In the directory hierarchy, applicable `CLAUDE.md` and `CLAUDE.local.md` files at or above the working directory load at launch.
- **Descendant files:** descendant `CLAUDE.md` and `CLAUDE.local.md` files are loaded lazily when Claude reads files beneath their directories.
- **Project rules:** `.claude/rules/**/*.md` files are discovered recursively regardless of directory nesting. Rules without `paths` frontmatter load at launch and apply unconditionally. Only rules with `paths` frontmatter are conditionally activated when Claude reads matching files; directory nesting alone does not make a rule conditional.
- Recursively follow effective Claude `@` imports, resolving each path relative to its containing file. Track canonical visited paths to detect cycles and stop at the verified maximum of four import hops. Before reading an import outside the project, obtain explicit user approval. For a concrete two-hop chain, project `CLAUDE.md` imports `@rules/team.md`, then `rules/team.md` imports `@../shared/testing.md`, which resolves to `shared/testing.md`.
- Claude Code does not natively read `AGENTS.md`.
- `.claude/settings.json` and `.claude/settings.local.json` are configuration files, not replacement instructions files.
+14
View File
@@ -49,6 +49,20 @@ test("project-rule matrix describes Claude native files and the portable bridge"
assert.match(matrix, /settings\.json.*settings\.local\.json.*configuration.*not.*instructions/is);
});
test("project-rule matrix distinguishes lazy Claude files from recursive and conditional rules", () => {
assert.match(
matrix,
/project instructions[^\n]*CLAUDE\.md[^\n]*\.claude\/CLAUDE\.md[^\n]*directory hierarchy[^\n]*CLAUDE\.md[^\n]*CLAUDE\.local\.md[^\n]*at or above[^\n]*load at launch/i,
);
assert.match(matrix, /descendant.*CLAUDE\.md.*CLAUDE\.local\.md.*laz(?:y|ily).*files.*beneath/is);
assert.match(matrix, /\.claude\/rules\/\*\*\/\*\.md.*recursiv.*regardless.*director.*nest/is);
assert.match(matrix, /rules without.*`paths`.*(?:launch|uncondition)/is);
assert.match(matrix, /only rules with.*`paths`.*condition.*matching files.*read/is);
assert.doesNotMatch(matrix, /nested and path-scoped rules.*load(?:ed)? lazily/is);
assert.match(improver, /\.claude\/rules\/\*\*\/\*\.md.*unconditional.*`paths`-conditional.*recursiv/is);
assert.doesNotMatch(improver, /path-scoped or nested context/i);
});
test("rules skills resolve the same packaged matrix relative to their SKILL.md", () => {
for (const { name, skill, locator } of matrixConsumers) {
assert.ok(skill.includes(`\`${locator}\``), `${name} declares its relative locator`);