Handbook 编写规范

本文说明 Async Handbook 应收录什么、如何表达规范，以及怎样持续修改。写作的目标，是让人类与 Agent 都能理解同一条规则为什么存在、何时适用，以及遇到例外时如何判断。各页面可以根据问题采用不同结构。

Handbook 写的是当前采用的协作方式

Handbook 是协作规范的权威来源。合并后的正文应描述当前采用的做法，而不是尚未决定的愿景、某个团队的临时安排或作者个人偏好。

Handbook 永远可以修改。记录当前做法并不会让流程僵化，反而使团队能够针对一段具体文字提出改变，并通过版本历史理解它为什么变化。有限范围的实验可以写入正文，但应说明适用范围、负责人和结束条件，避免被误认为永久规则。

一项内容值得进入 Handbook，通常因为团队会反复遇到相关问题，而缺少共同约定会造成信息丢失、等待、返工、责任不明或决定不可追溯。一次性项目计划、事件记录、纯工具教程和无法说明适用范围的“最佳实践”，应进入更合适的载体。

规范用语

• 必须：缺少这一行为会使协作无法可靠继续，或带来明确的安全、合规和追溯风险。
• 不得：明确禁止的行为。
• 应当：默认采用，但在合理例外下可以偏离；偏离者应能说明原因。
• 可以：可选路径或示例，不增加义务。

强制程度取决于风险，不能取决于作者希望别人照做的程度。无法说明违反后会造成什么实际问题时，不应使用“必须”。存在例外时，应尽量把判断条件写在规则附近；“最好”“尽量”等词会隐藏真正的边界。

从协作问题开始

编写一页 Handbook 前，应先理解它要解决的协作问题。作者通常需要想清楚以下问题，但不需要把它们变成固定标题：

• 谁在什么情况下会遇到这个问题？
• 当前信息或责任在哪里断裂？
• 什么最少信息能够让下一位参与者继续工作？
• 风险、跨度或参与者变化后，要求是否也应变化？
• 哪些情况需要例外，谁有足够上下文作出判断？
• 这项规则与哪些上位原则和现有规范有关？

页面应按问题本身自然组织。简单问题可能只需要几个段落；复杂问题可能需要背景、规则、边界和示例。不得仅为了便于 Agent 检查而要求作者增加固定字段、固定标题或固定页面结构。任何结构性要求都必须能够说明它降低了什么真实风险。

写出能够迁移的规则

解释原因

规则只描述行为时，读者只能照搬，无法判断新场景是否适用。正文应说明它防止什么失败、保护什么价值，以及主要取舍是什么。原因不需要重复规则，也不需要替决定者回应所有可能的反对意见。

优先约束结果

规范应优先说明协作需要达到的结果。例如，任务规则可以要求接收者能够判断要做什么、由谁推进以及怎样确认工作结束，无需统一规定八个字段。复杂任务可能需要背景、依赖和验收标准，简单请求不必为格式付出相同成本。

固定格式只有在格式本身承担真实功能时才应成为要求，例如机器接口、审计记录或高风险操作检查。即使如此，也应解释每个必要字段防止了什么问题。

让要求与风险成比例

低风险、可逆、参与者少的工作，应允许轻量表达。影响范围大、持续时间长、不可逆或需要跨团队交接的工作，需要更完整的背景和记录。不要用为复杂场景设计的流程惩罚日常小事，也不要用“小事无需记录”掩盖正在累积的风险。

给出边界和反例

容易误解的规则应说明不适用场景。示例用于展示判断过程，读者无需照抄示例中的形式。示例和反例都应使用虚构或脱敏信息，不得泄露凭据、客户数据和个人信息。

保持正文清楚而可引用

标题应帮助读者预测内容并通过搜索找到它。段落应给足上下文，但不把完整论证切成口号和项目符号堆积。首次出现的术语需要解释，并与术语表保持一致。

同一项规范只在一个权威位置维护，其他页面通过具有说明性的链接引用。外部资料可以提供背景，不代替本项目自己的结论。图片、视频和附件可以辅助解释，但关键规则、边界和结论必须同时存在于可检索的正文中。

需要长期维护的目录应提供入口，帮助读者判断内容边界和阅读路径。目录入口不复制正文规则，也不成为第二个规范来源。

稳定标题通常已经足以让人类和 Agent 引用规则。只有在多个系统确实依赖稳定标识时，才为个别规则增加标识；不要预先把自然语言正文改造成配置文件。

维护信息按需出现

维护信息应按实际需要出现。缺少某项信息会让读者无法判断内容是否仍然有效、由谁维护或适用于谁时，再增加相应说明。

例如，长期运行且经常变化的跨团队流程通常需要明确维护责任；一次性决定由版本历史和决定者即可追溯，不一定需要额外复核日期；稳定的概念说明也不应仅因时间经过就被判定过期。

元数据只能辅助理解正文，无法证明内容质量。字段存在不代表内容可靠，字段缺失也不自动代表文档有问题。

规范正文与平台落地

规范正文说明协作要求和预期结果；平台落地说明如何在飞书、GitHub、GitLab 或其他工具中实现。平台名称被替换后仍然成立的内容通常属于规范正文，只在某个平台成立的步骤通常属于落地说明。

平台落地可以靠近正文，也可以在较长时拆到独立页面，但必须链接回规范来源。它不得悄悄增加正文没有的义务，也不需要为了目录整齐而覆盖每一种平台。平台限制暴露出正文缺陷时，应修改并审阅正文，而不是在示例中隐藏冲突。

Handbook、Skill 与 Agent

Handbook 保存规范含义，供人类和 Agent 共同阅读。Skill 只帮助 Agent 定位相关章节、补齐上下文并准确引用，不保存第二份规则，也不把自然语言改写成隐藏的检查清单。

通用的引用和判断边界由Agent 如何使用 Handbook统一说明。某个领域存在特殊误判风险时，再在对应规则附近补充，无需为每一页设置“Agent 可检查性”小节。

不能仅凭可见结构判断的事情，不应为了自动化而被改写成字数、关键词或字段检查。Agent 可以提示风险，但不得把启发式判断伪装成确定违规，也不得将协作质量转化为对人的评分。

修改 Handbook

有具体文字可供审阅时，优先直接提出小而完整的变更。只有问题尚不清楚、需要先收集事实、影响跨越多个章节或存在明显迁移和安全风险时，才需要先展开独立讨论。

变更说明应让审阅者理解当前问题、修改会改变什么以及重要取舍。所需细节与影响成比例，不要求每次变更填写相同清单。讨论可以发生在不同工具中，但最终结论和关键理由应回到变更记录或其他权威载体。

审阅 Handbook 时，重点判断：

• 它是否解决真实且会重复出现的问题？
• 强制程度是否与风险相称？
• 读者能否理解原因、适用范围和必要例外？
• 是否重复或冲突于已有规范？
• 是否把工具选择、字段偏好或未来愿景冒充为当前规则？
• 是否让 Agent 或审阅者获得了正文并不支持的判断权？

合并表示正文成为当前规范。影响较大的变化应通过链接通知相关人员，但通知不替代 Handbook。

常见反模式

• 字段替代思考：用完整模板掩盖目标、判断或取舍的缺失。
• 推荐冒充规范：把一种可行做法写成所有团队的默认答案。
• 工具冒充原则：把平台对象和按钮操作写成跨平台义务。
• 愿景冒充现状：把尚未采用的流程写成当前做法。
• 复制而不引用：在多个页面分别维护同一项规则。
• 为了 Agent 改造人：要求人类提供机器易检但协作无用的字段。
• 自动化过度承诺：把依赖背景的判断包装成确定性检查。
• 只讲正确做法：没有解释失败机制、边界和合理例外。

进一步阅读

本规范吸收了多种 Handbook 实践，本项目仍自行决定采用哪些规则。研究过程、取舍和相关页面索引见GitLab Handbook 相关内容导览。