Ai development workflow

AI 開發工作流程

這是可用於 Codex 與 Claude Code 的平台中立入口。依使用者指定的模式工作，並以可驗證證據控制範圍。

核心原則

• 先確認目標、範圍、驗收條件與限制，再產出文件或程式碼。
• 只做目前已授權的工作；單一模式只做該模式，多模式只做明確指定的組合。
• 不以時限、上線壓力或主管要求為由，擅自縮減需求或驗收條件。指令與驗收條件衝突時，先列出影響並請使用者確認。
• 結論需區分已驗證事實、合理推論與待確認事項；不用歷史計畫取代當前實作證據。

四種模式路由

1. 需求計畫：先查證環境事實，再釐清必要決策、邊界、資料流、風險與驗收條件；適用時加入可觀察行為場景、以使用者可觀察的最高穩定公開介面為測試 seam，以及可驗證實作切片。
2. 測試設計：根據需求與現有測試設計正常、邊界、異常與回歸案例，不實作產品程式碼。
3. Git Diff 審查：對已有變更檢查正確性、合同、回歸、測試與範圍。「審查並修復」也歸此模式：可在原請求授權範圍內修復；若涉及對外合同變更、擴大需求、破壞性操作或偏離核准計畫，先確認。
4. 完整流程：「實作」、「完成需求」或端到端請求均走此模式。依序執行需求計畫 → 測試設計 → 核准實作 → 驗證／文件回填 → Git Diff 審查。若沒有明確核准的計畫，先完成計畫並等待核准，不開始實作。

若使用者只要求「計畫＋測試設計」，不得寫入程式碼。若無法判斷模式或範圍，只問一個最能界定範圍的問題。

共用探索順序

預設把目前工作目錄當作主倉庫，依序：

1. 讀根目錄的代理、貢獻與工作流程規範。
2. 讀與目標模組相關的 docs/agents/ 指南。
3. 追蹤相關程式碼、路由／入口、合同、資料流與測試。
4. 必要時查閱實作文件、原型、知識庫或表格。
5. docs/plans/ 只是歷史意圖，可能被 Git 忽略、過時或未實作；不得單獨當作當前事實。

只有發現具體的跨專案資料或合同缺口時，才詢問其他專案；同時列出已查到的證據與缺口，不籠統要求更多背景。

證據優先級

衝突時依下列順序判斷：

1. 目前對話
2. 需求與驗收條件
3. 原型／知識庫／表格
4. 已驗證的程式碼／測試／實作文件
5. 歷史計畫

同一層證據衝突時，標示版本或時間、說明影響，並請使用者決定。

文件與程式碼確認點

• 使用者明確要求需求計畫或測試設計時，先告知預計寫入路徑，即可寫入；若是代理自行判斷應產生文件，寫入前先確認。
• 不覆蓋歷史計畫；同名時使用 -v2、-v3 遞增版本。
• 只有計畫已被明確核准，才可新增或修改產品程式碼。
• 實作中出現新內容時，先依需求計畫指南區分「事實更正」與「待核准候選變更」；前者同步證據，後者立即停在安全邊界並等待再次核准，不把候選內容直接寫入正式範圍。
• 實作後依變更風險執行可重現的驗證，再審查完整 Diff；不把「看起來正確」當作通過。

語言選擇規則

• 互動語言跟隨使用者目前使用的語言；使用者明確指定時以指定語言為準。
• 計畫、測試設計、文件與程式碼中的註解、測試名稱、日誌及內部錯誤訊息，依目標倉庫規範；沒有明文規範時跟隨附近檔案慣例。
• 互動語言與目標倉庫語言可以不同，不為統一輸出而改寫既有檔案。
• 規範缺失或衝突，且選擇會造成跨檔案語言改寫時，先列出受影響的文件或介面並確認。
• API 欄位、類別、方法、路由、錯誤碼、事件、routing key 與其他固定合同／識別字保持原文，不翻譯。

公開與私有資料安全邊界

• 公開 Skill 套件中的範例、路徑、人名、專案名、網域、識別字與資料一律虛構，不可倒推真實組織或系統。
• 私有執行產物可保留必要的相對路徑、合同名稱與證據摘要，但只限完成當前任務所需。
• 任何產物、訊息或範例都不複述 secret、token、密碼、個資或不必要的真實業務資料；發現時以遮罩後摘要取代。

Reference 按需導航

每個階段只讀當下任務需要的 reference，不一次載入全部：

• 需求計畫：references/requirement-plan.md
• 測試設計：references/test-design.md
• Git Diff 審查或審查並修復：references/git-diff-review.md
• 已明確啟用 AI 協作成效，需建立計量、鎖定基準或完結回填：references/reference-timing.md
• 目前對話已明確觸發或使用外部能力，或倉庫規範／活動產物顯示外部工作流時：references/workflow-integration.md
• 需要輸出格式範例時：references/examples.md

完整流程仍依「需求計畫 → 測試設計 → 核准實作 → 驗證／文件回填 → Git Diff 審查」推進，進入階段時才載入對應文件。

外部工作流導航

• 只依目前對話已明確觸發或使用的能力、倉庫規範與可定位的活動產物判斷是否啟用整合。只有名稱、可用能力清單、已安裝工具或目錄存在不構成啟用證據。
• 有證據時才讀取外部工作流 reference；無證據時維持原生四種模式，不掃描全部歷史產物、不詢問安裝，也不增加橋接文件。
• 每個需求只選一套需求級主 Provider；其他工具只補上主 Provider 缺少、可獨立使用且不重複所有權的能力。
• 已有外部正式產物時，保留該產物的內容所有權；本 Skill 只記錄來源、狀態、完整性、唯一可寫所有者、缺口與同步結果，不複製全文。
• 外部命令在執行前必須驗證實際命令、工作目錄、輸入、寫入目標、可回復性、網路與遠端副作用。實作核准不自動授權安裝、初始化、封存、刪除、遠端寫入或發布。
• 可選 Provider 失效時將該能力降級為原生流程，不宣稱 Provider 通過；平台、已載入 Skill 或倉庫強制 Provider 失效時，阻斷受影響交付，只能使用其規範明示的替代路徑。

參考計時關卡

• AI 協作成效與本機參考計時預設關閉。只有使用者明確要求 AI 成效／提效，或目標倉庫政策明確要求時才啟用；啟用時簡短說明資料只存本機且可停用。
• 成效量化只使用時間；不收集、不估算、不輸出 Token 用量，也不以 Token 多寡推導效率。
• 未啟用時不建立計量 ID、不加入 AI 協作成效章節，也不猜測參考耗時或提效；Python 3 不可用或安全檢查失敗時，關閉計時但不阻斷主流程。
• 完整流程首次進入需求計畫階段時執行 start，把回傳計量 ID 寫入需求計畫。需求與檔案級計畫核准後、產品實作前，先寫入五階段 PERT 依據，再以 baseline 鎖定基準與指紋。
• 階段切換使用 enter；每個 AI 回合結束前，以及等待使用者、CI 或外部佇列前使用 pause。同一對話續接回合的第一個計時動作使用 resume --new-turn；若上回合意外留下 running，工具會排除該未閉合區間並標記部分覆蓋。
• 完結前先 pause，判斷混入工作與計量覆蓋度，再 complete --coverage complete|partial|unknown。只有完整覆蓋、有效 baseline 與一致指紋才計算節省工時及提效；將摘要回填需求計畫並回讀對帳後，才 delete。
• 新對話不搜尋、列舉、繼續或合併舊計量。同一需求換對話後，不另建續接計量，最終明確標示無法計算整體參考提效。
• 子代理與外部 reviewer 不執行計時命令；只由協調代理維護單一狀態，避免重疊區間。