Skip to content

Commit ca6cec2

Browse files
derek73claude
andcommitted
docs(agents): practise what the line-width note preaches
The note telling you not to hard-wrap prose was hard-wrapped across two paragraphs and 19 lines, having been offered as one. Now one unwrapped line, which is both the convention it states and the length it promised. Dropped in the trim: the per-medium enumeration of what makes no difference (rendering, build, size, tokens), the blame-commit counts, the .git-blame-ignore-revs escape hatch, and the exception's field list. The measurements stay in this PR's description and #386's history; a convention needs the rule and the one number that justifies it, not the workings. Note the section it sits in was already wrapped while "2.0 API modules" below is not, so the file was mixed before either note existed -- which is why the §5 bullet in the previous commit is unwrapped and correct without anyone deciding. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent bdc44c4 commit ca6cec2

1 file changed

Lines changed: 1 addition & 19 deletions

File tree

AGENTS.md

Lines changed: 1 addition & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -200,25 +200,7 @@ the two clears the words-to-spare guard. Running axis 1 over this
200200
very list caught an earlier wording of that sentence conflating the
201201
population with the movers, so the count above is the corrected one.
202202

203-
**Markdown line width: don't hard-wrap prose.** Measured 2026-08-16,
204-
the ~80-column wrap in these files buys nothing. Wrapped and unwrapped
205-
markdown render identically (single newlines inside a paragraph
206-
collapse to spaces), docs/design/ is not in the Sphinx build, and
207-
unwrapping is byte-identical because newline→space is 1:1 — so there
208-
is no rendering, build, size or token argument either way. The cost is
209-
one-sided: 74% of the deleted words in #386's decisions.md diff were
210-
reflow rather than change, which is churn a reviewer has to read past.
211-
Write new prose unwrapped and leave existing paragraphs until they are
212-
being rewritten anyway — a bulk rewrap would reset `git blame` across
213-
the 31 and 43 authoring commits in rules.md and decisions.md, which is
214-
the provenance that dates a stale claim (do it as one reformat commit
215-
in .git-blame-ignore-revs if you ever want it uniform).
216-
217-
The exception is enforced, not stylistic: rules.md's example lines and
218-
its `history:`/`interacts:`/`implemented:`/`tracked:` pointer lines are
219-
parsed per line, and a wrapped example line is a hard error naming its
220-
rule. Rule STATEMENT prose is free to rewrap, because the citation
221-
check normalizes whitespace before comparing (`" ".join(s.split())`).
203+
**Markdown line width: don't hard-wrap prose.** Measured 2026-08-16 — wrapped and unwrapped render identically, docs/design/ is not in the Sphinx build, and unwrapping is byte-identical (newline→space is 1:1), so the width buys nothing and costs diff churn (74% of #386's decisions.md deletions were reflow, not change). Write new prose unwrapped; don't bulk-rewrap old paragraphs, which would reset `git blame` on the provenance that dates stale claims. Enforced exception: rules.md's example and pointer lines are parsed per line, so a wrapped example is a hard error naming its rule — statement prose is free, since the citation check normalizes whitespace first.
222204

223205
**Guard tests** SHOULD carry a recorded negative control — the
224206
answer with the guard off, stored as data (the _EXCLUSION_EFFECT

0 commit comments

Comments
 (0)