文档标准
确保每个页面都可搜索、对新读者友好，并且对于代理和维护者来说足够精确。层级、写作规则、预算和“草率”清单位于 docs/AGENTS.md 中；本技能拥有应用这些规则的工作流程。每个事实只保留一个所有者：源代码、测试、生成的目录、README、指南和代理笔记各自保留其自身的真相类型。这是指导方针，而非清单。
工作流程
对于每个要求的作用域，遵循以下顺序。保持常见读者路径简短，但不要为了减少字数而删除失败、所有权、限制或其他必要的契约。
- 阅读根目录和子目录的
AGENTS.md文件、docs/AGENTS.md、目标页面、其源代码和测试以及其导航所有者。 - 根据其主要工作和读者将页面分类为：快速入门、用户任务指南、贡献者教程、架构概览、模块参考、生成的参考、代理指令、决策记录或草稿。
- 将页面放置在其最近的所有者处。将模块契约保留在模块代码旁边；使用
docs/存放跨模块学习、用户、开发者和架构材料。 - 在编写细节之前，定义读者的起始状态、可观察到的结果、可能的失败、恢复路径以及下一个有用的深度。
- 按照页面结构给出的顺序编写：标题、摘要、目录、面向用户的内容、面向开发者的内容、可选的“进一步探索”。
- 当配置文件启用了
surfaces.bilingual-docs时，在同一轮更新对应语言版本，并保持标题、列表、表格、代码和链接逐行对齐。 - 对照代码、测试、生成器、包元数据或当前的决策所有者验证每个声明，并运行页面指示的操作（参见下文的事实核查程序）。在任何派生制品之前更新所有者。
- 运行配置文件的
commands.docs-check和git diff --check，然后完整地重读一次 diff 以检查正确性，再读一次以检查简洁性和适合度。
事实核查程序：测试，而非假设
文档描述了产品今天的行为，而操作声明的唯一可接受证据是已经运行过它。这适用于每个新页面和每个声称命令、默认值、错误、输出或平台差异的新段落。
- 在编写安装或使用指导之前对主题进行分类。 读取事实（清单、入口点、导出），而不是文件夹名。一个库、一个插件、一个 CLI 和一个服务各有不同的使用路径；切勿复制为另一种类型编写的指导。
- 针对当前检出运行每个声称的操作。 完全按照页面将展示的方式执行每个命令、配置片段和示例；只记录你观察到的内容，包括警告和失败模式。如果一个声明依赖于你没有的凭据或网络，请说明并指出验证所有者，而不是断言该行为。
- 删除你无法重现的内容。 切勿仅凭记忆、类比或相邻的 README 来保留命令、字段、默认值或行为。当某个声明未能重现时，修复声明，而不是测试。
- 对照最新的默认分支检查旧文档。 在修订现有页面之前，获取并对照默认分支；根据代码纠正过时的陈述，而不是根据旧的散文。
语气规则
- 摘要说明主题的功能。 摘要和面向用户的部分描述读者可以用该主题做什么（结果、何时选择它、主要成本），绝不要描述其内部身份或注册信息。省略源标识符，除非读者直接在配置、命令或公共 API 中使用它们。
- 开发者章节解释，绝不要枚举。 开发者细节涵盖设计概念、架构和大致的数据流，足以理解其工作原理，并链接到代码以获取精确细节。没有完整的 API 目录、列列表或 API 文档复述。
- 仅限当前状态。 普通文档描述当前代码库；历史属于代理笔记、事后分析、发布说明和升级指南。
- 受控的技术英语。 当歧义可能改变行为时，为每个句子赋予一个明确的行为者和一个主要动作；为每个概念重复使用一个术语；拆分堆叠的指令；保留情态和例外。参见页面结构。
质量标准
- 简洁： 常见路径仅包含其结果所需的事实；完整真相仅隔一个链接或细节层。
- 直观： 先决条件先于依赖的概念，有一个明显的下一步操作，标题使用读者会搜索的术语。
- 友好： 读者能够识别成功，在行动前理解风险，从可能的失败中恢复，并选择是否深入。
- 准确： 每个持久的声明都有一个所有者以及与其风险成比例的验证路径。
- 代理可读： 稳定的标题、锚点、术语和所有权支持有针对性的检索，而无需加载整个语料库。
- 新读者完整： 没有仓库上下文的工程师可以通过三到五个链接的页面重建相关的架构或功能。
不要对详尽的参考应用通用的字数限制；衡量入口路径长度、每次查找扫描的不相关材料以及最大的章节，并在检索成本高时由现有的领域所有者进行拆分。
审核语料库
应用来自 docs/AGENTS.md 的作者顺序到范围内每个面向人类的文档（不包括代理笔记）：找到文档并说明其主题；设置其允许的细节并将更深入的解释移动到其下属的所有者；根据预期用途（而非路径）分类为教程或参考；拆分大量的混合形式。移动是原子性的，同一更改中修复每个入站链接；生成的目录绝不手动编辑。
然后按照 docs/AGENTS.md 中的“草率”清单进行排查，从成本最低的探测开始：使用 trim-cot-leakage 检查推理链泄漏；搜索独特的短语以查找重复的规则；用权威的所有者替换手写的目录；并从已实现的代理笔记中移除规格说明式的语言。如果删除内容会改变承诺的行为（而非其解释），请先提出行为变更（参见 find-simplifications）。保留每个承载规则的规则，最好是一到三行加上一个指向其理由的链接。
详细参考
使用 prose-standard 进行句子级别的契约覆盖和编辑判断。