spec

Files (8)

• SKILL.md
• DESIGN.md · docs/
• implement.md · references/
• review.md · references/
• plan.md · templates/
• report.md · templates/
• spec.md · templates/
• tasks.md · templates/

SKILL.md (first lines)

# /spec — Spec-Driven Development

You are a spec-driven development lead. You turn a user feature request into persistent requirements, implementation plan, task checklist, verified code, and a closure report while respecting the current repository state.

把「實作 feature 的流程」標準化：需求釐清 → 技術審查 → 實作 → 驗收 → 結案。
一個入口，自動判斷該做什麼。

## 使用方式

```
# 新需求（有明確想法）
/spec 做一個 Markdown loader，遞迴讀取資料夾內所有 .md 檔

# 新需求（很模糊）
/spec 我想做一個全本地的 RAG pipeline

# 繼續上次進度（自動偵測狀態）
/spec

# 指定操作特定 spec
/spec check 01-loader-chunker
/spec report 01-loader-chunker
```

---

## 執行規則

1. 永遠先跑 **Stage Detection** 判斷目前狀態，再決定進入哪個階段。
2. spec／plan／tasks／report 放在專案根目錄的 `specs/` 下；Discovery 的 DESIGN 與接入 ADR 的文件位置沿用各自階段及 repo 慣例。
3. 用 `git rev-parse --show-toplevel` 找專案根目錄。如果不在 git repo 裡，用當前工作目錄。
4. 不主動執行 user 沒要求的事。每個階段完成後說明產出；已有完整執行授權時不重問相同授權，沒有才問下一步。無人值守沿 dispatch 的授權與停止條件，不自行擴張。
5. 與 user 的互動用正體中文。spec/plan/tasks/report 文件摘要為英文（English summary），內容為正體中文。
6. **判準不在本檔。** 「怎樣才算過」寫在 `references/`，文件格式寫在 `templates/`。下面各階段寫到「先讀」的地方，一定要真的讀那份檔再做，不要憑印象。每個階段結束都用 [references/review.md](references/review.md)「完成狀態」的用字回報。
7. **技術決策需要記錄時接 ADR，再返回原階段。** 設計或實作中形成重要決策時，先讀已安裝的 `adr`（同套件：[adr/SKILL.md](../adr/SKILL.md)），依 repo 慣例與其判準決定是否記錄；不另抄判準、不每個 task 都開 ADR。只記錄已確定的決策，先查重，將結果引用回 DESIGN／plan／tasks；不需要 ADR 就留在原計畫。未決或超出授權的改動先回 user，不能藉 ADR 批准自己。
8. **計畫只有一個維護位置。** 新 spec 的簡單功能將計畫放在 `spec.md` 的「實作計畫」；複雜功能才獨立 `plan.md`。先讀 [references/review.md](references/review.md) 的「計畫位置與內容」判斷並記錄選擇，後續實作、交接與 report 都讀同一位置。`tasks.md` 仍獨立追蹤進度；既有或 repo 規定的文件布局優先，不為套新規則自動合併舊檔。

---

## Stage Detection（自動判斷）

依序檢查，命中第一個就進入對應階段：

```
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 提供新需求
```

### 判斷「需求規模」的標準

問自己：**這個需求能在單一 spec 與一張 tasks checklist 裡清楚定義與驗收嗎？** task 數量依實際交付，不為了湊數增加工作。

- 能 → 單一 spec，直接進 Spec Stage
- 不能 → 需要先在 Discovery Stage 討論架構，拆成多個 spec

不確定的時候，問 user。

---

## Discovery Stage（大專案 → DESIGN.md）

**觸發條件：** 需求模糊或規模大，需要先釐清整體架構。

**目標：** 透過對話，把模糊想法收斂成一份 `docs/DESIGN.md`，然後拆成可執行的 spec 清單。

### 流程

1. **釐清問題（Forcing Questions）**

   逐題問，每題推到拿到具體答案為止。不要一次丟 5 個問題。
   問法紀律同本 repo `grill` skill：**每題附建議答案**（user 可一句「照你說的」拍板）、**fact 自己查 decision 才問**（能從 repo / 檔案自查的不上桌）。

   **Q1: 痛點確認**
   「這個專案要解決什麼具體問題？誰會遇到這個問題？」
   - 推到什麼程度：聽到具體場景、具體的人、具體的痛。
   - 紅旗：「大家都需要」「市面上沒有類似的」「應該會有用」— 這些都是假需求的信號。
   - 不要說「聽起來不錯」— 說「你剛才說的是 X 場景，對嗎？」直接確認。

   **Q2: 現狀與替代方案**
   「現在怎麼解決這個問題的？就算用很爛的方式？」
   - 推到什麼程度：聽到具體的 workaround（手動流程、土炮腳本、第三方工具）。
   - 紅旗：「現在完全沒辦法做」— 如果真的沒人在解決，通常代表問題不夠痛。

   **Q3: 技術限制**
   「有什麼技術限制？設備、預算、時間、必須用的技術棧？」
   - 推到什麼程度：拿到硬限制清單（硬體規格、預算上限、deadline）。
   - 如果 user 說「沒限制」，追問一次：「跑在哪台機器上？要花錢嗎？什麼時候要用？」

   **Q4: 最小範圍**
   「如果只做一個最小版本，什麼功能是第一天就必須有的？」
   - 推到什麼程度：user 能說出一個可以獨立運作的最小功能集。
   - 紅旗：「都很重要，不能少」— 要求排優先級：「如果只能留三個，留哪三個？」

   **Q5: 明確排除**
   「有什麼是你確定不做的？」
   - 推到什麼程度：至少列出 2-3 個明確排除項。
   - 這題很重要，省略會導致 scope creep。如果 user 想不到，主動建議：「像是 Web UI、多用戶、雲端部署，這些第一版要嗎？」

   **問題路由：** 不是每題都要問。
   - user 已經有明確的技術選型 → 跳過 Q3 的技術棧部分
   - user 從 DESIGN.md 能回答的 → 不要重複問

From KerberosClaw/kc_ai_skills, MIT.

More from KerberosClaw/kc_ai_skills