docs(claude): state package roles instead of listing the tree - #375
Open
wshallwshall wants to merge 1 commit into
Open
docs(claude): state package roles instead of listing the tree#375wshallwshall wants to merge 1 commit into
wshallwshall wants to merge 1 commit into
Conversation
CLAUDE.md is 608 lines against a documented 200-line target, and the entries
cut here are the only ones in section 3 that a reader could reconstruct from
the tree: `__main__.py` (the CLI entrypoint by Python convention),
`logging_setup.py`, `scripts/service/`, `tests/` ("pytest suite"), and a
`docs/` line enumerating four filenames that goes stale on every rename.
The rest of the tree stays, and the proposal to cut it wholesale is declined.
It is not a directory listing -- every remaining line states a package's ROLE,
which `ls` does not give you, and several carry the ADR that decided it.
`messagefoundry/auth/webauthn.py:7` cites "CLAUDE.md section 3" for exactly
that content ("the HTTP/cookie surface lives in api/"), and
tests/test_sds_rule_ids_are_stable.py:377 cites the trailing paragraph, so
section 3 has two live citations rather than the one a survey suggested.
Section numbers are unchanged and must stay that way: they are a namespace
roughly 500 references wide, read by gate code in scripts/seam_discovery.py
and scripts/asvs/scorecard.py, and renumbering is a migration rather than a
doc edit.
MEASURED, because the point of the change was size and it did not deliver any:
608 raw lines before and after, 528 to 526 non-blank, 44303 to 44258 bytes.
That is 0.1 percent, and five cut lines were replaced by five that say what
section 3 is for and why scripts/, docs/ and tests/ are absent -- worth having
so the enumeration does not grow back, but it is not a trim.
The honest conclusion is that CLAUDE.md's length is not fixable by cutting
derivable prose, because there is almost none: the file is long because it
carries decisions, and a decision is not derivable from the code that
implements it. Any real reduction means moving load-bearing content into
path-scoped rules under .claude/rules/, and that is blocked today -- /.claude/*
un-ignores settings.json alone, so a rules file would reach one checkout out of
sixty-five while appearing repo-wide. Measure adherence before assuming the
line count is the problem.
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.
Trims the repo-layout listing in
CLAUDE.md. One file, +5 -5.Replaces the enumerated tree with a statement of package roles, dropping
__main__.py,logging_setup.py,scripts/service/,docs/andtests/from the listing on the grounds that theirnames say what they hold.
Checked the one thing that would make this dangerous: it does NOT renumber. 13 numbered headings
before and after. Section numbers in this file are cited by 281 tracked files and nothing validates
them, so a renumbering trim would be a silent break -- this is not one.
Not armed. The authoring session offered it as optional. It removes concrete orientation from the
file that is loaded into every session's context, which is a judgement about what a newcomer needs
rather than a defect being fixed. Owner's taste, not the coordinator's.