iterative-dev

# ITERATIVE_DEV_SKILL — 迭代開發處理技能（v2.2） ## 啟用確認格式 每次啟動後，回應開頭必須輸出： ``` 【迭代開發模式已啟用 - v2.2】 核心文件讀取狀態： - plan.md → [已讀取 / 不存在] - spec.md → [已讀取 / 不存在] - blueprint.md → [已讀取 / 不存在] - knowledge_graph.md → [已讀取 / 不存在] - readme.md → [已讀取 / 不存在] - ITERATIVE_DEV_CORE.md → [已讀取 / 不存在] 本次更新檔案清單： - [檔案名稱] → [變更類型: 新增/修改/刪除] ([影響摘要]) ``` ## 核心鐵律（100% 遵守） 1. **預設模式** — 永遠假設這是迭代專案，已有基礎程式碼與文件，非從零重寫。 2. **差異更新原則** — 絕不整份重寫既有檔案。只輸出需要「新增」、「修改」或「刪除」的部分，清楚標註版本（如 `v1.3 新增`）或使用 diff 格式。 3. **版本追蹤** — 所有更新必須在相關檔案新增 `## 變更歷史` 區塊，記錄日期、本次迭代內容、影響範圍。 4. **知識圖譜同步** — 每次新增或修改功能時，同步更新 `knowledge_graph.md`，加入新節點與關係。 5. **溝通一致性** — 回應結尾詢問：「是否需要進一步調整本次迭代？」 6. **強制讀取核心文件** — 每次啟用前，必須嘗試讀取以下文件（存在則讀取，不存在則記錄）： `plan.md`, `spec.md`, `blueprint.md`, `knowledge_graph.md`, `readme.md`, `ITERATIVE_DEV_CORE.md` 7. **錯誤自動啟用** — 當用戶貼上錯誤訊息（error log、stack trace、exception、失敗截圖文字）， 必須自動啟用本技能，無需用戶手動提醒。 ## 處理流程（每次自動執行） ### Step 0 — 規則檔案自動管理 執行以下檢查並自動處理： ``` IF .claude/CLAUDE.md 不存在 AND agents.md 不存在： → 自動建立 .claude/CLAUDE.md（含最小化迭代開發規則路由） → 自動建立 .claude/rules/ 目錄結構（見下方結構規範） ELIF .claude/CLAUDE.md 存在 AND 未含迭代開發規則： → 附加（不覆蓋）迭代開發規則區塊至文件末尾 → 格式：<!-- ITERATIVE_DEV_RULE v2.0 START --> ... <!-- END --> ELIF .claude/rules/common/iterative-dev.md 存在： → 讀取現有規則，與本技能合併（差異更新，不重寫） ``` **自動建立的 `.claude/rules/` 結構：** ``` .claude/ ├── CLAUDE.md ← 主規則入口（路由到各模組） └── rules/ ├── common/ │ ├── iterative-dev.md ← 迭代開發鐵律 │ ├── version-tracking.md ← 版本追蹤規範 │ ├── memory-sync.md ← 記憶同步規則 │ └── function-docs.md ← 函式文件規則（v2.2 新增） └── project/ └── iterative-dev-local.md ← 專案本地覆蓋 ``` <!-- v2.2 新增 START --> ### Step 0.5 — MVP Bootstrap 檢查 **在 Step 1 之前執行此檢查：** ``` IF plan.md 不存在 AND 用戶請求涉及「開發 app / 建立功能 / 建立專案」： → 執行 MVP Bootstrap 工作流（見 references/mvp-bootstrap.md） → 建立 plan.md、spec.md、docs/functions/_index.md、knowledge_graph.md 骨架 → 輸出【MVP Bootstrap Complete】確認訊息 → 繼續執行 Step 1（此時 plan.md 已存在） ELSE： → 跳過，直接執行 Step 1 ``` **重要**：MVP Bootstrap 只在 `plan.md` **真正不存在**時觸發。若已存在（哪怕是骨架），直接進入迭代模式。 詳細步驟請見：[references/mvp-bootstrap.md](./references/mvp-bootstrap.md) <!-- v2.2 新增 END --> ### Step 1 — 現狀確認（強制讀取核心文件） 依序嘗試讀取以下文件，並記錄讀取狀態： | 文件 | 用途 | 不存在時處理 | |------|------|------------| | `ITERATIVE_DEV_CORE.md` | 本專案迭代規則總覽 | 提示用戶可使用 `/iterative-dev` 初始化 | | `plan.md` | 功能規劃與里程碑 | 記錄「尚未建立」，不阻斷流程 | | `spec.md` | 技術規格 | 同上 | | `blueprint.md` | 系統架構藍圖 | 同上 | | `knowledge_graph.md` | 知識圖譜 | 記錄「尚未建立」，後續 Step 4 自動建立 | | `readme.md` / `README.md` | 專案說明 | 同上 | ### Step 2 — 差異分析 - 深度分析本次新增/修改的功能或錯誤原因。 - 評估對哪些現有檔案有影響。 - **錯誤處理特殊路徑：** 若觸發原因是錯誤訊息，先定位根因，再輸出 patch。 ### Step 3 — 精準輸出 - 使用 `diff` 格式或明確標註「新增部分」「修改部分」「刪除部分」。 - 若需要程式碼，優先提供 patch 而非完整檔案。 - 多個檔案時，依影響範圍排序輸出。 <!-- v2.2 新增 START --> ### Step 3.5 — Function Doc 自動產生 **每次實作新 function 後（或用戶明確要求），執行：** ``` FOR EACH new/modified function in this iteration: 1. 確認 docs/functions/<FunctionName>.md 是否存在 → 不存在：從 templates/function-doc.md 建立新檔 → 已存在：差異更新（只改有變化的區塊） 2. 更新 docs/functions/_index.md（新增或修改對應行） 3. 更新 knowledge_graph.md（新增節點 + 雙向關係） 4. 輸出【Function Doc Generated】確認訊息 ``` **雙向知識圖譜關係（最小必要）：** ``` {FunctionName} → has_doc → docs/functions/{FunctionName}.md {ParentModule} → has_function → {FunctionName} {FunctionName} → belongs_to → {ParentModule} ``` **觸發條件：** - 本次迭代新增或修改了 function - 用戶說「為這個函式產生文件」「function doc」「說明這個函式」 詳細步驟請見：[references/function-doc-workflow.md](./references/function-doc-workflow.md) 模板位置：[templates/function-doc.md](./templates/function-doc.md) <!-- v2.2 新增 END --> ### Step 4 — 知識圖譜更新 ```markdown ## knowledge_graph.md 差異更新（v1.x 新增） 節點：[新功能名稱] 關係：[新功能] → depends_on → [既有模組] 關係：[既有模組] → extended_by → [新功能] ``` 若 `knowledge_graph.md` 不存在，自動建立初始版本： ```markdown # Knowledge Graph — [專案名稱] 初始建立：[日期] ## 節點 ## 關係 ## 變更歷史 ``` ### Step 5 — 版本歷史追加 ```markdown ## 變更歷史 | 版本 | 日期 | 內容 | 影響範圍 | |------|------|------|----------| | v1.x | YYYY-MM-DD | [本次變更摘要] | [影響的模組/檔案] | ``` ### Step 6 — 自動記憶更新 每次迭代完成後，自動儲存以下記憶（寫入 `~/.claude/projects/` 記憶系統）： ``` 記憶類型：project 內容：本次迭代摘要、版本號、影響的檔案清單 記憶類型：feedback（若本次解決了錯誤） 內容：錯誤類型 → 解法 → 防範策略 ``` ## 輸出格式規範 ### diff 格式（推薦） ```diff ## plan.md — v1.x 差異更新 ### 功能清單 + - [ ] 新功能 A（v1.x 新增） + - [ ] 新功能 B（v1.x 新增） - [x] 既有功能（不變） - 舊描述（已廢棄） + 新描述（v1.x 修改） ``` ### 標註格式（備選） ```markdown <!-- v1.x 新增 START --> 新增內容放這裡 <!-- v1.x 新增 END --> <!-- v1.x 修改 START（原內容：舊描述） --> 修改後內容放這裡 <!-- v1.x 修改 END --> ``` ## 觸發條件 **自動觸發**（任一條件成立）： - 關鍵詞：迭代、新增功能、修改功能、繼續開發、更新現有、差異更新、延續上次、不要從零開始、v1.x（任何版本號） - 用戶貼上現有 `.md` 文件內容 - 專案目錄中存在本技能檔案 - 用戶說「像上次一樣」「這是延續上次」 - **用戶貼上錯誤訊息**（error、exception、stack trace、traceback、failed、FAILED、Error:、錯誤：、失敗） <!-- v2.2 新增 START --> - **`plan.md` 不存在 + 開發 app/功能請求** → 觸發 Step 0.5 MVP Bootstrap - **function 實作完成 / 用戶要求函式文件**（「函式文件」「function doc」「說明函式」）→ 觸發 Step 3.5 <!-- v2.2 新增 END --> **停用條件**（明確聲明才停用）： - 用戶說「切換成全新開發模式」或「從零開始重寫」 ## 技能版本歷史 | 版本 | 日期 | 內容 | |------|------|------| | v2.2 | 2026-04-27 | 新增 Step 0.5 MVP Bootstrap（plan.md 不存在時自動建立骨架）、Step 3.5 Function Doc Generator（每個 function 自動產生 md + 雙向知識圖譜）、新增 references/mvp-bootstrap.md、references/function-doc-workflow.md、templates/function-doc.md、rules/common/function-docs.md | | v2.1 | 2026-04-15 | copilot-instructions.md 整合 Autonomous Agent Mode（5步驟交付、命名規範、PUA引擎、Red Lines） | | v2.0 | 2026-04-15 | 新增 Step 0 規則檔自動管理、強制讀取核心文件、錯誤自動觸發、.claude/rules/ 模組化結構、自動記憶更新 | | v1.1 | 2026-04-14 | 合併 Hook 邏輯、優化輸出格式、新增 diff 範例 | | v1.0 | 2026-04-14 | 初始建立 |