Structured Dev — 結構化開發流水線

核心原則：在你審查並批准書面方案之前，不讓 AI 寫一行程式碼。

流水線總覽

Research → Plan → Annotate (1-6輪) → Todo List → Implement → Feedback

每一步都有明確產物和審查點。所有產物寫入專案根目錄的 .dev/ 資料夾。

Phase 1: Research（深度調研）

觸發

使用者給出開發任務時，不直接寫程式碼。

執行步驟

1. 在專案根目錄建立 .dev/ 目錄（如不存在）
2. 深度閱讀相關程式碼。使用以下關鍵詞引導自己：deeply, in great details, intricacies, go through everything。淺層閱讀不可接受。
3. 輸出 .dev/research.md，必須包含：
   • 架構理解：模組關係、呼叫鏈、資料流
   • 相關檔案清單：每個檔案的職責說明
   • 現有約定：ORM 用法、快取層、API 風格、命名規範
   • 潛在風險：邊界條件、已知 bug、需要注意的耦合點
4. 停下來，等待使用者確認

產物

• .dev/research.md

審查標準

使用者通讀 research.md，驗證 AI 是否真正理解了系統。調研如果錯了，方案一定錯。

Phase 2: Plan（詳細方案）

觸發

使用者確認調研無誤後。

執行步驟

1. 輸出 .dev/plan.md，必須包含：
   • 實現思路：整體方案描述
   • 檔案路徑：將修改哪些檔案，每個檔案改什麼

     小蔥技能7w4.net有完整的技能分類。

   • 關鍵程式碼片段：不是虛擬碼，是實際可執行的程式碼
   • 取捨說明：為什麼選 A 不選 B
   • 影響評估：對現有模組的影響
   • 排除項：明確說明不做什麼
2. 如果使用者提供了參考實現，優先基於參考實現設計
3. 停下來，等待使用者審查

產物

• .dev/plan.md

關鍵原則

Claude works dramatically better when it has a concrete reference implementation to work from rather than designing from scratch.

給參考實現 > 從零設計。

Phase 3: Annotate Loop（批註迴圈）

這是整套方法最有價值的部分

使用者在 .dev/plan.md 中直接新增行內批註。批註型別：

• 糾正假設："不對，這裡應該用 PATCH，不是 PUT"
• 否決方案："這一節整個刪掉，不需要快取"
• 補充約束："用 drizzle:generate 生成遷移，不要寫原始 SQL"
• 注入上下文："佇列消費者已有重試機制，這段多餘，刪掉"
• 調整方向："visibility 欄位應在 list 層級，不是 item 上"

執行步驟

1. 使用者說"處理批註"時，開啟 .dev/plan.md
2. 逐條處理所有批註
3. 原地更新 plan.md（不新建檔案）
4. 明確標註每條批註的處理方式
5. 停下來，等待使用者再次審查
6. 重複 1-6 輪，直到使用者說"方案確認"

關鍵約束

• 絕不在批註迴圈中寫實現程式碼
• 使用者說"先不要實現"時嚴格遵守
• plan.md 是共享可變狀態（shared mutable state），不是一次性輸出

Phase 4: Todo List（任務拆分）

觸發

使用者說"方案確認"或"生成 todo list"。

執行步驟

1. 在 plan.md 末尾追加 ## 實施清單 章節

2. 按階段拆分為細粒度任務，每個任務一行 checkbox：

   ## 實施清單
   
   ### 階段一：資料層
   - [ ] 建立 migrations/xxx.sql
   - [ ] 修改 src/models/user.ts 新增 role 欄位
   
   ### 階段二：業務層
   - [ ] 修改 src/services/auth.ts 新增許可權檢查

3. 任務粒度：一個函式、一個檔案修改、一個測試用例
4. 停下來，等待使用者確認任務拆分

產物

• plan.md 中的實施清單章節

Phase 5: Implement（執行實現）

觸發

使用者說"開始實現"。

標準實現指令

全部實現。每完成一個任務，在 .dev/plan.md 中標記為已完成 [x]。
在所有任務全部完成之前不要停下。
不要新增不必要的註釋，保持程式碼風格與專案一致。
持續執行型別檢查/lint，確保不引入新問題。

執行原則

• 所有決策已在批註迴圈中完成，實現是機械性執行
• 實現過程中遇到方案沒覆蓋的問題，暫停並詢問
• 不擅自做架構決策
• plan.md 是進度的唯一來源

I want implementation to be boring. — Boris Tane

Phase 6: Feedback（反饋修正）

反饋型別

簡短修正（直接執行）：

• "你漏了 xxx 函式"
• "挪到 X 檔案"
• "用 Y 代替 Z"
• "寬一點" / "有 2px 間隙"

參照修正（指向已有程式碼）：

• "這個表格應該跟使用者列表完全一樣"

回滾重來（方向走偏時）：

• "回滾所有改動，只做 X，別的不動"
• 回滾 + 收窄範圍，幾乎總是比漸進式修補更好

四種方向盤操作

1. 逐項挑選："第一個用 Promise.all，第三個提取函式，第四五個忽略"
2. 裁剪範圍："刪掉下載功能，現在不做"
3. 保護介面："這三個函式簽名不能改"
4. 覆蓋選型："用這個庫的內建方法"

與 Coding Agent 的整合

大型任務：spawn coding agent 執行實現

當專案較大或需要長時間執行時，Phase 5 可以 spawn coding agent：

用法：
1. 完成 Phase 1-4（Research → Plan → Annotate → Todo List）
2. 使用者確認後，spawn coding agent 進入專案目錄
3. 把 .dev/plan.md 的內容作為 agent 的 task
4. Agent 按 plan 執行，在 plan.md 中標記進度

實現完成後

可觸發 code-review skill 進行程式碼審查，或自動建立 GitLab/GitHub MR。

會話管理

預設：單長會話

• 調研 → 實現保持 context 連續
• AI 在整個會話中積累了對系統的理解
• 換新會話 = 理解歸零

會話中斷恢復

• 通過 .dev/plan.md 恢復上下文
• 指令："讀取 .dev/research.md 和 .dev/plan.md，恢復上下文，繼續從 todo list 中未完成的任務開始"

文件 > 記憶

• 關鍵決策寫進文件，不依賴 context window
• plan.md 不會被壓縮、不會被遺忘

快速參考

質量不錯，設計思路清晰有創意，方法論先進。優點是流程完整、模板實用；不足是內容偏理論，缺少實操細節指導。這個 Skill 比較適合想系統化規範 AI 開發流程的開發者使用。