Skip to content

docs(claude): move single-scope guidance out of the root CLAUDE.md - #143

Merged
rodrigorjsf merged 2 commits into
mainfrom
docs/claude-md-restructure
Oct 10, 2026
Merged

rodrigorjsf merged 2 commits into
mainfrom
docs/claude-md-restructure

Conversation

@rodrigorjsf

Copy link
Copy Markdown
Owner

What this changes

Documentation and agent guidance only. No source, test logic or behavior changes.

The root CLAUDE.md loads in every session and had grown to 277 lines against a 200-line limit.
About a third of its Applied Learning bullets apply to one file pattern each. This moves them to
path-scoped rules, which load only when a matching file is touched. The root is now 186 lines.

Where things went

From the root To Loads when
6 snapshot and fixture bullets, plus the 3 corpus-count bullets as one line new .claude/rules/behavior-gate.md tests/behavior/**, tests/fixtures/**, pattern_defaults.py
25 vocabulary-guard, tree-sitter and detection bullets new .claude/rules/framework-parsers.md the three framework packages, framework.py, framework_*.py, the vocabulary guard tests
5 CLI and fake traps .claude/rules/tests.md tests/**/*.py
Spec execution workflow (27 lines) new docs/agents/spec-workflow.md, with a pointer under Agent skills read on demand
The drift schedule's two human steps .claude/skills/upstream-sync/SKILL.md § 1 when the skill runs

Also in the root:

  • Deleted, because a rule already says it: the fingerprint invariant and the discovered analyzer
    registry (analyzers.md), the meta stage's rewritten fields and the per-skill baseline
    (suppression.md).
  • Merged near-duplicates: gh body edits (3 → 1), CRLF noise (2 → 1), Ticket PR checks (2 → 1),
    mutation testing (2 → 1).
  • Code search shrinks to what the maintainer's global instructions do not already say.

Every original bullet is either present verbatim in the root or a rule, or is one of the merges and
deletions listed here. I checked that by comparing the old bullet list against the new files.

Two corrections

  • A wrong bullet. "Renaming a vocabulary constant: … no test covers them" was false.
    contrib/vocabulary_sweep/tests/test_readers.py covers both role maps; it sits outside
    make test, which is probably how the bullet came to say otherwise.
  • The squashed-sync repair (second commit). The sync skill and a bullet gave the repair as
    git merge -s ours upstream/main. That is only right while upstream has not moved. Once it has,
    the merge records commits nobody integrated as already merged, and the next sync skips them with
    no conflict to show it. The command now names the commit the sync merged, and the section says how
    the repair lands. PR merge: sync with NVIDIA/SkillSpector 2.12.0 #142 was squashed despite the warning in its body, so this was needed again.

Not changed, on purpose

  • "Squash-merge Ticket PRs; DCO checks every merge commit inside the PR range." ci.yml appears
    to exempt a multi-parent merge whose committer is noreply@github.com, which would make this
    bullet imprecise. I have not measured it, so it stays as it is.
  • .claude/rules/license-compliance.md is 156 lines and loads on every .py and .md. It is
    the compliance rule; I did not trim it.
  • .gitattributes eol=lf would retire the CRLF bullets, but it renormalizes the tree of a fork
    that still merges upstream.

Verification

  • tests/unit/test_upstream_drift_workflow.py, which reads the sync skill: 18 passed.
  • Every path the moved text points to exists.
  • Total line count across the touched files went up by a few lines (rule frontmatter and intros);
    always-loaded content went down by 91.

The root file was 277 lines against a 200-line limit, and about a third
of its Applied Learning bullets apply to one file pattern each while
loading in every session.

- Thirty-six bullets move to path-scoped rules, unchanged: the
  snapshot and fixture ones to a new behavior-gate rule, the vocabulary
  guard, tree-sitter and detection ones to a new framework-parsers rule,
  and five CLI and fake traps into the existing tests rule.
- Four bullets are deleted because a rule already states them: the
  fingerprint invariant, the meta stage's rewritten fields, the per-skill
  baseline, and the discovered analyzer registry.
- Four clusters of near-duplicates become one bullet each: gh body
  edits, CRLF noise, Ticket PR checks, and mutation testing. The three
  corpus-count bullets become one line in the behavior-gate rule.
- The bullet saying no test covers the vocabulary_sweep role maps was
  wrong; contrib/vocabulary_sweep/tests/test_readers.py does, outside
  make test.
- The Spec execution workflow moves to docs/agents/spec-workflow.md, the
  drift schedule's two human steps move into the upstream-sync skill,
  and Code search shrinks to what the user's global instructions do not
  already say.

The root is now 186 lines. No instruction was dropped: every original
bullet is present verbatim in the root or a rule, or is one of the
merges and deletions listed above.

Signed-off-by: Rodrigo França <20980109+rodrigorjsf@users.noreply.github.com>
The upstream-sync skill and an Applied Learning bullet both gave the
repair as 'git merge -s ours upstream/main'. That is right only while
upstream has not moved. Once it has, the ours merge records commits
nobody integrated as already merged, and the next sync skips them
without a conflict to reveal it.

The command now names the synced commit, the verification says what the
drift count should be when upstream has moved, and the section records
how the repair lands: a fast-forward push the maintainer approves, since
a pull request goes back through the buttons that removed the parent.
PR #142 was squashed despite the warning at the top of its body, which
is the second time.

Signed-off-by: Rodrigo França <20980109+rodrigorjsf@users.noreply.github.com>
@rodrigorjsf
rodrigorjsf merged commit df0db41 into main Oct 10, 2026
6 checks passed
@rodrigorjsf
rodrigorjsf deleted the docs/claude-md-restructure branch October 10, 2026 19:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant