把工程上下文留在 GitHub：AI 编程跨工具接力与多分支协作
换一个 AI 编程工具，最让人头疼的可能不是它生成代码的水平，而是又要从头解释项目：上一轮为什么采用这套架构、正在改哪个分支、哪些测试已经通过、哪个 PR 还没审核，以及上一个 Agent 到底被允许做什么。
我后来把这些容易丢的进度从聊天框移到了 GitHub。Codex、Claude Code、Cursor 或浏览器里的 ChatGPT，都可以是下一次接手的入口：先读仓库里的任务与版本，能写的工具在自己的分支提交，只能读的就给出审查意见。
我把这叫 GitHub-first：AI 工具可以换，工程状态不能跟着聊天窗口消失。 不必为了记进度养一个常驻 Bot，出门带着手机也能把下一步交出去。
对话记忆与工程上下文：别把进度只留在聊天框里
长项目经常横跨许多天。A 工具已经做过的设计取舍，B 工具不知道；一个新会话看到旧版 CI 全绿，以为当前 HEAD 也绿；两个人同时改同一文件，各自觉得自己才是任务负责人。继续给提示词加十页上下文，能暂时缓解，却让项目越来越依赖某个特定产品的会话历史。
解决办法是把对话记忆和工程上下文分清楚。模型内部的推理过程和聊天记录，不会因为仓库在 GitHub 上就自动转移。能持久化的是另一组可以明确读回、验证和更新的对象：
- 项目约束与入口：AGENTS.md、README、必要的架构说明；不保证所有工具自动加载 AGENTS.md，不支持的客户端须显式读取。
- 任务身份：Issue、任务 ID、计划与 checkpoint，说明目标、阶段、负责人、已完成和待验证的工作。
- 代码版本：main、各个 feature branch、commit / Git Blob SHA；每个开发任务要找到真正正在工作的分支。
- 协作与验收：PR diff、审查评论、ACK、属于精确 HEAD 的 CI run，以及合并或部署记录。
这些记录不要求全部放在一个大 JSON 里。Git 本来就能追踪代码，Issue/PR 本来就适合讨论，checkpoint 只补足“下一步做什么、哪些门禁还没过”的空白。GitHub 不适合充当高频锁服务、临时模型上下文缓存或凭据仓库；密钥与敏感运行数据也不该为了“持久化”而提交。
我最先给新会话的不是十屏历史摘要，而是下面这段短指令。它先报出自己读到的任务与版本，再决定能不能修改：
你是本轮开发者，先只读恢复工程状态。
仓库：OWNER/REPO
任务：Issue #N，关联 PR #M，任务 ID：TASK_ID
先读取仓库规则、计划、checkpoint、当前 feature 分支 HEAD、
PR diff、最近的有效审查评论，以及属于该 HEAD 的检查。
说明当前可执行范围、已完成的证据与还缺的门禁。
如果分支已变化、权限不匹配或旧指令冲突，停止并说明原因。
未经另外批准，不合并、部署或修改生产配置。独立开发者可以先用轻量版：一份项目说明、一个 Issue 或 PR，再看最近几条提交，就足够试一次换工具接力。不需要先实现 checkpoint、Order/ACK 校验器。等任务跨天、多个 AI 同时写入、需要独立验收时，再把下面的版本化记录补上。
一个仓库底座，可以服务很多 AI 入口和开发分支
这套模式的关系可以简化为：
手机 / 浏览器 / 本地 IDE / 云端 Coding Agent
|
读取 GitHub 任务事实
|
AGENTS.md · Issue · plan
checkpoint · branch · PR
|
在授权范围内选择动作
|
功能分支 A 修复分支 B
| |
commit commit
| |
PR A PR B
\ /
审查 / 各自的 CI
|
人工批准合并
|
main图中有多个开发入口，但它们的 GitHub 权限不会自动相同。有的接入只能搜索、读仓库，有的 Coding Agent 能在自己的执行环境改文件、建分支和 PR。本文写于 2026 年 10 月，这里说明的是权限差异，并不是对上面几款工具逐一完成了最新能力实测。 真正开工前，我会按所用产品、账号和连接器的当前授权，分别核对 read、write、comment、merge、deploy，不能拿一句“已经连接 GitHub”代替权限检查。
分支是多人或多 Agent 并行开发的基本边界。例如功能 A 交给一个云端 Agent，文档修订由手机上的另一个会话提出，接口修复让本地 Codex 处理。它们可以读取同一份稳定项目规则，却分别写 feature/A、docs/B、fix/C，最后在 PR 中检查兼容性。
分支隔离并不等于改动不会冲突。 两个分支可以同时修改同一接口或公共依赖。一个任务分支最好限定一个实际写入者；合并前再核对共同基线、受影响文件、最新 CI 和必要的集成测试。GitHub 官方的 Pull Request 说明本来就把分支变更、讨论、检查与合并组合在同一个工作对象里；保护重要分支还可以设置必须审阅或通过检查的规则（Protected branches）。
在本地同时维护多个隔离工作目录，可以进一步用 Git Worktree，但那是另一个问题。我在多分支 Worktree 实践中讨论过目录与进程隔离；这里更关注不同 AI 工具如何认领同一个 GitHub 任务，以及它们的结果怎样重新汇合。
跨工具接手：先核对 Issue、分支和 PR
提示词只是接手的入口，真正决定能否继续的是仓库中能读回的几份文件。新工具至少要回答：当前是哪个 HEAD，上一手交付了什么，谁有权继续写？
轻量版先有一份 AGENTS.md 就够；长期任务才按需增加 checkpoint。AGENTS.md 负责告诉新工具“到哪里找规则、怎么运行测试”，例如：
# AGENTS.md
- 技术栈与架构：参考 README.md、docs/architecture.md
- 安装与测试：使用 README.md 中当前有效的命令
- 任务入口：GitHub Issue 和关联 PR
- 进度：tasks/<TASK_ID>/checkpoint.json
- 编辑前核对任务 ID、功能分支、最新 HEAD
- 一个功能分支原则上只有一个写入者
- 合并、部署须获得另外的批准checkpoint.json 负责留下上一手没法仅靠代码看出的阶段信息。下面保留了我真实 checkpoint 使用的字段名，值均替换为可编辑的占位符：
{
"task_id": "TASK_ID",
"phase": "P2",
"status": "IN_PROGRESS",
"branch": "feat/TASK_ID",
"commit_sha": "REPLACE_WITH_LAST_VERIFIED_40_HEX_SHA",
"pr": "https://github.com/OWNER/REPO/pull/N",
"verification": { "merge": { "status": "NOT_AUTHORIZED" } },
"next_action": "核对当前 HEAD 和审查评论后继续"
}这段 JSON 是最小示例，不是我的私有 checkpoint 原件。它也不是每次 commit 都必须更新的文件：小任务可以只用 Issue/PR；我只在跨阶段交接、验收或发生阻塞时更新 checkpoint，避免把 Git 历史刷满状态提交。
这里有一个容易踩的坑：checkpoint.commit_sha 记录的是上次确认的代码版本，不是包含 checkpoint 文件的那次提交，更不是实时 HEAD。 假设代码验收后有提交 A，之后用提交 B 更新 checkpoint 文件，文件可以指向 A，但不可能在 B 产生之前预先填入 B 自己的哈希。这不是“永远差一个 commit”的固定偏移，后面还可能继续产生其他提交。
所以新会话要先从 GitHub 读实时分支 HEAD，再与 checkpoint 所记录的历史基线和后续变更核对；不能因为两个 SHA 不同就一律认定任务失败。把示例里的占位符替换成真实的已确认提交即可。后面 ACK 的 observed_head_sha 和 new_head_sha 分别指审查时与修改后的版本，它们另有用途；Order 绑定的旧 HEAD 与实时目标 HEAD 不一致时，才由该 Order 的过期检查决定停止。
这三种对象各管一段：AGENTS.md 给项目规则，Issue/PR 留任务和审阅，checkpoint 保存当前进度。有些客户端不会自动读取 AGENTS.md，就在接手时明确要求它读。
我把自己实际使用的进阶交接协议单独整理成了开源仓库。前面的轻量接手不必安装它；如果你想检查 Order/ACK 怎样绑定 HEAD、怎样拒绝过期指令，以及校验器如何处理重复交接，可以直接读这份源码和离线测试。
这份仓库存放的是协议、校验器和示例，不会把你的业务仓库状态镜像到别处，也不负责自动唤醒 AI 会话。真正的任务、分支和 PR 仍由你自己的 GitHub 仓库管理。
真实 PR 复盘：FIX_REQUIRED、ACK 与独立复审
有了架构图，最容易自我感动的地方是：两个 AI 都说“收到”了，我们就以为任务真的接力成功。所以我回查过一次私有项目的文档 PR：它只负责修好一份 Runner 审计计划，不涉及真正安装 Runner。
这里的 FIX_REQUIRED、ACK、ADVANCE 是我自己定义的交接约定：B 要求修、A 回写新版本、B 复核后允许推进。STALE_ORDER 表示版本过期而停止。它们不是 GitHub 自带的 PR 状态。
独立审查会话 B 当时给出 FIX_REQUIRED，指出两项具体问题。较严重的 F-001 是：文档要求审计 GitHub Actions 的评论触发风险，命令却只列出 workflow 文件名。
# 原版文档中的检查动作，只会列出文件名
gh api "repos/OWNER/REPO/contents/.github/workflows" --jq '.[].name'这无法知道 YAML 顶层 on: 是否包含 issue_comment 等事件。另一项 F-002 是审计计划的章节引用错误。修复后的文档不再只列名字，而是要求固定审计 SHA、读取每份 YAML 的实际触发器，并在审计结束时复核 HEAD 没有移动。我已比对旧版与新版文件，确实有对应变化。有关评论触发事件可参考 GitHub 的 Actions 事件文档。
随后 A 在原 PR 回写 ACK 和新 HEAD；B 重新读取新版本并复核两项修复，才给出 ADVANCE。这些评论和提交差异都能从 GitHub 回读。
这次是人在两个 AI 会话间主动推进的：B 写评论，A 在新会话读评论并修改，B 再复审。它没有自动唤醒另一个聊天，也没有把 decideResume() 安装成 GitHub Actions 门禁或本地 Git hook。轻量使用时，普通 PR 评论加具体 HEAD 就能交接；下面的结构化 ACK 和校验源码，是需要更严格防重复、验证指令版本时才增加的工程层。
从那条真实 ACK 评论里摘出最有用的字段、换掉私有 ID 和 SHA 后，大致是这样：
{
"protocol": "ai-supervisor/ack/v1",
"task_id": "TASK_ID",
"order_id": "REPLACE_WITH_ORDER_ID",
"decision_received": "FIX_REQUIRED",
"observed_head_sha": "REPLACE_WITH_OLD_HEAD",
"new_head_sha": "REPLACE_WITH_NEW_HEAD",
"executed": [
"F-001: 检查固定 SHA 的 workflow YAML 触发器",
"F-002: 修正审计计划章节引用"
]
}这段节选保留了实际 ACK 的关键字段，去掉私有标识和完整协议所需的摘要校验。A 知道自己处理的是哪个旧 HEAD，B 也能确认 A 交回的新 HEAD。
ACK 表示开发者回写，ADVANCE 是 B 对新版本的审查结论；合并仍是另外一步。这个 PR 只改文档，没有对应 HEAD 的成功 CI，也没有做生产 VPS 审计。我能确认的是一次可回读的审查交接，而不是系统已经自动完成所有开发和部署。
STALE_ORDER：旧 HEAD 上的指令为什么要停止
这里的 Order 是审查会话 B 留在 Issue/PR 评论中的一份结构化交接指令，包含 task_id、目标分支、审查时的 observed_head_sha、问题和允许/禁止的操作。上面 ACK 里的 order_id 就指向这样一份 Order。
我们还做过一次负向演练：测试 Issue 里的 Order 绑定着旧的 main HEAD，后来仓库版本前进了。新会话再次读取这条 Order，就应该返回 STALE_ORDER，而不是沿着旧指令继续写入。
存档显示开发侧作出了这样的拒绝，并报告没有继续提交、评论或重新跑 CI。旧 Order、后来的 HEAD 和源码里的 decideResume() 过期检查都可以核对。当时 A 侧的停止结果是由人带回存档的，没有 A 自己写回 GitHub 的 ACK。对我来说，这是一次有价值的演练，还不是所有客户端都已端到端验证通过。
最小的机制其实不复杂：审查 B 绑定 task_id、分支、HEAD、发现与允许操作；开发 A 读取时重新比对当前 HEAD；有变化就停止，交给 B 按新版本重审。真正做到自动防重复和权限拒绝，还需要相应校验代码、可信身份与运行时检查，不能只靠一句提示词。
这也解释了为什么我仍然保留独立审查：一个 Agent 能输出一段看起来合理的 diff，和另一个会话在真实新 HEAD 上核实修复，是两个不同的事实。更通用的多 Agent 状态/owner 问题，我另写在AI Agent Orchestration：共享状态与交接中。
手机可以发起协作，但不能把 GitHub 当作免费的计算机
这套架构让我舒服的一点，是不必把监督与工程交接绑定到某一台一直开着的 Mac，也不必为了存储任务进度特地部署一个常驻的云端 Bot。坐在电脑前可以用 IDE 编写、调试；出门只带手机时，只要当前客户端有权限，就能读取 PR 状态、审阅差异、给下一位开发者留下任务，或调用已经配置好的受控执行工作流。
真正改代码和跑测试，仍要交给当前有权限、有执行环境的云端 Agent、Runner 或本地工具。
成本分两本账：少复制聊天、少维护专用 Bot，可能省的是时间和运维；模型调用、Chat/Codex/API 的使用额度和 CI 另算。我没做同任务 Token 对照，所以不报一个没有依据的省钱百分比。
我的博客还有一条从 GitHub Actions 到 Self-hosted Runner 的发布链；那篇跨设备开发与统一部署写的是代码怎样最终上线。这里要解决的是更靠前的问题：不管谁、在哪个设备、借助哪个有权限的 AI 工具开发，怎样确认自己接手的是同一个任务，而不是另起一段没人能核对的聊天。
如果只做低风险的单文件改动，一个 AI 工具加一个分支通常就够。等任务开始跨天、跨模型、跨人，才值得增加明确的 checkpoint、独立审查与操作许可。GitHub-first 最吸引我的不是“任意 AI 都能自动延续记忆”，而是换了 AI 以后，工程事实依然留在原处，下一位有办法把工作准确接回来。