Documentation structure, tiers, and budgets
文档结构、层级与预算
Standing docs accumulated repeated rules, retold incidents, duplicated package maps, and stale Agent Note summaries despite existing writing guidance. That guidance also did not define how a document's place in the hierarchy limits its scope or how ordered teaching differs from lookup-oriented material. Because review alone did not prevent that growth, the repository needed a mechanical budget alongside its documenta
English
Problem
Standing docs accumulated repeated rules, retold incidents, duplicated package maps, and stale Agent Note summaries despite existing writing guidance. That guidance also did not define how a document's place in the hierarchy limits its scope or how ordered teaching differs from lookup-oriented material. Because review alone did not prevent that growth, the repository needed a mechanical budget alongside its documentation taxonomy.
Decision
- Structure follows the documentation tree. docs/AGENTS.md is the documentation standard: a document owns detail about its subject, summarizes only the purpose, responsibility, and high-level behavior of direct children, and links to deeper owners. Agent Notes remain outside this structural contract. Every human-facing document is a tutorial with an ordered outcome or a reference with an explicit lookup scope; a postmortem is an incident-scoped reference whose chronology records evidence. Tutorials introduce concepts in prerequisite order for the reader's starting knowledge.
- A tier taxonomy with one home per fact. The standard assigns every Markdown tier one job, forbids restating a fact outside its home tier, and carries the slop checklist used when writing or reviewing any doc.
- One product onboarding path. The root README owns the recommended package-run path, the source-run alternative, and compact
dsh plugin --profileusage. The published user guide starts with tasks inside the running Web UI, then links to distinct tutorials or reference owners for other interfaces, plugin development, and advanced configuration instead of repeating Web startup. - A narrow, hard budget gate. scripts/verify-doc-budgets.ts joins
doc-sync: every doc listed in scripts/doc-budgets.manifest.json must stay under its word ceiling (wc -wsemantics, whole file), and a budgeted file that is missing fails the gate so a rename cannot silently orphan its budget. Scope is deliberately only the accretion-prone standing docs — the root and subtreeAGENTS.mdfiles,architecture.md,packages/README.md, and the standing policy docs they evict content into (docs/testing.md,docs/defensive-patterns.md). Reference docs, Agent Notes, and package READMEs are unbudgeted: length is legitimate there when every row is a fact, and review plus the slop checklist govern them. - Ceilings are an enforcement frontier that ratchets. A doc at or below its target keeps at least 5% headroom as its ceiling ratchets down; a doc above target keeps a frozen ceiling that prevents growth until it reaches the target (root
AGENTS.md≤ 1,600 words;architecture.md≤ 1,800; subtreeAGENTS.md≤ 600 exceptpackages/AGENTS.md≤ 650 anddocs/AGENTS.md≤ 1,250;packages/README.md≤ 600). When the gate goes red, relocate or condense; raise a ceiling only with explicit PR justification. - A thin workflow skill, contracts in docs. .agents/skills/dsh-doc-standards carries the placement/audit/red-gate workflow and defers to the standard as its source of truth, the same split as dsh-translate-docs over the i18n contract.
Alternatives considered
- Skill and review discipline without a gate — rejected: the accretion above happened while the current-state rule and reviewer attention already existed; a prose rule with no mechanical backstop demonstrably does not hold here, and this repo's own quality-gates stance says invariants worth keeping are worth encoding.
- A broad gate over every doc tier — rejected: a blanket ceiling punishes exactly the right kind of long doc (a feature matrix or type catalog where every row is a fact) and generates per-file override churn that trains contributors to rubber-stamp raises.
- Independent onboarding tutorials for each documentation entry point — rejected: duplicated setup steps drift in command order, first outcome, and product identity. A short README path followed by task-focused guides keeps the transition explicit without maintaining competing tutorials.
- Housing the standard inside the skill — rejected: contracts live in docs and workflows in skills; a standard packed into SKILL.md is invisible to an agent that edits docs without invoking the skill, and
docs/AGENTS.mdalready loads as subtree instructions for anyone working underdocs/.
Consequences
- Adding to a budgeted doc requires displacement: relocate the addition to its taxonomy home with a pointer, or condense existing prose to pay for it. Growth without pruning fails CI.
- Structural review starts with ownership and document form before sentence-level editing, so lower-level detail moves to its owner instead of being polished in the wrong place.
- Readers reach a running Web UI before encountering headless execution, SDK embedding, custom profiles, or direct settings files; those interfaces remain available from their reference owners.
- Budgeted docs that remain above target cannot grow; reaching the target restores the 5% working headroom.
- Word count is a crude proxy accepted deliberately: it cannot judge quality, but it forces the relocation decision at exactly the moment content is being added, which is when the author has the context to place it correctly.
中文
问题
尽管已有写作指导，常设文档仍不断累积重复规则、反复讲述的事故、重复的包映射，以及陈旧的 Agent Note 摘要。该指导也未明确文档在层级中的位置如何限定其内容范围，以及按顺序引导读者学习的内容与面向查阅的材料有何不同。仅靠评审无法阻止这种增长，因此仓库需要在文档分类体系之外再配一套可自动执行的预算。
决策
- 结构遵循文档树。docs/AGENTS.md 是文档标准：文档负责承载其主题的详细内容，仅概述直接子项的目的、职责和高层行为，并链接到更深层内容的归属文档。Agent Note 仍不受这一结构约定约束。每份面向人的文档要么是按顺序引导读者达成结果的教程（tutorial），要么是查阅范围明确的参考文档（reference）；事故复盘（postmortem） 是范围限定于单起事故的参考文档，其时间线记录证据。教程结合读者的起始知识，按前置依赖顺序介绍概念。
- **每项事实只归属一处的层级分类。**文档标准为每种 Markdown 层级分配单一职责，禁止在事实归属层级之外重复陈述，并包含编写或评审任何文档时使用的赘余检查清单。
- **单一产品入门路径。**根 README 负责推荐的包运行路径、从源码运行的备选路径和简要的
dsh plugin --profile用法。已发布的用户指南从运行中的 Web UI 内部任务开始，再链接到其他界面的独立教程或插件开发与进阶配置的参考文档归属处，而不会重复介绍 Web 启动步骤。 - 范围窄且严格的预算门禁。scripts/verify-doc-budgets.ts 接入
doc-sync：scripts/doc-budgets.manifest.json 列出的每份文档都必须低于其词数上限（采用wc -w语义，统计整个文件）；预算内文件缺失也会使门禁失败，使重命名无法悄然遗落其预算。范围刻意只涵盖容易膨胀的常设文档——根目录和子树中的AGENTS.md文件、architecture.md、packages/README.md，以及它们将内容移入的常设策略文档（docs/testing.md、docs/defensive-patterns.md）。参考文档、Agent Note 和包 README 不设预算：只要每一行都是事实，长度在这些位置就是合理的；评审和赘余检查清单负责约束它们。 - 上限是只进不退的执行红线。 达到或低于目标的文档在上限逐步下调时保留至少 5% 的余量；高于目标的文档则维持冻结的上限，在达到目标之前不得增长（根
AGENTS.md≤ 1,600 词；architecture.md≤ 1,800；子树AGENTS.md≤ 600，但packages/AGENTS.md≤ 650、docs/AGENTS.md≤ 1,250；packages/README.md≤ 600）。门禁变红时，迁移或压缩内容；只有在 PR（Pull Request）描述中给出明确理由时才提高上限。 - 精简的工作流 skill（技能），约定归文档。.agents/skills/dsh-doc-standards 承载文档放置、审计和门禁失败处理工作流，并以文档标准为真源，与 dsh-translate-docs 和 i18n 约定之间的分工相同。
曾考虑的替代方案
- 仅靠 skill 和评审纪律，不设门禁：否决。上述膨胀正是在现行规则和评审注意力已经存在的情况下发生的；一条没有自动化保障的行文规则在此处已被证明无法维持，而本仓库自身的质量门禁立场认为值得保持的不变式就值得编码。
- 对所有文档层级全面设限：否决。一刀切的上限恰好惩罚了那些正当的长文档（如功能矩阵或类型目录，每一行都是事实），并产生逐文件的例外变更，训练贡献者机械地批准提限。
- 为每个文档入口维护独立入门教程：否决。重复的设置步骤会在命令顺序、首个结果和产品定位上产生分歧。简短的 README 路径接上面向任务的指南，可明确衔接两者，且不需要维护相互竞争的教程。
- 将标准放在 skill 内部：否决。约定归文档，工作流归 skill；如果标准被塞进 SKILL.md，那些不调用该 skill 而直接编辑文档的 agent（智能体）就看不到它，而
docs/AGENTS.md已经作为子树指令被任何在docs/下工作的人加载。
后果
- 向受预算约束的文档添加内容需要腾挪空间：将新增内容迁移到其分类体系归属地并留下链接，或压缩现有行文来腾出空间。只增不减会导致 CI 失败。
- 结构评审先检查归属关系和文档形式，再进行句子层面的编辑，使较低层级的细节迁移到其归属文档，而不是在错误的位置加以润色。
- 读者会先进入可运行的 Web UI，再遇到 headless 执行、SDK 嵌入、自定义 profile 或直接 settings 文件；这些入口仍可从各自的参考文档归属处访问。
- 仍高于目标的受预算约束文档不得增长；达到目标后，将恢复 5% 的工作余量。
- 词数是一个粗糙的代理指标，这是有意接受的：它无法判断质量，但它在内容被添加的那一刻强制触发迁移决策，而那正是作者拥有足够上下文来正确放置内容的时刻。