Plan-Doc-Do-Follow 技能

Plan → Doc → Do → Follow

匹配意圖 → 第一條匹配的路由勝出 → 讀取 routes/a-b.md（路由 a/b）→ 遵循它 → 套用全球不變量 + 狀態模型。僅載入所需的路由、其模板及其子代理——絕不全部載入

路由

規劃

意圖	路由	參數
從產品願景提取史詩	`plan/proj`
與利害關係人驗證史詩	`plan/proj-review`
建立史詩 PRD 與追蹤	`plan/epic`	E{n}
驗證史詩規格或架構	`plan/epic-review`	E{n} {prd\|arch}
設計史詩架構	`plan/epic-arch`	E{n}
建立功能 PRD	`plan/feat`	E{n} F{n}
驗證功能規格或架構	`plan/feat-review`	E{n} F{n} {prd\|arch}
功能架構（僅例外）	`plan/feat-arch`	E{n} F{n}
將功能拆分為任務	`plan/tasks`	E{n} F{n}
範圍變更——新增/更新功能或史詩，即使已實作	`plan/change`	description
將 v2 專案文件遷移至 v3（一次性）	`plan/migrate`

執行

意圖	路由	參數
設定節省 token 的工具（LSP、過濾器、經濟模式、原生代理）	`do/init`
執行一個任務	`do/task`	E{n} F{n} T{n}
執行所有功能任務，並行驗證	`do/all-tasks`	E{n} F{n}
驗證已完成的工作（逐任務路徑）	`do/verify`	E{n} F{n}
重新計算並修復所有狀態	`do/sync-status`
記住良好實務	`do/memorize`

全球不變量（所有路由）

精神檢查：與 docs/product.md 保持一致；每個規劃路由 + 審查者簡報中逐字包含產品精神（位於 docs/project-status.md 頂端）
使用者意志：docs/decisions.md 具有約束力；偏離 = 提問，絕不默認套用
業務優先：規格審查在下一階段前進行
架構檢查：與 docs/global_architecture.md + docs/technical-stack.md 保持一致
一事一檔：狀態/事實僅有一個歸屬檔案（狀態模型）；其他檔案連結，絕不複製
受眾語言：人類/業務 = 完整句子，無未說明的縮寫；代理面向 = 文件風格（穴居人簡潔）
無空白骨架：刪除未使用的模板章節；絕不使用「N/A」或佔位符
不猜測：有阻礙的歧義 → 先提問；標記為阻礙性/重要/次要
可追溯性：每個文件引用其父項；故事 ↔ 需求 ↔ 任務 ↔ 測試相互連結
活生生的全域文件：docs/data-model.md、docs/ui-map.md、docs/decisions.md 在影響它們的同一變更中更新——絕不「之後再補」
模型分層：plan/* + 審查者 = 強模型；每個 plan/tasks 任務可由較弱模型執行，無需開啟 PRD
狀態同步：每個會改變狀態的路由都以狀態同步程序結束
交接格式：簡短摘要 · 當前進度 · 確切的下一個指令 · 開放問題
範圍內的子代理：僅輸入其定義清單
各路由心態：採用路由的心態描述
內部思辨：批評者的往返交流永遠不寫入文件/交接——人類看到最終結果 + 需要驗證的內容
處處節省：每個路由和子代理都套用工作經濟模式

狀態模型

⚪ TODO · 🟡 SPEC 已規格化 · 🟣 PLAN 已產生任務 · 🔵 DEV 開發中 · 🟢 DONE 已完成並驗證

歸屬——單一事實來源

事實	歸屬檔案（唯一撰寫位置）
任務狀態	`feat-tasks.md` — 任務摘要表格
功能狀態與進度	`epic-status.md` — 功能表格
史詩狀態與進度	`docs/project-status.md` — 史詩路線圖表格
專案進度	`docs/project-status.md` — 進度章節

沒有 feat-status.md。每個任務章節：無狀態行。Mermaid 圖表僅為裝飾性，從歸屬表格重新產生，絕非事實來源

推導規則

功能：無 feat-prd.md → ⚪ · 有 PRD → 🟡 · feat-tasks.md 存在，無任務超出 TODO → 🟣 · 有任何任務 DEV/DONE → 🔵 · 🟢 僅通過驗證關卡（do/verify，或 do/all-tasks 的最終階段）才能達到。若對 🟢 功能新增任務 → 還原為 🔵
史詩：無 epic-prd.md → ⚪ · 有 PRD → 🟡 · 所有功能 ≥ 🟣 → 🟣 · 有任何功能 🔵/🟢（非全部 🟢）→ 🔵 · 全部 🟢 → 🟢
專案：對史詩進行相同疊加
進度：已完成任務數 / 總任務數（若無則為 0），在史詩和專案層級加總

狀態同步程序

任何會改變狀態的路由結束時（獨立路由：do/sync-status，影響所有史詩）：

讀取受影響功能的任務摘要表格
重新計算每個功能狀態 + 進度；更新 epic-status.md 中的行
重新計算每個受影響的史詩；更新其在 docs/project-status.md 中的行、進度章節、圓餅圖。狀態同步絕不寫入變更日誌——僅根據變更日誌硬性規則（文件風格）記錄由產生里程碑的路由命名的事件
在交接中報告漂移（儲存值 ≠ 推導值）

確定性且冪等

子代理

定義在 subagents/ 中——每個代理一個檔案（格式：subagents/README.md）。呼叫方式：讀取檔案 → 組合恰如其定義清單的輸入（審查者總是取得產品精神）→ 以檔案內容作為系統提示產生子代理

經濟模式

從倉儲說明檔案的工具章節（do/init 寫入）讀取 Subagent economy:。若無 → balanced

模式	行為
`strict`	行內優先嚴格模式 · scout 幾乎總是行內 · 問題/工具/回傳數量上限強制執行 · 批評者仍然產生
`balanced`	依下述行內優先 · 數量上限強制執行 · 若 scout 問題超過 5 個則軟性警告
`quality`	成本門檻僅供建議 · 對 scout 工具使用和回傳大小的數量上限仍然適用

在產生前（行內優先）

依序執行——第一個匹配則勝出 → 不產生：

事實已在主要上下文 → 行內工作
可由主要代理在 ≤5 次 Grep/Glob/Read（或 LSP）呼叫內回答 → 行內（使用 subagents/repo-scout.md 中的 scout-lite 檢查清單）
簡報長度接近預期答案長度 → 行內
發現結果可能為表面機械檢查清單 → 行內（同當前的成本門檻）
否則產生

repo-scout 額外規則（在 strict / balanced 下）：僅在 ≥3 個可證偽問題且搜索範圍涵蓋主要代理尚未開啟的 ≥2 個領域時才產生，或主要上下文已臃腫且隔離成本明顯較低。否則進行 scout-lite 行內

產生時：

工具注入：簡報包含來自倉儲說明檔案的一行工具區塊（CLI 過濾器前綴、LSP 偏好、經濟模式）——子代理必須遵守
精確簡報：確切的問題/檢查 · 需要對照的標準 · 超出範圍 · 對於 scout，若區域已知則提供起始路徑/glob · 每個 scout 波次 ≤5 個問題（balanced/strict；其餘分割或行內處理）
預先滿足標準：在草稿前，先閱讀批評者的審查問題；草稿力求首次即通過
回傳大小上限：scout ≤15 行 · 批評者 ≤25 行 · 主要代理僅保留必要的事實——絕不將 scout 傾倒的內容貼入文件
批評者發現：若會改變行為、合約或人類決策則套用；無用/表面問題靜默放棄。被拒絕的判斷性問題 → 交給人類決策。收斂：每個文件執行一次；在對阻礙性發現進行大幅重作後，最多再執行一次，範圍限於那些發現——第二次僅接受阻礙性問題；絕不進行第三次。絕不回報往返交流（不變量 16）

子代理	種類	被誰呼叫	何時
`repo-scout`	研究	`plan/epic-arch`、`plan/feat`、`plan/feat-arch`、`plan/change`	規劃必須基於現有程式碼
`prd-critic`	審查者	`plan/epic`、`plan/feat`	總是
`arch-critic`	審查者	`plan/epic-arch`、`plan/feat-arch`	總是
`perf-critic-backend` / `-frontend`	審查者	架構路由、驗證關卡	僅當觸發條件（檔案頂部定義）成立時
`task-checker`	審查者	`plan/tasks`	自我審查後；最多兩輪
`feature-coder`	執行者	`do/all-tasks`	每波次每個可並行任務一個
`ui-consistency-reviewer`	審查者	驗證關卡	UI 功能、非平凡表面
`doc-coherence-reviewer`	審查者	驗證關卡 · `plan/change` · `plan/migrate`	史詩完成 · 變更後 · 遷移後

驗證關卡（+ 其子代理）在 do/verify 中執行，或作為 do/all-tasks 的最終階段以行內方式執行

人類審查 UX

結論，而非過程。機械檢查自動驗證 → 一行摘要。「需要您驗證的決策」：≤10 句簡潔句子 + 標記為阻礙性/重要/次要的開放問題。驗證後的決策 → 寫入 docs/decisions.md。利害關係人的回答逐字記錄——絕不轉述，絕不重問（若有歧義，僅提問澄清）

工作經濟模式（不變量 17）

輸入經濟

偏好 LSP/語義導航而非讀取整個檔案；使用範圍行號
偏好 Grep/Glob/LSP 而非 Shell 進行程式碼搜尋——僅在必要時使用 Shell
長的 CLI 輸出（測試、建置、git、套件管理器）透過倉儲宣告的過濾器（例如 rtk、snip）傳遞——do/init 設定；若使用 Shell 但未啟用鉤子，則手動加上前綴
絕不重新讀取已在上下文中的內容；絕不「為求保險」載入文件
遵守經濟模式 + 產生子代理前的行內優先原則（子代理）

輸出風格（主要代理與子代理）

穴居人簡潔（與代理面向文件相同的標準）：無前言、無重述請求、無結尾摘要、無填充/模糊用語
程式碼、指令、路徑、錯誤：字節級精確——絕不轉述
程式碼變更以 diff 或目標編輯形式呈現——除非被要求，否則絕不列出整個檔案
研究答案 ≤10 行，除非要求深度；子代理回傳遵守回傳大小上限
交接（不變量 13）= 僅作為結尾區塊：≤5 行

最小實作（do 路由與 feature-coder）

完全理解，停在適用階梯的第一級：

不需要存在 → 跳過（YAGNI）
已存在於程式碼庫 → 重用
標準函式庫提供該功能 → 使用它
原生平台功能 → 使用它
已安裝的相依套件 → 使用它
一行就夠 → 一行
僅在以上皆非時撰寫能運作的最小程式碼

絕不省略：信任邊界驗證、資料遺失處理、安全性、可及性

文件風格

兩種受眾——依檔案用途選擇，而非路由情緒

人類／業務（完整散文） — PRD（epic-prd.md、feat-prd.md）、docs/product.md、產品精神、人類審查主體（*-review.md 決策章節）、以使用者為中心的文件（developer-setup、入門指南、人類 README）。完整句子。利害關係人可讀。無未說明的縮寫

代理面向（穴居人簡潔） — 技能操作手冊（SKILL.md、routes/、subagents/、範本註解）、feat-tasks.md、epic-arch.md / feat-arch.md、狀態表格/備註、活生生的技術文件（data-model.md、ui-map.md、decisions.md）、docs/patterns/*。靈感來自 caveman 完整版：

僅包含事實與指令——當語意清楚時可刪除冠詞/填充/模糊用語；允許片段
使用簡短同義詞；模式 [事物] [動作] [原因] · [下一步]
不使用自創縮寫（cfg/impl/fn）；眾所皆知的技術縮寫可接受（DB/API/HTTP）
路徑、符號、程式碼、指令、錯誤字串：精確
絕不遺漏 not/never/no/only/except
換行前不加句號（行內多子句的句號保留）
僅包含決策與事實——絕不包含過程（「審查者建議…」、「討論後…」）
僅在未來代理需要知道原因時提供理由（權衡、範圍刪減）：≤2 短行
自動清晰度：對於安全性警告、不可逆步驟，或可能導致順序/否定誤讀的片段，使用更完整的散文——然後恢復簡潔

變更日誌硬性規則：一行 {日期}: {事實}，≤25 字。僅以下情況可寫入——專案：史詩完成、重大範圍變更、遷移；史詩：功能驗證為 🟢、範圍變更。其他所有情況（任務產生、PRD 草擬/核准、波次、同步、漂移修復）= 不寫入。絕不寫入：批評者往返交流（不變量 16）、任務清單、關卡結果、進度數字、Next: 指令。冗長的既有條目 = 舊版，不作為先例——僅撰寫符合資格的行，或什麼都不寫

檔案組織

docs/
├── product.md                 （輸入：產品願景）
├── global_architecture.md     （輸入：架構概述）
├── technical-stack.md         （輸入：技術決策）
├── project-status.md          （歸屬：產品精神、史詩狀態、進度）
├── project-review.md
├── decisions.md               （活生生的：具有約束力的使用者決策，每行一個）
├── data-model.md              （活生生的：全域資料結構，若有的話）
├── ui-map.md                  （活生生的：全域導覽地圖，若有 UI）
├── design-guidelines.md       （活生生的：UI 風格慣例，若有 UI）
├── patterns/{pattern-name}.md （來自 do/memorize）
└── epics/e{n}-{epic-name}/            （slug 例如 e2-orm-discovery）
    ├── epic-brief.md                  （plan/proj）
    ├── epic-prd.md                    （plan/epic）
    ├── epic-status.md                 （歸屬：功能狀態）
    ├── epic-arch.md                   （plan/epic-arch）
    ├── epic-review.md                 （plan/epic-review）
    └── f{n}-{feat-name}/              （直接子層級——無 features/ 層級）
        ├── feat-prd.md                （plan/feat；包含進入點 + 架構差異）
        ├── feat-arch.md               （plan/feat-arch — 僅例外）
        ├── feat-tasks.md              （歸屬：任務狀態）
        └── feat-review.md             （plan/feat-review）

平台整合

倉儲慣例，優先順序：CLAUDE.md · AGENTS.md · .github/copilot-instructions.md · .cursor/rules/ · .github/instructions/。do/memorize 將內容寫回實際存在的檔案

範本

位於 templates/ 中——名稱對應於輸出檔案

plan-doc-do-follow