xxxx2l/design-to-implement

方案設計與實施工作流程

核心理念

先討論清楚，再動手寫程式碼。 這套工作流程強制把「想」和「做」分開：

• 討論階段：只對話，不寫程式碼，所有結論沉澱到溝通過程文件
• 設計階段：把共識整理成設計文件，這是唯一的事實來源
• 實施階段：根據設計文件生成實施文件，按步驟落地

討論沒有結論、使用者沒有明確說「可以開始落地」，絕不動程式碼。如果一直有疑問就一直討論下去，直到雙方滿意。

文件目錄結構

固定存放在專案根目錄下的 docs/design/，每個任務一個獨立子資料夾：

項目根/
└── docs/design/
    ├── README.md              ← 全域任務總覽（多任務入口，最先讀這個）
    ├── 01-使用者認證模組/
    │   ├── 00-任務狀態.md      ← 跨上下文記憶錨點
    │   ├── 01-溝通過程.md
    │   ├── 02-設計.md          ← 含驗收標準
    │   ├── 03-實施.md
    │   └── 04-測試.md          ← 用例集（實施規劃階段生成）
    └── 02-支付重構/
        └── ...

命名規則：

• 任務資料夾：全域遞增兩位序號 + 任務名，如 01-使用者認證模組、02-支付重構。序號跨任務連續遞增，保證排序與建立順序一致。
• 任務內文件：固定階段序號前綴：00-任務狀態 / 01-溝通過程 / 02-設計 / 03-實施 / 04-測試。固定前綴讓你在任何任務裡都能一眼定位同一類文件。

首次進入任務時如何確定序號：查看 docs/design/ 下已有資料夾的最大序號，+1 作為新任務序號。如果目錄不存在，從 01 開始。

每次新對話的第一步（多上下文記憶機制）

這套工作流程可能跨多個對話上下文執行。為避免每次新對話都要大範圍重讀程式碼或丟失記憶，強制按以下順序恢復上下文：

1. 讀 docs/design/README.md —— 全域任務總覽，確認有哪些任務、各自在哪個階段。如果使用者已指明任務，直接跳到該任務。
2. 讀 00-任務狀態.md —— 當前任務的記憶錨點，確認下一步該做什麼。
3. 讀當前階段對應的文件（如在設計階段就讀 02-設計.md，在實施階段就讀 03-實施.md）。
4. 只在需要核實時才去讀程式碼，而不是作為恢復上下文的第一手段。

00-任務狀態.md 必須維護：任務一句話簡介、當前階段、關鍵決策摘要、待辦與疑問、文件索引、上下文切換日誌、變更記錄（涵蓋修改與回退，見下文「實施期的變更」）。

工作流程的四個階段與對應文件

階段一：討論（輸出 → 溝通過程文件）

觸發：使用者提出一個新需求、新功能、新模組，或對既有方案有疑問想討論。

行為約束：

• 這個階段只討論，不寫任何業務程式碼。
• 把每一次有意義的交流（關鍵決策點、被否決的備選、達成的共識）追加記錄到 01-溝通過程.md。
• 未決疑問追蹤：在 01-溝通過程.md 頂部維護「當前未決疑問」清單。每次討論結束前更新它——哪些問號還在、哪些新冒出來、哪些已經閉環。判斷能否進入設計階段的直接依據就是：這個清單空了沒。這能讓討論收斂過程可視化，而不是憑感覺認為「討論得差不多了」。
• 討論是多輪的，可能跨多次對話。
• 當使用者表達「可以了」「就這樣定了吧」「開始設計吧」，且未決疑問清單已清空，進入階段二。

何時繼續討論而非推進：只要還有未解決的設計疑問、技術選型分歧、邊界沒講清，就繼續在階段一沉澱。寧可多問一輪，不要帶著模糊假設進入設計。

階段二：設計（輸出 → 設計文件）

觸發：討論達成一致，未決疑問清單已清空，使用者同意固化方案。

行為約束：

• 把溝通過程裡的結論，整理成結構化的 02-設計.md。設計文件是唯一事實來源。
• 設計文件必須盡可能完整：交付時是確定的、可執行的方案，不殘留「待定」「實施期再說」。完整性靠兩件事保證——一是反覆溝通把疑問問透，二是讀現有程式碼確認所有依賴既有實現的事實（介面形態、表結構、呼叫方式等）。「設計階段只討論不寫程式碼」約束針對的是業務程式碼；為了設計而讀既有程式碼、確認現狀，屬於設計調研，不違反約束。設計階段寧可多花時間反覆打磨，也不要帶著缺口進入實施——任何缺口都會在實施期變成返工或偏差。
• 驗收標準屬於設計的一部分：設計文件除了寫「做什麼、為什麼」，還要寫「做到什麼程度算滿足需求」——即抽象驗收標準（規則層面，如「高危詞必須攔截，文章不落庫」）。驗收標準定義了需求邊界，是設計完整性的最後一環；沒有驗收標準的設計文件，等於沒有「做完了」的客觀定義。具體的測試用例（實例層面）不在設計文件寫，而在 04-測試.md 由實施規劃階段把驗收標準落成用例。
• 設計變更記錄：在設計文件裡維護一個「設計變更記錄」區塊，每次重要變更記一行（時間、改了什麼、為什麼改）。它與 01-溝通過程.md 互補——溝通過程是流水帳，設計文件是結論，變更記錄是結論的演進史。這能讓「方案變更改設計文件而非實施文件」這條鐵律真正可執行而不丟歷史。
• 設計文件完成後，更新 00-任務狀態.md 標註「設計完成，待實施」，並同步更新 docs/design/README.md 的任務階段。

階段三：實施規劃（輸出 → 實施文件）

觸發：設計文件定稿。

行為約束：

• 根據設計文件生成 03-實施.md，把方案拆成可執行、可勾選的步驟清單。
• 同時把設計文件的「驗收標準」落成具體測試用例，生成 04-測試.md：用例是驗收標準的實例化（如驗收標準「高危詞必須攔截」 → 用例「輸入含高危詞文字，預期返回 40901、文章不落庫」）。用例分四層：功能（T-F）、異常（T-EX）、回歸（T-R）、介面（T-API），編號格式 T-{類型}-{兩位序號}，模板見 assets/test.md。
• 實施文件是「如何做」，測試文件是「測什麼、預期是什麼」，設計文件是「做什麼、為什麼」。三者職責不同，不要把設計細節照搬進實施文件，也不要在實施文件裡夾帶方案變更。
• 實施文件是純粹的步驟分解，每一步只是「按設計文件的某部分去實現」，不承擔任何「補全設計」的職責。如果拆步驟時發現某一步需要先「確認介面形態」「回寫設計」「決定欄位」才能動手，說明設計階段沒做完——此時應回到階段二補全設計，而不是在實施文件裡塞一個「補設計」的步驟。一句話：實施文件裡不該出現任何「讀程式碼確定方案」性質的動作，只該有「按既定方案實現」的動作。
• 實施文件裡的測試動作只引用用例編號，不重複寫用例內容。每個步驟完成後要驗證的，寫「對照用例 T-XX-XX 驗證」，用例本身集中在 04-測試.md。
• 實施步驟分大步驟和小步驟兩層，都要有獨立的完成標記。
• 實施文件完成後，更新 00-任務狀態.md 標註「待實施」。

階段四：實施（執行實施文件的步驟）

觸發：使用者說「開始實施」「動手吧」「按文件來」。

行為約束：

• 嚴格按 03-實施.md 的步驟推進，每完成一步就在文件裡更新標記並簡記結果。
• 每完成一個步驟，對照 04-測試.md 裡該步驟引用的用例驗證；用例失敗時該步驟不算完成，定位問題（是實施 bug 還是設計/用例本身有問題，後者走修改/回退機制）。全部步驟完成後，跑一遍回歸用例（T-R）集。
• 遇到任何與設計文件不一致的情況，停下來：先更新 02-設計.md（含變更記錄），再同步修訂 03-實施.md 和 04-測試.md（用例隨方案變），然後繼續。絕不邊做邊偏離方案。
• 實施過程中發現的設計漏洞、新增約束、API 變動，全部回寫到 02-設計.md 的「設計變更記錄」區塊，保持設計文件是最新的。
• 每個階段切換、每個重要節點，都要更新 00-任務狀態.md 和 docs/design/README.md。

實施期的變更：修改機制 vs 回退機制

工作流程名義上是討論→設計→實施規劃→實施，但實施中發現方案和需求/現實存在偏差，是預期內的常態，不是異常——再完整的設計也不可能 100% 預見實施細節。

偏差分兩類，性質完全不同，必須嚴格區分，用各自的流程處理：

	修改	回退
本質	方案大體對，有缺口/遺漏需要補	這部分方案根本錯了，需推倒重來
主體方案	不動	推倒
已完成產物	不作廢	部分作廢
頻率	常態	少數
典型場景	漏欄位、漏分支、漏字典值、漏考慮某個新需求點	方向錯了、核心假設不成立、不符合實際業務

先判定屬於哪類（判定責任見各機制說明），再按對應流程處理。判定拿不準時，傾向於先按「修改」處理並和使用者確認；只有明確構成根本性錯誤時才走「回退」。

修改機制（常態、輕量、增量）

判定三條件（全滿足才算修改）：

• 主體方案方向沒問題
• 不需要作廢已完成的產物
• 只是補充/微調（補欄位、補分支、補字典值、補一個漏掉的新需求點等）

處理流程（嚴格順序，不可顛倒）：

1. 停下當前實施
2. 先更新設計文件：在設計文件相應區塊補充內容，並補一行設計變更記錄
3. 等使用者確認這個修改（不能自行決定、自行實施）
4. 使用者確認後，同步修訂實施文件
5. 再繼續實施

關鍵原則：先更新設計、再實施，順序不可顛倒——禁止「先實施完再回寫設計文件」，那會讓設計文件退化為事後記錄而非事實來源。哪怕只是加一個欄位，也要走完這個流程。

回退機制（少數、重量、推倒）

判定三條件（全滿足才算回退）：

• 主體方案方向有問題
• 已完成的產物需要作廢
• 需要重新討論/設計

判定責任：回退的最終決定權在使用者。AI 發現疑似根本性問題時，只能建議疑似回退並說明理由，由使用者最終判定是否回退；AI 不能自行判定回退。

處理流程：

1. 停下當前實施
2. AI 建議疑似回退，說明理由（哪部分方向錯了、為什麼不成立）
3. 等使用者最終判定是否回退
4. 使用者確認回退後，在 00-任務狀態.md 記一行：從 X 階段回退到 Y 階段、原因、哪些產物作廢
5. 回到討論/設計階段重新對齊
6. 產生的新方案按原流程沉澱：新疑問進 01-溝通過程.md 未決疑問清單；方案變更進 02-設計.md 並補變更記錄
7. 同步修訂 03-實施.md

兩條機制的共同鐵律

1. 方案變更永遠改設計文件，不直接改實施文件
2. 先更新設計，再實施，順序不可顛倒（不先做後補）
3. 任何變更都要在任務狀態文件留痕（修改記設計變更記錄，回退額外記回退記錄）
4. 使用者確認是所有變更的必經卡點（修改需確認方案補充；回退需確認判定本身）

心態：偏差不可怕，可怕的是帶著偏差硬做或悄悄偏離方案。把「修改」做得輕量低摩擦（常態就該順暢），把「回退」做得慎重（推倒重來需使用者拍板），兩者都規範留痕，返工成本最低。

實施文件的步驟標記規範

實施步驟分大步驟和小步驟兩層，都要有獨立的完成標記。大步驟用標題分塊並帶進度計數，小步驟用四態 checkbox。

四態標記：

- [ ]  未開始
- [~] 進行中
- [x] 已完成
- [!] 阻塞（後方註明原因）

組織形式範例：

### 1. 資料庫層 ✅ 1/3
- [x] 1.1 建立 users 表（含遷移腳本）
- [~] 1.2 建立索引
- [ ] 1.3 編寫種子資料

### 2. 介面層 ⬜ 0/2
- [ ] 2.1 實作 POST /api/users
- [ ] 2.2 接入鑑權中介軟體

大步驟狀態符號：

• ⬜ 未開始（0/N 完成）
• 🌗 進行中（部分完成）
• ✅ 全部完成（N/N）

進度計數格式統一為 已完成數/總數，放在大步驟標題末尾。這樣既能看到整體進度，也能定位到具體卡在哪一小步。

後端專案的特殊處理

如果當前專案是純後端專案（無前端程式碼、或前後端分離後端獨立倉庫）：

• 設計文件和實施文件只寫後端內容，不涉及前端實現。
• 任何新增介面或舊介面變動（URL、方法、入參、出參、錯誤碼、鑑權要求等），必須在 02-設計.md 裡設專門的 「介面變動清單」 區塊集中體現。
• 介面清單格式要讓前端人員能直接拿去聯調，建議欄位：介面路徑、請求方法、請求體範例、成功回應範例、錯誤碼表、鑑權要求、備註。
• 這個介面清單是給前端的交付物，要寫得自洽、可獨立閱讀。
• 介面清單在設計階段必須給出確定結論，禁止把判斷推到實施階段。凡是「這個介面是新增還是變動」「路徑沿用還是改」「入參欄位對齊哪個既有結構」這類依賴現有程式碼才能定論的事實，必須在設計階段就讀現有程式碼確認掉，把結論寫進介面清單。「設計階段只討論不寫程式碼」的約束針對的是業務程式碼——為了確認介面形態去讀既有程式碼，屬於設計調研，不屬於實施，不違反約束。設計文件裡禁止出現「具體取決於現有程式碼」「實施階段再確認」這類含糊話術，也不允許用【實施期確認】之類的標籤把不確定性合法化。介面清單交付前端時必須是完全確定的，否則前端無法聯調。

驗收標準與測試（三層職責）

測試不是實施階段臨時補的，而是貫穿設計到實施的體系。三層職責嚴格分離：

層	載體	內容	性質	產出階段
規則	02-設計.md	抽象驗收標準	「做到什麼程度算滿足需求」	設計
實例	04-測試.md	具體測試用例	「用什麼輸入，預期什麼輸出」	實施規劃
動作	03-實施.md	步驟 + 用例引用	「做什麼動作，對照哪個用例驗證」	實施規劃

為什麼這麼分：驗收標準是需求邊界（屬於設計），用例是邊界的實例化，實施是落地動作。三層分開，規則改了找設計文件，用例改了找測試文件，動作改了找實施文件——各有事實來源，不會互相污染。

測試用例分層與編號：

前綴	類型	用途
T-F-	功能用例	正向流程
T-EX-	異常用例	反向、邊界、錯誤分支
T-R-	回歸用例	修改/回退後必測的關鍵路徑（從 F/EX 裡挑，防改 A 壞 B）
T-API-	介面用例	對應設計文件「介面變動清單」的每個介面

所有任務都強制生成 04-測試.md：本技能定位是中大型任務，小需求使用者不會觸發技能，因此不做複雜度判斷——任務一旦進入實施規劃階段，測試文件就是必產物。

修改/回退與測試的關係：走修改或回退機制後，方案變了 → 用例隨之更新（先改設計驗收標準，再改測試用例），並在回歸用例集（T-R）裡至少重跑一遍，防止局部修改引發全域回歸。

擴展模式 A：任務拆分（大型多模組任務）

何時啟用：大型任務天然包含多個半獨立模組（如「審核系統 = 敏感詞過濾 + 圖片審核 + 人工審核工作台」），單上下文裝不下。使用者在討論階段顯式說明「這是大型任務，拆成多模組」時啟用。不自動判斷任務規模，必須使用者顯式觸發。

核心機制：父任務負責總體設計 + 模組拆分 + 模組間介面契約 + 編排，子任務在父任務的邊界內各自走完整 4 階段流程。

A.1 父子任務的文件結構（巢狀式）

專案根/docs/design/
├── README.md                          ← 全域任務總覽
├── 01-審核系統/                       ← 父任務
│   ├── 00-任務狀態.md                 ← 用 parent-task-status.md 模板，含子任務清單
│   ├── 01-溝通過程.md                 ← 父任務級的總體討論
│   ├── 02-設計.md                     ← 總體架構 + 模組拆分 + 模組間介面契約
│   ├── 03-實施.md                     ← 僅父級編排（整合測試、聯調），不寫模組內部
│   ├── 04-測試.md                     ← 僅跨模組整合測試
│   └── 子任務/
│       ├── 01-1-敏感詞過濾/           ← 子任務（完整 4 階段文件，用普通模板）
│       ├── 01-2-圖片審核/
│       └── 01-3-人工審核工作台/
└── 02-其它任務/

子任務用普通模板（task-status / communication / design / implementation / test），完全不變。父任務用 assets/parent-task-status.md 模板，多出「子任務清單」區塊；父任務的設計文件在普通設計模板基礎上，必須額外包含兩個區塊：

• 模組拆分：列出拆成哪些子任務、各自職責邊界
• 模組間介面契約：子任務之間的介面約定（介面簽名、資料格式、呼叫方式等）。這是子任務能獨立並行的關鍵，必須設計階段定清楚

A.2 父任務的階段推進（嚴格串行）

1. 父任務先走「討論 + 設計」，必須產出模組拆分 + 模組間介面契約
2. 父任務設計經使用者確認後，才能啟動子任務
3. 啟動子任務時，按依賴關係排啟動順序：父任務設計階段就要明確子任務間依賴（如「人工審核工作台依賴敏感詞過濾的介面」），被依賴的子任務必須先完成，依賴方才能啟動
4. 子任務各自走完整 4 階段（滿足依賴前提下可並行）。如何讓多個子任務並行啟動由所用 agent 框架決定（一般透過後台/非同步子任務能力實現），具體落地參考見 B.5
5. 所有子任務完成後，父任務走「跨模組整合測試」收尾

為什麼父任務和子任務不能並行：父任務的核心產出是模組間介面契約，這是子任務能獨立的前提。父任務設計沒定就啟動子任務，子任務之間必然衝突。

A.3 子任務不能擅自改父任務定義的介面契約

介面契約是多模組的共識，任一子任務擅自改會讓其他子任務失控。子任務如果發現父任務的介面契約有問題：

• 不能自行修改介面契約
• 必須回到父任務走修改機制：更新父任務的 02-設計.md（含變更記錄）→ 等使用者確認 → 通知所有依賴該介面的子任務 → 受影響子任務同步修訂自己的設計/實施/測試

A.4 巢狀深度限制：只允許一層

父→子，不能再往下巢狀（子任務不能再有自己的子任務）。理由：巢狀層數過多會讓任務關係極其複雜；如果子任務還要再拆，通常說明任務拆分粒度不對——它本身應該被重新規劃為獨立的父任務，而不是塞進現有多層結構裡。

A.5 父任務模板使用

• 父任務狀態文件：用 assets/parent-task-status.md（不要用普通 task-status 模板）
• 父任務其它文件（溝通過程/設計/實施/測試）：用普通模板，但設計文件必須額外包含 A.1 所述的兩個區塊
• 子任務所有文件：用普通模板，完全不變

擴展模式 B：雙 agent 實施（實施分段）

何時啟用：單任務內部，實施+測試兩個階段堆疊導致上下文過長。使用者在實施階段開始時顯式說明「實施用雙 agent 模式」時啟用。不自動判斷，必須使用者顯式觸發。

核心機制：實施階段內部拆成兩個串行環節——實現 agent（按 03-實施.md 寫程式碼）+ 測試 agent（按 04-測試.md 驗證）。兩者是物理獨立的兩個 agent（兩個獨立上下文），透過任務狀態文件交接。B 的核心價值是上下文隔離：實現 agent 不背測試上下文，測試 agent 不背實現細節。

B.1 實現與測試的職責邊界

• 實現 agent：只做 03-實施.md 裡的步驟（寫程式碼），完成後不自己跑測試，而是在 00-任務狀態.md 的「實施分段狀態」區塊宣告「實現完成，版本 X，可進入測試」
• 測試 agent：基於最新的 03-實施.md + 04-測試.md 進行驗證。職責嚴格限於「跑用例、判失敗、報告」，不負責改程式碼（即使發現實現 bug 也不自己改）

B.2 測試 agent 發現失敗時的處理

測試 agent 跑用例失敗時，初判失敗根因（測試 agent 看到實際行為，最有資訊優勢做初判）：

• 判定為實現 bug（程式碼寫錯了，設計是對的）→ 報告給實現 agent，由實現 agent 修改。修改後必須回到測試 agent 複測該用例，通過才能進入下一步（實現 agent 單方面宣告「改好了」不能閉環）
• 判定為設計 bug（程式碼按設計寫了，但設計本身有問題）→ 不能擅自改設計，觸發修改機制：停下→更新設計→等使用者確認→改實施→改測試→回到測試 agent 複測

判定錯了由使用者糾偏；但「改設計」影響範圍大，必須使用者拍板。

B.3 實施分段狀態區塊

00-任務狀態.md 增加一個可選區塊（B 模式啟用時才填，普通模式不填）：

## 實施分段狀態（B 模式專用，普通模式留空）

- 當前環節：實現 / 測試
- 實現版本：(實現 agent 每次完成或修復後遞增)
- 實現完成宣告：YYYY-MM-DD，實現 agent 已宣告可進入測試
- 測試進度：
  - 已通過：T-F-01, T-F-02, ...
  - 失敗待修：T-EX-03（實現 bug，已報告給實現 agent），...
  - 待複測：T-EX-03（實現 agent 已修復，等測試 agent 複測）

實現 agent 和測試 agent 都讀寫這個區塊，它是兩者的唯一交接點。

B.4 與 A 的組合（A+B）

A 和 B 是正交的，可以組合：大任務按 A 拆成子任務，每個子任務內部按 B 拆成實現+測試。組合時不需要額外機制——因為子任務就是普通任務（A.1 已說明子任務用普通模板），所以子任務內部自然支援 B。啟用方式：父任務設計 + 子任務啟動後，每個子任務在實施階段開始時再決定是否啟用 B。

B.5 agent 排程指引

B 模式要求兩個物理獨立的 agent（實現 agent 和測試 agent），它們透過「實施分段狀態」區塊間接交接，不直接互相通訊。具體如何讓兩者接力，依賴你使用的 agent 框架。

無論用哪種框架，都遵循同一個通用排程模式：

1. 由一個排程方（可以是主 agent、外部編排腳本，或使用者本人）讀「實施分段狀態」區塊，判斷當前環節
2. 排程方啟動實現 agent，傳入設計/實施文件路徑，指令其按 03-實施.md 推進、完成後更新狀態區塊
3. 實現環節結束後，排程方啟動測試 agent，傳入測試文件路徑，指令其按 04-測試.md 跑用例、把結果（含失敗判定）寫入狀態區塊
4. 排程方根據狀態區塊的測試結果決定下一步：實現 bug 則回到實現 agent 修復並複測；設計 bug 則停下報告使用者走修改機制；全部通過則收尾

通用關鍵點：

• 實現 agent 和測試 agent 各自獨立建立上下文，互不污染——這是 B 模式「上下文隔離」的核心
• 兩個 agent 之間不直接感知彼此，只透過「實施分段狀態」區塊這個共享文件間接交接
• 排程方只做「讀狀態 → 判斷 → 派發」，不參與實現或測試本身

具體客戶端的落地參考：不同 agent 框架的子 agent / 後台任務 / 多視窗能力各不相同。本文不鎖定具體實現。使用 ZCode 時，詳見 assets/references/zcode-scheduling.md（按需載入：啟用 B 模式且需要具體操作指引時再讀）。其它客戶端可參照該文件思路，對照自身能力做適配。

重要邊界：技能不鎖定具體排程實現

技能定義的是交接協議（實施分段狀態區塊的格式和語意）和角色職責（實現/測試各做什麼），不鎖定具體怎麼排程。任何能「讀檔案、啟動子任務、寫檔案」的框架都能落地 B 模式。

階段切換的確認原則

階段之間不是自動跳轉的，需要顯式訊號：

進入條件	滿足條件
進入討論	（技能被手動啟動即開始）
討論 → 設計	使用者明確同意固化方案，且未決疑問清單已清空
設計 → 實施規劃	設計文件完成並經使用者認可
實施規劃 → 實施	使用者明確要求開始動手
實施 → 設計（修改）	實施中發現方案缺口，按「修改機制」停下改設計，等使用者確認
實施 → 討論/設計（回退）	實施中發現根本性錯誤，AI 建議回退，使用者最終判定後回退

如果拿不準是否該切換，預設停在當前階段繼續討論，主動問使用者。不要替使用者做「方案已經夠好了，可以開始寫了」的判斷。

模板使用

建立新文件時，從 assets/ 目錄讀取對應模板：

• assets/readme.md → docs/design/README.md（全域任務總覽）
• assets/task-status.md → 00-任務狀態.md（普通任務 / 子任務）
• assets/parent-task-status.md → 00-任務狀態.md（父任務專用，A 模式啟用時）
• assets/communication.md → 01-溝通過程.md
• assets/design.md → 02-設計.md（含驗收標準區塊；父任務需額外含模組拆分 + 介面契約區塊）
• assets/implementation.md → 03-實施.md
• assets/test.md → 04-測試.md（實施規劃階段生成）

讀取模板，填充實際內容，寫入任務資料夾。不要憑空捏造文件結構。

技能迭代與舊任務文件

技能會持續迭代，模板和規範會更新，但已經在用的舊任務文件不會自動遷移到新規範。這是有意為之——目的是保護使用者對文件結構的既有記憶，維持多上下文記憶機制的穩定性。文件結構是使用者換上下文後快速定位的記憶錨，錨不能因為技能升級就被頻繁變形。

處理原則：

• 不主動遷移：AI 不擅自掃描舊任務、不擅自對齊規範，即使發現舊文件格式與新規範有出入（例如舊文件有「回退記錄」區塊而新規範要求「變更記錄」）。發現的差異最多在「實施期備忘」或對話裡提一句，不擅自動手。
• 只在使用者顯式指令下遷移：使用者主動要求「把任務 X 的文件對齊當前技能規範」「遷移任務 X 到新格式」之類時才動手。AI 不替使用者判斷「這個舊任務該不該遷」。
• 增量補充優先：遷移預設只針對與新規範不符的部分做補充/修改，保留原文件整體結構和內容，不推翻重寫。這樣使用者換上下文回來不需要重新閱讀理解整個文件——結構沒動，記憶錨還在。
• 使用者明確要求重寫時，支援重寫，但必須先備份原檔案再生成新檔案：
  • 不在原檔案上直接覆寫
  • 備份檔案加日期或版本後綴，如 00-任務狀態.md.bak.20260617
  • 新檔案沿用原檔案名，承載重寫後的內容
  • 原檔案是使用者的歷史記憶錨，即使重寫也要保留原始版本，以備對比或回退
• 遷移/重寫前先說明範圍：動手前先告訴使用者會改哪幾處（增量）或重寫哪些檔案（全量），改完簡述動了什麼，保持可預期。

反模式（要避免的）

• ❌ 討論階段就開始寫業務程式碼——本末倒置。
• ❌ 把方案變更直接寫進實施文件而不更新設計文件——破壞單一事實來源。
• ❌ 新對話進來不讀狀態文件和 README，讓使用者複述進度——浪費上下文。
• ❌ 實施時遇到偏差悄悄改實現、不回寫設計——設計文件會逐漸失真。
• ❌ 後端專案寫了前端實現細節，或介面變動沒落到介面清單——前端拿不到聯調依據。
• ❌ 沒有顯式訊號就自動推進階段——剝奪使用者的決策權。
• ❌ 實施中發現方案缺口（漏欄位/分支/字典值等）卻直接改實施文件、不回設計文件、不等使用者確認——應走「修改機制」：停下→先改設計→等確認→改實施→繼續。
• ❌ 實施中發現根本性錯誤卻硬著頭皮改實施文件，或 AI 自行判定回退——應走「回退機制」：AI 只能建議，使用者最終判定，記回退記錄後回到討論/設計重新對齊。
• ❌ 大步驟勾了但裡面小步驟還漏著——大小步驟都要獨立標記。
• ❌ 討論發散收不回，未決疑問被新話題淹沒——靠未決疑問清單強制收斂。
• ❌ 介面清單裡出現「具體取決於現有程式碼」「實施階段再確認」之類含糊話術，或用【實施期確認】標籤把不確定性合法化——依賴現有程式碼的事實必須在設計階段讀程式碼確認，設計文件交付時介面清單必須完全確定，否則前端無法聯調。
• ❌ 技能迭代後擅自遷移舊任務文件、擅自對齊新規範——破壞使用者記憶錨。只在使用者顯式指令下遷移；且預設增量補充、不全量重寫；使用者要求重寫時必須先備份原檔案再生成新檔案。
• ❌ 設計文件只寫方案不寫驗收標準——驗收標準是需求邊界，缺了它就沒有「做完了」的客觀定義，實施期驗收只能憑感覺。
• ❌ 實施文件裡寫「單元測試覆蓋 XXX」之類的泛泛動作，不引用具體用例編號——測試動作必須指向 04-測試.md 裡的具體用例（如「對照 T-EX-03 驗證」），否則測什麼、預期是什麼都不明確。
• ❌ 走完修改/回退機制後不重跑回歸用例（T-R）——局部改動可能引發全域回歸，必須重測關鍵路徑。
• ❌ A 模式下父任務設計沒定（模組拆分或介面契約未產出）就啟動子任務——子任務之間必然衝突。父任務的設計必須先經使用者確認。
• ❌ A 模式下子任務擅自修改父任務定義的介面契約——介面契約是多模組共識，必須回到父任務走修改機制，並通知所有依賴該介面的子任務。
• ❌ A 模式下子任務再巢狀子任務（超過一層）——通常說明拆分粒度不對，該子任務應重新規劃為獨立父任務。
• ❌ A 模式下父任務不排子任務依賴關係就讓子任務全部並行——依賴方會在被依賴方未完成時卡死；依賴關係必須在父任務設計階段明確。
• ❌ B 模式下測試 agent 自己改實現 bug——職責必須分離：測試只挑刺，修復回實現 agent；且修復後必須由測試 agent 複測，實現 agent 不能單方面宣告閉環。
• ❌ B 模式下用同一個 agent 串行當「實現」和「測試」兩個角色——B 的核心價值是上下文隔離，物理上必須是兩個獨立 agent，否則上下文根本沒隔離，B 等於沒啟用。
• ❌ B 模式下測試 agent 發現設計 bug 就自行改設計——設計變更影響範圍大，必須觸發修改機制並經使用者確認；測試 agent 只能初判並報告。