你讓 Claude Code 在 worktree A 重構付款架構，同時讓 Codex 在 worktree B 加入 PayPal。兩邊沒有改到同一行，Git 也能乾淨合併；但第一個 Agent 已把呼叫端搬到 StripePaymentService，第二個 Agent 卻還在替舊的 PaymentService 加功能。這正是 Foremerge 教學 要處理的問題：程式碼還沒衝突，兩個人的意圖已經互相拆台。
這篇專為第一次管理平行 Agent 的讀者寫。你不需要先懂 SQLite 或 MCP；我們會先用一句話抓住原理，再固定版本、驗 checksum、初始化共享狀態，最後人工注入「替換 Stripe」對上「沿用舊抽象加 PayPal」的衝突。讀完後，你不只會安裝 Foremerge，也會知道它何時命中、何時可能誤報、何時會漏掉，以及人類應在哪一關按下暫停。
先說結論：Foremerge 是 Agent 的「開工白板」
一句話記住：Worktree 隔離「檔案」，Foremerge 對齊「意圖」；兩者加起來，才是可控的平行開發。
- Git／worktree 處理程式碼歷史與檔案隔離，擅長發現同一段文字互撞。
- Foremerge 讓 Agent 在動手前宣告「要改哪個語意範圍、是延伸還是替換」，再把相斥的宣告變成 advisory。
- 共享狀態 預設放在 Git common directory 下的
foremerge/state.sqlite3，同一個 repository 的 linked worktree 會看到同一份資料。 - 警告不是鎖。claim 仍是 advisory；真正的硬閘門在 ChangeSet 驗證與接受階段，人類仍負責架構判斷。
如果你還不熟 Agent 為什麼需要執行層，先讀 AI Agent Harness 是什麼；本文處理的是更窄的一層：多個 Harness／Client 同時工作時，如何共用一張「誰正打算改什麼」的白板。
Foremerge 教學：先拆開 5 個零件
① Agent：「這一輪工作是誰做的」
每個 Claude Code、Codex 或 Cursor session 都要先註冊自己的 Agent ID、模型與 worktree。它像工地簽到，不是帳號驗證；官方限制文件明示，Agent identity 是 caller 自行宣告，不能把它當成安全邊界。
② Intent：「還沒動手的工作票」
Intent 記錄 task、summary、scope 與 operation。關鍵不是把 prompt 再存一次，而是把容易衝突的部分結構化：symbol:PaymentService=replace 代表會破壞別人依賴的舊介面；symbol:PaymentService=extend 則代表要保留它並加功能。
③ Semantic scope：「大家講同一個地址」
Scope 不只可以是 file，還有 symbol、api、schema、config、infra、migration、component、contract 等。檔名像街名；semantic scope 更像門牌。跨語言 API、資料庫 schema 與環境變數衝突，通常只看檔案抓不到。
④ Conflict advisory：「停下來對話的證據」
官方 v0.5.0 規則把 exact canonical scope 且雙方明確宣告 operation 的結果標成 asserted。其中 replace/remove/rename/migrate 對上 add/extend/modify 會觸發 FM-C001、嚴重度 HIGH。模糊 scope 或從 prose 推測 operation 的結果不會升到 HIGH。
⑤ ChangeSet＋named check：「完成不是 Agent 自己說了算」
Agent 做完後發布 ChangeSet，Foremerge 針對確切 Git fingerprint 執行人類先註冊的 named check。MCP Agent 只能選 test、lint 這類名稱，不能臨時塞任意 command；但這仍不是 sandbox，命令會使用 Foremerge process 的本機權限執行。
Foremerge 教學安裝：固定 v0.5.0，再驗官方 checksum
截至 2026 年 9 月 24 日，最新 GitHub release 是 v0.5.0，發布於 2026 年 9 月 23 日。這版修正 HTTP validation endpoint 可執行任意 argv 的風險，改為只接受 named check；CLI 與 MCP surface、ledger schema 則維持相容。專案仍明確標示為 pre-1.0、local-first MVP，public schema 可能變動。
官方一行 installer 會自行下載 archive 並驗 SHA-256；教學環境若要同時固定版本與保留收據，建議直接下載 release artifact。以下以 Apple Silicon 為例；Intel Mac 改成 x86_64-apple-darwin，Linux 依 CPU 改成對應的 *-unknown-linux-gnu：
VERSION=v0.5.0
TARGET=aarch64-apple-darwin
ARCHIVE="foremerge-${VERSION}-${TARGET}.tar.gz"
BASE="https://github.com/naw103/foremerge/releases/download/${VERSION}"
curl -fL -O "${BASE}/${ARCHIVE}"
curl -fL -O "${BASE}/${ARCHIVE}.sha256"
shasum -a 256 -c "${ARCHIVE}.sha256"
tar -xzf "${ARCHIVE}"
./foremerge --version
驗收點有兩個：checksum 必須顯示 OK，版本必須精確回報 foremerge 0.5.0。不要只看檔名像不像；版本與 digest 都對，才把 binary 放進 PATH。
初始化：讓 Claude Code 與 Codex 看同一份狀態
在要協調的 Git repository 根目錄執行：
foremerge init foremerge setup all foremerge checks set test -- pnpm test foremerge doctor --client all
init 會把狀態放到 $(git rev-parse --path-format=absolute --git-common-dir)/foremerge/state.sqlite3，不會改 tracked files。setup all 會安裝各 Client 的 Skill 與 MCP entry：Claude Code 使用 project .mcp.json，Codex 使用 user-level MCP registration；後者一份註冊可服務多個 repository，實際 repository 由你啟動 Codex 的目錄決定。
這也解釋了為什麼兩個 Client 能共享狀態：不是 Claude 把記憶傳給 Codex，而是兩邊的 Foremerge MCP 都解析到同一個 Git common directory。若 Agent 彼此看不到，先比較兩邊的 git rev-parse --path-format=absolute --git-common-dir，再跑 foremerge doctor --client all；不要先猜是模型問題。
Claude Code 官方 MCP 文件把本機 stdio MCP 定義為由 Client 啟動的本機 process；Codex 的官方 MCP 文件也確認 CLI 與 IDE extension 共用 MCP 設定。Foremerge 的 setup 只是替你產生符合兩邊 discovery 規則的 entry，並以絕對 binary path 避免 desktop launcher 的 PATH 差異。
故障注入：兩個 Agent 還沒寫 code，就先讓意圖互撞
先註冊兩個 session。這裡使用 --no-worktree 只為縮短教學；正式工作請讓每個 Agent 註冊自己的 isolated worktree 與真實 model identifier。
STRIPE_AGENT=$(foremerge --json agent register \ --name stripe-agent --model claude-code --no-worktree | jq -er '.data.id') PAYPAL_AGENT=$(foremerge --json agent register \ --name paypal-agent --model codex --no-worktree | jq -er '.data.id')
Agent A 先宣告要替換抽象：
foremerge --json intent publish \ --agent "$STRIPE_AGENT" \ --task modernize-payments \ --summary "Replace PaymentService with StripePaymentService" \ --scope symbol:PaymentService=replace
Agent B 再宣告要沿用同一個抽象加入 PayPal：
foremerge --json intent publish \
--agent "$PAYPAL_AGENT" \
--task add-paypal \
--summary "Add PayPal support to PaymentService" \
--scope symbol:PaymentService=extend | \
jq '.data.conflicts[] | {
kind, severity, scope, explanation, suggestion, evidence
}'
你要驗收的不是某一句漂亮解釋，而是結構欄位：kind 應為 destructive_vs_additive、severity 應為 HIGH、evidence.rule 應為 FM-C001，而且 asserted 為 true。這代表雙方明確宣告同一 canonical scope 的相斥 operation；suggestion 仍只是 heuristic，不是 Foremerge 替你決定架構。
讀懂命中、誤報壓力與漏報：三組測試矩陣
案例 A：exact scope＋replace／extend，應命中 HIGH
這是上面的 PaymentService 例。它是 Foremerge 最強的案例，因為 detector 不必猜 prose；兩邊自己宣告了相同 scope 與相斥 operation。若沒有 HIGH，先檢查 key 大小寫正規化以外的拼字差異、operation 是否遺漏，以及兩個 Client 是否真的讀同一個 database。
案例 B：同一 scope 都是 extend，MEDIUM 不等於錯誤
例如一個 Agent 加 latency metrics，另一個加 request ID，兩邊都宣告 symbol:AuditService=extend。Foremerge 會用 FM-C003 shared_contract 提醒它們可能共用 contract。兩份實作也許完全相容；此時 MEDIUM 的正確用法是交換介面與 dependency order，而不是停止所有工作。這就是「可能的 false positive 壓力」：工具看見共享邊界，人類判斷是否真的互斥。
案例 C：概念相同、名字不同，空結果不等於安全
若一邊宣告 symbol:AuditService=extend，另一邊其實要替換同一條 logging boundary，卻寫成 component:ObservabilityPipeline=replace，detector 可能回傳空陣列。官方限制也明示：Foremerge 不做 whole-program semantic analysis，對同義概念會漏報。改善方法不是把所有詞塞進 summary，而是團隊先建立 scope vocabulary，重要邊界同時宣告 symbol 與 contract。
Foremerge 與純 worktree 流程差在哪？
純 worktree 流程的強項是隔離 working tree。Stripe branch 改 app.py 與新增 stripe_payment_service.py，PayPal branch 只新增 paypal_payment_service.py，Git 可以把兩個 branch 都乾淨合併；結果卻是 app 已不再使用舊 PaymentService，PayPal extension 留在無人呼叫的路線上。Git 沒做錯，它只負責文字與歷史。
- 只用 worktree：先讓兩邊自由產生 diff，最後才在 merge、review 或整合測試發現方向不合。
- 加上 Foremerge：開工前宣告 scope／operation，讓 Agent 在成本最低時看到 related work；實作後仍回到 Git、review、CI 與 protected branch。
- 最佳組合：一個 task 一個 worktree，再用共享 semantic state 連起來。Foremerge 不自動 merge、rebase、cherry-pick、push，也不取代 Git hosting 規則。
如果你想把 worktree 本身補齊，可接著讀 Proliferate／worktree 教學；要比較兩個 coding Agent 的工作模型，則看 Claude Code vs Codex。
人類批准閘門：HIGH 出現後要做什麼？
- 停在寫 code 前。不要把 HIGH 當成紅色通知看完就算；先確認兩邊的 scope 與 operation 是否真實。
- 比較 outcome，不只比較檔案。問「Stripe 重構完成後，PayPal extension point 還存在嗎？」
- 選擇一個共同 contract 或明確排序。可能是先建立
PaymentProvider，也可能是 PayPal task 等待重構完成後再 rebase；suggestion 只是起點。 - 留下 assessment 與 coordination message。讓下一個 Agent 知道為什麼改 scope、合併 task 或延後，而不是只看到衝突被關掉。
- 跑 named check，再接受 ChangeSet。例如
foremerge checks set test -- pnpm test。MCP 不允許 Agent 自行繞過 HIGH 或 unverified gate；若真的要 override，必須由人類走 CLI／HTTP operator surface 並留下理由。
想把這種「模型提案、執行層驗收」擴成完整系統，可搭配 AI Agent Harness 實作；要檢查外部 Plugin／Skill 的供應鏈，則看 Plugin4Shell 防護教學。
清理、停用與完整卸載
先關閉正在使用此 repository 的 Claude Code／Codex sessions。只想停用 Client integration 時，移除 Foremerge 自己的 entry 與 skill，不要刪整份共享設定：
codex mcp remove foremerge claude mcp remove foremerge --scope project # 只刪 Foremerge 的 skill 目錄 rm -r .codex/skills/foremerge rm -r .claude/skills/foremerge
這些動作不會刪除 SQLite ledger、accepted Git refs 或 event history。若還要移除 installer 放進 ~/.local/bin 的 binary，先用 command -v foremerge 與 command -v fmg 確認精確路徑，再只移除那兩個檔案。Ledger 若要重建，先跑不帶 --yes 的 foremerge ledger reset 看計畫；正式 reset 會把舊 ledger 與 sidecar 搬到 timestamped backup，不是直接刪除。
常見問題 FAQ
1. Foremerge 會阻止 Agent 繼續工作嗎？
不會。 Intent conflict 與 claim 都是 advisory。它會在接受 ChangeSet 時檢查未解 HIGH、Git cleanliness 與 validation，但不在開工時鎖檔案或鎖 Agent。
2. 它會自動讀懂所有 code dependency 嗎？
不會。 v0.5.0 的 detector 比較 Agent 宣告的 scope／operation，加上有限的文字相似度；官方明示目前不做 whole-program semantic analysis。
3. 只有一個 Agent 也需要嗎？
不一定。 單一線性 session 的協調收益較小；當同一 repository 同時有 subagent、多個 terminal、Claude Code 與 Codex 交錯工作時，共享 intent ledger 才最有價值。
4. 不同電腦上的 Agent 能共享同一份狀態嗎？
目前的官方範圍不是這樣。 v0.5.0 是 local-first，SQLite 不做跨機 replication、network partition 解決或 multi-host consensus；官方也要求不要把 network-mounted database 當成 distributed safety。
5. Claude Code 與 Codex 真能共用嗎？
可以，但前提是指向同一個 Git common directory／database。 MCP Client 不必相同；Foremerge protocol 與 SQLite store 才是共用層。
6. 如何降低 false positive？
把 HIGH 與 MEDIUM 分開處理。 HIGH 要求 exact canonical scope 與雙方明確 operation；MEDIUM 是協調提示。不要把每個 shared contract 都當成互斥，也不要用過大的 component:backend 包住所有工作。
7. 如何降低漏報？
建立團隊 scope vocabulary，並在重要邊界重複宣告。 例如同時列出 symbol:PaymentService、contract:payment-provider 與 api:POST /payments；工作方向改變時釋放舊 intent，再發布新 intent。
8. 有公開 benchmark 證明它能省多少時間嗎？
還不能這樣下結論。 官方 README 與 benchmark plan 明確寫著：目前有 fixtures、query harness 與研究設計，但尚未發布 coordinated-vs-uncoordinated performance results；因此不要引用節省工時百分比，也不要把維護者內部經驗當成獨立審計結果。
給新手的 6 個重點
- 先用 worktree 隔離檔案，再用 Foremerge 對齊意圖。
- 版本固定到 release，checksum 與
--version都要驗。 - HIGH 只相信明確 scope＋operation；空結果只代表目前沒有已知衝突。
- MEDIUM 是請你協調，不是自動判定其中一個 Agent 錯了。
- 重要 API／schema／contract 要建立共同命名，否則同義詞會漏報。
- Foremerge 記錄協調與驗證；Git、review、CI、安全掃描與人類架構責任仍保留。
想系統化學會把 Agent 從「會回答」推到「可驗收地做事」，可以前往 AlphaLab 課程；更多工具與方法整理在 AI 專區。
結語：先讓意圖相遇，再讓程式碼相遇
Foremerge 最值得帶走的不是某個指令，而是開工順序：先宣告 intent 與 semantic scope，再進 worktree 寫 code；先處理 HIGH，再跑 named check；最後才交給 Git 整合。今天就用一個 disposable repository 重跑 PaymentService 的 replace／extend lab，再刻意把兩邊 scope 改成不同名字，親眼看見一次命中與一次漏報。你理解了這兩個邊界，才真正學會怎麼用它。