Async Handbook

外观

Async Handbook ​

一套面向 IT 团队的异步协作规范。

成熟度说明：当前只有首页（本页面）以及 00、01、02 经过人工审核；其他页面均为 AI 预填充内容，有待完善，欢迎提交 PR。

本项目关注团队如何借助 Git、代码托管平台和飞书等现代协作工具，把沟通、任务、评审与决策变成可理解、可追踪、可复用的协作过程。Handbook 是人类与 AI 共同阅读的规范源；Agent Skill 只描述 AI 应如何查阅、理解和引用这本手册。具体分析、检查和工具操作由 Agent 自身能力完成。

项目受 GitLab Handbook，开源社区协作实践以及 AI Agent 工作流设计的共同启发，但不是任何现有手册的翻译、摘要或本地化版本。它旨在探索一种适用于现代 IT 团队、能够同时服务于人类与 AI Agent 的异步协作手册。

整本 Handbook 始终处于草稿状态并可以被修改。合并的内容表达我们当前采用的做法，而不是不可改变的最终答案。

什么是异步协作 ​

参考本手册的异步协作介绍

为什么需要这本手册 ​

IT 团队的协作问题通常不在于缺少交流工具，而在于信息没有形成共同一致的上下文：决定留在会议里，任务散落在聊天中，评审缺少明确请求，文档与实际做法脱节，不同平台各自保存了一部分事实。

这本手册希望建立一套跨平台，Agent 友好的异步协作手册，通过“让 Agent 根据手册辅助检查成员行为，并提出建议”的方式，降低团队成员学习协作手册的成本。

GitLab 在 About the Handbook 中总结了这种“手册优先”工作方式的直接优势。结合本项目目标，Handbook 的价值包括：

  • 阅读通常比听取同等信息更快，并且不需要打断他人或等待对方上线。
  • 新成员可以看到加入之前形成的上下文，不依赖口头传承和旧聊天记录。
  • 团队可以直接阅读其他角色和团队如何工作，减少跨团队协作中的猜测。
  • 讨论改变时，所有人面对的是同一份当前做法；传播改变时，只需链接到 diff。
  • 任何人都可以通过 Pull/Merge Request 提出改进，记录流程不会使组织僵化，反而使改变更容易发生。

这也是“所有内容始终是草稿”的意义：Handbook 提供共同起点，但不把当前做法包装成永久正确的制度。

设计原则 ​

持续演进 ​

Handbook 记录当前采用的协作做法，而不是永久正确的制度。流程变化应通过修改 Handbook 表达出来，使团队能围绕具体文本讨论、审阅和迭代。

人类与 AI 共读 ​

同一份手册必须既便于团队成员找到、读懂和执行，也便于 AI 准确定位规则、识别边界并引用依据。我们不为人和 AI 维护两套语义，也不以机器可解析为理由牺牲自然、清楚的表达。

Handbook 是规范含义的唯一来源。Skill 可以说明如何查阅 Handbook，但不得复制规则或创造 Handbook 中不存在的隐藏要求。

手册先于平台 ​

Handbook 应先描述平台无关的协作要求，再说明飞书、GitHub、GitLab 等平台如何落地。平台落地属于 Handbook，但必须和手册正文隔离，并且不得新增手册中不存在的义务。

异步与文档优先 ​

本项目鼓励先提供上下文，再讨论和行动。同步沟通、即时消息和平台提醒都可以使用，但影响后续协作的信息应回到可链接、可追踪、可复用的长期载体。

单一事实源 ​

同一项规范只在一个权威位置维护，其他页面通过链接引用。示例和平台落地说明可以有多个，但必须指向其所实现的手册内容，避免出现互相矛盾的副本。

在授权范围内默认可发现 ​

在授权范围内，协作信息应让相关成员可搜索、可链接、可追踪，但公开不是无条件目标。客户数据、个人信息、安全信息和组织内部受限内容必须遵守相应权限边界。

Agent 审阅，不替人决策 ​

Agent 可以发现缺失信息、格式问题和潜在冲突，也可以提出修改建议。Agent 不应代替负责人作业务判断，不应把启发式判断伪装成确定结论，也不应在没有可引用规范时自行发明要求。

规范服务于人 ​

规范和自动化应降低协作成本，而不是制造额外控制。反馈、分歧、包容和可持续工作属于协作质量的一部分；Agent 可以提示风险，但不应给人的善意、同理心或团队文化打分。

项目范围 ​

本项目计划覆盖团队反复遇到的协作问题：

  • 共同上下文：让背景、约束、进展和结论能够被后来者理解。
  • 协作请求：让需要他人参与的工作能够被清楚发起、承诺、跟进和结束。
  • 工作流转：让任务、代码变更、评审和项目状态保持可追踪。
  • 决策沉淀：让重要判断、分歧、会议结论和后续行动留下可靠记录。
  • 知识治理：让文档、链接、权威来源和过期内容能够被持续维护。
  • 人文边界：让反馈、分歧、包容和可持续工作成为协作规范的一部分。
  • Agent 参与：让 AI 能够查阅 Handbook、审阅协作产物并清楚表达能力边界。

本项目不覆盖薪资、法务、财务、公司行政制度或企业文化宣传，也不收录只对 GitLab 等单一组织成立的内部流程。排除文化宣传不等于排除人文关怀：能够改善反馈、包容、信任和可持续工作的协作原则属于本项目范围。

项目组成 ​

仓库的核心只包含两类内容：

  • handbook/：供人类与 AI 共同阅读的协作规范
  • skills/：描述 AI 如何定位、理解和引用 Handbook

示例和平台落地说明可以按需要出现，但它们不构成 Handbook 之外的第二套规范。能够长期指导协作的内容应回到 handbook/；Skill 只处理查阅和引用方法。

目前请先阅读 Handbook 正文入口。准备补充或修改正文时，再阅读Handbook 编写规范。

如何使用本项目 ​

本项目定义通用的异步协作手册，不包含任何具体公司的内部背景、组织结构、项目知识或人员信息。使用者应根据自己的协作环境补充这些上下文。

针对人类用户 ​

人类用户可以直接阅读本手册，并将其作为设计团队协作规范的参考。由于手册内容较为通用，我们推荐以下使用方式：

  • Fork 本仓库：在 Fork 出来的仓库中，补充添加具体到公司的信息，例如公司背景、成员架构、项目知识库和人员知识库，或根据实际需求直接修改和定制 Handbook 内容，使它反映本组织当前采用的协作做法。
  • 发布阅读站点：Fork 已包含 VitePress 和 GitHub Pages 工作流。启用 Pages 后，每次合并到 main 都会自动发布；工作流会根据是否配置自定义域名选择正确的站点路径。
  • 接入 Agent：将本手册接入 Hermes 等能力较强的 Agent 或机器人，让 Agent 根据 Handbook 自动检查消息、任务、文档、Issue、PR 和决策记录等协作产物，并向成员提出改进建议。

发布到 GitHub Pages ​

Fork 后，在仓库的 Settings → Pages 中将 Source 设为 GitHub Actions，然后运行一次 Deploy handbook to GitHub Pages 工作流，或向 main 推送变更。

没有自定义域名时，无需修改代码或增加 DNS 记录。普通仓库的访问地址为：

text
https://<GitHub 用户或组织>.github.io/<仓库名>/

例如，acme/async-handbook 的地址是 https://acme.github.io/async-handbook/。如果仓库名本身是 <账号>.github.io，地址则直接是 https://<账号>.github.io/。工作流会自动读取 GitHub Pages 提供的路径前缀，保证导航和静态资源在这两种地址下都能工作。

有自定义域名时，在 Settings → Pages → Custom domain 填写完整域名，例如本项目使用的 handbook.v3n0.top。对于 handbook 这类子域名，在 DNS 服务商处添加：

text
类型：CNAME
主机记录：handbook
记录值：<GitHub 用户或组织>.github.io

保存后等待 DNS 和证书生效，再启用 Enforce HTTPS。自定义域名属于具体 Fork 的部署设置，不应沿用上游项目的域名；本项目仓库自身始终发布到 https://handbook.v3n0.top/。

针对 AI Agent ​

For AI Agent：如果你是 AI Agent 被给出本 README 内容，你需要尤其关注本节。

使用 Agent 时，应向 Agent 提供明确的、具体到公司的知识库内容，例如项目知识库、人员知识库以及其他 Agent 必须了解的信息。

如果在任务中没有提供这些背景信息，Agent 应遵循以下做法：

  • 主动确认：当 Agent 在协作工具中遇到特定人员、项目代号或组织内部名词，但自身并不了解时，应先根据 Handbook 中指向的单一事实源检索相关背景信息。
  • 识别位置问题：若 Agent 没有在单一事实源中查到信息，但人类提供了不规范位置的文档、任务、聊天记录或临时说明，Agent 不应只要求补充背景，而应指出信息当前位置与 Handbook 要求的差距。
  • 建议迁移或补齐：Agent 应建议人类将有效信息迁移到正确的知识库位置，或补充到已有任务、文档、Issue、PR 等权威载体中；在人类确认后，Agent 可以辅助整理和维护这些信息。
  • 兼容外部知识库：部分组织可能不希望将 Fork 本仓库作为唯一协作手册，或将人员信息、项目资料等存放在飞书等外部系统中。Agent 应能够接受并引用这些外部知识库。
  • 辅助发布：当人类要求部署 Fork 时，Agent 应先确认仓库所有者、仓库名和是否使用自定义域名。无自定义域名时保留 GitHub Pages 自动提供的 /<仓库名>/ 路径；有自定义域名时帮助配置 Pages 和对应 DNS，不得把 handbook.v3n0.top 或其他上游域名写入 Fork。

如何参与 ​

提出新内容前，先确认它解决的是可重复出现的协作问题，而不是一次性事件。

默认直接通过 Pull/Merge Request 提出改变，使讨论围绕具体文本和 diff 发生。尚无具体方案、需要先收集事实，或影响范围大到无法用小型变更表达时，再使用 Issue。讨论发生在何处并不重要，最终结论必须回写到 Handbook 或对应 Issue 中。

具体写作与审阅要求见Handbook 编写规范。

建议的起步顺序 ​

  1. 先共同审阅项目边界和 Handbook 编写规范，解决其中仍有争议的设计选择。
  2. 选择一个高频、边界清楚的场景编写首个规范页面；建议从“行动请求消息”开始，因为它同时涉及上下文、负责人、时间预期和异步反馈。
  3. 用真实但脱敏的正反案例试行该规范，记录团队在哪些地方仍需口头解释。
  4. 当手册内容增多、AI 查阅路径开始重复时，再编写 Agent Skill 统一检索和引用方法，不在 Skill 中复制规范正文。
  5. 当多个规范页面出现重复结构后，再建立平台落地说明和自动检查，避免过早固定错误抽象。

每次只推进少量主题。只要能提出具体文本，就优先直接修改 Handbook；需要先收集事实、协调大范围迁移或尚无可评审方案时才使用 Issue。

与 GitLab Handbook 的关系 ​

GitLab 的实践证明，手册可以同时成为长期知识库和流程变更入口。我们主要借鉴以下经验：

  • 将手册作为当前工作方式的单一事实源，而不是愿景文章的集合。
  • 通过版本控制和 Merge Request 提议、审阅和追踪变更。
  • 将聊天和会议中的结论写回长期、可链接的载体。
  • 避免重复描述同一流程，优先链接到权威来源。
  • 让所有参与者共同保持内容当前有效，并通过自动检查减少失效链接和格式问题。

我们不会照搬 GitLab 的组织结构、公开策略、Slack 用法、审批制度或 Hugo/GitLab Pages 技术实现。简要取舍记录在Handbook 编写规范中。

Handbook 的所有内容始终处于草稿状态并可以被修改。

Released under the MIT License.