多人（或多 agent）並行開發時，如果修改集中在同一個檔案，協調成本可能抵消並行的收益。以下是一個具體案例。

v0.3.0 的 JS SDK 開發中，五張 ticket 被並行派發給五個 AI agent：flush 邏輯、離線容錯、自動攔截、頁面生命週期、rate limiting。前四個都需要修改同一個檔案 monitor.ts。

結果：

• 三個 agent 回報 branch protection hook 阻擋 src 編輯
• 兩個 agent 回報 file modified since read 拒絕 Edit（另一個 agent 正在寫同一檔案）
• PM 花了多個回合協調 commit 策略：「你先 commit」「你等他完成」「你只 git add 你的檔案」
• 最終 PM 手動合併所有 agent 的變更，做了一個統一 commit

並行派發的目標是縮短總工時。但五個 agent 改同一檔案時，協調成本抵消了並行的收益。

根因：派發粒度錯在 ticket 層而非檔案層

派發決策看的是 ticket 的獨立性——五張 ticket 描述的功能確實獨立（flush、離線、攔截、生命週期各自有清楚的邊界）。但獨立的功能不等於獨立的檔案。五個功能的修改都集中在 monitor.ts 這一個檔案上。

ticket 獨立 =/= 檔案獨立。並行安全的判斷基準應該是後者。

教訓

派發前掃描 where.files：如果多張 ticket 的目標檔案有交集，序列化派發。前一張完成並 commit 後，再派下一張。

序列的代價比衝突的代價低：五個 agent 序列執行可能需要 5 倍時間，但每個 agent 在乾淨的工作區上操作，不需要協調。五個 agent 並行但衝突，PM 的協調時間加上 agent 的等待和重試，總成本可能更高。

Worktree 隔離不是萬靈丹：git worktree 讓每個 agent 有獨立的工作目錄，避免 working tree 衝突。但如果兩個 agent 修改同一檔案的不同區段，merge 時仍需人工判斷。Worktree 解決的是「同時寫同一個 working tree」的問題，不解決「同時改同一個檔案的語意衝突」。

適用場景

這個 pattern 不限於 AI agent。人類開發者在同一個 Sprint 中被分配修改同一個檔案的不同功能時，也會遇到 merge conflict。差異在於人類可以口頭協調（「我先改完你再改」），agent 目前缺乏這個即時溝通管道。派發者（PM 或 CI 系統）需要在派發時就做好檔案衝突預判。

JS SDK 的 Monitor class 在一輪並行開發中，三個開發者各自新增了 private 欄位：flushing（flush 併發 guard）、retryCount（重試計數）、lastHeartbeat（心跳時間戳）。三個欄位各自在功能邏輯中被正確使用，但都沒有加進 __reset() 方法。

測試框架在每個 test case 之間呼叫 __reset() 清理狀態。因為 retryCount 沒被重置，第一個 test case 把 retryCount 遞增到 1，第二個 test case 繼承了這個值，retry 邏輯提前觸發，測試失敗。

失敗的測試看起來像是 retry 邏輯有 bug，但實際上 retry 邏輯完全正確——問題出在測試隔離。

根因：隱含契約沒有顯性化

Class 的每個 private 欄位都有一個隱含契約：「所有生命週期路徑都知道你的存在。」這包括初始化（constructor / init）、重置（reset / dispose）、序列化（toJSON，如適用）。

新增欄位時，開發者通常會先在功能邏輯中使用這個欄位——因為那是他加欄位的目的。但「同步到 reset」不是功能邏輯的一部分，它是一個跨切面的維護動作。遺漏的機率隨欄位數和開發者數增加而上升。

多人（或多 AI agent）並行開發時問題更嚴重——每個人只看自己加的欄位，沒有人有動機去檢查 reset 的完整性。並行修改同一檔案的協調問題見 parallel_agent_same_file_conflict。

防護：State Registry Pattern

將所有 private 欄位的初始值集中宣告一次：

 1function initialState() {
 2  return {
 3    config: null,
 4    buffer: [],
 5    flushing: false,
 6    retryCount: 0,
 7    lastHeartbeat: 0,
 8    // 新增欄位加在這裡——init 和 reset 自動包含
 9  };
10}

reset 改用 Object.assign(this, initialState())。新增欄位只改一處，init 和 reset 自動同步。

配合一個 reset 完整性測試：reset 後 snapshot 比對 initialState 的所有 key——新增欄位但忘記加到 initialState 會因型別或 key 不一致而紅燈。

適用場景

任何有「重置到初始狀態」需求的 class：測試框架的 setUp/tearDown、物件池的回收、singleton 的 reinit。問題在「新增欄位」和「同步 reset」是兩個分開的動作（TypeScript、Go、Dart 都會遇到）——只要是分開的，就有遺漏的可能。State Registry 把兩者合併成一個動作。