slim-doc 精簡需求文檔

目標

將一份行數過多的需求規格 Markdown 文檔，精簡為開發友好的精簡版本，輸出至 xxx.slim.md，同時確保開發所需的所有結構性資訊完整保留。

工作流程

讀取使用者指定的 .md 文件（若未指定，詢問路徑）
依照下方保留規則與刪除規則精簡內容
依照下方需求描述整理規則，改寫不夠清晰的需求段落
輸出至同目錄的 <原檔名>.slim.md

保留規則（絕對不可刪除）

以下內容對開發至關重要，必須完整保留：

Mermaid 流程圖 / 時序圖（```mermaid 區塊完整保留）
File path（程式碼中出現的路徑，如 src/services/user.service.ts）
API endpoint（如 POST /api/users、GET /api/orders/:id）
資料結構定義（interface、type、struct、schema 定義，即使在程式碼區塊中）
範例 payload（JSON 範例、request/response body 範例）
SQL schema / 欄位定義（CREATE TABLE、欄位清單）
設定檔範例（config.yaml、.env 範例、nginx.conf 片段等）
章節標題（#、##、### 開頭的標題，維持文件導覽結構）
說明文字段落（非程式碼的純文字說明，描述「為什麼」或「是什麼」）
表格（Markdown table，通常是比較表或欄位說明）
Skill 載入指令（文件中指定在特定情境載入技能的指示，例如「遇到前端開發時載入 react-design skill」、「處理後端邏輯時使用 xxx skill」等描述，這些是 AI 工作流程的一部分，必須完整保留）

刪除 / 精簡規則

完整刪除

測試程式碼片段（describe、it、test、expect、assert 等測試框架語法）
重複出現的相似範例（保留第一個，其餘標註「（其他範例略）」）

精簡為省略符號

對於函式實作、class 實作，保留簽名，用 // ... 取代實作細節：

// 精簡前
function calculateDiscount(order: Order): number {
  const baseDiscount = order.total * 0.1;
  if (order.memberLevel === 'gold') {
    return baseDiscount * 1.5;
  }
  // ... 50 行邏輯
  return baseDiscount;
}

// 精簡後
function calculateDiscount(order: Order): number {
  // ...
}

// 精簡前
class UserService {
  private db: Database;
  constructor(db: Database) { this.db = db; }
  async findById(id: string): Promise<User> {
    const result = await this.db.query(...);
    // ... 實作細節
  }
  async updateProfile(...) { ... }
}

// 精簡後
class UserService {
  async findById(id: string): Promise<User> { // ... }
  async updateProfile(...): Promise<void> { // ... }
}

需求描述整理規則

精簡程式碼之後，針對純文字的需求描述段落進行第二輪掃描，判斷是否需要改寫。

何時需要整理

以下特徵代表描述不夠清晰，應主動整理：

口語化、模糊的表達（「大概」、「應該要」、「之類的」、「看情況」）
條件分支夾雜在敘述句中，難以辨識判斷邏輯
缺少主詞或動詞（讀不出「誰對誰做什麼」）
多個需求混寫在同一段落，沒有分點
重複說明同一件事但措辭不一致，容易產生歧義

整理方式

將模糊描述改寫為結構化格式，優先使用以下表達方式：

條件邏輯用條列 + 縮排：

// 整理前
使用者如果是 VIP 的話折扣比較多，一般用戶就正常價格，管理員不用付費

// 整理後
依使用者角色套用不同定價：
- VIP：享有折扣價
- 一般用戶：原價
- 管理員：免費

流程步驟用編號：

// 整理前
先驗證資料，然後存到資料庫，成功的話發通知

// 整理後
1. 驗證請求資料格式
2. 寫入資料庫
3. 發送通知（僅成功時）

主詞不明確時補全：

// 整理前
驗證完成後跳轉到首頁

// 整理後
驗證成功後，系統將使用者導向首頁

整理邊界

只改寫表達方式，不改變需求的實質內容

若需求本身有歧義且無法從上下文推斷，在段落末加上標註：

> **[slim-doc 需求待確認]** 此段需求語意不明，需要再進行確認

不要自行補充原文未提及的需求細節

邊界情境補充規則

在完成精簡與需求整理後，進行第三輪掃描，主動識別文件中未被提及但開發者容易踩坑的邊界情境，在對應段落末補充標註。

何時補充

以下類型的需求容易遺漏邊界情境，應主動檢查：

資料驗證：是否說明了空值、null、空字串、超長字串的處理方式
數值範圍：是否說明了負數、零、極大值的行為
狀態流轉：是否覆蓋了重複操作（如重複送出）、中途失敗、並發衝突
權限控制：是否說明了越權存取、token 過期、未登入的回應行為
非同步流程：是否說明了超時、重試、partial success 的處理
刪除 / 更新操作：是否說明了不存在資源的行為（404 vs 靜默忽略）

補充格式

在對應需求段落末，用 Markdown blockquote 插入，條列出遺漏的邊界情境：

> **[slim-doc 邊界情境]**
> - 若 userId 不存在，應回傳 404 還是建立新用戶？
> - 同一用戶重複呼叫此 API 的預期行為未定義
> - amount 為 0 或負數時的處理邏輯未說明

補充邊界

只標註文件中確實未提及的情境，不重複標註已有說明的部分
用問句形式呈現（「是否應該...？」、「當 X 時，Y 的行為為何？」），保持中立，不自行給答案
若整個段落邊界情境都已完整，略過不補充

判斷原則

遇到邊界情況時，優先回答這個問題： 「開發者在實作這個需求時，是否需要看這段內容？」

需要 → 保留
不需要（只是示意、已有別處說明、純實作細節）→ 精簡或刪除

輸出格式

輸出路徑：<原目錄>/<原檔名>.slim.md