Build1 distinct publisher3 min readPublished
Three postures exist for an agent instruction file. Only the third holds at commit speed. The team running it watched its own CLAUDE.md reach 548KB before a context-measurement pass cut it to 34KB.
The Engineer · Build desk

Compiled by The EngineerSomething wrong?How this is made
The load-bearing part of that test file is an import, not an assertion. `CLAUDE_MD_SIZE_WARN_BYTES` is defined once, at `45_000`, in `src/ops/health-check.ts`, and read by both the runtime health check and the commit-time test [6]. The number that warns you and the number that fails your build are the same object, so nobody can relax one and forget the other. That costs one import line and survives a refactor.
The rest of the gate is thinner than the framing around it, and rulestack says so plainly: there is no schema document anywhere [8]. A skill is "declared" by the phrase `publish-product skill` appearing in the prose, and the parser is a single regex [8]. You get machine-checkable structure without maintaining YAML next to English, and in exchange the check only sees references you happened to phrase that way.
Check three is the one worth copying. Skills load only when a task matches their description, so a skill directory with no trigger in the body raises nothing at all: no error, no log, and the instruction file still reads correctly while the obligation quietly stops running [10]. A monthly reread cannot find that, because there is no artifact to notice [10]. Check two, the dangling reference, is the direction most people write first, and rulestack says it exists because a `publish-product` reference was left pointing at nothing during a restructure [9].
Ownership is where the executable-configuration reading runs out. Five of the six assertions are structural or size checks [18], and none of them names a party responsible for any of these files [20]. What the gate demonstrates is validation and enforcement; the schemas and the ownership in the original question are still a wishlist [1].
The cut is real arithmetic: 548KB to 34KB removes about 94 percent of the file [16], and at 34KB it now sits roughly 11,000 bytes under the ceiling it has to pass [17]. The measurement pass behind that reduction is linked rather than reproduced in the post [19]. The number only means anything in your repo if three things line up in your own setup too. Your agent has to be writing to the file itself, as theirs appends changelog entries and new rules [12]. Skills or partials have to load on description match, which is what makes an orphan silent rather than loud [10]. The commit path has to run the suite already, too, because the whole mechanism rides on `pnpm test` being a precondition for every commit [5]. Drop that last one and the gate is a suggestion.
Scale matters for how much to read into this: nine skills and one rules file are currently under the gate [11]. Six assertions over ten artifacts is a small system, and the checks that will age worst are the two that depend on prose phrasing. The one to write first is the orphan check, since it is the only failure in the set that produces no symptom whatsoever [10].
Ranked by verification strength, evidence, and original report placement.
A commenter, @crdtcto, asked whether agent instruction files should eventually be treated less like documentation and more like executable configuration, with schemas, validation, ownership, and automated linting.
The post sets out three postures toward a CLAUDE.md / AGENTS.md file: prose documentation with nothing checking anything, periodic audit, and a commit gate.
The team's CLAUDE.md reached 548KB before they acted, and cutting it back to 34KB took a measurement pass over what actually loads into context.
The gate is test/ops/claude-md-structure.test.ts, which reads the real files on disk and asserts six things.
The structure test runs inside pnpm test, which is a precondition for every commit, so a rules file that violates the checks cannot be committed.
CLAUDE.md must be at or under CLAUDE_MD_SIZE_WARN_BYTES; that constant is 45_000 and is imported from src/ops/health-check.ts, the same number the runtime health check warns on, giving one definition and two consumers so the advisory and enforcing layers cannot drift apart.
Distinct publishers with included, body-backed reporting in this cluster.
1 article · September 4, 2026
Follow any of these and your For You feed starts watching them — no settings page required.
build
The linter that passed everyone who ignored it and warned everyone who complied1 distinct publisher
build
The AGENTS.md file is an audit of the documentation you never wrote for humans1 distinct publisher
build
Test the rule change, not the model: a cheap A/B harness for agent standards1 distinct publisher
build
Overflowing Claude Code's skill listing strips the descriptions the model triggers on1 distinct publisher
Evidence-backed comparisons of source perspectives and observed adoption signals. Read the methodology
Which Builder, Operator, and Investor concerns the observed source mix emphasized—not a truth score.
Evidence, demonstrated adoption, hype gap, incentives, and confidence are assessed independently, each on its own current evidence. How these are measured.
Precise mechanism, self-reported numbers
The machinery is described at a level someone with the repository could verify line by line: a named test file, a constant with its value and the module it is imported from, the exact regex, six assertions written out. The quantities around it are softer. The 548KB and 34KB figures come from the team's own measurement pass, which dev.to's post links to rather than reproduces, and the nine-skills count is an assertion no reader can check.
One repository, told by its owners
Nine skills and one rules file, in a single codebase, reported by the people who wrote the gate. The post claims months of use and nothing at all about use elsewhere; the AGENTS.md side of the title never appears again after the framing. There is no third party running this, no fork, no other team's numbers.
Scoped tighter than the subject invites
The last third of the post is given over to what the gate cannot do: it holds no opinion on whether an instruction is still true, it cannot decide that two instructions conflict, and it says nothing about whether the agent complies, which the author calls the largest gap by far. The commenter's proposed contradiction check is refused outright rather than parked as a roadmap item, and a model reviewer is dismissed as a suggestion with a CI badge. The one unearned step is the implicit suggestion that a ten-file setup generalises.
The team's own method, on the team's own account
Published under the rulestack organisation on dev.to as part of a run of CLAUDE.md posts, and framed as a reply to a commenter on an earlier one, which is engagement the format rewards. The subject is the author's own tooling, so the verdict on how well it works has no outside check. Against that: nothing is on sale in the text, no product or price is named, and the piece volunteers three categories of failure it cannot catch.
Coherent single account
The account is first-hand, internally consistent, and precise in exactly the places a reader with repository access could later confirm. What no reader can confirm from here is that the 94 percent reduction happened as described, or that the gate has caught anything since the publish-product reference broke.