Coding Agent 工作流：從 Issue 到 PR 的實際 SOP¶

整理自 Anthropic 工程文件與 Claude Code 官方最佳實務（見文末），2026-06-20。本頁把「用 coding agent 寫程式」拆成一條可重複的流程：Issue → Plan → Implement → Test → Review → PR，每一步寫明「怎麼做」與「為什麼」。

實證標記：〔Anthropic〕= 出自 Anthropic 官方文件；〔實務〕= 業界慣例/本人整理。預設 under-claim。

心法：把 agent 當「有工具的資淺工程師」¶

Coding agent 不是「魔法產碼機」，而是有工具、有記憶、會迭代的資淺工程師。〔Anthropic〕你給它的是清楚的任務、約束與回饋迴圈，不是模糊的願望。整條 SOP 都是在替這個心法服務。

整體流程¶

┌──────┐   ┌──────┐   ┌──────────┐   ┌──────┐   ┌────────┐   ┌────┐
│Issue │──▶│ Plan │──▶│Implement │──▶│ Test │──▶│ Review │──▶│ PR │
│ 規格 │   │ 計畫 │   │  實作    │   │ 測試 │   │ 審查   │   │    │
└──────┘   └──────┘   └──────────┘   └──────┘   └────────┘   └────┘
              ▲            │             │           │
              └────────────┴─────────────┴───────────┘
                     不過就退回上一步迭代

每一階段都有明確的「完成定義」，沒達標就退回上一步——這是讓 agent 能自主迴圈而不亂跑的關鍵。〔實務〕

1. Issue / Spec — 先把要做什麼講清楚¶

怎麼做：開工前先寫一份輕量規格（spec），描述要做的功能、輸入輸出、邊界條件、成功標準。〔Anthropic〕不必是長文件，但要能回答「做完長怎樣、怎麼算對」。

為什麼：規格是後面所有階段的錨。沒有成功標準，agent 無法判斷自己做完了沒，也無法自主迭代。〔實務〕

反模式：把模糊任務丟給 agent 就期待好結果。需求越模糊、越靠多輪對話慢慢補，token 效率與品質都越差。〔Anthropic〕

2. Plan — 先規劃，明確「先別寫 code」¶

怎麼做：要 agent 先產出計畫再動手，並明確說「現在先不要寫程式」。讓它列出步驟、要動的檔案、架構取捨，你先審過計畫再放行。〔Anthropic〕

為什麼：明確阻止過早寫 code，能避免「先射箭再畫靶」的早熟解，提升架構品質。〔Anthropic〕計畫階段也是你最便宜的介入點——改一行計畫比改一百行程式便宜。

實務：複雜任務切換到推理較強的模型來規劃；計畫拍板後再交給執行模型寫 code。〔實務〕

3. Implement — 外科手術式的最小改動¶

怎麼做：照計畫實作，只動該動的。配合 TDD 時，先有失敗的測試再寫實作碼。

為什麼：最小改動 = 最小爆炸半徑。不順手「順便」重構鄰近程式、不為單次使用做抽象、不加不可能發生情境的防呆。〔實務〕

實務：跑長任務時給足輸出空間與明確的單一目標；讓 agent 邊做邊checkpoint（做了什麼、驗證了什麼、還剩什麼）。〔Anthropic〕

4. Test — 測試驗證「意圖」而非只驗「行為」¶

怎麼做：一個常見且有效的模式是 Writer/Tester 分工——一個 agent 寫測試，另一個寫程式去通過它。〔Anthropic〕

為什麼：測試要編碼「為什麼這行為重要」，不只是「它做了什麼」。一個無論業務邏輯怎麼改都不會失敗的測試是壞測試。〔實務〕讓寫測試與寫實作分開，能減少「為自己的碼量身訂做測試」的偏誤。

完成定義：測試全綠才算過。任何被略過（skip）的測試都要明講，「測試通過」若隱藏了被略過項目就是錯的回報。〔實務〕

5. Review — 用「乾淨的 context」審查¶

怎麼做：用 Writer/Reviewer 模式——換一個全新 context 的 agent 來 review，因為它不會對「剛剛自己寫的碼」有偏袒。〔Anthropic〕

為什麼：同一個 context 的 agent 容易為自己辯護、看不到自己的盲點。新鮮 context 的審查者更能挑出真問題。〔Anthropic〕

實務：收到 review 意見時要技術性查證，不要表演式同意也不要盲目照改；意見不清或技術可疑時先釐清再動手。〔實務〕

6. PR — 收斂成可審查、可回溯的變更¶

怎麼做：把通過測試與審查的工作整理成一個聚焦的 PR；commit 訊息與 PR 描述說明為什麼這樣改，而非流水帳。〔實務〕

為什麼：PR 是人類把關與回溯的介面。清楚的「意圖說明」讓 reviewer 不必逆推你的思路。〔實務〕

⚠️ 注意外向、難回復的動作（push、開 PR、發佈）通常需要先確認；在一個情境得到的批准不自動延伸到下一個。〔實務〕

貫穿全程的紀律原則〔實務〕¶

Checkpoint：每個重要步驟後summarize「做了什麼／驗證了什麼／還剩什麼」，別從一個你描述不出來的狀態繼續。
Fail loud：跳過了就講跳過、測試有 skip 就講 skip；預設surface不確定性，而非藏起來。
成功標準驅動：定義完成標準後讓 agent 迴圈到驗證為止，而不是死板照步驟。強的成功標準才能放心自主迴圈。

進階：並行與隔離¶

要加速或跑隔離實驗時，可並行多個 agent session——透過 git worktree、桌面 App 多視窗、或 agent 團隊。〔Anthropic〕並行時務必避免共用狀態：別讓兩個 session 同時改同一批檔案、同時 commit、或搶用同一組會限流的外部 API。〔實務〕