Help us improve
Share bugs, ideas, or general feedback.
From sc-cc-plugin
從棕地專案(brownfield project)的既有程式碼中回推、產生、補齊規格文件。 適用於任何前端(Vue / React / Angular / 任意框架)與後端(Node.js / Python / Go / 任意語言)專案, 不限定框架或語言。 當使用者提到「回推規格」、「補規格書」、「產生規格文件」、「從 code 生成文件」、 「reverse engineer spec」、「recover specification」、「建立文件」、 「幫我寫規格」、「這段 code 的規格是什麼」、「分析這個模組」, 或者使用者給了一段程式碼或一個專案目錄要求產出文件時,都應觸發本技能。 也適用於使用者想對某個特定檔案、元件、API、模組產生規格描述的情境。 即使使用者只說「幫我看看這段 code」但上下文暗示需要文件化,也應主動觸發。 Chinese triggers: "規格書", "規格文件", "產生規格", "文件化", "棕地專案", "逆向工程文件"
npx claudepluginhub dannychou7911/sc-cc-pluginHow this skill is triggered — by the user, by Claude, or both
Slash command
/sc-cc-plugin:spec-recoveryThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
從既有程式碼中萃取結構化規格文件,讓團隊能理解、維護、並安全修改系統。
references/analysis-strategy.mdreferences/document-conventions.mdreferences/implicit-rules-standard.mdreferences/interview-questions.mdreferences/nestjs-patterns.mdreferences/progress-tracking.mdreferences/qa-protocol.mdreferences/react-patterns.mdreferences/scoring-rubric.mdreferences/template-summaries.mdreferences/templates-L0.mdreferences/templates-L1.mdreferences/templates-L2.mdreferences/templates-L3.mdreferences/templates-L4.mdreferences/vue2-nuxt2-patterns.mdreferences/vue3-patterns.mdGuides 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.
從既有程式碼中萃取結構化規格文件,讓團隊能理解、維護、並安全修改系統。
本技能只產出規格文件,不執行以下工作:
| 方法論 | 採用的概念 |
|---|---|
| BDD | 以行為為單位拆解功能,Given-When-Then 思維萃取行為 |
| DDD 戰略設計 | Bounded Context、模組邊界識別、同名異義概念辨識 |
| Specification by Example | 活文件策略、規格與程式碼共同演進 |
| Architecture Decision Records | 記錄決策的 why 與 trade-off(系統級 + 模組級) |
| Working Effectively with Legacy Code | 漸進式策略、安全網思維、識別測試接縫 |
| C4 Model | 文件分層(L0-L4),不同粒度給不同受眾 |
根據使用者的請求範圍,選擇合適的起始階段。整個專案從 Phase 0 開始;單一模組或功能可從 Phase 2 或 Phase 3 開始。
Phase 0: 既有文件掃描 ← 掃描專案內已有的文件作為參考
↓
Phase 1: 全局地圖 (L0)
↓
Phase 2: 模組拆解 (L1) ← 含模組級決策考古
↓
Phase 3: 功能行為拆解 (L2) ← 投資報酬率最高
↓
Phase 4: API 契約 (L3)
↓
Phase 5: 程式碼內文件建議 (L4) ← 含活文件維護策略
每個 Phase 結束後依序執行以下三步驟(後續以「執行 Phase 結束流程」引用):
[待確認] 項目,使用 AskUserQuestion 工具逐一向使用者確認,將回答寫回文件(更新為 [確認] 或 [未確定])references/qa-protocol.md(含業務脈絡收集、補充 Q&A)strategic-compact skill 評估是否需要壓縮,若建議壓縮則執行 /compact。若使用者環境缺少 strategic-compact skill 或 /compact command,提醒使用者補上每個 Phase 開始時(或從中斷處恢復時):
docs/spec-recovery-progress.md — 必讀「工作偏好」和「待處理項目」,「歷史紀錄」可跳過docs/L0-system-overview.md)— 取得分析基礎使用 Agent tool(subagent_type: "Explore")平行化獨立的探索任務,大幅縮短分析時間。
原則:
"very thorough",確保不遺漏檔案讀取策略(漸進式,節省 context):
Glob(找檔案)→ Grep(找關鍵模式,定位行號)→ Read(limit: 1200)(預覽前 1200 行)→ 確認相關才完整讀取
Read(limit: 1200) 預覽檔案,不要一次讀取整個檔案offset + limit 讀取剩餘部分offset 精準讀取片段Agent prompt 模板:
分析 {專案路徑} 的 {探索目標}。
檔案讀取規範:
- 使用 Glob 找出目標檔案,用 Grep 定位關鍵模式
- 預設用 Read(limit: 1200) 預覽,確認相關才完整讀取
- 超過 1200 行的檔案,用 offset + limit 讀取剩餘部分
可復用邏輯追蹤:
- 若目標檔案引用了可復用邏輯單元(mixin、hook、composable、service、utility、base class、decorator、HOC 等),必須追蹤原始檔並展開其完整行為
- 特別注意互動行為(輸入過濾、自動提交、焦點管理、鍵盤事件處理、資料轉換)
流程圖使用 mermaid.js flowchart 語法繪製。
回傳以下結構:
## 發現
- (條列式發現)
## 隱性規則
- 🔴 {規則描述}(Why:{為什麼這樣設計})(忽略會導致:{後果})
- 🟡 {規則描述}(Why:{為什麼})
- 若無法從程式碼判斷 Why,標記 [待確認]
(分級標準見 references/implicit-rules-standard.md)
## 待確認
- (無法從程式碼確定的項目)
所有產出存放於專案 docs/ 目錄下:
docs/
├── spec-recovery-progress.md ← 進度追蹤(必須維護)
├── L0-system-overview.md
├── L1-modules/
│ └── {module-name}.md
├── L2-features/
│ ├── {feature-name}.md
│ └── shared-{component-name}.md ← 使用 ≥2 頁面的共用元件
├── L3-api/
│ ├── api-inventory.md
│ └── {domain}.md
└── L4-code-notes/
└── (建議清單或 PR 形式)
維護 docs/spec-recovery-progress.md 追蹤所有任務的完成狀態。詳見 references/progress-tracking.md。
核心規則:
每個 Phase 的第一份文件完成後,暫停並用 AskUserQuestion 確認粒度、格式、方向是否符合使用者需求。通過後再批量處理剩餘項目。將確認結果記錄到進度檔的「工作偏好」區塊。
目標:在分析程式碼之前,先掃描專案內已存在的文件,作為後續分析的輔助參考。
執行步驟:
README.md、docs/**/*.md、wiki/**/**.swagger.json、*.openapi.yaml、openapi/**/*ARCHITECTURE.md、DESIGN.md、CHANGELOG.md*.api.md、api-docs/**/*CLAUDE.md(專案特定指引)@description、@design、@architecture)產出:參考資料清單(不獨立輸出檔案,併入 L0 文件的附錄)。
若專案無任何既有文件,跳過此 Phase 直接進入 Phase 1。
目標:建立系統鳥瞰圖,識別所有入口點、邊界、與架構決策。
執行步驟(⚡ 標示可平行化的步驟):
使用 4 個 Explore agent 同時啟動以下探索任務:
| Agent | 探索任務 | 掃描範圍 |
|---|---|---|
| ⚡ Agent A | 技術棧與第三方依賴 | package.json / requirements.txt / go.mod、config 檔 |
| ⚡ Agent B | 前端入口點(路由定義、頁面清單) | 路由設定檔、pages/ 目錄結構 |
| ⚡ Agent C | 後端入口點(API route、controller) | server/、api/、controller/ 目錄 |
| ⚡ Agent D | 資料模型(型別定義、DB migration、ORM model) | types/、models/、migration/、schema 相關檔案 |
主 agent 整合 4 個結果後: 5. 繪製模組清單與依賴關係 6. 系統級決策考古:記錄可觀察到的架構決策(技術選型、通訊方式、部署架構),嘗試推斷 why
產出:L0 系統概觀文件。讀取 references/templates-L0.md 取得模板。產出前檢查「文件通用規範」(mermaid、🔴/🟡 分級、TOC)。產出後執行「品質檢查與評分」(含啟動 spec-scorer agent)。
業務脈絡收集:Phase 1 Q&A 時,根據分析發現主動收集全局業務脈絡(見 references/qa-protocol.md「業務脈絡收集」)。
Confidence Tagging:每項發現標記信心度:
[確認] — 程式碼明確顯示[推斷] — 從程式碼模式合理推論[待確認] — 無法僅從程式碼判斷Phase 1 是「施工鷹架」,快速完成比精確更重要。
目標:針對每個模組,定義職責、邊界、資料流、對外依賴、以及設計決策。
執行步驟(⚡ 標示可平行化的步驟):
⚡ 平行分析各模組:為每個模組啟動獨立的 Explore agent(建議同時不超過 5 個),每個 agent 負責回答:
主 agent 整合各模組結果後:
產出:L1 模組規格文件。讀取 references/templates-L1.md 取得模板。產出前檢查「文件通用規範」(mermaid、🔴/🟡 分級、TOC)。產出後執行「品質檢查與評分」(含啟動 spec-scorer agent)。
目標:以使用者或系統行為為單位,產出可直接轉化為測試案例的功能規格。這是投資報酬率最高的階段。
執行步驟(⚡ 標示可平行化的步驟):
⚡ 平行分析各頁面/功能:為每個頁面或功能啟動獨立的 Explore agent(建議同時不超過 5 個),每個 agent 用以下框架分析:
[待確認]。分級標準見 references/implicit-rules-standard.mdshared-change-password.md),頁面文件改為引用業務脈絡收集:每個模組的 Phase 3 開始前,根據 L1 文件中的發現,收集該模組的業務語義(見 references/qa-protocol.md「業務脈絡收集」)。
產出:L2 功能規格文件。讀取 references/templates-L2.md 取得模板。產出前檢查「文件通用規範」(mermaid、🔴/🟡 分級、TOC)。產出後執行「品質檢查與評分」(含啟動 spec-scorer agent,需額外執行 B 可測試性評分)。
框架特定的萃取技巧,根據偵測到的技術棧載入對應參考文件:
- Vue 2 / Nuxt 2 專案:讀取
references/vue2-nuxt2-patterns.md- Vue 3 專案:讀取
references/vue3-patterns.md- React 專案:讀取
references/react-patterns.md- NestJS / Node.js 後端:讀取
references/nestjs-patterns.md
目標:記錄前後端之間的資料契約,特別是隱性假設。
執行步驟(⚡ 標示可平行化的步驟):
⚡ 使用 2 個 Explore agent 同時掃描:
| Agent | 探索任務 |
|---|---|
| ⚡ Agent A | 前端 API 呼叫層:掃描所有 API 呼叫(axios/fetch),整理端點清單、請求參數、回應處理 |
| ⚡ Agent B | 後端 API 定義:掃描 server/api/ 目錄,整理路由、middleware、handler、回應格式 |
若後端不在分析範圍內,僅啟動 Agent A 從前端反推。
主 agent 整合後:
產出:L3 API 規格文件。讀取 references/templates-L3.md 取得模板。產出前檢查「文件通用規範」(mermaid、🔴/🟡 分級、TOC)。產出後執行「品質檢查與評分」(含啟動 spec-scorer agent)。
目標:識別需要但缺少的行內註解,並建立讓規格文件「活下去」的策略。
執行步驟(⚡ 標示可平行化的步驟):
⚡ 使用 2 個 Explore agent 同時掃描:
| Agent | 探索任務 |
|---|---|
| ⚡ Agent A | 掃描需要註解的程式碼段落:複雜業務邏輯、Workaround/Hack、非顯而易見的副作用、magic number |
| ⚡ Agent B | 靜態掃描測試覆蓋狀況(不執行測試):比對測試檔與源碼檔的對應關係,識別無測試覆蓋的高風險區域,產出測試接縫(test seam)建議清單 |
主 agent 整合後:
產出:L4 程式碼註解建議。讀取 references/templates-L4.md 取得模板與標記規範。產出前檢查「文件通用規範」(mermaid、🔴/🟡 分級、TOC)。產出後執行「品質檢查與評分」(含啟動 spec-scorer agent)。
詳見 references/analysis-strategy.md(含前端/後端分析順序、Sub-agent 使用時機、隱性規則偵測清單)。
重要:所有需要使用者回答的問題(模組優先級、確認項目、Q&A 問題等),必須使用
AskUserQuestion工具提問,不要用普通文字輸出。這讓使用者能清楚辨識需要回應的地方,避免問題被分析文字淹沒。
適用於 Phase 1-2 已完成,使用者想針對單一模組走完 Phase 3→4→5 的情境。
跳過所有 Phase,使用 references/interview-questions.md 進行延伸訪談,根據回答建構規格。
產出規格文件後,依序執行:
references/analysis-strategy.md「品質自查清單」和 references/document-conventions.md 檢查格式規範spec-scorer agent 評分:使用 Agent tool 啟動 spec-scorer 自訂 agent(subagent_type 不需指定,直接用 agent name spec-scorer)。Prompt 需提供:待評文件路徑、文件層次(L0-L4)、模板格式要求摘要、原始碼目錄路徑、是否啟動差異驗證(C 評分)。模板格式要求可引用 references/template-summaries.md,或自行讀取對應 references/templates-L{N}.md 後摘要(因 sub agent 無法讀取 skills 目錄)AskUserQuestion 請人工介入。將最終分數記錄到進度檔對應表格詳細的評分維度、權重矩陣、Prompt 範例、修正流程、進度檔記錄格式,見 references/scoring-rubric.md。
所有 L0–L4 產出文件的格式規範(Header、TOC、Confidence Markers、mermaid、隱性規則標記、語言)詳見 references/document-conventions.md。
產出前必須對照該規範檢查。
專案結構特殊情境(Monorepo、Micro-frontend、混合 legacy 等)的處理方式,詳見 references/analysis-strategy.md「Edge Cases」。