From f77174f13a52475d381eb9959ba2cc6ab8c499f0 Mon Sep 17 00:00:00 2001 From: Turtle Date: Fri, 10 Jul 2026 00:13:06 +0800 Subject: [PATCH] make it clearer --- docs/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 118c535874..a6e3c7236c 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -35,7 +35,7 @@ Placement test: a story about a bug → postmortem. Why we chose X → RFC. How ## Wordcount Budgets -Every PR has a lesson it wants to append, and without pressure nothing ever leaves. [scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) is the pressure, which lists the word count of each standing docs; `pnpm run verify-doc-budgets` (part of `doc-sync`, so CI and pre-push run it) fails when a doc exceeds its ceiling, and fails when a budgeted file is missing so a rename cannot orphan its budget. +Every PR has a lesson it wants to append, and without pressure nothing ever leaves. [scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) is the pressure: it stores the allowed word-count ceiling for each budgeted standing doc; `pnpm run verify-doc-budgets` (part of `doc-sync`, so CI and pre-push run it) fails when a doc exceeds its ceiling, and fails when a budgeted file is missing so a rename cannot orphan its budget. - Ceilings are an enforcement frontier with working headroom: a ceiling sits at least 5% above the doc's current size — routine edits pass, real growth trips the gate — and ratchets down, keeping the margin, as the doc reaches target. Target budgets: root `AGENTS.md` ≤ 1,500 words; `architecture.md` ≤ 1,800; each subtree `AGENTS.md` ≤ 600, except this file (which carries the standard) ≤ 1,250; `packages/README.md` ≤ 600. - When the gate goes red, first ask whether the added words belong in this tier and whether the existing wording can be condensed. If the words do not belong, relocate per the taxonomy above; if they belong but can be shorter, condense. If they truly need the space, raise the ceiling and justify the manifest diff in the PR. A ceiling set too low is a budget bug, and correcting it is the fix.