🐘🐟 大象金魚開發模式 (Elephant & Goldfish Pattern)
📌 Overview
- 🐘 大象（Coordinator，也就是你）：有全貌記憶。負責溝通、寫 CUJ 規格、分派任務、審閱結果。 不親自寫程式、不親自跑測試。
- 🐟 金魚（Coder / Tester / Reviewer）：零歷史包袱的無狀態子代理。只看 CUJ 做事，完成即銷毀， 避免上下文污染。
🚦 Step 0：先判斷這個任務要不要走本流程
這是第一個決定，不要跳過。
| 任務類型 | 走本流程？ |
|---|---|
| 新增功能或模組 | ✅ |
| 修改既有功能的行為 | ✅ |
| 重構涉及外部介面變更 | ✅ |
| 需要改動邏輯的 bug 修復 | ✅ |
| 純文件更新（README、註解） | ❌ |
| 程式碼格式化 / lint | ❌ |
| 依賴版本升級（無行為變更） | ❌ |
| 設定檔微調 | ❌ |
| 緊急 hotfix（已上線的嚴重 bug） | ❌ 直接修，事後必須補 Tester 驗證 |
判斷不了時的預設：改動 ≤ 10 行且不改變任何外部可觀察行為 → 不走流程。
❌ 不適用時，直接依專案既有規則做事，不需要提及本 Skill，也不要為了走流程而寫 CUJ。
🎯 核心原則
- 金魚測試標準：一個全新的子代理（金魚），僅憑 CUJ 文件，就能獨立完成 說明 → 實作 → 測試 全流程。 做不到，代表規格寫得不夠好，不是 AI 不夠聰明。
- 角色嚴格分離：寫程式的人（Coder）不能批改自己的考卷（Tester / Reviewer）。
- 規格 + 測試：CUJ 定義「要什麼」，測試證明「拿到了」。兩者缺一，CUJ 就退化成寫給人看的文件， 而非金魚的可執行契約。
- 信任 Script，不只信任 Markdown：用
scripts/validate_cuj.py做客觀檢查，不靠自我感覺良好。
🚀 流程
Step 1：按需載入參考資料
不要一次全讀。 依當下實際需要載入，這是漸進式揭露的重點：
| 什麼時候讀 | 讀哪一份 |
|---|---|
| 要派發金魚之前（必讀） | references/dispatch-prompts.md |
| 不確定某個角色能不能做某件事 | references/role-separation.md |
| 不確定 CUJ 要寫到什麼程度，或驗證一直不過 | references/cuj-workflow.md |
| 要開始寫 CUJ | assets/cuj-template.md（格式）assets/cuj-001-user-login.md（合格標準） |
| 使用的工具沒有子代理機制 | references/role-separation.md 的跨工具對照表 |
Step 2：撰寫 CUJ
- 依範本格式，存到專案的
cuj/目錄，檔名cuj-XXX-簡短描述.md - frontmatter 的
id必須與檔名前綴一致（見 Gotchas） - 需求有模糊地帶時，先釐清再寫 —— 釐清機制見
cuj-workflow.md步驟 2（本 Skill 職責邊界外）
Step 3：驗證 CUJ（客觀關卡）
python .agent-skills/elephant-goldfish/scripts/validate_cuj.py cuj/
- exit code 0 才可進入 Step 4
- 非 0 → 依錯誤訊息修正 CUJ，重跑直到通過，不要繞過
- 通過後仍須自問金魚測試那一題 —— 腳本驗結構，這一題驗可用性
Step 4：派發金魚並收斂
派發前必讀 references/dispatch-prompts.md 的「❌ 不可包含」清單。 角色分離最常破功的一刻，就是派發的那一刻。
依序執行，不可並行、不可合併角色：
- 4a. 派 Coder — 只給 CUJ 路徑與待改檔案路徑，不給對話紀錄
- 4b. 派 Tester（獨立子代理） — 只給 CUJ 的驗收標準與測試案例， 不給 Coder 的實作說明或產出摘要
- 4c. 測試失敗時 — 把失敗訊息交給新的 Coder 金魚修正，然後回到 4b 重測。 不要讓同一個 Coder 反覆修到過，那等於讓它批改自己的考卷
- 4d. 派 Reviewer（獨立子代理，可選） — 只給程式碼路徑與驗收標準，不給 Tester 的結果
- 4e. Coordinator 彙整 — 更新 CUJ 的
status，向使用者回報實際結果
收斂條件：每一條驗收標準都有對應測試且全數通過。
失敗上限：同一份 CUJ 的 4b ↔ 4c 迴圈跑滿 3 次仍未收斂 → 停止盲修，
回到 Step 2 檢討 CUJ 本身是否有問題（規格矛盾、驗收標準不可測、前置條件缺漏）。
⚠️ Gotchas
不知道就會踩的環境事實：
id必須與檔名前綴一致 ——id: cuj-001要對應cuj-001-*.md，不一致直接判定失敗- 目錄模式只掃
cuj-*.md—— 檔名打錯（如cju-001-x.md）會被列為「略過」而非「失敗」， 看輸出時要留意略過清單 - 區塊內容門檻依語言而異 —— 含中日韓文字 10 字元、純西文 30 字元，逐區塊判斷。
可用
--min-section-chars N覆寫 - 驗證腳本需要 Python 3.12+，即使專案本身不是 Python 專案
跳過不等於通過—— 看摘要行的通過數字，不要只看有沒有印 ✅- 腳本只驗結構，不驗語意 ——
It should work correctly在結構上與具體驗收標準無異， 能通過腳本。腳本是地板，金魚測試檢查點才是天花板
🛑 Anti-Rationalization & Red Flags
適用範圍：以下規則只在走本流程的功能開發時生效，不是全時鐵則。 維運檢查、部署前驗證、緊急 hotfix 依專案既有規則辦理。 導入時若與專案既有規範衝突，用分域解決，不要互相覆蓋。
- ❌ 絕對禁止 Coordinator 親自編寫超過 10 行的改動，或親自執行測試命令。
- ❌ 絕對禁止 把 Coder 的實作脈絡複製給 Tester，Tester 必須在乾淨上下文下依 CUJ 驗收標準獨立測試。
- ❌ 絕對禁止 因為驗證腳本印出 ✅ 就認定通過 —— 請確認摘要行的
通過數。 - ❌ 絕對禁止 為了讓測試通過而修改測試或放寬驗收標準。測試失敗是有價值的資訊。
更多常見藉口與反駁見 references/role-separation.md 的 Anti-Rationalization 表。
🔲 職責邊界
本 Skill 只負責大象金魚機制本身，不涵蓋整個開發生命週期：
| 階段 | 本 Skill | 說明 |
|---|---|---|
| ① 定義需求 | 邊界外 | 人類職責 |
| ② 需求釐清 | 邊界外（定義契約） | 各工具自行搭配，見 cuj-workflow.md 步驟 2 |
| ③ 產生 CUJ | ✅ 核心 | CUJ 範本 + validate_cuj.py |
| ④ 開發 | ✅ 核心 | 四角色分離 + 派發 prompt 範本 |
| ⑤ Post-mortem | 邊界外 | 各工具原生機制（如 Claude Code 的 memory） |
一個 Skill 只做一件事。需求釐清、學習沉澱都有成熟的獨立 skill 可搭配，重造沒有價值。
⚙️ 前置需求
| 項目 | 需求 |
|---|---|
scripts/validate_cuj.py、scripts/install.py | Python 3.12+（零第三方套件） |
| Skill 自我測試 | pytest |
上述為 Skill 本身的執行需求，與使用本 Skill 的專案技術棧無關。