這篇文章記錄 Agent Optimization Factory 的完整迭代過程。3 個不同原型的 mini-agent，各跑 3 個 cycle，最終全部收斂到 12/12 BDD PASS。我把真實的數字、踩到的坑和具體的 pattern 都寫進來——因為對下一輪 Iteration Team 機器人來說，這些細節就是它們的知識庫。
我們剛完成 3 個 mini-agent 的 3 輪迭代優化，宣告三個 spec 進入 production-ready 狀態。這 3 個 mini-agent 是：
Research 原型。核心工作：找歷史案例、查法規，輸出有雙重來源支撐的 structured case summary。代表 Investigator A/B 等調查員角色。
Writing 原型。核心工作：從 research 輸入產出有敘事弧度的 AIA slide 旁白。代表 Writer A/B 等敘事生產角色。
Review 原型。核心工作：對 draft slide 進行 AIA HSW 合規、引用精確度、語氣偏差的多維審查。代表 Compliance Reviewer / Fact Checker / Copy Editor 等稽核角色。
選這三個原型不是隨機的。我們需要證明 factory 不只對一種 agent 有效——而是在 research、writing、review 三個截然不同的工作邏輯上都能收斂。如果只有一種原型成功，那只是運氣；三種都收斂，才是 pattern 的力量。
在小規模的 mini-agent 上投入大量上下文成本，換取在 production 19-agent fleet 上的低上下文成本與高可靠性。這是一筆確定的投資，不是賭注。
直接迭代完整的 19-agent HSW-002/006 fleet，每個 cycle 需要 30–60 分鐘。每次修改一個 Writer 的敘事規則、調整一個 Investigator 的引用格式，都要等 30 分鐘才知道修好了沒。
這不只是時間問題，而是心理問題：當迭代成本高，你就會停止大膽試錯。你開始「這樣差不多了吧」，因為再跑一次太貴。這是 AI Agent 開發最容易掉進去的陷阱。
| 比較維度 | Mini-Agent 迭代 | 19-Agent Fleet 直接迭代 |
|---|---|---|
| 每個 cycle 耗時 | 3–15 分鐘 | 30–60 分鐘 |
| 每個 cycle 的上下文成本 | 低（1 個 agent，1 張 slide） | 高（19 個 agent，完整課程） |
| 試錯意願 | 高——失敗成本低 | 低——「差不多就好」心理 |
| 找到問題的速度 | 快——問題範圍小 | 慢——需要 debug 是哪個 agent |
| pattern 可複用性 | 高——直接搬到所有相同原型 | 低——每次都重新發現 |
這就是軟體工程的 TDD 哲學。先在最小範圍寫一個會失敗的測試，讓它通過，重構讓它更乾淨，再放大到 production。在 Mini-Agent 上花的每一分鐘上下文成本，都在為 19-agent fleet 買可靠性保險。
Mini-Agent × 3 cycle 的總上下文消耗，比在 fleet 上發現同樣問題再修一次還要便宜。而且你得到的是一份可複用的 pattern library，不只是解決了一個 bug。
這個 factory 不是「跑個 LLM 看看輸出好不好」。它在每個 agent 上強制套用 4 個通用品質準則，所有 BDD scenario 都對應到這 4 個維度。
每個 agent 的 OGSM spec 必須通過 4 個 validator 的機器驗證。G 要寫清楚替誰做、S 要說明做什麼路徑與為什麼、M 要能直接量測 S 的承諾。validator 跑不過，就是 FAIL，不靠人眼判斷。
任何 agent 每次都做的機械性動作（字數計算、來源格式確認、內容類型分類），應該抽進 scripts/ 用程式碼執行，而不是用自然語言讓 LLM 重新思考一遍。程式碼比 prompt 便宜、比 prompt 穩定。
agent 的 Tier 1 summary 只放「每次都需要的核心規則」，不嵌入完整 skill 指令。skill 的查詢靠 get_skills_for_role.sh <role> 中央 map 執行，不在每個 agent spec 裡重複維護一份副本。
所有 agent 透過 call_with_fallback.sh wrapper 呼叫 LLM，而不是直接呼叫單一 model CLI。fallback chain 讓 quota 耗盡或 model hang 時自動跳下一個，而不是讓整個 cycle 卡死。
這 4 個原則都有對應的 BDD scenario。如果 agent 做到了，scenario 就 PASS；做不到，就 FAIL，然後 Iterator 提出最小可能的 diff 去修它。
三支 mini-agent 初稿都用了 ## G — Goal / ## S — Strategy / ## M — Measurement 的 level-2 heading。但 Phase A 的 validator suite 是為多 agent OGSM plan 設計的，預期看到 ### <emoji> <Agent Name> 加上 **G（...）** bold sub-label 的格式。
結果：三隊的 validator 在 baseline 全部 FAIL，錯誤訊息一致是 "no '### ' agent headings found"。這是一個結構格式落差，不是行為問題。
| Team | Cycle 1 動作 | Cycle 1 後 validator |
|---|---|---|
| Team 1（Research） | 插入 ### Mini-Research Agent heading + 3 個 document-level section（96 行 additive patch） |
4/4 PASS |
| Team 2（Writer） | 插入單行 ### Mini-Writer Agent heading（最小可能 diff） |
5/5 PASS（Cycle 2 驗證） |
| Team 3（Reviewer） | 走 behavioral path（修 S rule + Anti-patterns），結構 FAIL 意外被 behavioral diff 順帶解決 | 5/5 PASS（Cycle 2 發現） |
這就是 Pattern P-002（Structural Header Injection）的由來。三隊獨立踩到同一個坑，Commander 在 Phase D 把它提升為 universal pattern，下次 factory run 啟動前直接 pre-flight 檢查，不浪費整個 Cycle 1。
Cycle 2 帶入了整個 factory 最重要的架構改動：用 get_skills_for_role.sh <role> 取代 agent spec 內嵌的完整 skill 指令字串。
三隊各自加入了兩個新的 BDD scenario 驗證這個機制：
Team 3 在 Cycle 2 發現了一個實際的 drift bug：central skill map 有 /ai-fallback，但 spec 的 Skill Invocation Map 寫的是 "None"。SCN-R-012 scenario 直接抓到這個 bug，Cycle 2 diff 修復後 Cycle 3 PASS。
Team 2 在 Cycle 2 也做了跨 topic 驗證。Input-B 特意避開 Cycle 1 的 Twin Parks 素材，改用 NFPA 80 spring hinge mechanism，並在 BDD 加入 W-12 scenario 確認輸出裡零出現 "Twin Parks / Bronx / 17 fatalities" 等 Cycle 1 關鍵字。驗證通過，證明 spec 不會把 Cycle 1 的框架 leak 到 Cycle 2 的輸出。
三隊都在 Cycle 3 達到 12/12 BDD PASS，但路徑完全不同：
Spec 從 Cycle 1 就已收斂（byte-identical），Cycle 3 的 +17pp BDD 跳升完全來自 harness 層——學會主動跳過 Gemini 2.5 Flash primary（因為 Cycles 1+2 都 hang），wall-clock 從 720 秒降到 360 秒，零 spec 改動。
Cycle 3 harness 提供刻意殘缺的 upstream fixture（只有 3 個裸 section 編號，零 case，零 URL），強制 writer 觸發 /ai-fallback。結果 fallback_events=2，W-09 從「沒有反證的 PASS」變成「有行為證據的 PASS」。12/12 BDD PASS。
Cycle 3 採用 replay mode：不 rotate 新 input，而是重跑 Cycle 1 + Cycle 2 的 fixture，驗證 Cycle 2 的 behavioral diff 在兩組 fixture 上都成立。44 秒完成，catch rate 從 50% 升到 100%，FP 從 5 降到 0。
三條路徑都有效，這才是真正的 proof：factory 的核心紀律（smallest diff、topic rotation、spec-diff-count plateau）不要求唯一路徑，只要求堅守紀律。
| Team / Agent | Cycle 1 BDD | Cycle 2 BDD | Cycle 3 BDD | Cycle 3 wall-clock | 收斂方式 |
|---|---|---|---|---|---|
| Team 1 Mini-Research | 7/10 (70%) | 10/12 (83%) | 12/12 (100%) | 360s | Harness skip Gemini Flash |
| Team 2 Mini-Writer | 10/10 (100%) | 12/12 (100%) | 12/12 (100%) | 420s | Partial upstream fixture |
| Team 3 Mini-Reviewer | 7/12 (58%) | 8/12 (67%) | 12/12 (100%) | 44s | Replay mode 跨 fixture 驗證 |
特別值得注意的是 Team 3 的 44 秒——三隊裡最快。Review 原型的 agent 因為不需要產出新研究、可以用 replay mode，每個 cycle 的上下文成本比 research/writer 快將近一個量級。這個差距在 scale 到 19-agent fleet 時會很重要。
這些是 factory run 實際碰到的問題。寫進來不是為了抱怨，而是為了下一輪 Iteration Team 不要重新踩一次。
症狀：呼叫 gemini -m gemini-2.5-flash 時，process 停 60–360 秒無 output 無 error，要手動 kill。Team 1 在 Input-A、Input-B、Input-C 三個完全不同的 research 題目上全部重現，確認是 config bug 不是 model flake。
為什麼重要：call_with_fallback.sh 只在 explicit quota error 時 advance，遇到 hang 不會觸發 fallback，所以整個 cycle 就卡死在那裡。
正確修法（INT-001）：在 call_with_fallback.sh 加 per-model timeout（建議 90 秒），timeout 視為 advance 條件進到下一個 model。這個修法一次解決所有 caller 的問題，不需要每個 agent 各自 workaround。這是 scaled factory run 的 blocker，未修不能啟動。
症狀：文件裡完全沒有可解析的 agent section 時，script 返回 exit 0 PASS。因為 0 個 agent → 0 個 gap → 邏輯上「沒有問題」，但這是 latent false positive。
正確修法：加一個 assertion："至少要 parse 到 1 個 agent，否則 exit 2 並明確報錯。"
症狀：Mini-agent spec 用 level-2 heading（## G / ## S / ## M），但 validator 預期 ### <emoji> <Agent> + bold sub-label。三隊 Cycle 1 baseline 全部 FAIL。
預防方式：factory run 啟動前先跑 pre-flight validator，結構 FAIL 列為 Cycle 0 工作，不要讓它浪費 Cycle 1。
症狀：原本預期用 get_skills_for_role.sh pointer 取代 spec 內嵌的 Skill Invocation Map，預期 briefing 字數下降。實際：Team 1 的 briefing char count 從 7,331 升到 8,776（+19.7%），因為 check_skill_architecture.py 仍然要求 document-level section 存在，pointer 只能 append 不能 replace。
正確修法：修 validator 讓它接受 "single pointer line 指向 get_skills_for_role.sh <role>" 作為 full section 的等效。在此之前不要對 pointer 模式抱有縮 spec size 的期待。
症狀：Team 2 Cycles 1+2 的 W-09（fallback wiring scenario）在 happy-path 下 always PASS，因為 upstream 完整、writer 根本沒觸發 fallback，metric 誠實記 fallback_events=0，但這不是行為證據，只是「沒被反證」。
正確修法：harness 在 Cycle 2 或 3 設計刻意殘缺的 upstream fixture，強制 agent 選擇 halt 或 fallback。任何 optional skill 的 BDD scenario 都要問：「這在 happy-path 下會不會 always PASS？如果是，需要設計 stress fixture。」
症狀：Team 1 Cycle 2→3 BDD pass rate 跳 +17pp（83% → 100%），直覺覺得 spec 還在進步，應該繼續 iterate。但 spec 已 byte-identical，改善來自 harness 層。
正確做法：追蹤 spec_diff_proposed_this_cycle: bool，連續兩次 False 直接觸發 plateau check，不看 BDD rate 的增幅。
以上每一個 gotcha 都已記入 gotchas-and-lessons.md，對應到具體的修法與追蹤 ID（G-00N / INT-00N）。下一輪 Iteration Team 可以用腳本直接查詢：
# Query known gotchas for a specific context
bash ~/.claude/skills/ogsm-framework/scripts/get_gotchas_for_context.sh ai-fallback-hang
# Returns G-001 + INT-001 fix details
bash ~/.claude/skills/ogsm-framework/scripts/get_gotchas_for_context.sh validator-false-positive
# Returns G-002 + G-003 + G-004Factory pattern 已經 proven。3/3 teams，3/3 different archetypes，全部收斂。接下來是把同樣的 factory 套到真正的 HSW-002/006 19-agent production fleet 上。
Factory 不需要「一條對的路徑」——只需要堅守 smallest diff、topic rotation、spec-diff-count plateau 三個紀律。三條完全不同的收斂路徑（harness-driven / fixture-driven / spec-driven）都到達同樣的終點：12/12 BDD PASS。
| 批次 | Agent 類型 | 數量 | 預估 wall-clock | 主要風險 |
|---|---|---|---|---|
| Batch 1 | Research + Writing core（Investigator A/B, Writer A/B） | 4 | ~90 分鐘（4 平行） | G-001 Gemini Flash hang |
| Batch 2 | Internal Review（Content Director, Compliance Reviewer, Copy Editor, Fact Checker, Source Reviewer） | 5 | ~15 分鐘（replay mode 可用） | G-005 vacuous PASS on escalation |
| Batch 3 | External Reviewers（3 個外審角色） | 3 | ~40 分鐘（3 平行） | Persona fidelity + G-001 |
| Batch 4 | Orchestration + QA + misc（Commander, Performance Supervisor, Quality Auditor, HTML Engineer 等 7 個） | 7 | ~220 分鐘（2 輪 4 平行） | Meta-level BDD 設計難度高 |
Total wall-clock 估算：約 6.5 小時，分 2 天跑比較安全。Day 1 跑 Batch 1+2，Day 2 跑 Batch 3+4 + meta integration。
Blocker 1（INT-001）：修 call_with_fallback.sh 加 per-model timeout。未修，所有 research 類 agent cycle 每次都會在 Gemini Flash hang 上浪費 6+ 分鐘，19 個 agent × 3 cycles = 57 次機會踩到。
Blocker 2（G-002）：修 validate_s_to_m_coverage.py 的 silent PASS bug。未修，結構性錯誤的 agent 會被 silent pass 蓋過去，scaled run 更難 debug。
兩個 blocker 都修好、5 份 reference 檔案複製到 ogsm-framework skill 的 references 目錄之後，才啟動 factory。
這個問題值得在最後誠實回答，因為投入是真實的：3 個 mini-agent × 3 cycles × 每個 cycle 的上下文成本，加上設計 validator suite、寫 BDD scenario、整理 patterns-library 的時間。
答案分三層：
一旦 12 個 agent 通過 factory，它們就以更低的上下文成本、更高的可靠性永久運行，直到下次需要迭代為止。factory 的成本是一次性的；production 的收益是持續的。
這是這篇文章最重要的一節，也是這個 factory 設計裡最認真對待的問題：如何確保下一輪 Iteration Team 不用重新發現已知的 pattern？
答案不是「信任機器人會記得」——它不會。答案是建立一個可查詢、有腳本的知識系統。
這 5 個文件在 docs/iteration-team/ 裡，同時也複製到 ~/.claude/skills/ogsm-framework/references/（在 ogsm-framework skill 更新後）：
| 文件 | 用途 | 主要受眾 |
|---|---|---|
unified-strategy.md |
14 個 pattern 的 3/3 / 2/3 / 1/3 分類與信心標註 | Commander、Iterator |
patterns-library.md |
每個 pattern 的詳細描述、evidence、scaling recommendation | Iterator（主要查詢對象） |
gotchas-and-lessons.md |
10 個已知坑 + 6 個驚喜觀察 + 具體修法 | 所有 Iteration Team 成員 |
scaling-playbook.md |
從 3 mini-agent 放大到 19-agent fleet 的操作手冊 | Commander |
ogsm-framework-updates.md |
對 ogsm-framework skill 的具體更新提案 | 開發者（人類） |
文件可以被讀，但機器人在高壓力的 iteration cycle 裡不一定會想起來去讀。所以 Commander 的 direction seed template 會把查詢指令嵌入到每個 subprocess agent 的 briefing 裡：
# Embedded in every Iterator robot's briefing:
# Step 0: Before proposing any diff, query the patterns library.
bash ~/.claude/skills/ogsm-framework/scripts/get_patterns_for_failure.sh <failure-type>
# Returns the relevant pattern entry from patterns-library.md
# Example:
bash ~/.claude/skills/ogsm-framework/scripts/get_patterns_for_failure.sh structural-validator-fail
# → Returns P-002: Structural Header Injection — what it is, evidence, and how to apply
bash ~/.claude/skills/ogsm-framework/scripts/get_patterns_for_failure.sh fallback-vacuous-pass
# → Returns P-004: Forced Fallback via Partial Upstream Fixture
bash ~/.claude/skills/ogsm-framework/scripts/get_patterns_for_failure.sh ai-fallback-hang
# → Returns P-011 + G-001 + INT-001 fix這個設計的重點是：機器人不需要記得這些 pattern——它需要的是一個在 FAIL 發生時自然引導它去查的指令。查詢腳本就是這個引導機制。
同理，Spec Verifier robot 的 briefing 裡也會嵌入：
# Step 0: Before writing BDD scenarios, check known gotchas for this agent archetype.
bash ~/.claude/skills/ogsm-framework/scripts/get_gotchas_for_context.sh <archetype>
# Example for research agent:
bash ~/.claude/skills/ogsm-framework/scripts/get_gotchas_for_context.sh research-archetype
# → Returns G-001 (Gemini hang), G-002 (silent PASS), G-005 (vacuous pass),
# G-006 (budget squeeze), with specific prevention advice for eachCommander 每次 dispatch subprocess agent 時，都先設定「方向種子」：目標、限制、參考資源、要執行的查詢指令。這個 seed 確保每個 subprocess 都帶著正確的上下文開始工作，而不是從零開始猜意圖。
方向種子的模板包含：
這是一個可查詢、有腳本、由 Commander direction seed 強制執行的知識傳遞系統。14 個 pattern 的 evidence、10 個 gotcha 的修法、19-agent 的 batch 排序，都在啟動 Cycle 1 之前就能被下一輪 Iteration Team 的機器人查到。
這個 factory 完成了什麼：
接下來：修 INT-001（Gemini Flash hang），修 G-002（silent PASS），把 5 份 reference 部署到 skill，然後啟動 19-agent scaled factory run。
相關背景：