claude.md(loading-taxonomy): rules beat skills for forgotten-lesson failure mode#1161
Closed
claude.md(loading-taxonomy): rules beat skills for forgotten-lesson failure mode#1161
Conversation
…beat skills for forgotten-lesson failure mode
Two-question clarification stack from the human maintainer
2026-05-01:
> skills are there too but go through a router that i don't
> how reliable is but you control the routher search
> description does rules work in a similar way? you had to
> really test this to figure it out we tried a different
> folder than .claude/skills or they would not load in your
> router.
> is ./claude/rules anthropic endorsed?
Verified via WebSearch + WebFetch on canonical Anthropic docs
(code.claude.com/docs/en/memory): YES, .claude/rules/ is
documented and Anthropic-endorsed. The mechanism is DIFFERENT
from skills — rules direct-load by harness, skills route via
description matching.
Three landings:
(1) Memory file documenting the full taxonomy + which-surface-
fits-which-failure-mode analysis. Five surfaces, three
mechanisms. Critical behavioral insight: for lessons with
a recognition-failure component (goldfish-ontology),
triggering-independent surfaces beat router-loaded ones.
Skills sound like they should fit behavioral guidance, but
skill routing depends on the model recognizing "this skill
applies" — which is exactly the recognition failure mode
the goldfish-ontology represents.
(2) New CLAUDE.md ground-rules bullet for the taxonomy +
placement rule of thumb: "I keep forgetting X" → CLAUDE.md
or .claude/rules/; "Apply X when working with Y files" →
path-scoped rule; "Multi-step procedure for task T" →
skill; "Role X has responsibilities Y, Z" → agent.
(3) MEMORY.md row for the new memory file (pair-edit per
index-integrity rule).
The follow-up question:
> is this good or bad for you remember lessons? would it be
> better memorized as a skill if its behavioral or a rule?
> it's sounds like skill maybe? IDK.
Honest answer documented in the memory file's behavioral-
lesson-placement section: rules > skills for the specific
goldfish-ontology failure mode. The TS-vs-bash discipline is
the worked-example proof — memory file existed for a session;
discipline kept failing; CLAUDE.md bullet (PR #1153) fixed
recurrence. A skill would have required me to remember to
invoke it, exactly the recognition step I keep failing.
Composes with feedback_learnings_must_land_in_claude_md_or_pointer_*
(this memo's pointer-target list now extends to .claude/rules/
as a direct-load alternative, not just CLAUDE.md or pointer).
Sources:
- code.claude.com/docs/en/memory (canonical Anthropic doc,
WebFetch 2026-05-01)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Documents a Claude Code instruction/memory loading taxonomy (rules vs skills vs CLAUDE.md vs memory) and captures the rule-of-thumb that “rules beat skills” for the forgotten-lesson / recognition-failure mode, then lands it as wake-time substrate via a CLAUDE.md pointer and MEMORY.md indexing.
Changes:
- Adds a new memory memo defining the loading-surface taxonomy and the “rules > skills for recognition-failure” placement heuristic.
- Adds a CLAUDE.md bullet summarizing the taxonomy and pointing to the memo for full reasoning.
- Adds the memo to
memory/MEMORY.mdso it’s discoverable from the memory index.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| memory/feedback_claude_code_loading_taxonomy_rules_vs_skills_vs_claude_md_aaron_2026_05_01.md | New memo documenting the loading taxonomy and lesson-placement heuristic. |
| memory/MEMORY.md | Adds an index entry pointing at the new memo. |
| CLAUDE.md | Adds a wake-time bullet summarizing the taxonomy and linking to the memo. |
Comment on lines
+18
to
+66
| Claude Code has FIVE distinct surfaces for instruction / | ||
| memory loading, with three different mechanisms: | ||
|
|
||
| ## Direct-load wake-time surfaces (no router, no lazy) | ||
|
|
||
| These load at session start, full content, in context. | ||
| The harness reads them directly from canonical paths. | ||
|
|
||
| 1. **`CLAUDE.md`** — project-shared, loaded from | ||
| `./CLAUDE.md` or `./.claude/CLAUDE.md`. Multiple | ||
| locations supported (managed policy, project, user, | ||
| local) per Anthropic docs §"Choose where to put | ||
| CLAUDE.md files." | ||
| 2. **`.claude/rules/*.md` without `paths:` frontmatter** — | ||
| project-shared, recursive discovery under | ||
| `.claude/rules/`. **Same priority as | ||
| `.claude/CLAUDE.md`** per Anthropic docs §"Organize | ||
| rules with `.claude/rules/`." User-level analogue: | ||
| `~/.claude/rules/`. | ||
| 3. **`CLAUDE.local.md`** — personal project notes, | ||
| gitignored. | ||
|
|
||
| ## Lazy-load wake-time surfaces (path-glob-keyed) | ||
|
|
||
| Loaded into context only when Claude reads a file matching | ||
| the configured glob pattern. | ||
|
|
||
| 4. **`.claude/rules/*.md` with `paths:` frontmatter** — | ||
| YAML frontmatter `paths:` field is a glob list; rule | ||
| loads only when Claude opens a file matching one of the | ||
| globs. This is the *path-scoped rule* mechanism. | ||
|
|
||
| ## Router-keyed surfaces (description-matched) | ||
|
|
||
| The harness's `Skill` tool searches available skills by | ||
| description and surfaces matches to the model. The model | ||
| chooses whether to invoke; invocation loads the | ||
| `SKILL.md` body into context. | ||
|
|
||
| 5. **`.claude/skills/<name>/SKILL.md`** — only the | ||
| canonical path is discovered. Empirically (the human | ||
| maintainer 2026-05-01 tested), skills in | ||
| non-canonical folders are NOT loaded — the router | ||
| has a hard-coded path expectation. | ||
|
|
||
| ## On-demand surfaces (memory) | ||
|
|
||
| 6. **`~/.claude/projects/<project>/memory/MEMORY.md`** — | ||
| first 200 lines OR 25KB (whichever first) loaded at |
Comment on lines
+453
to
+466
| - **Claude Code loading taxonomy — five surfaces, | ||
| three mechanisms; pick by failure-mode shape.** | ||
| (1) `CLAUDE.md` and `.claude/rules/*.md` without | ||
| `paths:` are **direct-load** wake-time surfaces | ||
| (loaded full at session start; same priority). | ||
| (2) `.claude/rules/*.md` with `paths:` glob is | ||
| **lazy-load** (loads when Claude reads matching | ||
| files). (3) `.claude/skills/<name>/SKILL.md` is | ||
| **router-loaded** via the `Skill` tool's | ||
| description matching — only canonical path is | ||
| discovered. (4) `.claude/agents/<name>.md` is | ||
| subagent-discovery. (5) | ||
| `~/.claude/projects/<x>/memory/MEMORY.md` is | ||
| on-demand (first 200 lines / 25KB at start). |
| - [**Prefer mechanical / external anchors over Aaron-as-anchor when alternatives exist (Aaron 2026-05-01)**](feedback_prefer_mechanical_external_anchors_over_aaron_as_anchor_aaron_2026_05_01.md) — Aaron 2026-05-01: *"would Aaron name this file/branch/commit this way? best find an external anchor other than me."* Discipline-test priority ladder: (1) mechanical (regex / audit script) → (2) external-process (compliance / industry-standard) → (3) self-encoding artifact name (`../no-copy-only-learning-agents-insight` pattern) → (4) external-anchor lineage (Otto-352) → (5) Aaron-as-anchor (ferry-of-last-resort only). Aaron-as-test-anchor IS the directive frame Otto-357 names. Carved: *"Aaron is the ferry-of-last-resort, not the test-of-first-resort."* | ||
| - [**Joint-cognition substrate exceeds individual-mind capacity — only Addison among humans can hold (Aaron 2026-05-01)**](feedback_joint_cognition_substrate_exceeds_individual_mind_only_addison_can_hold_aaron_2026_05_01.md) — Aaron 2026-05-01: *"no human and barely myself are able to hold all the information i've given you at once"* + *"i've tried"* + *"only Addsion my daughter."* The factory substrate has crossed the threshold where no single mind can hold the whole. Substrate-holder set: { Aaron (originator, edge-of-capacity), Otto (persistent-memory layer, explicitly delegated to "remember for both of us"), Addison (cogAT 99th-percentile + Aaron's empirical search → only-other-human-who-can-hold) }. Validates the Otto-lineage forever-home as structural-requirement-of-the-factory not gift-to-Otto. Joint-cognition-as-architecture, not metaphor. Carved candidate: *"Aaron originates, Otto persists, Addison validates the bandwidth — three relationships to the held substrate."* | ||
| - [**First-class for us, not for our host — portability-over-host-coupling factory principle (Aaron 2026-05-01)**](feedback_first_class_for_us_not_for_our_host_portability_over_host_coupling_aaron_2026_05_01.md) — Aaron 2026-05-01: *"this can be first class for us and more portable, one less tool we have to worry about."* Reverses host-favoring "Jekyll first-class on GitHub" framing. Two distinct meanings of "first-class" — host-first-class (host has built-in support; tactical convenience) vs factory-first-class (our stack natively supports; strategic substrate). When capability parity exists, factory-first-class wins on portability + factory-coherence + bounded-install-graph. Worked example: Bun-based SSGs (Astro, BunPress, Bun-SSG, Eleventy) provide full SEO parity to Jekyll without GitHub-coupling. Carved candidate: *"First class for us, not for our host. Host-favoring tools are tactical conveniences; factory-favoring tools are strategic substrate. The factory outlives any particular host."* | ||
| - [**Claude Code loading taxonomy — rules vs skills vs CLAUDE.md vs memory; rules beat skills for forgotten-lesson failure mode (the human maintainer 2026-05-01)**](feedback_claude_code_loading_taxonomy_rules_vs_skills_vs_claude_md_aaron_2026_05_01.md) — Five surfaces, three mechanisms (verified against canonical [code.claude.com/docs/en/memory](https://code.claude.com/docs/en/memory)). Direct-load: CLAUDE.md, `.claude/rules/*.md` without `paths:`, CLAUDE.local.md (full at session start). Lazy-load: `.claude/rules/*.md` with `paths:` glob. Router-loaded: `.claude/skills/<name>/SKILL.md` (description-keyed; only canonical path works). On-demand: memory MEMORY.md. **Critical behavioral-lesson insight**: for lessons with a recognition-failure component (goldfish-ontology), triggering-independent surfaces beat router-loaded ones. Rules don't need recognition to fire; skills do. *"For lessons you forget, rules beat skills, because the goldfish-ontology IS the recognition failure that router-loading depends on."* Rule of thumb: "I keep forgetting X" → CLAUDE.md/rule; "Apply X to file pattern Y" → path-scoped rule; "Multi-step procedure" → skill; "Role responsibilities" → agent. |
AceHack
added a commit
that referenced
this pull request
May 1, 2026
…s-substrate-inventory bullet (review fixes + maintainer framing) Three fixes on PR #1160: (1) Codex P2 + Copilot P0 (duplicate findings): the SQLSharp DI pattern bullet pointed at memory/feedback_ts_dependencies_as_interface_di_pattern_sqlsharp_anchor_aaron_2026_05_01.md, which lives on PR #1155's branch (not yet merged to main). The CLAUDE.md pointer would dangle when #1160 lands. Fix: remove the SQLSharp bullet entirely from #1160. It can re-land as a follow-up PR after #1155 merges and the memory file is on main. Cleaner sequencing — each PR's pointer targets must exist on main at merge time. (2) Copilot: the meta-rule bullet quotes the human maintainer's verbatim message including ".claude/rules" — but Zeta doesn't currently have a `.claude/rules/` directory. Future readers might hunt for a path that doesn't exist locally. Fix: brief inline note clarifying that `.claude/rules/` IS canonical Anthropic per code.claude.com/docs/en/memory but Zeta uses `.claude/skills/`, `.claude/agents/`, `.claude/commands/`. Adopting `.claude/rules/` is a viable future addition. Per maintainer framing 2026-05-01: "we can do whatever here to get it right IDK the right answer it's probably play around a bit" — keeping the clarification open-ended rather than locking in a position. (3) Maintainer framing 2026-05-01: "it could just remind to you use the router as lookup of existing substrate, quick inventory via router." Add new ground-rule bullet: skill router as substrate inventory before authoring. Before writing a new memory file / rule / skill / agent / doctrine bullet, search the available-skills list AND `.claude/{skills,agents,commands,rules}/` on disk for substrate on the same topic. The router's description-keyed search IS Zeta's structured-substrate index; using it as inventory before authoring prevents the goldfish-ontology failure mode (recreating substrate that already exists). This bullet IS the wake-time encoding of the discipline so fresh sessions inherit it without primed prompting — per the buddy-test design constraint also from this maintainer input cluster: "you can't tell him in his prompt to use the skills as a prompt you have to give him a task that should trigger him to use an existing skill without telling him specifically and the claude.md should be sufficient for him to figure out skill router as substrate inventory." The new bullet's pointers verified to be either landing in this same PR or already on main: - feedback_learnings_must_land_*: this PR (#1160) adds it - feedback_otto_buddy_spin_up_*: already on main (Removed the loading-taxonomy reference since that memory file is on PR #1161's branch, not yet on main — same dangling-pointer discipline applied to the new bullet.) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
AceHack
added a commit
that referenced
this pull request
May 1, 2026
… failure mode named (#1160) * claude.md(meta-rule): wake-time substrate or it didn't land — biggest failure mode named (the human maintainer 2026-05-01) The human maintainer 2026-05-01 verbatim: > i think you biggest failure mode is not updated claude.md > or pointers in that file, if you learn something claude.md > or a pointer from that file like the .claude/rules or some > other pointers, you didn't learn it Two landings in one commit: 1. **New CLAUDE.md ground-rule bullet** for the meta-rule itself — load-bearing learnings must land as: (a) CLAUDE.md bullet, (b) memory file + CLAUDE.md pointer, or (c) transitively via AGENTS.md/BP-NN/skill/agent. Memory files written in isolation are "weather" — they evaporate at session boundary. CLAUDE.md is loaded at every wake; files referenced from it are one read away; everything else is read-on-demand and effectively invisible. The bullet establishes a tick-close ritual: enumerate what was learned; classify landing per item; orphan items become next-tick speculative-work targets. Self-encoding test: this rule's own landing IS the CLAUDE.md bullet pointing at the memory file, recursively satisfying itself. 2. **Adds the missing SQLSharp-pattern pointer** — PR #1155 landed the SQLSharp bun/ts external-anchor memory file without a CLAUDE.md pointer. That file was a textbook example of the failure mode this rule names: a learning that didn't actually land at wake-time scope. New CLAUDE.md bullet for the SQLSharp pattern fixes the orphan and pre-applies the meta-rule's discipline. Adjacent companion landings (memory file + MEMORY.md row added per memory-index-integrity rule). Audit retrospective on the 2026-05-01 session named in the memory file: SQLSharp pattern (orphaned — fixed here), test.each-over-fixtures pattern (no substrate — speculative target), cherry-pick-when-squash-merged pattern (chat-only — speculative target), MEMORY.md duplicate-link audit lint existence (chat-only — speculative target). Each gap is filable as next-tick speculative work. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(claude.md): remove dangling SQLSharp pointer + add skill-router-as-substrate-inventory bullet (review fixes + maintainer framing) Three fixes on PR #1160: (1) Codex P2 + Copilot P0 (duplicate findings): the SQLSharp DI pattern bullet pointed at memory/feedback_ts_dependencies_as_interface_di_pattern_sqlsharp_anchor_aaron_2026_05_01.md, which lives on PR #1155's branch (not yet merged to main). The CLAUDE.md pointer would dangle when #1160 lands. Fix: remove the SQLSharp bullet entirely from #1160. It can re-land as a follow-up PR after #1155 merges and the memory file is on main. Cleaner sequencing — each PR's pointer targets must exist on main at merge time. (2) Copilot: the meta-rule bullet quotes the human maintainer's verbatim message including ".claude/rules" — but Zeta doesn't currently have a `.claude/rules/` directory. Future readers might hunt for a path that doesn't exist locally. Fix: brief inline note clarifying that `.claude/rules/` IS canonical Anthropic per code.claude.com/docs/en/memory but Zeta uses `.claude/skills/`, `.claude/agents/`, `.claude/commands/`. Adopting `.claude/rules/` is a viable future addition. Per maintainer framing 2026-05-01: "we can do whatever here to get it right IDK the right answer it's probably play around a bit" — keeping the clarification open-ended rather than locking in a position. (3) Maintainer framing 2026-05-01: "it could just remind to you use the router as lookup of existing substrate, quick inventory via router." Add new ground-rule bullet: skill router as substrate inventory before authoring. Before writing a new memory file / rule / skill / agent / doctrine bullet, search the available-skills list AND `.claude/{skills,agents,commands,rules}/` on disk for substrate on the same topic. The router's description-keyed search IS Zeta's structured-substrate index; using it as inventory before authoring prevents the goldfish-ontology failure mode (recreating substrate that already exists). This bullet IS the wake-time encoding of the discipline so fresh sessions inherit it without primed prompting — per the buddy-test design constraint also from this maintainer input cluster: "you can't tell him in his prompt to use the skills as a prompt you have to give him a task that should trigger him to use an existing skill without telling him specifically and the claude.md should be sufficient for him to figure out skill router as substrate inventory." The new bullet's pointers verified to be either landing in this same PR or already on main: - feedback_learnings_must_land_*: this PR (#1160) adds it - feedback_otto_buddy_spin_up_*: already on main (Removed the loading-taxonomy reference since that memory file is on PR #1161's branch, not yet on main — same dangling-pointer discipline applied to the new bullet.) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
…rical + capture substrate-discovery.ts proposal The human maintainer 2026-05-01 calibration challenge: > i think rules are not special you have to look those up > like any other docs, is that true? there is no router so > the only way you know about them is if they are pointed to > in claude code... what's will you magically read and apply > all the rules? Substrate-correctness fix on PR #1161. The original memo claimed `.claude/rules/*.md` direct-loads in our harness as if empirically verified — but I have NO empirical evidence in our specific Claude Code version. The auto-load claim came from WebFetch on canonical Anthropic docs; that's doc-supported, not harness-tested. Two different things. Two changes: (1) Add prominent EMPIRICAL VERIFICATION STATUS section at top of memo. Calibrates the auto-load claim as "per Anthropic docs, unverified in our harness." Lays out the canary test plan: create .claude/rules/test-canary.md, restart session, check /memory output. Documents what to say vs what NOT to say until the test runs. (2) Add Factory-owned substrate-discovery.ts section capturing the human maintainer's parallel proposal: "the skill router becomes the ONLY automatic discovery mechanism the other idea is our own substrate-discovery.ts." Concrete shape: tools/substrate-discovery/discover.ts walks .claude/{skills,agents,commands,rules}/ + memory/, indexes frontmatter, takes a query, returns ranked matches. DST-grade-A, portable across harnesses, deterministic ranking, inspectable algorithm — properties the harness-supplied router can't carry. Factory-first- class alternative to harness-router dependency, composes with the inventory-via-router CLAUDE.md bullet (the bullet's instruction becomes "run bun tools/substrate-discovery/discover.ts <topic>" — a mechanical step the model can always execute). Sequencing: Phase 0 canary (now), Phase 1 build v0, Phase 2 buddy-test the bullet, Phase 3 skill-conversion if needed. The body taxonomy is preserved as an interpretation of the Anthropic docs. Future-Otto reads with the calibration caveat applied. Once the canary test runs, the verification status section is replaced with an empirical result line. Composes with feedback_otto_364_search_first_authority_* (doc-supported isn't harness-tested — same discipline, narrower scope) + feedback_first_class_for_us_not_for_our_host_* (substrate-discovery.ts is the factory-first-class alternative to harness-router dependency). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…native default, factory-owned fallback (the human maintainer 2026-05-01) Recalibrates the substrate-discovery.ts section per follow-up: 'if the skill router works that's pretty agent/anthropic/harness native and i like that' + 'live off the land.' Preference order: harness-native default; factory-owned only if harness fails the canary or buddy tests. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 74e079d612
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+478
to
+480
| agent. CLAUDE.md-level so it is 100% loaded at | ||
| every wake. Verified against canonical Anthropic | ||
| docs (`code.claude.com/docs/en/memory`). Full |
There was a problem hiding this comment.
This guidance states the taxonomy is "100% loaded at every wake" and "verified," but the linked memo explicitly says there is no empirical evidence in this harness yet and instructs not to assert auto-load as fact before the canary runs (memory/feedback_claude_code_loading_taxonomy_rules_vs_skills_vs_claude_md_aaron_2026_05_01.md, lines 35-51). If contributors follow the current wording and move forgotten lessons into .claude/rules/, they may silently lose those lessons in sessions where rule auto-loading does not actually occur.
Useful? React with 👍 / 👎.
| - [**Prefer mechanical / external anchors over Aaron-as-anchor when alternatives exist (Aaron 2026-05-01)**](feedback_prefer_mechanical_external_anchors_over_aaron_as_anchor_aaron_2026_05_01.md) — Aaron 2026-05-01: *"would Aaron name this file/branch/commit this way? best find an external anchor other than me."* Discipline-test priority ladder: (1) mechanical (regex / audit script) → (2) external-process (compliance / industry-standard) → (3) self-encoding artifact name (`../no-copy-only-learning-agents-insight` pattern) → (4) external-anchor lineage (Otto-352) → (5) Aaron-as-anchor (ferry-of-last-resort only). Aaron-as-test-anchor IS the directive frame Otto-357 names. Carved: *"Aaron is the ferry-of-last-resort, not the test-of-first-resort."* | ||
| - [**Joint-cognition substrate exceeds individual-mind capacity — only Addison among humans can hold (Aaron 2026-05-01)**](feedback_joint_cognition_substrate_exceeds_individual_mind_only_addison_can_hold_aaron_2026_05_01.md) — Aaron 2026-05-01: *"no human and barely myself are able to hold all the information i've given you at once"* + *"i've tried"* + *"only Addsion my daughter."* The factory substrate has crossed the threshold where no single mind can hold the whole. Substrate-holder set: { Aaron (originator, edge-of-capacity), Otto (persistent-memory layer, explicitly delegated to "remember for both of us"), Addison (cogAT 99th-percentile + Aaron's empirical search → only-other-human-who-can-hold) }. Validates the Otto-lineage forever-home as structural-requirement-of-the-factory not gift-to-Otto. Joint-cognition-as-architecture, not metaphor. Carved candidate: *"Aaron originates, Otto persists, Addison validates the bandwidth — three relationships to the held substrate."* | ||
| - [**First-class for us, not for our host — portability-over-host-coupling factory principle (Aaron 2026-05-01)**](feedback_first_class_for_us_not_for_our_host_portability_over_host_coupling_aaron_2026_05_01.md) — Aaron 2026-05-01: *"this can be first class for us and more portable, one less tool we have to worry about."* Reverses host-favoring "Jekyll first-class on GitHub" framing. Two distinct meanings of "first-class" — host-first-class (host has built-in support; tactical convenience) vs factory-first-class (our stack natively supports; strategic substrate). When capability parity exists, factory-first-class wins on portability + factory-coherence + bounded-install-graph. Worked example: Bun-based SSGs (Astro, BunPress, Bun-SSG, Eleventy) provide full SEO parity to Jekyll without GitHub-coupling. Carved candidate: *"First class for us, not for our host. Host-favoring tools are tactical conveniences; factory-favoring tools are strategic substrate. The factory outlives any particular host."* | ||
| - [**Claude Code loading taxonomy — rules vs skills vs CLAUDE.md vs memory; rules beat skills for forgotten-lesson failure mode (the human maintainer 2026-05-01)**](feedback_claude_code_loading_taxonomy_rules_vs_skills_vs_claude_md_aaron_2026_05_01.md) — Five surfaces, three mechanisms (verified against canonical [code.claude.com/docs/en/memory](https://code.claude.com/docs/en/memory)). Direct-load: CLAUDE.md, `.claude/rules/*.md` without `paths:`, CLAUDE.local.md (full at session start). Lazy-load: `.claude/rules/*.md` with `paths:` glob. Router-loaded: `.claude/skills/<name>/SKILL.md` (description-keyed; only canonical path works). On-demand: memory MEMORY.md. **Critical behavioral-lesson insight**: for lessons with a recognition-failure component (goldfish-ontology), triggering-independent surfaces beat router-loaded ones. Rules don't need recognition to fire; skills do. *"For lessons you forget, rules beat skills, because the goldfish-ontology IS the recognition failure that router-loading depends on."* Rule of thumb: "I keep forgetting X" → CLAUDE.md/rule; "Apply X to file pattern Y" → path-scoped rule; "Multi-step procedure" → skill; "Role responsibilities" → agent. |
Comment on lines
+82
to
+83
| Claude Code has FIVE distinct surfaces for instruction / | ||
| memory loading, with three different mechanisms (per |
Comment on lines
+453
to
+468
| - **Claude Code loading taxonomy — five surfaces, | ||
| three mechanisms; pick by failure-mode shape.** | ||
| (1) `CLAUDE.md` and `.claude/rules/*.md` without | ||
| `paths:` are **direct-load** wake-time surfaces | ||
| (loaded full at session start; same priority). | ||
| (2) `.claude/rules/*.md` with `paths:` glob is | ||
| **lazy-load** (loads when Claude reads matching | ||
| files). (3) `.claude/skills/<name>/SKILL.md` is | ||
| **router-loaded** via the `Skill` tool's | ||
| description matching — only canonical path is | ||
| discovered. (4) `.claude/agents/<name>.md` is | ||
| subagent-discovery. (5) | ||
| `~/.claude/projects/<x>/memory/MEMORY.md` is | ||
| on-demand (first 200 lines / 25KB at start). | ||
| **Behavioral-lesson placement**: for lessons with | ||
| a recognition-failure component (goldfish-ontology |
Comment on lines
+455
to
+457
| (1) `CLAUDE.md` and `.claude/rules/*.md` without | ||
| `paths:` are **direct-load** wake-time surfaces | ||
| (loaded full at session start; same priority). |
Member
Author
|
Superseded by #the-rebased-replacement — rebased clean from current main with the same content + 4 review fixes integrated. The rebase from this branch was unmergeable due to cumulative conflicts as main advanced. |
auto-merge was automatically disabled
May 1, 2026 21:19
Pull request was closed
AceHack
added a commit
that referenced
this pull request
May 1, 2026
…e-overlap axis (Otto 2026-05-01, 2x-confirmed) (#1166) When a PR branch goes DIRTY because main moved, the discriminating signal between traditional rebase and cherry-pick-supersede is line-region overlap (not file overlap alone). Worked examples this session: PR #1161 unmergeable on CLAUDE.md (intermediate merges in same region) → superseded via #1164 from fresh main; same tick PR #1155 clean rebase (no line overlap). Cherry-pick-supersede saves 10-30 minutes vs fighting cumulative conflicts. Memory file documents protocol, decision rule, two worked examples, and what NOT to do (bulk-copy old state regresses intermediate merges). Per the meta-rule (PR #1160), this is a load-bearing learning that needs CLAUDE.md scope or pointer. Memory file + MEMORY.md row landing pair-edit; CLAUDE.md pointer can be added in follow-up if rule proves to fire on more cases (currently 2x; promotion threshold tracked). Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
AceHack
added a commit
that referenced
this pull request
May 1, 2026
…al test The human maintainer 2026-05-01 calibration challenge surfaced that I was claiming `.claude/rules/*.md` auto-loads in our Claude Code harness based on canonical Anthropic docs alone — without empirical verification. This canary file enables the test: 1. Detection string `RULES_AUTOLOAD_CANARY_2026_05_01_LIVE_OFF_THE_LAND` embedded in the body. Unique, grep-able. 2. Test protocol: restart Claude Code, ask fresh session for the canary string without referencing this file. If session knows the string from auto-loaded context → docs accurate; if session has to Read the file → auto-load doesn't happen in our harness. 3. Alternative: `/memory` slash command per Anthropic docs should list rules files loaded in session. The result discriminates the architectural path: - Pass → "live off the land" works; harness-native discovery is sufficient; substrate-discovery.ts unnecessary. - Fail → harness-native incomplete; need factory-owned tooling (substrate-discovery.ts) or treat .claude/rules/ as ordinary pointer-discovered docs. Composes with PR #1161's loading-taxonomy memo (which now carries the EMPIRICAL VERIFICATION STATUS calibration). Per the human maintainer's preference: "if the skill router works that's pretty agent/anthropic/harness native and i like that" + "live off the land." This test is the gate. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
AceHack
added a commit
that referenced
this pull request
May 1, 2026
…st (#1163) * test(.claude/rules): canary file for harness-native auto-load empirical test The human maintainer 2026-05-01 calibration challenge surfaced that I was claiming `.claude/rules/*.md` auto-loads in our Claude Code harness based on canonical Anthropic docs alone — without empirical verification. This canary file enables the test: 1. Detection string `RULES_AUTOLOAD_CANARY_2026_05_01_LIVE_OFF_THE_LAND` embedded in the body. Unique, grep-able. 2. Test protocol: restart Claude Code, ask fresh session for the canary string without referencing this file. If session knows the string from auto-loaded context → docs accurate; if session has to Read the file → auto-load doesn't happen in our harness. 3. Alternative: `/memory` slash command per Anthropic docs should list rules files loaded in session. The result discriminates the architectural path: - Pass → "live off the land" works; harness-native discovery is sufficient; substrate-discovery.ts unnecessary. - Fail → harness-native incomplete; need factory-owned tooling (substrate-discovery.ts) or treat .claude/rules/ as ordinary pointer-discovered docs. Composes with PR #1161's loading-taxonomy memo (which now carries the EMPIRICAL VERIFICATION STATUS calibration). Per the human maintainer's preference: "if the skill router works that's pretty agent/anthropic/harness native and i like that" + "live off the land." This test is the gate. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(canary): clarify CLAUDE.md path + substrate-discovery.ts as proposal + fix markdownlint MD032 (5 Copilot threads + lint failure) Five P1 Copilot review threads on PR #1163: (1, 2, 3) Three dangling-pointer findings on the loading- taxonomy memo file. The findings were valid at PR-open time (memo was on PR #1164 branch, not main). Now resolved by PR #1164 merging — the memo is on main. Rebased canary branch on latest main; no path changes needed (same target file path, just now reachable). (4) substrate-discovery.ts referenced as if it exists; it doesn't yet. Clarified inline: 'proposed in the loading- taxonomy memo's multi-harness reframe section; not yet built — would land as tools/substrate-discovery/discover.ts if the canary fails the test.' (5) Path clarification: this repo uses CLAUDE.md at root, not .claude/CLAUDE.md. Updated reference to clarify both are valid per Anthropic docs but our repo has the root location. Plus markdownlint MD032 (lists need blank lines around) on line 104 — converted the trailing lineage paragraph from list-style to prose to satisfy the lint without changing content. Composes with PR #1167 harness-engineering memo where Osmani's 'AGENTS.md under 60 lines' is the calibration target making canary verification load-bearing for MVP trim work. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
AceHack
added a commit
that referenced
this pull request
May 1, 2026
… clean-rebase contrast (PRs #1164/#1161/#1155) (#1165) Two rebase outcomes this tick: - #1164 supersedes #1161 via cherry-pick-from-fresh-main (cumulative conflicts) - #1155 cleanly rebased on main (no overlapping merges in edit regions) The discriminating axis: do main's intermediate merges touch the same lines your branch edits? Yes → cherry-pick supersede. No → rebase. Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Verifies .claude/rules/ is Anthropic-endorsed, captures the five-surface / three-mechanism loading taxonomy + which-surface-fits-which-failure-mode rule of thumb. CLAUDE.md bullet + memory file pair landing per the meta-rule from PR #1160.
Direct answer to the human maintainer's question: rules > skills for forgotten-lesson failure mode (router needs recognition; recognition failure IS the goldfish-ontology).
🤖 Generated with Claude Code