doc-standards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Applying the documentation standard

文档标准的应用

The documentation rules live in the repository's documentation standard (typically

docs/AGENTS.md

). This workflow covers placement, corpus audits, budgets, and validation across Markdown, JSDoc, and code comments. It is guidance, not a script; use

prose-standard

for required coverage and editorial judgment, and never treat length alone as a defect.

文档规则存放在仓库的文档标准文件中（通常为

docs/AGENTS.md

）。本工作流涵盖了Markdown、JSDoc和代码注释中的文档放置、全集审核、预算管控及验证环节。这是指导性内容，而非固定脚本；使用

prose-standard

确保必要覆盖范围并运用编辑判断，切勿仅将篇幅长短视为缺陷。

Sources of truth (read, don't re-summarize)

可信来源（仅阅读，勿重新总结）

The repository's documentation standard — hierarchy, tutorial/reference forms, taxonomy, budgets, and slop checklist.
The repository's Agent Note rules — when a decision earns an Agent Note, how to file it, and what goes inside one (the header block, per-lifecycle skeleton, and alternatives-considered mandate, gated by the repository's note-format gate); the repository's postmortem rules, when present — when an incident earns a postmortem.
The repository's bilingual pairing contract — editing either side of a pair obligates the counterpart in the same change.
The root
```
AGENTS.md
```
— the standing orders whose budget discipline this skill protects.
Frozen archived Agent Notes — historical snapshots excluded from editorial maintenance and evolving documentation gates.

仓库的文档标准——包含层级划分、教程/参考文档格式、分类体系、预算规则及冗余文档排查清单。
仓库的Agent Note规则——何时应为决策添加Agent Note、如何归档、以及Agent Note的内容要求（头部块、全生命周期框架、备选方案说明要求，需符合仓库的笔记格式检查要求）；若仓库存在事后复盘规则，则需遵循该规则——何时应为事件撰写事后复盘报告。
仓库的双语文档配对约定——编辑配对文档中的任意一方，都需同步更新另一方。
根目录下的
```
AGENTS.md
```
——本技能所维护的、具备预算约束的长期规范。
已冻结归档的Agent Note——历史快照，无需进行编辑维护或适配更新后的文档检查规则。

Review structure before prose

先检查结构，再处理文案

Apply the standard's authoring order to every human-facing document in scope. Do not apply this structural pass to Agent Notes. Classify a postmortem as a reference scoped to one incident; preserve its required chronological evidence without treating chronology as a teaching sequence.

Locate the document in the repository and navigation trees. State its own subject and identify its direct children.
Set the permitted level of detail. Keep full detail about the document's subject, summarize direct children by purpose, responsibility, and high-level behavior, and move deeper explanations to their owning descendants with links. Treat test infrastructure as descendant-owned unless it is the document's subject.
Classify the document from its intended use, not its path or title. A tutorial must lead through ordered work to an observable outcome; a reference must support lookup within an explicit scope without requiring sequential reading.
For a tutorial, privately classify the starting reader and concepts as beginner, intermediate, or advanced. Trace each concept to its prerequisites, reorder premature material, and move optional advanced detail to a later tutorial or reference.
Split substantial mixed forms. Put a small secondary form in a clearly labeled section.

Then check constraints that make placement expensive or wrong:

Paired docs (the repository's pairing gate with its list flag) cost a counterpart update and a re-record on every edit — prefer an unpaired home for content that will churn.
Generated catalogs are never hand-edited; if the fact belongs there, change the generator's source.
Before renaming or moving any doc, grep for inbound references: the repository's Markdown link gate catches link targets AND
```
#fragment
```
anchors onto Markdown files (heading slugs and explicit
```
<a id>
```
); a doc-refs gate, when present, catches
```
docs/*.md
```
citations in code comments; anchors cited from code strings still need a manual grep when their output never reaches gate-scanned Markdown.
A move is atomic: remove from the old home, add to the new home, and fix every inbound link in the same change.

对所有面向用户的文档，按照标准规定的编写顺序进行结构检查。此结构检查不适用于Agent Note。将事后复盘报告归类为针对单一事件的参考文档；保留其必需的时序证据，但无需将时序作为教学逻辑。

确定文档在仓库及导航树中的位置，明确自身主题并列出直接子文档。
设定允许的细节层级：保留当前文档主题的完整细节，按用途、职责和核心行为总结直接子文档的内容，将更深入的说明移至对应子文档并添加链接。除非测试基础设施是当前文档的主题，否则相关内容应归属于子文档。
根据文档的预期用途而非路径或标题进行分类：教程需引导用户完成有序操作以达成可观察的结果；参考文档需支持在明确范围内快速查阅，无需按顺序阅读。
针对教程，私下界定目标读者的入门、中级或高级水平，梳理每个概念的前置知识，调整提前出现的内容顺序，将可选的高级细节移至后续教程或参考文档。
拆分混合格式的长篇文档。若次要格式内容较少，可放在清晰标注的章节中。

随后检查可能导致文档放置成本过高或位置错误的约束条件：

配对文档（仓库的配对检查规则及列表标记）每次编辑都需同步更新另一方并重新记录——对于频繁变更的内容，优先选择非配对的存放位置。
自动生成的目录绝不能手动编辑；若内容应归入此类目录，需修改生成器的数据源。
在重命名或移动任何文档前，需搜索所有入站引用：仓库的Markdown链接检查规则会捕获链接目标及Markdown文件中的
```
#fragment
```
锚点（标题别名和显式
```
<a id>
```
）；若存在文档引用检查规则，会捕获代码注释中对
```
docs/*.md
```
的引用；当代码字符串中的锚点输出未进入检查扫描的Markdown时，仍需手动搜索。
文档移动操作需原子化：在同一变更中完成从旧位置移除、添加至新位置，并修复所有入站链接。

Audit the corpus

文档全集审核

After the structural pass, hunt the standard's slop checklist with the cheapest probes first. Verify and fetch the live base when reviewing a change, then run the repository's change-scope tool, when present, to identify committed and dirty paths before applying semantic judgment. After a retarget or base merge, rerun the report and audit prose introduced by the new base.

Measure: the repository's budget gate with its list flag, then
```
git ls-files '*.md' ':(exclude)vendor/**' | xargs wc -w | sort -rn | head -30
```
to spot unbudgeted outliers.
Hunt reasoning-transcript leakage — narrated history, dead design-session citations, review choreography, control-flow narration, test walkthroughs — with
```
trim-cot-leakage
```
, which defines the taxonomy, recall batteries, and rules for what to keep or delete. Preserve only a non-obvious contract or durable rationale; the same rationale repeated beside sibling methods keeps one home.
Hunt duplication by grepping distinctive phrases. Keep one home and replace other copies with links.
Replace hand-written catalogs, test/status inventories, and JSDoc restatements with the authoritative tree, script, or generated reference.
In
```
implemented/
```
Agent Notes, remove migration plans, acceptance-task checklists, and future-tense spec language. Keep concise verification contracts that identify the behaviors and tiers pinning the shipped decision, plus named coverage gaps.
If removing prose changes a promised behavior rather than its explanation, use a proposed Agent Note first (follow
```
find-simplifications
```
).

Exclude frozen archived notes from corpus audits and edits. Active prose may repair, redirect, or delete an inbound link, but never follow an archive-wide cleanup into the frozen target.

Keep every load-bearing rule, preferably as one to three lines plus a link to its rationale. Cut stories, duplicates, status notes, and the path used to derive the rule. Do not create a new explanation merely to relocate disposable reasoning.

完成结构检查后，按照标准中的冗余文档排查清单，先用最简便的方法逐一检查。审阅变更时，需获取并验证最新基线，若仓库存在变更范围工具，可先运行该工具识别已提交和未提交的路径，再进行语义判断。在重新定位或合并基线后，需重新生成报告并审核新基线引入的文案。

量化检查：先运行仓库的预算检查规则及列表标记，再执行
```
git ls-files '*.md' ':(exclude)vendor/**' | xargs wc -w | sort -rn | head -30
```
命令，找出超出预算的异常文档。
排查推理过程泄露内容——如叙述性历史、失效的设计会议引用、审阅流程记录、控制流说明、测试演练内容——可使用
```
trim-cot-leakage
```
工具，该工具定义了分类体系、召回规则及内容保留/删除准则。仅保留非显而易见的约定或持久化的理由；若相同理由在同级方法旁重复出现，仅保留一处。
通过搜索独特短语排查重复内容，保留一处原文，其余替换为链接。
将手写目录、测试/状态清单及JSDoc重复说明替换为权威目录、脚本或自动生成的参考文档。
在
```
implemented/
```
目录下的Agent Note中，移除迁移计划、验收任务清单及未来时态的规范语言。保留简洁的验证约定（明确绑定已发布决策的行为及层级），以及已命名的覆盖缺口。
若删除文案会改变承诺的行为而非仅修改说明，需先创建一份拟议的Agent Note（遵循
```
find-simplifications
```
流程）。

已冻结归档的Agent Note无需纳入全集审核及编辑范围。现有文案可修复、重定向或删除指向归档内容的入站链接，但绝不能对冻结的目标内容进行批量清理。

保留所有核心规则，最好以1-3行内容加理由链接的形式呈现。删除故事、重复内容、状态说明及推导规则的过程。切勿仅为转移可丢弃的推理内容而创建新的说明。

When the documentation-budget gate goes red

文档预算检查不通过时的处理

Apply the ordered relocate-condense-raise policy in the repository's documentation standard; this skill only supplies the workflow probes above.

遵循仓库文档标准中规定的「迁移-精简-升级」有序策略；本技能仅提供上述工作流中的检查方法。

Validation and PR hygiene

验证与PR规范

Run at least the repository's documentation gates, lint, and

git diff --check

; JSDoc changes may regenerate catalogs. If a paired doc changed, follow the repository's lightweight pairing routine and re-record with the pairing gate's write flag. The PR body should give word deltas, explain any deliberately long exception, and list checks.

至少运行仓库的文档检查规则、代码检查工具及

git diff --check

；JSDoc变更可能需要重新生成目录。若配对文档发生变更，需遵循仓库的轻量配对流程，并使用配对检查规则的写入标记重新记录。PR正文应说明字数变化、解释刻意保留长文档的例外情况，并列出已执行的检查项。