FlexGodX/自主代理開發週期

自主代理開發週期（品質閘門管道）

此技能形式化了在自主建立 Quest Nova（Flutter + Go + PostgreSQL 16 + Drift/SQLite）期間開發並驗證的 5 階段工程工作流程與多代理仲裁管道。

它保證高架構保真度、零資料遺失、嚴格的安全性（零信任/IDOR），以及在各階段之間無需人工干預的數學驗證分散式同步。

[!NOTE] 逆向工程已排除： 逆向工程階段已省略/停用。管道直接從目標定義與功能規格撰寫開始（或將現有產品簡報作為輸入）。

---

1. 核心架構原則

1. 零中斷自主性： 協調器自主地完成所有階段。確認來自嚴格的品質閘門審計，而非詢問使用者。
2. 乾淨上下文獨立驗證： 審查員與評審員以獨立的子代理身分產生，並配備乾淨上下文（他們僅接收可驗證的目標工件、參考規格與明確的評估標準，不含先前的聊天推理）。
3. 一致批准屏障： 在所有審計員/評審員明確授予「已批准」裁決之前，無法進入下一階段。缺陷清單（「請求變更」）會觸發立即的修正-重新審計迴圈。
4. 備援模型路由： 當主要推理模型遇到速率限制（例如 HTTP 429 配額耗盡）時，管道會無縫地將任務路由至可用的高吞吐量模型（例如 Gemini 3.8 Flash），同時嚴格保留代理角色與乾淨上下文的邊界。

---

2. 5 階段管道

flowchart TD
    P1["階段 1：目標制定與功能規格"] --> QG1{"品質閘門 1：規格審計"}
    QG1 -->|"請求變更"| P1Fix["規格缺陷修正"]
    P1Fix --> QG1
    QG1 -->|"已批准（一致同意）"| P2["階段 2：系統設計與架構"]
    P2 --> QG2{"品質閘門 2：3 代理審判庭"}
    QG2 -->|"請求變更"| P2Fix["架構精煉"]
    P2Fix --> QG2
    QG2 -->|"已批准（一致同意）"| P3["階段 3：QA 工件與實作計畫"]
    P3 --> QG3{"品質閘門 3：可追溯性交叉審查"}
    QG3 -->|"請求變更"| P3Fix["計畫與 QA 對齊"]
    P3Fix --> QG3
    QG3 -->|"已批准（一致同意）"| P4["階段 4：實作（後端 + 用戶端）"]
    P4 --> P5["階段 5：完整驗證、壓力測試與發布"]

---

3. 工件命名慣例

管道產生的每個工件都是一個版本化檔案。切勿就地覆蓋工件，應建立下一個版本。

<ARTIFACT-NAME>-<date>-<NN>.md

• <ARTIFACT-NAME> — 工件的 UPPER_SNAKE 名稱：GOAL, SPECIFICATION, DESIGN, QA_ARTIFACT, IMPLEMENTATION_PLAN, RELEASE_NOTES。
• <date> — ISO 格式 YYYY-MM-DD 的建立日期。
• <NN> — 兩位數序號（01, 02, …），用於區分同一天內建立的相同名稱工件。從當天第一個工件的 01 開始，並為該工件在同一天的每次後續修訂遞增。此計數器是根據工件名稱獨立計算的，因此同一天建立的不同工件可能共用相同的數字（例如 GOAL-2026-11-10-01.md 和 DESIGN-2026-11-10-01.md）。新的一天開始時，計數器會從 01 重新開始。

範例：

工件	當天第一個工件	當天第二個工件
目標	docs/GOAL-2026-11-10-01.md	docs/GOAL-2026-11-10-02.md
規格	docs/SPECIFICATION-2026-11-10-01.md	docs/SPECIFICATION-2026-11-10-02.md
設計	docs/DESIGN-2026-11-10-01.md	docs/DESIGN-2026-11-10-02.md

規則：

1. 階段交付成果及所有交叉參照（品質閘門提示、計畫、版本說明）必須引用精確的版本化檔名，絕不引用未版本化的名稱，例如 docs/GOAL.md。
2. 工件名稱的最高 <NN> 是目前權威版本；較早的版本保持不變，作為稽核軌跡。
3. 品質閘門審計提供給它們的特定版本，並在裁決中記錄該檔名。

在本技能中，<date> 和 <NN> 代表上述的日期和序號。

---

4. 各階段執行指南

階段 1：目標制定與功能規格（品質閘門 1）

• 目標： 根據需求/簡報，明確制定系統邊界、使用者迴圈、領域模型和技術規格。
• 交付成果：
  • docs/GOAL-<date>-<NN>.md：全域系統範圍、核心不變量、完成定義 (DoD)。
  • docs/SPECIFICATION-<date>-<NN>.md：實體架構、時間機制、同步協定、OCC 版本控制、3 路合併規則、IDOR 保護、DDL 架構。
• 品質閘門 1（乾淨上下文審計員）：
  • 產生子代理（typeName: "research"）。
  • 提供僅 docs/SPECIFICATION-<date>-<NN>.md 和標準（完整性、安全性、資料完整性、一致性）。
  • 迴圈直到「已批准」。

階段 2：系統設計與「三代理審判庭」（品質閘門 2）

• 目標： 設計可擴展、容錯的後端和反應式用戶端。
• 交付成果： docs/DESIGN-<date>-<NN>.md（系統設計文件：後端、用戶端、安全性）。
• 品質閘門 2（三代理審判庭）： 產生 3 個獨立的子代理，並配備乾淨上下文：
  1. 評審員 1（後端與系統架構師）： 評估資料庫架構、交易邊界、行級鎖、拓撲 DAG 排序、分割方案和 OCC。
  2. 評審員 2（用戶端與 UI 架構師）： 評估離線優先資料庫 (Drift/SQLite)、背景隔離區、影格預算 (< 16.6 ms)、突變佇列合併和 BLoC 狀態機。
  3. 評審員 3（安全性與邊緣案例評論員）： 識別競爭條件、冷啟動死結、迴聲迴圈、令牌重放 (RTR)、工作階段竊取和 IDOR 漏洞。
  • 所有 3 位評審員必須返回「已批准」才能繼續。

階段 3：QA 工件、可追溯性計畫與品質閘門 3

• 目標： 在編寫程式碼之前，確保規格、架構和測試之間具有 100% 的雙向可追溯性。
• 交付成果：
  • docs/QA_ARTIFACT-<date>-<NN>.md：完整的驗收標準 (AC-XX)、單元測試、整合測試、分散式同步測試 (TC-SYNC-XX) 和壓力測試情境 (STRESS-XX)。
  • docs/IMPLEMENTATION_PLAN-<date>-<NN>.md：分階段任務分解，直接映射到 QA 案例。
• 品質閘門 3（交叉審計員）：
  • 驗證 docs/QA_ARTIFACT-<date>-<NN>.md 中的每一個驗收標準和邊緣案例都直接對應到 docs/IMPLEMENTATION_PLAN-<date>-<NN>.md 中的一個實作步驟。
  • 迴圈直到「已批准」。

階段 4：實作與測試驗證

1. 資料庫遷移： 應用所有包含複合索引和分割區的 DDL 遷移。
2. 後端引擎：
   • 乾淨架構：domain/, repository/, usecase/, delivery/http/。
   • 執行單元與整合測試：cd backend && go test -v ./...。
3. 用戶端引擎：
   • 核心時間工具（PlainDate, FloatingTime, SparseSortOrder）。
   • 3 路差異合併引擎（5 個檢查清單情境，零資料遺失備註）。
   • 就地突變合併與進行中競爭處理（MutationQueueManager）。
   • BLoC 架構與自適應 UI（桌面 3 窗格 + 行動導航）。
   • 執行用戶端測試：cd client && flutter test。
   • Linter 驗證：cd client && flutter analyze（0 個問題）。

階段 5：壓力測試、發布與交接

1. 分散式同步驗證： 執行多裝置並發、OCC 衝突、迴聲抑制和 HTTP 410 啟動協調。
2. 壓力測試：
   • 資料庫連線池飽和 (STRESS-01)：並發工作者，0 個連線池洩漏。
   • UI 影格預算基準測試 (STRESS-02)：在 < 16.6 毫秒內處理 1000 個任務（穩定的 60/120 FPS）。
3. 工件編譯：
   • 建構原生後端二進位檔：go build -o bin/<service> cmd/<service>/main.go。
   • 建構用戶端套件：flutter build bundle / flutter build macos / flutter build web。
4. 版本說明： 產生 docs/RELEASE_NOTES-<date>-<NN>.md，記錄已驗證的指標、DoD 檢查清單和執行說明。

---

5. 審計員與評審員提示範本

有關在品質閘門 1、2 和 3 中調用乾淨上下文子代理時使用的提示範本，請參閱 references/auditor_prompts.md。