Help us improve
Share bugs, ideas, or general feedback.
From sc-cc-plugin
通用軟體開發工作流程,適用於新增功能、修正功能、重構等程式開發需求。 以棕地專案為預設情境(保護既有行為、最小擾動),同時支援綠地專案豁免。 涵蓋五個階段:需求分析、程式碼探索、設計(計畫)、開發(棕地 TDD 任務清單)、驗證。 每個階段會產生對應的 Markdown 文件(analysis.md、plan.md、task.md、followups.md)供下一階段參考。 當使用者提出功能開發、Bug 修復、重構等需求時,主動使用此 Skill 引導整個開發流程。 觸發情境:「新增功能」、「修正功能」、「開發需求」、「implement」、「fix」、「refactor」、「建立需求」、「開發流程」。
npx claudepluginhub dannychou7911/sc-cc-pluginHow this skill is triggered — by the user, by Claude, or both
Slash command
/sc-cc-plugin:dev-workflow-v2The summary Claude sees in its skill listing — used to decide when to auto-load this skill
通用軟體開發工作流程,適用於前端與後端開發。預設為棕地專案優先,綠地專案可豁免特定步驟。
Guides technical evaluation of code review feedback: read fully, restate for understanding, verify against codebase, respond with reasoning or pushback before implementing.
Share bugs, ideas, or general feedback.
通用軟體開發工作流程,適用於前端與後端開發。預設為棕地專案優先,綠地專案可豁免特定步驟。
flowchart LR
P1["Phase 1<br/>需求分析"] --> P2["Phase 2<br/>程式碼探索"]
P2 -->|產出 analysis.md| P3["Phase 3<br/>設計/計畫"]
P3 -->|產出 plan.md| P4["Phase 4<br/>開發/TDD"]
P4 -->|產出 task.md| P5["Phase 5<br/>驗證"]
subgraph P4_Loop ["Phase 4 — 棕地 TDD 循環"]
C["⚪ Characterize<br/>釘住既有行為"] --> R["🔴 Red<br/>寫新行為失敗測試"]
R --> G["🟢 Green<br/>最少程式碼通過"]
G --> RF["🔵 Refactor<br/>優化但限縮範圍"]
RF -.->|下一個任務| C
end
綠地專案可省略 Characterize 步驟,直接從 Red 開始。
每個階段必須滿足退出條件才能進入下一階段。任何階段發現問題可回退到前一階段修正。
本流程預設專案為棕地(已有既有程式碼、使用者、測試)。在所有階段中,三條紀律凌駕於其他考量:
綠地專案豁免:若使用者明確聲明這是綠地專案(無既有使用者、無既有測試需保護),可豁免紀律 2 的 characterization 要求。紀律 1 與 3 仍適用。
LLM 在 Refactor 階段最常見的失誤是「順手改」。以下情境必須停手:
若在執行中發現「真的很想改但不在範圍內」的程式碼,記錄到 .tmp/followups.md,由使用者決定是否另開任務。
每個 Phase 結束時須執行對應的 self-check checklist。執行 self-check 時:
[ ],必須在下方寫出「未通過原因」與「補救方式」Self-check 的目的不是形式化驗收,而是強迫 Claude 在切換階段前停下來檢視自己的產出。若發現自己想跳過某項或敷衍勾選,這就是該項真正需要被檢查的訊號。
所有階段產出的文件統一存放於專案根目錄的 .tmp/ 資料夾下。
文件清單:
.tmp/analysis.md — Phase 1+2 的需求分析與程式碼探索結果.tmp/plan.md — Phase 3 的設計計畫與技術決策.tmp/task.md — Phase 4 的開發任務 Checklist.tmp/followups.md — 流程中發現但不在當前範圍內的改進建議備份規則:
{原檔名}.{YYYYMMDD-HHmmss}.md(例如 analysis.20250611-143022.md)目錄初始化:
.tmp/ 目錄存在,若不存在則建立.tmp/ 加入 .gitignore# 後續建議事項
> 產生時間:{YYYY-MM-DD HH:mm}
> 來源需求:{需求摘要}
本流程中發現但**不在當前範圍**的改進機會。請評估是否另開任務處理。
## 建議項目
### 1. {標題}
- **發現於**:Phase {N}, {context}
- **位置**:`{file:line}`
- **現況**:{描述}
- **建議**:{描述}
- **優先級**:高/中/低
- **預估規模**:小型/中型/大型
目的:釐清「做什麼」和「為什麼」。
執行步驟:
退出條件:
在進入 Phase 2 前,逐項確認:
未通過項目處理: {若有 [ ] 項,於此說明原因與補救方式}
產出:向使用者輸出需求摘要,包含範圍、雙欄驗收標準、風險。等待使用者確認後進入 Phase 2。
注意:Phase 1 的結果暫存於記憶中,待 Phase 2 完成後一併寫入
analysis.md。
目的:了解現有架構、行為契約、風險訊號,為設計提供依據。
執行方式:使用 Agent tool(subagent_type: Explore)派出子代理進行三軸探索:靜態軸、動態軸、歷史軸。每軸可獨立派一個 sub-agent 並行執行,避免大量搜尋結果佔用主要 context window。
根據以下需求,探索程式碼庫的靜態結構並回報:
1. 與需求相關的檔案清單(路徑、用途、是否需修改)
2. 現有架構模式與設計慣例(命名、結構、風格)
3. 相關模組的相依關係(depends on / depended by)
需求描述:{從 Phase 1 得到的需求摘要}
針對以下需修改的目標檔案/函式,回報:
1. 反向依賴:誰呼叫了這些函式?列出所有呼叫點(檔案 + 行號)
2. 行為契約:呼叫方對這些函式有哪些隱含假設?
- 輸入格式假設
- 回傳值/副作用假設
- 錯誤處理假設(會不會 throw?回 null?)
- 執行順序假設(同步/非同步、前置條件)
3. 測試覆蓋現況:
- 哪些行為已有測試保護?(列出測試檔案 + 測試名稱)
- 哪些行為「沒有」測試保護?(這是 Phase 4 需要補 characterization tests 的區域)
4. 資料流:相關資料從哪裡來、到哪裡去?是否跨越 API/DB/外部服務邊界?
目標檔案/函式:{從靜態軸結果得到的修改目標}
針對以下檔案,從 git history 蒐集風險訊號:
1. 過去 6 個月的修改頻率(高頻修改 = 不穩定區域 = 高風險)
2. 是否有 revert commit?revert 的原因?
3. 最近一次重大變更的 commit message 與相關 PR 描述
4. 是否有 TODO / FIXME / HACK 註解?內容為何?
目標檔案:{從靜態軸結果得到的修改目標}
執行順序:靜態軸通常先做,動態軸與歷史軸可並行。若任一軸的回報不夠完整,可追加探索或在主 context 中補充閱讀關鍵檔案。
退出條件:
在進入 Phase 3 前,逐項確認 .tmp/analysis.md:
結構完整性:
內容深度(這幾項最容易敷衍,要特別檢查):
file:line,不是只寫「多處」「若干」{假設} 占位符棕地專案額外檢查(綠地可略):
未通過項目處理: {若有 [ ] 項,於此說明原因與補救方式}
產出:
.tmp/analysis.md,內容結構如下:# 需求分析與程式碼探索報告
> 產生時間:{YYYY-MM-DD HH:mm}
> 需求摘要:{一句話描述}
> 專案類型:棕地 / 綠地
## 1. 需求分析
### 1.1 需求描述
{需求的具體內容}
### 1.2 需求範圍
{功能範圍與邊界}
### 1.3 驗收標準
#### 1.3.1 Positive Criteria(新行為)
- [ ] {新功能應達成的標準 1}
- [ ] {新功能應達成的標準 2}
#### 1.3.2 Regression Criteria(舊行為保護)
- [ ] {既有功能 X 在修改後仍正常運作}
- [ ] {既有 API contract 不變}
- [ ] {既有資料格式仍能處理}
### 1.4 風險與限制
- {風險 1}
- {風險 2}
## 2. 程式碼探索
### 2.1 相關檔案清單(靜態軸)
| 檔案路徑 | 用途 | 需修改 | 修改類型 |
|---------|------|--------|---------|
| {path} | {description} | ✅ / ❌ | 新增/修改/刪除 |
### 2.2 現有架構與慣例
- 架構描述:{description}
- 命名規則:{description}
- 設計模式:{description}
### 2.3 反向依賴與行為契約(動態軸)
針對每個需修改的目標:
#### {目標函式/模組 1}
- **呼叫方**(共 N 處):
- `{file}:{line}` — {使用情境}
- **行為契約**:
- 輸入:{假設}
- 輸出:{假設}
- 錯誤:{假設}
- 順序:{假設}
- **測試覆蓋**:
- 已覆蓋:{test file/name}
- **未覆蓋**(Phase 4 須補 characterization):{behavior description}
### 2.4 風險訊號(歷史軸)
| 檔案 | 修改頻率 | revert 紀錄 | TODO/FIXME | 風險評級 |
|------|---------|------------|-----------|---------|
| {path} | {N times / 6mo} | {yes/no} | {內容} | 高/中/低 |
### 2.5 影響範圍總評
{綜合三軸資訊,評估本次修改的影響範圍與風險等級}
目的:決定「怎麼做」,制定具體的實現方案,並選定修改策略以控制風險。
輸入:讀取 .tmp/analysis.md 作為設計依據。
重要:此階段不使用 EnterPlanMode。由 skill 自行管理計畫流程,確保後續階段不被中斷。
執行步驟:
讀取 .tmp/analysis.md,掌握需求、行為契約、測試空白區、風險訊號
選擇修改策略(棕地必做): 根據 analysis.md 的反向依賴數量、風險評級、是否影響 public API,從以下策略中選擇一種或組合:
| 策略 | 適用情境 | 代價 |
|---|---|---|
| 直接修改 | 反向依賴 ≤ 3、無 public API、低風險區 | 最簡單,但測試保護要求高 |
| Adapter / Wrapper 隔離 | 需改變內部實作但要保留外部介面 | 多一層間接,但隔離風險 |
| 平行新舊並存(Strangler Fig) | 大型重構或邏輯顛覆,無法一次切換 | 短期程式碼膨脹,長期可控 |
| Feature Flag | 需要漸進釋出或快速回滾能力 | 增加分支,但提供安全網 |
| 新建+棄用(不刪) | 既有 API 不能立即移除(外部使用者) | 留下 dead code,需後續清理計畫 |
策略選擇必須寫入 plan.md 並說明理由。
確認與本次需求直接相關的技術決策:
查閱最新技術文件(必要時):
mcp__context7__resolve-library-id 解析相關套件的 library ID,再使用 mcp__context7__query-docs 查詢最新的 API 用法、最佳實踐、breaking changes設計解決方案,包含:
向使用者呈現完整設計方案,使用 AskUserQuestion 確認或調整
確認後產生 .tmp/plan.md
退出條件:
.tmp/plan.md 已產生在進入 Phase 4 前,逐項確認 .tmp/plan.md:
結構完整性:
修改策略品質(最容易敷衍的環節):
Rollback 品質:
對齊使用者:
未通過項目處理: {若有 [ ] 項,於此說明原因與補救方式}
產出:
產生 .tmp/plan.md,內容結構如下:
# 設計計畫
> 產生時間:{YYYY-MM-DD HH:mm}
> 需求摘要:{一句話描述}
> 參考文件:.tmp/analysis.md
## 1. 技術決策
與本次需求相關的技術選型與版本確認:
| 項目 | 版本 | 決策理由 |
|------|------|---------|
| {item} | {version} | {reason} |
### Context7 / 內部歷史查閱結果(如有)
| 來源 | 查閱重點 | 關鍵發現 |
|------|---------|---------|
| {package / commit / PR} | {query topic} | {findings} |
## 2. 修改策略
**選定策略**:{直接修改 / Adapter 隔離 / Strangler Fig / Feature Flag / 新建+棄用}
**選擇理由**:
- 反向依賴數:{N}
- 風險評級:{高/中/低}
- 是否影響 public API:{是/否}
- 其他考量:{description}
**策略落地方式**:
{具體說明這個策略在本次需求中如何實現,例如「在 X 模組新增 Adapter,舊呼叫方繼續走原 API,內部委派到新實作」}
## 3. Rollback 策略
**回退觸發條件**:{什麼情況下需要 rollback}
**回退方式**:
- [ ] {步驟 1,例如「revert commit X」}
- [ ] {步驟 2,例如「關閉 feature flag Y」}
## 4. 資料相容性
- 是否涉及資料格式變更:{是/否}
- 舊資料處理:{description}
- 遷移計畫(如有):{description}
## 5. 規劃方向
### 5.1 新增項目
| 項目 | 說明 | 理由 |
|------|------|------|
| {item} | {description} | {reason} |
### 5.2 修改項目
| 項目 | 現狀 | 調整方向 | 理由 |
|------|------|---------|------|
| {item} | {current} | {planned} | {reason} |
### 5.3 移除項目(如有)
| 項目 | 理由 |
|------|------|
| {item} | {reason} |
## 6. 實現方案
### 6.1 架構設計
{整體設計思路與架構圖(如有)}
### 6.2 修改檔案清單
| 檔案路徑 | 操作 | 說明 |
|---------|------|------|
| {path} | 新增/修改/刪除 | {description} |
### 6.3 邊界情況與錯誤處理
- {case 1}
- {case 2}
## 7. 風險評估
- {risk 1}
- {risk 2}
目的:以棕地 TDD 循環(Characterize → Red → Green → Refactor)逐步實現設計方案,以 .tmp/task.md 的 Checklist 追蹤進度。
輸入:讀取 .tmp/plan.md 作為開發依據。
執行步驟:
.tmp/plan.md,掌握修改策略與規劃方向.tmp/task.md,以 Checklist 格式列出所有任務綠地專案可跳過此步驟,直接從 Step A 開始。
characterize_ 或 legacy_behavior_ 為前綴,方便識別.tmp/task.md 中對應任務的 Characterize 步驟為 [x]為什麼需要這步:接下來 Green 步驟會修改實作。如果沒有 characterization tests,你無法分辨「測試通過」是因為新行為正確,還是因為新行為意外覆蓋了你不知道的舊行為。
.tmp/analysis.md 中的 Positive Criteria,撰寫對應的測試案例.tmp/task.md 中對應任務的 Red 步驟為 [x].tmp/task.md 中對應任務的 Green 步驟為 [x].tmp/followups.md.tmp/task.md 中對應任務的 Refactor 步驟為 [x]完成一個任務的 Characterize → Red → Green → Refactor 後,再進入下一個任務。
退出條件:
.tmp/task.md 中所有項目皆為 [x]Phase 4 的 self-check 分兩層:單任務完成時檢查 TDD 循環、全部任務完成時檢查任務集合品質。
未通過項目處理: {若有 [ ] 項,於此說明原因與補救方式,必要時回退到對應 TDD 步驟}
[x]未通過項目處理: {若有 [ ] 項,於此說明原因與補救方式}
產出:
產生並持續更新 .tmp/task.md,內容結構如下:
# 開發任務清單
> 產生時間:{YYYY-MM-DD HH:mm}
> 需求摘要:{一句話描述}
> 參考文件:.tmp/plan.md
> 專案類型:棕地 / 綠地
## 任務列表
### Task 1: {任務標題}
- **涉及檔案**:`{file1}`, `{file2}`
- **測試檔案**:`{test_file}`
- **說明**:{具體要做什麼}
- **對應驗收標準**:Positive {1.3.1.x}, Regression {1.3.2.x}
**棕地 TDD 循環**:
- [ ] Characterize:補 characterization test `{描述}`,確認既有行為通過
- [ ] Red:撰寫新行為測試 `{描述}`,確認紅燈
- [ ] Green:實作程式碼,確認新測試綠燈、characterization 仍綠燈
- [ ] Refactor:審視並優化(限縮在本任務範圍內),確認所有測試仍綠燈
### Task 2: {任務標題}
...(依此類推)
目的:確認整體功能正確性、未破壞既有功能、並確保程式碼品質與 diff 紀律。
Phase 4 已確保每個任務各自的單元測試通過。Phase 5 關注「全局」:整合驗證、主動驗證、雙欄驗收標準確認、diff 紀律檢查。
執行步驟:
pnpm type-check)pnpm build)pnpm lint)try/catch、.catch()、onError,確認沒有把錯誤吞掉.tmp/analysis.md 的雙欄驗收標準:
.tmp/plan.md 的修改清單,確認沒有意外的 diff(執行 git diff --stat 檢視)若任一檢查失敗,回到 Phase 4 以 TDD 循環修正。
退出條件:
向使用者宣告「需求完成」前,逐項確認:
自動化驗證實際執行紀錄(不可只說「跑過了」,要附結果):
主動驗證實際執行紀錄(棕地必填):
驗收標準逐項對照:
[x],每條附對應的驗證證據(測試名稱或檢查方式)[x],每條附對應的驗證證據Diff 紀律:
git diff --stat 並檢視變更檔案清單最終產出物:
未通過項目處理: {若有 [ ] 項,於此說明原因與補救方式,必要時回退到 Phase 4}
產出:向使用者報告最終結果,包含:
任何階段發現需要回退時:
analysis.md;Green 無法通過:回到 Phase 3 調整 plan.md;Refactor 破壞測試:立即還原plan.md,告知使用者analysis.md回退時向使用者說明原因和調整方向。涉及文件更新時,同步更新對應的 .tmp/ 文件。
用以下「訊號清單」客觀判斷需求規模。任一高風險訊號出現即升級為大型流程。
| 訊號 | 小型 | 中型 | 大型 |
|---|---|---|---|
| 修改檔案數 | 1 | 2-5 | 6+ |
| 反向依賴數(最大) | ≤ 1 | 2-5 | 6+ |
| 影響 public API | 否 | 否 | 是 |
| 跨 layer 修改 | 否 | 否 | 是 |
| 涉及資料格式變更 | 否 | 否 | 是 |
| 測試覆蓋現況 | 完整 | 部分 | 缺乏 |
| 風險評級(歷史軸) | 低 | 中 | 高 |
| 引入新依賴 | 否 | 否 | 是 |
小型流程(所有訊號皆為「小型」欄):
中型流程(訊號落在「中型」欄):
大型流程(任一訊號落在「大型」欄):