載入中

Claude Code 計劃模式作為預設起點

第 4 課6 分鐘

工程師以計劃模式啟動 Claude Code 工作階段,將第 2 階段:設計中已核准的 spec.md 交給 Claude,讓它向他們提問,並反覆修改計劃,直到他們滿意為止。

改變了什麼

傳統做法AI 原生做法
工程師閱讀設計文件後就開始寫程式碼。變更將如何實作,細到哪些檔案、哪些測試,這些資訊都留在工程師腦中,頂多寫在工單留言裡。其他人都無法審查。審查者首先看到的是完成的差異(diff),而到那時候再返工已經很慢了。工作從一份書面計劃開始,由 Claude 在計劃模式下產生,此時它可以讀取程式碼庫而不做任何變更。工程師在程式碼撰寫之前修正計劃,經核准的版本會以 plan.md 的形式提交,供後續階段核對。

開始使用

  • 先決條件:如果已有意圖文件(intent.md 或 spec.md),以及 CLAUDE.md 檔案,都會有所幫助。
  • 基礎架構:具有存取儲存庫權限的 Claude Code。

如何執行

  1. 工程師以計劃模式與 Claude 開始工作階段。
  2. 工程師將 intent.md 和 spec.md 交給 Claude,並要求一份實作計劃,其中要指明會變更哪些檔案、工作順序,以及能證明其正確性的測試。
  3. 藉由詢問這項變更可能會破壞什麼、哪個步驟風險最高,以及 Claude 選擇不採用的其他方案,來質問這份計劃。
  4. 反覆修改,直到一位從未參與這段對話的工程師,僅憑這份計劃就能實作這項變更為止。
  5. 將核准的計劃以 plan.md 的形式提交。這份計劃會併入稽核軌跡,而 PR 審查環節(第 5 階段:部署)會用它來核對最終的差異。
  6. 接受這份計劃,並讓 Claude 進行實作。有了紮實的計劃,實作通常一次就能完成。
  7. 當實作偏離計劃時,在同一次提交中更新 plan.md。可以考慮使用掛鉤(hook)來強制兩者保持同步。

實際情況

以下這份計劃,是為一家保險公司的一項變更而寫:客戶入口網站中的一個面板,用來顯示理賠狀態。該面板會呼叫入口網站的後端 claims-api,而後者會從較舊的內部系統 claims-core 讀取資料。

plan.md:

markdown
# Plan: claims status self-service (from intent.md and spec.md)

## Files that change

portal/src/claims/StatusPanel.tsx (new), claims-api/routes/status.py, claims-api/tests/test_status.py

## Order of work

1. Add the status endpoint behind existing auth (R1, R2, R3).
2. Panel against the endpoint, with the 60-second cache (R1, R4).
3. Wire into the portal nav.

## Risks

The claims-core API rate-limits at 50 rps; the panel must cache (spec concern 3).

## Proof

test_status.py covers the four claim states (R2) and fails on any extra field (R3); screenshot matches the approved mock.

R1 到 R4 是 spec.md 中已編號的需求,而 concern 3 則是 spec.md 中標記的一項風險。由於計劃引用了這些編號,審查者便能逐行對照計劃與規格書。

治理考量

設計審查會在任何程式碼產生之前進行,此時要改變方向仍只是編輯文件的問題。計劃模式本身就強制執行這一點,因為在工程師接受計劃之前,Claude 無法編輯檔案。計劃及其修訂版本都會連同核准者一併記錄下來。常規變更由工程師核准,而組織歸類為較高風險的任何事項,則交由技術主管或架構師處理。

如何衡量

  • 領先指標:第一次實作即合併的變更比例,以及從計劃核准到 PR 合併所需的時間,這些資料都包含在 PR 中繼資料所需的資料裡。
  • 落後指標:每項變更的返工循環次數(同樣來自 PR 中繼資料),以及合併後的差異與已提交的 plan.md 仍相符的頻率。

自動模式下的 Claude Code

Claude Code 也可以在自動模式下執行,由工程師反覆修改並核准計劃,然後 Claude 會套用每一項變更,而不會逐項編輯時都詢問。隨著後續環節中的防護機制逐漸成熟(經過調整的 CLAUDE.md、將政策編碼成技能、能阻擋不安全動作的掛鉤,以及 Claude 可以執行的測試套件),自動模式會成為常規工作的預設方式:精簡的 spec.md、較小的影響範圍,以及測試已經涵蓋到的程式碼。

這種轉變,現在是從使用者看著代理程式進行編輯並審查每個動作,轉向在較長的自主工作階段後審查產出物。搭配 worktree 使用時,自動模式能進一步提升個人與團隊之間的平行處理能力,這對於自主執行 SDLC 以及如第 6 階段:維護所述的閉環運作,是不可或缺的基礎。

舊系統與真實來源

現有的 SDLC 流程很可能已經在追蹤產出物,只是並非以 Markdown 檔案的形式。工作項目可能在 Jira 中,需求可能在內建法規可追溯性功能的工具中,設計可能在 Figma 中,而變更核准則透過變更委員會進行。這些系統很難被取代,因為稽核人員和監管機構已經接受它們,其他團隊也依賴它們,因此 AI 原生的 SDLC 必須配合既有的一切。對於流程所產生的每一項產出物,都應指定一個系統作為真實來源,其他系統則保留副本或連結。

您可以設定以下組態,讓每項產出物依其不同選擇擁有各自的單一真實來源:

  • 以儲存庫作為真實來源。 Markdown 產出物是權威紀錄,舊系統則在提交(commit)中參照這些檔案。對於工程主導的組織而言,這可能是最乾淨的組態之一,因為所有紀錄都存放在同一個工具中,且由同一個時間戳記權威機構管理。
  • 舊系統才是真實來源。 Jira、ServiceNow 或需求工具保存權威紀錄,而 Markdown 產出物則是工作副本。Claude 會在工作階段開始時讀取該紀錄,並在同一個產出規格或計劃的工作階段中,透過 Model Context Protocol(MCP)連接器將結果寫回去。
  • 以連結作為最低標準。 所有產出物都註明紀錄 ID,而所有舊紀錄都包含 Markdown 檔案的提交 SHA 值。在轉換為 AI 原生 SDLC 的過程中,由於存在兩個真實來源,這個連結選項是一個不錯的起點。

只要兩者之間存在連結,或其中一方被宣告為真實來源,舊系統與 AI 原生的 Markdown 優先系統便可以並存。