docs(agents): describe the design, not the change to it - #357
Merged
Conversation
Three authoring rules under Code and doc style, each earned during the #346 work: - Definitions, code and doc comments, and commit subjects state the system as it is. A commit subject is a permanent log entry, so `move usage accounting off the transition and onto the dispatch` makes a future reader learn the old model just to parse it; `account for token usage per dispatch` needs nothing. PR and issue bodies are the carve-out — a reviewer needs the before-state, and those stop being read once merged. Includes the sweep habit, because two stale descriptions of replaced behaviour survived a first pass and only a deliberate grep found them. - Prose warning "do not also use X" usually means two paths now do one job. Retire one and the warning has nothing to say, along with any validation that existed only to police the overlap — which is how a tool parameter, a validation warning and its test all left together rather than being documented around. - Sync CLAUDE.md and AGENTS.md by merging, never copying. That last one is why this commit also reconciles the two files. They had diverged: CLAUDE.md carried the #327 guard, worktree-provision and triage guidance; AGENTS.md carried the GitHub auth-and-shell section. Each had been overwritten by the other at some point, so both were missing content the other still had. This is the union — verified line-by-line against both prior versions, with nothing from either dropped. Every script the restored lines document is still in package.json. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Under Testing and PR instructions: each change lands as its own commit with its own message, pushed with plain git push. Where a push will not fast-forward, stop and ask rather than rewriting. Force-push has exactly one legitimate use — correcting a genuine error in an earlier commit, on a branch with no other contributors. Not squashing, not rewording, not folding a follow-up into the commit it fixes, never on a shared branch. The rule records why: repeated amending collapses distinct pieces of work into one commit, and the intermediate states then exist only in a local reflog. That loss is not recoverable, only reconstructable by hand — itself a rewrite. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
m2ux
added a commit
that referenced
this pull request
Jul 30, 2026
Three files needed a decision; workflow-tools.ts, the state schema, the site tools page, the walk snapshots and mcp-server.test.ts all auto-merged. AGENTS.md held two versions of "Describe the design, not the change to it" — this branch and #357 wrote it independently, with different carve-outs. The rule now carries both: main's PR and issue bodies alongside this branch's commit body and provenance-bearing measurement, plus the live-hazard-as-invariant guidance and the link to principle 17. CLAUDE.md takes the same union, since this branch had only edited its twin and the two are kept in sync by merging. The worktree-naming rule rides in here too. It was committed to docs/agent-authoring-guidance after #357 had already merged at 618d9ff, so it never reached main and would have been lost with the branch. The workflows pointer moves to 6bc46fa, the corpus tip carrying both #351 and #355, and the stamp names the same commit. binding-fidelity passes: main's detector predicate and reconciled triage arrive with this merge, which is what the 17 stale entries on this branch were waiting for. Co-Authored-By: Claude Opus 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.
Three authoring rules, each earned during the #346 work, plus a reconciliation of two files that had silently diverged.
The rules
Describe the design, not the change to it. Definitions, code and doc comments, and commit subjects state the system as it is. A commit subject is a permanent log entry, so
move usage accounting off the transition and onto the dispatchforces a future reader to learn the old model just to parse the sentence;account for token usage per dispatchneeds nothing. PR and issue bodies are the explicit carve-out — a reviewer needs the before-state to judge a change, and those stop being read once merged.It also carries the sweep habit: after a behaviour change, look for surviving descriptions of the old behaviour in doc comments, tool descriptions, technique
## Rules, resource prose and READMEs. In #354 two of those survived a first pass —projectUsage's doc comment and arender-token-usageprotocol line — and only a deliberate grep found them. A stale claim reads as current fact.Prefer removing the thing that needs a prohibition. Prose warning "do not also use X" usually means two paths now do one job. Retire one and the warning has nothing left to say. In #354 that removed a tool parameter, a validation warning and its test together, rather than documenting around all three.
Sync
CLAUDE.mdandAGENTS.mdby merging, never copying.Why that last rule is here
Because both files needed repairing, and this PR does it.
They had diverged.
CLAUDE.mdcarried the#327guard,worktree:provisionand triage guidance;AGENTS.mdcarried the GitHub auth-and-shell section. At some point each had been overwritten by the other, so both were missing content the other still had — including the triage rule ("classify a new finding rather than suppressing it") that the whole #346 effort followed.This commit is the union of the two prior versions plus the new rules, verified line-by-line against both: nothing from either is dropped. Every script the restored lines document —
test:ci,check:all,check:delta,worktree:provision— is still present inpackage.json, so the removal was documentation loss rather than cleanup following a script deletion.The single deletion in the diff is
- **Tests:** npm testbeing restored tonpm test (watch) / npm run test:ci (single run).Each file keeps its own
# CLAUDE.md/# AGENTS.mdtitle rather than one claiming to be the other; they are otherwise identical.Verification
Documentation only — no source, schema or corpus change. Independent of #351, #352 and #354; merges in any order.
🤖 Generated with Claude Code