docs(claude): lean CLAUDE.md index + path-scoped rules, and a standards-check skill#73
Merged
Merged
Conversation
added 3 commits
July 20, 2026 11:39
…/rules CLAUDE.md becomes a lean, always-loaded index (the change loop, the gate, required skills, and a rule-file table). The detailed working agreement moves into path-scoped .claude/rules/*.md so each area loads into context only when its code is edited, keeping the always-on context small. One rule file per area: code-standards, architecture, configuration, api, permissions, ingestion, mcp, database, vector-db, testing, and skills (the required review/verify skills).
…working agreement The /standards-check skill maps each changed file to the rule files that govern it (via their paths: globs), reads CLAUDE.md + those rules live, and reports a per-standard pass/warn/fail checklist with file:line references and fixes. Report-first; complements /code-review (bugs) and the ruff/mypy/pytest gate (mechanical).
Ignore .claude/settings.local.json in-repo (it was only excluded via a machine-global gitignore, so a fresh clone could leak it), while CLAUDE.md and .claude/{rules,skills}/ stay committed and travel with the project.
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
1 participant
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.
What & why
CLAUDE.mdhad grown to ~7.4 KB of always-loaded working-agreement detail — most of it irrelevant to any given task, which bloats the model's context every session. This restructures it so the right guidance loads at the right time.CLAUDE.mdis now a lean, always-loaded index (~5.4 KB): the change loop, the gate, the required skills, and a table pointing at the rule files..claude/rules/*.mdfiles. Each carries apaths:front-matter glob, so Claude Code loads it into context only when its code is edited, and leaves it out otherwise./standards-checkskill (.claude/skills/standards-check/) audits a change set against these rules and reports a per-standard pass/warn/fail checklist withfile:linereferences and fixes. It reads the rules live, so it never drifts from them..gitignorehardened so.claude/{rules,skills}/travel with the repo on any clone, while.claude/settings.local.jsonstays local (it was previously only excluded via a machine-global gitignore).Rule files
code-standards,architecture,configuration,api,permissions,ingestion,mcp,database,vector-db,testing,skills. The four new subsystem docs (api,permissions,ingestion,mcp) were written from the actual code, not invented.How it fits together
The mandate to run the skills lives in the always-loaded
CLAUDE.md(§ The loop, § Required skills); the detail (when / how / order) lives in the path-scoped.claude/rules/skills.md./standards-checkreads all of.claude/rules/, so the checker is itself aware of the standards — including which skills must run.Reviewer notes
api/,worker/,tests/are untouched. This is docs + AI tooling only, so the ruff/mypy/pytest gate and/code-reviewdo not apply here.paths:front-matter for on-demand loading; without it they would auto-load at launch and defeat the purpose — confirmed all 11 carry it, and every internal doc link resolves.docs/feat/chorefor easier review.