Repository navigation
docs(claude-md): make CLAUDE.md the contributor guide (ADR 0019) - #66
Merged
Merged
Conversation
The root CLAUDE.md was about 2,000 words, mostly restating the skills, the tier model, the plugin tree and the ADR list, and it told contributor sessions to behave as the product. Every restatement in it had drifted at least once, and plugin users never receive the file. - Rewrite CLAUDE.md as about 650 words: two modes, a table of pointers to each source of truth, and nine rules for changing the repo, including a legal move for requests that conflict with an Accepted ADR - Keep four runtime rules that never shipped in the plugin in a labelled section pending issue #62 - Add ADR 0019 and back-link amendments on ADRs 0006, 0016 and 0017 - Add the claude-md-scope check at warn: links resolve, 1,000-word budget - Guard: protect an ADR only once it exists in HEAD so drafts can be revised - Mark the two CLAUDE.md-era test documents as historical Co-Authored-By: Claude Opus 5.5 <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
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.
Summary
CLAUDE.mdgoes from about 2,000 words to about 650. What left was restated product specification: the four workflow tables, the tier and run-conditionality model, the plugin tree, the deliverables and the ADR list. Each is now a link to its source.CLAUDE.mdand so never reached plugin users. They stay in a labelled section and issue Move the runtime rules that live only in CLAUDE.md into the plugin #62 tracks moving them into the plugin, which is a product decision.claude-md-scopecheck (warn): every relative link resolves, and the file stays within 1,000 words.HEAD, so a draft can be corrected before its first commit.Behaviour change
Contributor sessions in this repo no longer receive the instruction to read
.product-dev/and greet with project status. Running the plugin's commands here is unchanged: the skills carry their own instructions.Evidence and its limits
The constitution-lift experiment found no behavioural gain from splitting rules across layered files, so this does not layer rules. It did not test removing restated product documentation, and it did not test this repo. The case for this change is maintainability and audience separation.
Test plan
python checks/run_checks.py --ci— 18 checks, 0 findingspython -m unittest discover -s checks/tests— 26 tests passclaude-md-scopereports a broken link and an over-budget file when given themADR impact
docs/adrs/0019-claude-md-contributor-guide.md🤖 Generated with Claude Code