🛡️ 開發週期協議 (dev-cycle-protocol v4)
路徑:
<skills_root>是包含此技能（即此SKILL.md檔案所在資料夾的上層資料夾）的資料夾。在執行指令時，請使用真實的絕對路徑。請從專案的儲存庫中執行指令（或傳遞--dir參數）：如果從儲存庫上層的目錄開始一個工作階段（例如雲端工作階段中的/home/user），將會讀取到錯誤的資料夾。引擎: 已翻譯為 Rust 語言的腳本 (IMP-005) 透過啟動器執行，在此處寫為
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" <skill> <script> [args]（sh shell：Linux, macOS, Git Bash）。在 PowerShell 中，請執行& "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" <skill> <script> [args]。首次執行會為該機器下載引擎並檢查其校驗和。
dev-cycle-protocol 像一個專家團隊一樣協調軟體工作。它擁有階段、閘門以及每個角色何時執行的決定權；每個角色技能則擁有自己的產出物、規則和檢查器。它與語言和專案無關。
語言: 與使用者交談時使用他們所使用的語言，但所有專案產出物必須使用英文撰寫：程式碼、註解、文件、ADR、計畫、手動測試、提交訊息和拉取請求描述。專案可以在
.dev-cycle.json中設定另一種文件語言 (architecture_docs.language)。
🧭 開始一個工作階段 (/dev-cycle)
使用者透過一個指令 /dev-cycle（可以包含一個產品想法或一個請求，也可以單獨使用）開始。它會執行診斷（在引擎上執行 onboard diagnose），用一句話說明專案是否為最新狀態並繼續執行，或按建議順序顯示選項：進行中的計畫、待處理的發布候選版本、未關閉的阻礙性錯誤、缺失的設定（配置、分支模型、整合分支、Spec Kit）、缺失的產品基線、當前發布的下一個項目、請求。一個新的儲存庫會進入第 0 階段。一個從未使用過此協議的儲存庫會獲得一個初始設定清單，可以一次性確認或逐項確認；在獲得使用者確認之前，不會寫入任何內容。當使用者要求工作但未使用該指令時，請先執行相同的診斷。
👥 角色
| 角色 | 技能 | 擁有者 |
|---|---|---|
| 協調器 | dev-cycle-protocol | 階段、閘門、每個變更的路徑、.dev-cycle.json、/dev-cycle 診斷、Spec Kit 設定與產生的章程 |
| 產品 | product-inception | 第 0 階段：產品基線、docs/product/VISION.md 與 TECH_SPEC.md |
| 規劃者 | plan-memory | 包含史詩的待辦事項清單 (docs/BACKLOG.md，/backlog 指令)、路線圖 (docs/ROADMAP.md)、位於 docs/plans 的計畫檔案、里程碑、漂移偵測 |
| 架構師 | software-design | 設計原則、架構風格、計畫中的設計章節、結構性審查 |
| 技術文件 | architecture-docs | TECDOC.md、docs/architecture、ADR |
| 品質保證 | quality-assurance | 自動化測試策略、精心策劃的手動測試套件、發布候選版本測試執行 |
| DevOps | devops-release | 分支模型、CI、版本、發布候選版本、發布、可觀測性 |
| 技術作家 | user-docs | README 和終端使用者文件 |
| 審查者 | code-review | 對其平台上的每個拉取請求進行審查：附帶等級的逐行評論，永不核准 |
| 工作階段記憶體 | session-memory | 開發者自身的工作階段上下文 |
| Gedo 回饋 (暫時，預設關閉) | gedo-feedback | 在實際工作中與 Gedo 相關的問題，記錄到 Gedo 的待辦事項中（當專案使用 Gedo 時，gedo.enabled） |
| 規格執行器 (可選) | GitHub Spec Kit | 第 1、2、4 階段中功能的細節：specs/NNN-slug/（規格、計畫、任務） |
角色是一組規則和一個檢查器，而不是一個獨立的人：當一個階段開始時載入角色技能，遵循它，並在離開該階段之前執行其檢查器。Spec Kit 是一個工具，而不是一個角色：協議決定何時執行它並檢查其產出物（請參閱「Spec Kit」）。
🏛️ 原則
- 設計：模組化程式碼，職責明確，遵循 SOLID、Clean Code、明確的錯誤處理，僅在必要時使用設計模式，採用專案的架構風格 (
software-design)。 - 證據：每次變更都需有自動化測試證明；手動測試僅涵蓋無法自動化的部分，並整合在一個精心策劃的測試套件中 (
quality-assurance)。 - 文件描述的是當前的狀態：技術文件和 README 應直接原地編輯；歷史記錄存在於 Git 和發布說明中 (
architecture-docs,user-docs)。 - 計畫是共享且完整的：已核准的計畫是專案中的版本控制檔案 (
plan-memory)。 - 安全交付：基於專案分支模型的短期分支、每個拉取請求都執行 CI、發布候選版本、使用者的發布閘門 (
devops-release)。 - 安全性：Git 中不包含機密、向後相容的資料遷移、每個發布都有復原路徑。
- 錯誤優先：在新的功能、改善和調整之前，必須先規劃並修復已開啟的
critical、high和medium等級的錯誤；low等級的錯誤最遲在下一個發布中處理；不能有已知錯誤處於未分類狀態（必須指定嚴重性，以及為非阻礙性錯誤指定預計發布版本）。只有使用者可以明確接受風險。任何發現都不會被丟失，它會被立即修復或記錄在待辦事項清單中。 - 貫徹到底：代理程式會追蹤 CI 和發布流程直到最後，並修復任何失敗的問題；使用者的決定（計畫核准、候選版本接受、發布閘門）絕不能由代理程式代為執行。
- 無 AI 歸屬，任何地方：任何產出物都不得將 AI、模型或編碼代理程式列為作者、共同作者、審查者或來源：包括提交及其追蹤資訊、標籤、分支、拉取與合併請求、審查及審查意見、議題、計畫、文件、發布說明和程式碼註解。所有內容都應歸屬於儲存庫的 Git 身分 (
devops-release)。專案為其工具所需進行的配置（代理程式的設定資料夾、整合名稱）是技術性配置，而非歸屬。透過pr_sync（一種平台工具、連接器、網頁）以外的任何工具張貼的文字，都須先使用"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol _no_ai --file <text>進行檢查，並在張貼後重新讀取：工具附加的任何頁尾、連結或標記（例如「由...產生」、代理程式的會話或執行緒連結）應立即編輯移除。閘門 8 也會拒絕作者或提交者為 AI 身分的提交。
🧭 選擇路徑
| 路徑 | 使用時機 | 階段 |
|---|---|---|
| 初始階段 | 從一個想法開始的新產品，或是尚未有產品基線的現有專案（導入模式） | 第 0 階段，每個產品執行一次；然後對路線圖中的第一個項目執行完整路徑 |
| 完整路徑 | 新功能、重構、資料或綱要變更、命令、配置、檔案格式或公開 API 的變更、CI/發布變更、任何跨越多個模組的變更 | 每個變更執行第 1 到 7 階段；每個發布執行第 8 到 10 階段 |
| 短路徑 | 小型錯誤修復、僅文件、僅測試或打字錯誤的變更，可容納在一個小型拉取請求中，且不改變任何介面或資料 | 第 1、4、5、6（僅受影響的部分）、7 階段 |
對於短路徑，當使用者的請求已明確指出變更內容時（例如「修復 X 的崩潰」），該請求即構成核准；否則，請用一兩句話描述變更內容，並等待使用者同意。如有疑問，請使用完整路徑。
🔄 週期
graph TD
P0["0. 產品初始階段 (僅一次)<br/>product-inception, 閘門 0 (使用者)"] -.-> P1
P1["1. 探索<br/>orchestrator, plan-memory, software-design"] --> P2["2. 計畫<br/>plan-memory + 所有角色"]
P2 --> G3{"3. 計畫核准<br/>(使用者)"}
G3 -- "問題 / 變更" --> P1
G3 -- "已核准" --> P4["4. 在分支上實作<br/>software-design"]
P4 --> P5["5. 自動化測試<br/>quality-assurance"]
P5 --> P6["6. 文件<br/>architecture-docs, user-docs, quality-assurance"]
P6 --> P7["7. 審查並建立 PR 到工作基底，CI 通過<br/>reviewer, software-design, devops-release"]
P7 -. "下一個變更" .-> P1
P7 --> P8["8. 發布候選版本<br/>devops-release, quality-assurance"]
P8 --> G9{"9. 接受<br/>(使用者執行手動測試)"}
G9 -- "失敗 / 阻礙" --> P4
G9 -- "全部通過" --> G10{"10. 發布閘門 (使用者)<br/>將 dev 合併到 main，或提升候選版本"}
G10 --> P11["最終發布已追蹤並驗證<br/>devops-release, plan-memory, session-memory"]
第 0 階段每個產品只執行一次。第 1 到 7 階段每次變更都需執行。第 8 到 10 階段在使用者想要發布已累積在工作基底中的變更時執行。
分支模型 (devops.branching, devops-release)：以下每個階段都提到了工作基底、候選分支和發布閘門；模型會提供它們（在引擎上執行 branching show："<skills_root>/dev-cycle-protocol/bin/dev-cycle" devops-release branching show）：
| 模型 | 工作基底 (從此分支，PR 合併至此) | 候選分支 | 發布閘門 (使用者) |
|---|---|---|---|
integration (預設) | dev | dev | 將 dev 合併到 main |
trunk | main | main | 為已接受的候選版本執行提升工作流程 |
release-branches | main (某個發布的修復: release/X.Y) | release/X.Y | 為已接受的候選版本執行提升工作流程 |
0. 🌱 產品初始階段 (每個產品僅一次)
遵循 product-inception：訪談、商業文件、架構、技術規格、章程 (Spec Kit)、包含史詩的產品待辦事項清單、路線圖，每一項都需經使用者核准。它以閘門 0 結束，即使用者核准產品基線：
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol verify_gate --gate 0
一個尚未有基線但正在進行中的專案可以採用它（導入模式）或跳過它：第 0 階段對新產品是必需的，對現有產品則是建議的。
1. 💡 探索
- 保持諮詢模式：當使用者提問、討論或提出建議時，不要編輯檔案或開始撰寫程式碼。
- 檢查專案及其配置：
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol inspect_project "<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol project_config --validate - 優先查看日誌：對於任何回報的錯誤，在形成假設之前，請先閱讀實際的日誌。
- 閱讀進行中的計畫（在引擎上執行
list_plans："<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory list_plans；plan-memory check_milestone --list）以及架構風格與結構 (software-design)。 - 閱讀待辦事項清單和路線圖（在引擎上執行
plan-memory backlog summary、roadmap current："<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory roadmap current；inspect_project會顯示兩者）。向使用者展示在新工作之前需處理的未關閉錯誤，然後是當前發布的未關閉項目以及與請求相關的項目；由使用者決定要提升、重新排定優先順序、移動或丟棄哪些項目（請參閱「待辦事項清單和路線圖」）。 - 為了規劃待辦事項清單中的項目，請提升它們 (
backlog promote <ID> ...)：草稿計畫（錯誤的錯誤修復計畫）是記錄探索內容的地方。 - Spec Kit：檢出工作基底，然後使用項目的描述執行
/speckit-specify：它會建立工作分支feat/NNN-slug和specs/NNN-slug/spec.md。執行/speckit-clarify直到沒有留下[NEEDS CLARIFICATION]標記；使用者回答其問題。被提升的計畫是信封；探索內容則存在於規格中。 - 窮舉所有未解決的問題，並與使用者一起收斂到一種方法。
2. 📋 計畫
使用以下模板撰寫完整計畫，收集每個角色的章節：
- 目標與決策：變更的內容及原因；包含替代方案的決策會成為 ADR (
architecture-docs)。 - 設計 (
software-design)：每個部分的存放位置、介面、資料流程、錯誤處理策略、依賴關係、明確不進行抽象化的部分。 - 受影響的表面與檔案：
architecture.surfaces中會變更的介面；檔案和模組。 - 測試 (
quality-assurance)：要新增的自動化測試（每個錯誤一個回歸測試）、要新增、變更或移除的手動測試、驗收標準。 - 文件 (
architecture-docs,user-docs)：子系統頁面和 ADR、README 章節。 - CI、發布與可觀測性 (
devops-release)：工作流程變更、版本影響、要新增的日誌、診斷和遙測資料及其測試方式。 - 安全性、遷移與復原：機密、資料遷移（需向後相容）、如何復原。
- 執行步驟與里程碑。
Spec Kit：執行 /speckit-plan（其計畫攜帶
...
[截斷以進行翻譯]