원클릭으로
Spec-driven 開發流程 — 從模糊需求到驗收結案。自動判斷專案狀態,引導 user 走完:需求釐清 → 技術審查 → 實作 → 驗收 → 結案報告。
npx skills add https://github.com/KerberosClaw/kc_ai_skills --skill spec이 명령을 Claude Code에 복사하여 붙여넣어 스킬을 설치하세요
Spec-driven 開發流程 — 從模糊需求到驗收結案。自動判斷專案狀態,引導 user 走完:需求釐清 → 技術審查 → 實作 → 驗收 → 結案報告。
npx skills add https://github.com/KerberosClaw/kc_ai_skills --skill spec이 명령을 Claude Code에 복사하여 붙여넣어 스킬을 설치하세요
Use when the user wants to build a consistent-identity LoRA for an original character — defining the character, generating a face/body-consistent multi-angle dataset (via the gpt-image-gen skill for codex image generation), captioning it, doing base-specific homework, training on a chosen base (Pony / Z-Image / others) on a local GPU, and producing a usable LoRA. This skill ORCHESTRATES the end-to-end pipeline and gates every expensive/irreversible step; it delegates actual image generation to gpt-image-gen and never improvises training settings from memory.
Use when the user asks to generate an image via GPT/Codex (e.g. 「叫 gpt 生圖」「幫我用 gpt 生圖」「gpt 畫一個 X」). The skill drafts a Chinese + English prompt pair, iterates with the user until they explicitly approve, then dispatches Codex CLI ($imagegen skill, codex built-in image_gen) in the background, monitors progress, converts the result to a jpg in the current working directory, and writes a sidecar prompt log. Does text-to-image AND img2img — drop a reference image (on-disk file) and it runs Codex `-i` to lock a face/character across scenes.
Convert a Markdown report into a presentation-quality .pptx via interactive design decisions + hand-coded build script. Use when user says '/md2ppt', 'markdown to pptx', 'make slides from this md', '簡報', '做投影片', or similar. Optional self-check loop: if LibreOffice available, renders pptx → PNG per slide and checks for overflow / tiny font / emoji / misaligned content before user review. NOT a generic auto-converter — drives a per-slide layout dialogue then emits a reusable build script. Brand-template integration is supported as ad-hoc primitives (helpers exist) but is intentionally not a prescribed workflow — every brand template differs and is best handled by direct LLM-user dialogue.
Use when the user attended one or more sessions of a conference (with audio recordings + slide photos) and needs help building (1) faithful per-session reconstructions in markdown (slide visuals + speaker transcript with Whisper hallucination annotations), and (2) a downstream report deliverable whose scope and format are decided interactively with the user. Pipeline phase (raw → mlx_whisper Chinese SRT → per-slide multimodal reconstruction → official agenda cross-check via Playwright if available) is deterministic. Report phase is interactive — always quiz user on scope (single-session / single-day / multi-day synthesis), format (existing template / free-form fallback), recipient (formal / informal), and any business workstream mapping before drafting.
Use when the user wants to lint a repo following the Karpathy LLM Wiki pattern (raw/ + wiki/ + SCHEMA.md / index.md / log.md). The skill detects path, scans wiki pages + schema layer, reports frontmatter gaps, source traceability breaks, stale claims, orphan pages, missing topics, data gaps, cross-page contradictions, and SCHEMA-vs-reality drift. Read-only — never auto-fixes, never writes to log.md, never touches the network.
Use when the user wants to lint a Claude Code memory directory (~/.claude/memory or custom path) for index inconsistency, stale project state, duplicate / conflicting feedback rules, naming convention violations, frontmatter gaps, and oversized files. The skill detects path, scans root-level *.md, reports findings by severity. Read-only — never auto-fixes, never deletes, never merges.
| name | spec |
| description | Spec-driven 開發流程 — 從模糊需求到驗收結案。自動判斷專案狀態,引導 user 走完:需求釐清 → 技術審查 → 實作 → 驗收 → 結案報告。 |
| version | 1.2.0 |
| triggers | ["spec","開 spec","建 spec","新功能"] |
把「實作 feature 的流程」標準化:需求釐清 → 技術審查 → 實作 → 驗收 → 結案。 一個入口,自動判斷該做什麼。
# 新需求(有明確想法)
/spec 做一個 Markdown loader,遞迴讀取資料夾內所有 .md 檔
# 新需求(很模糊)
/spec 我想做一個全本地的 RAG pipeline
# 繼續上次進度(自動偵測狀態)
/spec
# 指定操作特定 spec
/spec check 01-loader-chunker
/spec report 01-loader-chunker
specs/ 下。git rev-parse --show-toplevel 找專案根目錄。如果不在 git repo 裡,用當前工作目錄。依序檢查,命中第一個就進入對應階段:
1. user 明確指定了操作?(如 /spec check 01-xxx)
→ 進入指定階段
2. user 提供了新需求描述?(如 /spec 做一個 loader)
→ 判斷規模:
├── 需求能在一個 spec 內完成(單一功能/模組)
│ → 進入 Spec Stage
└── 需求涵蓋多個模組/需要整體架構設計
→ 進入 Discovery Stage
3. user 沒提供描述?(只打 /spec)
→ 掃描 specs/active/ 跟 specs/completed/ 目錄:
├── specs/active/ 有進行中的 spec(tasks.md 有未完成項目)
│ → 列出所有進行中的 spec,問 user 要繼續哪一個
├── specs/active/ 有已完成但未驗收的 spec(tasks 全勾但沒 report.md)
│ → 提示 user 可以跑 check + report
├── 舊版扁平 specs/NN-xxx/ 還存在(向後相容)
│ → 當成 active 處理,下次結案時順便搬到 specs/completed/
└── 沒有任何 spec / 全部已歸檔
→ 提示 user 提供新需求
問自己:這個需求能拆成一張 tasks checklist(5-10 項)就做完嗎?
不確定的時候,問 user。
觸發條件: 需求模糊或規模大,需要先釐清整體架構。
目標: 透過對話,把模糊想法收斂成一份 docs/DESIGN.md,然後拆成可執行的 spec 清單。
釐清問題(Forcing Questions)
逐題問,每題推到拿到具體答案為止。不要一次丟 5 個問題。
Q1: 痛點確認 「這個專案要解決什麼具體問題?誰會遇到這個問題?」
Q2: 現狀與替代方案 「現在怎麼解決這個問題的?就算用很爛的方式?」
Q3: 技術限制 「有什麼技術限制?設備、預算、時間、必須用的技術棧?」
Q4: 最小範圍 「如果只做一個最小版本,什麼功能是第一天就必須有的?」
Q5: 明確排除 「有什麼是你確定不做的?」
問題路由: 不是每題都要問。
產出 docs/DESIGN.md
拆 Spec 清單
觸發條件: user 提供了明確的 feature 需求。
目標: 產出三份文件,確保「想清楚再動手」。
讀取上下文
docs/DESIGN.md,先讀它specs/ 下已有其他 spec,讀它們的 spec.md 了解已完成的部分釐清需求(跟 user 對話,最多 3-5 個問題)
建立 spec 資料夾
specs/active/NN-feature-name/specs/active/ 跟 specs/completed/ 現有資料夾一起推算(避免撞號)specs/active/ 不存在,先建好再用產出 spec.md
# 功能名稱
> **English summary:** One-line summary of what this feature does and why.
## 六要素摘要(Task Prompt Schema)
這個區塊是結構化欄位,給 pm-sync 這類外部工具 parse 用。填得模糊就代表還沒想清楚,回去修。
- **目標(Goal):** [一句話:這個 feature 要達成什麼]
- **範圍(Scope):** [精確路徑清單,如 `src/api/users.ts`, `tests/users.test.ts`]
- **輸入(Inputs):** [上游依賴:schema、API spec、前置 spec、環境變數]
- **輸出(Outputs):** [交付物:新檔案 / 新 API endpoint / 新測試 / schema migration]
- **驗收(Acceptance):** [指向下方 AC 列表,或直接摘要「見 AC-1〜AC-3」]
- **邊界(Boundaries):** [指向下方「不做的事」,或直接摘要]
## 背景
為什麼需要這個功能。如果有 DESIGN.md,標註對應的章節。
## 驗收條件
- [ ] AC-1: [具體、可測試的條件]
- [ ] AC-2: [具體、可測試的條件]
- [ ] AC-3: ...
## 不做的事
- [明確排除的項目]
- [另一個排除項目]
## 依賴
- [外部服務、套件、或必須先完成的其他 spec]
Self-Review(自己審自己)
產完 spec.md 後,逐項檢查:
| 檢查項目 | 不通過怎麼辦 |
|---|---|
| 六要素都填了,沒有「待補」「TBD」? | 回去補。模糊 = 沒想清楚 |
| 六要素之間一致?(範圍 vs 輸出、驗收 vs AC、邊界 vs 不做的事) | 對齊,有衝突就問 user |
| 每個 AC 都可測試?(不是「要好用」這種) | 改寫成可測試的條件 |
| 邊界條件有定義?(空輸入、超大檔、錯誤格式) | 補到 AC 或 Out of Scope |
| 範圍明確?(不做的事有列出來) | 補 Out of Scope |
| 外部依賴有交代? | 補 Dependencies |
| 跟已有的 spec 衝突嗎? | 標出衝突,問 user |
Anti-Sycophancy(審查時禁止的行為):
如果有不通過的項目,當場問 user 釐清,不要自己猜。 全部通過後,告訴 user:「spec 審查通過,接下來產 plan。」
產出 plan.md
# 實作計畫
> **English summary:** Brief description of the implementation approach.
## 做法
[1-2 段:怎麼做這個功能]
## 關鍵決策
| 決策 | 選擇 | 理由 |
|------|------|------|
| ... | ... | ... |
## 風險
| 風險 | 對策 |
|------|------|
| ... | ... |
## 實作順序
1. [先做什麼 — 為什麼先做]
2. [再做什麼 — 因為依賴 #1]
3. ...
tasks.md# 任務清單
> **English summary:** Task checklist for [feature-name].
**Spec:** [feature-name]
**Status:** NOT_STARTED | IN_PROGRESS | DONE | BLOCKED | VERIFIED
## Checklist
- [ ] Task 1: [交付物描述 — 完成時可以怎麼驗證]
- [ ] Task 2: ...
- [ ] Task 3: ...
## 備註
[實作筆記、踩坑紀錄、或交接給其他人時需要知道的事]
Task 粒度原則:
觸發條件: spec 資料夾存在,tasks.md 有未完成項目。
目標: 按 tasks.md 逐項實作,完成後更新 task 狀態。
參考 Karpathy 對 LLM coding pitfalls 的觀察:
1. Surgical Changes — 只動必要的
2. Simplicity First — 最少的 code 解決問題
3. Orphan Cleanup — 只清自己造成的孤兒
4. 如果實作中發現 spec 有問題
載入上下文
spec.md、plan.md、tasks.mddocs/DESIGN.md,也讀它進入 Claude Code Plan Mode
每完成一個 task
tasks.md:把 - [ ] 改成 - [x]遇到阻塞時
BLOCKED全部完成時
DONE觸發條件: user 明確要求 /spec check,或 tasks 全部完成後 user 同意驗收。
目標: 對照 spec.md 的 Acceptance Criteria,逐條驗證。
讀 spec.md 的 Acceptance Criteria
逐條驗證
產出驗收結果(印在對話中,不另存檔)
## Acceptance Criteria Check
| AC | Status | Evidence |
|----|--------|----------|
| AC-1: ... | PASS | [file:line or test result] |
| AC-2: ... | FAIL | [what's missing or wrong] |
FAIL 的處理
全部 PASS
觸發條件: user 明確要求 /spec report。
目標: 產出 report.md,記錄這個 feature 的完整生命週期。
收集資訊
spec.md、plan.md、tasks.md產出 report.md
# 結案報告:功能名稱
> **English summary:** Brief summary of what was built and the outcome.
**Spec:** specs/completed/NN-feature-name
**Status:** completed
**Date:** YYYY-MM-DD
## 摘要
[1-2 句:做了什麼]
## 方案
[選了什麼方案 + 為什麼;替代方案為何被否決。如果 plan.md 已寫清楚就標「見 plan.md 關鍵決策」。]
## 改動
| 檔案 | 重點 |
|------|------|
| `path/to/file.ts` | [這個檔案改了什麼,一句話] |
| ... | ... |
## 影響分析
[哪些呼叫方 / 下游模組 / 測試被這次改動影響,為什麼安全。附路徑+行號。]
## 三問自審
- **方案正確嗎?** [符合原始需求?沒有誤解?附依據]
- **影響分析全面嗎?** [有沒有沒考慮到的呼叫方或邊界條件?]
- **有回歸風險嗎?** [原本會用到這段的場景還能正常運作?]
## 驗收條件結果
| 驗收條件 | 狀態 |
|---------|------|
| AC-1: ... | PASS |
| AC-2: ... | PASS |
## 剩餘風險
[誠實列出還沒覆蓋的點:沒寫測試的邊界、已知但沒修的小問題、未來可能要處理的 tech debt。完全沒有就寫「無」。]
## 關鍵 Commit
| Commit | 說明 |
|--------|------|
| abc1234 | ... |
## 與計畫的偏差
[實作過程中跟原本 plan 不同的地方。完全照做就寫「無」。]
## 備註
[學到的教訓、踩過的坑、對未來有用的資訊]
更新 tasks.md Status 為 VERIFIED
歸檔:把整個 spec 資料夾從 specs/active/ 搬到 specs/completed/
git mv specs/active/NN-feature-name specs/completed/NN-feature-name(有 git 的話用 git mv 保留歷史)mvspecs/completed/ 不存在,先建好/pm-sync push NN-feature-name 把 tasks.md 推到遠端專案管理平台(需裝 kc_pm_sync skill;spec skill 本身不 import pm-sync,只提示)Spec: 欄位路徑更新為新位置告訴 user 結案完成。
{project-root}/
├── docs/
│ └── DESIGN.md # 整體架構(大專案才需要,Discovery Stage 產出)
├── specs/
│ ├── active/ # 進行中或待驗收的 spec
│ │ ├── 02-another-feature/
│ │ │ ├── spec.md # 需求規格 + 驗收條件
│ │ │ ├── plan.md # 實作計畫 + 技術決策
│ │ │ └── tasks.md # 任務清單 + 狀態追蹤
│ │ └── 03-yet-another/
│ │ └── ...
│ └── completed/ # 已歸檔的 spec(Report Stage 搬進來)
│ └── 01-first-feature/
│ ├── spec.md
│ ├── plan.md
│ ├── tasks.md
│ └── report.md # 結案報告(Report Stage 產出)
└── src/ # 你的程式碼
為什麼分 active/completed? 一眼看到還剩幾個 active,completed 歸檔不擋視野。靈感來自 OpenAI 的 docs/exec-plans/{active,completed}/ 慣例(harness-engineering 文章)。
每個階段結束時,用以下狀態回報:
| 狀態 | 意思 | 後續動作 |
|---|---|---|
| DONE | 全部完成,有證據 | 進入下一階段 |
| DONE_WITH_CONCERNS | 完成了,但有疑慮 | 列出疑慮,問 user 要不要處理 |
| BLOCKED | 卡住了,無法繼續 | 說明卡在哪、試過什麼、建議怎麼解 |
| NEEDS_CONTEXT | 缺少資訊,無法判斷 | 明確說需要什麼資訊 |