把工程上下文留在 GitHub：AI 程式開發跨工具接力與多分支協作

2026-10-21

GitHub-first 工作流程：不同 AI 工具讀取 GitHub 任務與版本，分支開發、PR 複審，最後經人工同意才合併。 — 架構示意：跨工具接力、分支隔離、獨立複審與過期版本停止；權限和分支名稱只是示例。

換一套 AI 程式開發工具，最煩的往往不是模型不會寫程式，而是得重新解釋整個專案：上一輪為什麼選這個架構、哪個分支還在改、哪些測試真的過了、哪份 PR 還沒審查，以及上一位 Agent 究竟被授權做到哪一步。

我後來把這些容易隨對話消失的進度放回 GitHub。Codex、Claude Code、Cursor，或瀏覽器裡的 ChatGPT，都可以成為下一個入口：先讀專案任務和版本。有寫入權限的工具在自己的分支提交；只有讀取權限的工具則提出審查意見。

這就是我所說的 GitHub-first：AI 工具可以換，工程狀態不能跟著聊天視窗消失。 為了記住進度，不必另外維護一個常駐 Bot；只帶手機出門時，也能把下一步交出去。

對話記憶不等於工程上下文

長期專案常跨越數天。A 工具之前否決了什麼設計，B 不知道；新對話看見舊版 CI 全綠，卻以為目前 HEAD 也通過；兩個人改同一份檔案，都認為自己是負責人。把十頁歷史貼進 Prompt 可以暫時解決，但專案只會越來越綁定某個產品的對話紀錄。

真正要分清的是對話記憶與工程上下文。把程式碼推到 GitHub，不會讓模型自動共享先前的思考或聊天記憶；但下面四類資訊可以被讀取、核實和更新：

專案規則：AGENTS.md、README、架構文件。工具不一定自動載入 AGENTS.md，必要時明確要求讀取。
任務身分：Issue、task ID、計畫、負責人、checkpoint、已完成工作及待驗證項目。
程式碼版本：main、feature branch、commit／Git Blob SHA，以及目前真正工作的分支。
審查與驗收：PR diff、審查留言、ACK、對應精確 HEAD 的 CI run、合併與部署紀錄。

它們不用全部塞進一個大型 JSON。Git 管版本，Issue／PR 管討論，必要時 checkpoint 補充下一步。金鑰、臨時對話快取、高頻鎖狀態都不適合放進版本庫。

我通常給新會話一段短指令，先要求它唯讀恢復事實；為了跨工具複製，下面的程式範本維持英文：

You are the developer for this task. Recover project state read-only first.
Repository: OWNER/REPO
Task: Issue #N, linked PR #M, task ID TASK_ID

Read repository rules, the plan, checkpoint, current feature-branch HEAD,
PR diff, the latest applicable review comments, and checks for that HEAD.
Explain the authorized actions, verified work, and remaining gates.
Stop and report if the branch moved, permissions differ, or orders conflict.
Do not merge, deploy, or change production settings without separate approval.

獨立開發者可先從輕量版開始：一份專案說明、一個 Issue 或 PR、最近幾筆 commit，就能練習換工具接力。工作跨天、多位 Agent 同時寫入或需要獨立審查時，再考慮加入 checkpoint 與 Order／ACK 校驗。

一個 GitHub 底座，連接多個 AI 入口與分支

整體流程可以簡化成這張文字圖，首屏動態 SVG 也在呈現相同的關係：

Phone / browser / local IDE / cloud coding agent
                       |
             Read GitHub task facts
                       |
       AGENTS.md · Issue · plan · checkpoint
                  branch · PR
                       |
              Check permission scope
                       |
         Feature branch A     Fix branch B
                  |                |
                commit           commit
                  |                |
                 PR A             PR B
                     \           /
                   review + CI per HEAD
                           |
                  Human approval to merge
                           |
                          main

各入口的 GitHub 權限並不相同。有的整合只能搜尋與閱讀，有的 Coding Agent 能在自己的環境修改檔案、建立分支或 PR。本文寫於 2026 年 10 月，這是在解釋不同能力類型，並非逐一實測上述產品當前的所有權限。 真正開始前仍要依帳號和連接器確認 read、write、comment、merge 和 deploy 的授權。

分支讓多位開發者或 Agent 能平行工作。例如雲端 Agent 處理功能 A，手機上的對話提出文件修訂，本地 Codex 處理介面修復。它們可以讀相同的專案規則，但分別在 feature/A、docs/B、fix/C 寫入，最後由 PR 匯合。

分支隔離不代表邏輯上不會衝突。 兩條分支仍可能同時改同一個 API。最好限制每條任務分支只有一位實際寫入者，合併前再次確認共同基線、受影響檔案、最新 CI 和整合測試。GitHub 的 Pull Request 文件與受保護分支說明了既有的審查與檢查機制。

若要在本機維護多個獨立工作目錄，可使用 Git Worktree；我在多分支 Worktree 實踐另有介紹。本文更關心的是：不同 AI 工具如何正確認領同一個 GitHub 任務，然後把結果匯回。

跨工具接手：先核對 Issue、分支和 PR

Prompt 只是入口，真正能不能接手取決於版本庫裡留下的事實。新工具至少要回答：目前是哪個 HEAD？上一位交付了什麼？誰有權繼續寫入？

輕量版可以先建立簡短的 AGENTS.md，說明專案規則、測試命令與任務位置：

# AGENTS.md

- Stack and architecture: see README.md and docs/architecture.md
- Install and test: follow the current commands in README.md
- Task entry points: GitHub Issue and linked PR
- Optional state: tasks/<TASK_ID>/checkpoint.json
- Before editing: verify task ID, branch, and live HEAD
- Prefer one writer for each feature branch
- Merges and deployments need separate approval

checkpoint.json 用來記錄程式碼本身看不出的階段資訊。下面使用我真實專案裡的欄位名稱，但識別碼都換成占位值：

{
  "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": "Read current HEAD and review comments before resuming"
}

這不是私有 checkpoint 的原件，也不是必須每次 commit 都修改的檔案。小任務放在 Issue／PR 留言即可；我只在重要交接、階段驗收或阻塞時更新 checkpoint，以免讓 Git 歷史全是狀態更新。

還有一個常被忽略的陷阱：checkpoint.commit_sha 是上一次確認的程式碼版本，不一定是包含這份 checkpoint 的 commit，更不是即時 HEAD。 假設版本 A 已驗證，隨後用版本 B 寫入 checkpoint，文件可以指向 A，但不能在建立 B 之前就知道 B 自己的雜湊值。兩者也不是固定「差一個 commit」。

新會話應先向 GitHub 讀取即時 HEAD，再核對 checkpoint 記錄的歷史基線與後續變更；兩個 SHA 不同並不必然表示錯誤。ACK 的 observed_head_sha 與 new_head_sha 分別描述舊的審查版本與修改後版本；過期的 Order 要另外執行過期檢查。

AGENTS.md 保存規則，Issue／PR 保存討論與審查，checkpoint 則按需要摘要階段。若工具沒有自動讀 AGENTS.md，就直接在接手指令裡要求讀取。

我也把自己使用的較嚴格交接協定開源了。輕量接手不需要安裝它；想檢查 Order／ACK 如何綁定 HEAD、拒絕過期指令，以及離線校驗器如何處理重複接手，可以查看原始碼和測試：

vxime/conversation-memory-hub

倉庫提供的是協定、校驗器與範例，不是會自動喚醒其他 AI 對話的託管服務。真正的任務、分支和 PR 仍保存在你自己的 GitHub 倉庫。

真實 PR：FIX_REQUIRED、ACK 與獨立複審

看到架構圖很容易讓人自我滿足：兩個 AI 都說「收到」，就以為接力成功。我回頭檢查了一份真實的文件 PR：B 提出兩項問題，A 修訂後回寫，B 對新 HEAD 再次審查，最後由人決定是否合併。

先說清楚，大寫的 FIX_REQUIRED、ACK、ADVANCE 是我這個專案自訂的評論協定，不是 GitHub 原生 PR 狀態。它們分別代表要求修復、開發者確認及回報新版本、審查者複核後允許繼續。STALE_ORDER 則表示指令綁定的版本已經過期。

那份 PR 只是修正 Runner 的唯讀審計計畫，並沒有安裝 Runner。較關鍵的 F-001 發現是：計畫想檢查 GitHub Actions 的留言事件風險，實際命令卻只列出 workflow 檔名：

# Original plan: names only; the YAML triggers remain invisible.
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。這是由人主動推進的兩個 AI 會話，不會自動喚醒另一個對話，也沒有把 decideResume() 安裝成 GitHub Actions 門禁或本機 Git hook。簡單任務用普通 PR 留言加上精確 HEAD 就能交接。

以下是實際 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: Inspect workflow triggers at a pinned SHA",
    "F-002: Correct the audit plan's section reference"
  ]
}

原始協定還有其他完整性欄位；這是方便理解的節選。重點是 A 明確知道自己修的是哪個舊 HEAD，也交出能讓 B 重新審查的新 HEAD，而不是只說「修好了」。

這次 PR 只改審計文件，沒有對應 HEAD 的成功 CI，也沒有在正式 VPS 執行審計。可確認的是一次可追溯的修復與複審流程，而不是整套系統已經全自動上線。

STALE_ORDER：舊 HEAD 的指令必須停止

Order 是 B 留在 Issue／PR 留言裡的結構化指令，包含 task ID、目標分支、當時的 observed_head_sha、問題及准許或禁止的操作。ACK 的 order_id 用來指回這份指令。

我們做過一次負向演練：測試 Issue 的 Order 綁在舊的 main HEAD，後來版本已前進。新會話再次看到舊 Order 時，應該回傳 STALE_ORDER 而不是按照過期指令繼續寫入。

我直接核對了舊 Order、後來的 HEAD，以及原始碼裡 decideResume() 的過期檢查。當時 A 回報確實已停止，但這份結果是由人轉述存檔，不是 A 自己在 GitHub 另留一條獨立 ACK。這是一項有用的負向演練，不能寫成所有客戶端已通過端到端安全驗證。

實用規則就是：B 把任務、分支、HEAD 與權限綁在指令裡；A 接手時重新查即時 HEAD；若版本已變，就停止並請 B 用新版本複查。曾經正確的建議，也可能不再適用於現在的程式碼。

我因此保留獨立審查。AI 產生一份看起來合理的 diff，與另一個會話對真正的新 HEAD 核實修正，是兩個不同的事實。更一般的多 Agent owner 與交接設計，另見AI Agent Orchestration：共享狀態與交接。

只帶手機，也能推進工程協作嗎？

這套方式讓我不必為了盯進度一直開著某台 Mac，也不必另外養一個常駐協調 Bot。只要手機端有合適權限，就能讀 PR、看差異、回覆審查與交代下一步。真正的程式修改、建構與測試，仍須由有權限的雲端 Agent、Runner 或本機環境執行。

成本也要分開看：少重複貼聊天、少維護專用服務，可能節省的是時間與運維；模型推論、Chat／Codex／API 額度與 CI 仍各有成本。我沒做過同任務的 Token 對照，所以不會杜撰節省百分比。

我的部落格另有 GitHub Actions → Self-hosted Runner 的部署流程；跨裝置開發與統一部署講的是最後如何上線。這篇要回答的是更前面的問題：換人、換 AI 或換裝置後，如何確認接手的真的是同一項任務？

低風險的單檔修改，一個 AI 加一條分支或許就夠了。等專案跨天、跨工具、跨人，checkpoint、分支責任、獨立審查和操作授權才越來越有用。GitHub-first 最吸引我的不是 AI 神奇地共享記憶，而是工程事實一直留在原處，讓下一位能準確接手。

AI & Coding github ai-coding ai-agents context-management git-workflow agents-md