小丁的家

標籤: AI 輔助開發

  • 拔掉 RLS 的兩天：AI 時代規模化 Day One 為何從奢侈變預設

    重點摘要

    • 灌 540 萬包裹壓測，警衛的社區包裹列表要 7330 毫秒。病根是 RLS 兩條 PERMISSIVE policy 用 OR 合併，讓查詢規劃器用不到 community_id 索引。
    • 全面拔除 173 條 policy、85 張表的 RLS，租戶隔離 100% 改由應用層帶 community_id。同一條查詢從 7330ms 降到 1.34ms，約 5500 倍。
    • 但拔掉 RLS 不是終點——第二波跨社區洩漏被「單租戶壓測」蓋住了：對照社區在多數表是 0 筆，洩漏判準（本社區數＝全平台數）自動成立。要每張表都灌 ≥2 個社區才測得出；而且漏帶 community_id 不只洩漏，更是少了索引，同一個病根換地方又長。
    • AI 把規模準備的「建造成本」打掉了，但有兩個成本它打不掉：分區帶來的「複雜度稅」（維護照繳），與「取決於規模實測才知道對錯」的經驗決策（RLS 自己就是反例）。
    • 結論：AI 時代「規模化 Day One」從奢侈變預設，但「準備什麼」的判斷力更值錢——有把握的提前上，取決於壓測的，老實留給壓測。

    一個 V2 產品、兩天、一個 AI 協作者，把一套多租戶系統從「靠資料庫兜底」推進到「應用層自己負責」。這篇記錄的不是 commit log，是技術選型的隱性成本，怎麼在特定規模與特定哲學下才現形——以及 AI 怎麼悄悄改寫了「該不該提前準備規模化」這道老題目。

    先講結論：MVP 智慧是成本算出來的啟發法，不是定律

    傳統智慧說：MVP 先做，別過度工程，規模化以後再說。這句話我一直信，直到這兩天我意識到——它是一條成本驅動的啟發法，不是定律。

    它成立的前提是「規模準備很貴」。以前要做分區、多租戶隔離、idempotency、離線佇列這整套規模機械，往往要多三到四倍的人力、好幾個月。那個成本，才讓「先別做、等需要再說」變成理性選擇。但兩件事同時改變了這個算式：

    1. AI 把建造成本打掉了。那套規模機械，AI 輔助下生成 + 維護的人力崩塌。
    2. 這是 V2，不是 try。前一版已經證明了領域——住戶、警衛、包裹是真需求，而且會有很多社區。規模不是猜測，是 near-certainty。「You Ain’t Gonna Need It」的前提「你可能不需要」，直接是假的。

    所以對一個 AI 輔助、領域已驗證的 V2，Day One 就準備規模化，比經典 MVP 智慧主張的更該做。但這篇真正有料的地方，是兩個 AI 也打不掉的成本。後面講。

    當初為什麼這樣選技術？

    這套系統的技術選型，是三股力量的合力：領域驅動 + 規模前瞻 + 不重蹈前版覆轍。

    • Flutter 單一 codebase：住戶用手機、警衛用平板，功能大半重疊靠角色 gate。兩份原生 = 兩倍維護；一份 + responsive 是省力的對。加上離線優先是硬需求（警衛平板斷網也要能收件、拍照、印通知條）。代價老實說：CanvasKit 的 web 端很痛，e2e 自動化一路在跟它的無障礙語意樹搏鬥。
    • Go + GraphQL（型別契約）：Go 單一 binary 好部署、並發強，對著「1000+ RPM / 1000 社區」的目標。GraphQL 用型別嚴謹的契約——這是對前版的反動：舊版用 category/method 字串路由 + PHP 的型別強制轉換怪招，踩過坑。型別世界 = runtime 少驚喜。
    • PostgreSQL + RLS（Row-Level Security）：這個最值得講，因為我們親手拆了它。

    RLS 的故事：為安全而選，為清亮而拆

    RLS 當初為什麼選？防禦縱深。理由聽起來無懈可擊：「把租戶隔離放在資料庫層，app 出 bug 也繞不過。」每個社區的資料用 policy 鎖死，誰都別想跨社區看到別人的包裹。

    然後規模化壓測來了。我們灌了 540 萬包裹、5.4 萬戶、202 個社區，模擬一個 V2 跑兩三年後的樣子。一量——警衛的社區包裹列表，7330 毫秒。七秒。

    病根不是索引沒建，是 RLS 的兩條 PERMISSIVE policy 用 OR 合併：(是系統管理員) OR (社區=X)。community_id 只出現在 OR 的一邊，查詢規劃器就用不到 community_id 索引，只能 Seq Scan 掃完整張表的所有分區。這個病，設計時看不出來，要到 5.4M 才現形。

    業主的反應很關鍵。他不要「在 DB 加更多限制」來繞，他要的是更乾淨：「我不要我的資料庫跟我的 AP 有這樣的依賴。本來就該做到零洩漏，怎麼會依賴 RLS？」

    於是我們全面拔除 RLS——173 條 policy、85 張表，全部 DROP。租戶隔離 100% 改由應用層：每一條碰租戶資料的查詢，自己帶上 community_id = current_setting('app.community_id')。

    拆的過程，反過來證明「本來就該零洩漏」當時是假的

    審計時我抓到，授權中介層對「同社區範圍」的操作寫死了一行註解：「RLS 負責租戶隔離，這裡不另外檢查。」也就是說，有好幾個改別人資料的後端進入點（停用警衛、在別社區建戶、復活別社區的軟刪戶），它們的隔離正確性，本來就完全押在 RLS 上。RLS 一拔，這些就是跨社區提權漏洞。

    派去掃的 AI 子代理一開始判了 23 個缺口；我逐條人工驗證，收斂到 3 個真缺口——其餘有的早被別的守衛擋著、有的是子代理幻覺出根本不存在的函式。這也是個教訓：AI 的清單要逐條驗，不能盲信。

    拆完，效能呢？同一條查詢，帶上 community_id：

    查詢 RLS 開（OR 合併擋索引） RLS 拔除 + 應用層 community_id
    警衛社區包裹列表（5.4M 列） 7330 ms（Seq Scan 全分區） 1.34 ms（Index Scan）
    包裹改動歷程鑽取 — 0.2 ms

    從 7330ms 到 1.34ms，約 5500 倍。反諷的地方：當初選 RLS 是「為了安全」。它不但變成效能地雷，還讓 app 層偷懶——「反正 DB 會兜底」，於是 app 層的隔離就不嚴謹了。兜底機制養出了被兜底者的鬆懈。

    拔完 RLS 之後：洩漏沒結束，是換了個地方躲

    拔掉那天修了 3 個提權，我以為收工了。錯。RLS 一拔，等於把「DB 兜底」這層拿掉，所有原本偷懶的查詢全部裸奔——真正的第二波，要再跑一輪壓測才現形。

    一個包裹計數查詢，給某社區警衛回了 280 萬——那是整個平台的數字，不是他那個社區的。病根：這個 count 自己手寫 WHERE，繞過了會自動補 community_id 的中央 helper。同一類的還有一票：社區統計（*Stats）、各種計數（*Count）、住戶/包裹 picker、以及「先 load-by-id 再改」的 mutation——全是各自為政手寫查詢、漏帶租戶欄位的高風險地帶。

    但這篇最該記住的，是為什麼第一次壓測沒抓到。答案很反直覺：單租戶結構上測不出跨租戶洩漏。

    我第一次灌的 540 萬，只灌在 parcels 和 households 兩張表，其他維度（使用者、訪客、公告、picklist）對照社區根本 0 筆。而洩漏的判準是「本社區查到的數字 == 全平台的數字」——當對照組是 0，這條恆等式自動成立，洩漏被 0 資料蓋得死死的。修法不只是補 WHERE，是補資料形狀：每一張要驗的表，都灌進 ≥2 個社區的資料，動態探針才有對照組去抓「你回給我的，有沒有混進別人的」。

    還有一層，業主一句話點破：漏帶 community_id 不只是洩漏，是效能。「為什麼還有功能沒戴上 ID，這不只會洩漏，重點是效能會變差，沒用到 index。」少了那個欄位，查詢就跟當初 RLS 的 OR 一樣用不到索引、掃全表。防洩漏和上索引，是同一個動作——community_id 既是隔離邊界，也是索引前綴。當初那個「OR 擋索引」的病根，拔了 RLS 之後，在每一條手寫查詢裡換個地方又長了出來。

    規模下另外兩個 Day One 就得拍的板

    同一輪還拍了兩個一旦上線就很難回頭的板，都是「規模 + 時間」逼出來的。

    • 快照 vs 正規化：歷史標籤不准 join。包裹上的物流公司、儲位、包裹類型、收件人姓名，全部存成當下的文字快照，不是外鍵。為什麼不正規化？因為這些是歷史事實。若做成外鍵去 join 現行字典，哪天某家物流公司改名或下架，過去的包裹紀錄會被回頭改寫——未來的公司出現在過去的資料上。原則一句話：身分用外鍵，歷史標籤用快照。這跟「證據鏈不可竄改」是同一個底層要求。
    • 控制面狀態用單例快取，不是每頁查 DB。社區可被系統管理員停用，每個請求都得確認「這社區還活著嗎」。最笨的做法是每頁打一次 DB——那又是另一種 RLS 式的過度防禦。做法是一個程序級單例快取（map + 鎖），10 分鐘 TTL，miss 才查 DB，停用/復活時主動逐出；隔離檢查收斂在一個 chokepoint（進交易時查一次），不撒在每條查詢。順手修了個誠實問題：社區停用後登入原本回「帳密錯誤」會誤導用戶，改成帳密對的人才告知「社區暫停服務中」——既不誤導本人，也不洩漏社區存在給攻擊者。

    兩個 AI 也打不掉的成本

    回到開頭的 thesis。AI 讓規模準備「便宜到值得 Day One 就做」——但有兩個成本它打不掉。

    成本 AI 打掉了什麼 AI 打不掉什麼
    複雜度稅 建造成本（生成分區/隔離/佇列） 維護稅：每次改動/debug 都要付。例：pg_total_relation_size 對分區母表回 0，最大的表都報 0，要展開分區層才量得到
    經驗決策 實作速度 壓測經驗：RLS 的「OR 擋索引」要 5.4M 才看得見，連 AI 都沒辦法 Day One 告訴你對的選擇

    成本一：AI 打掉「建造成本」，沒打掉「複雜度稅」。月分區讓程式更難推理。這兩天我們親自繳了這個稅：監測資料量時，pg_total_relation_size 對分區母表只算母表本身（回 0）；還有 FK 要複合鍵、分區不繼承 RLS、清測試資料時被自己剛上的 append-only trigger 擋住……這個複雜度，是每一次未來改動、每一次 debug 都要付的稅，連 AI 也付。「AI 讓規模準備好建」是真的，「規模準備免費」是假的——稅照繳，只是從建造繳給了維護。

    成本二：有些規模決策是「經驗的」，Day One 就是準備不了——RLS 自己就是鐵證。RLS 本來就是 Day One 的規模準備（多租戶隔離），結果它是錯的 Day One 選擇。為什麼當初設計看不出來？因為「OR 擋索引」這個病要 5.4M 壓測才看得見。有些決策，正確答案取決於規模行為，而那行為你預測不了——那是壓出來的，不是設計出來的。而且如前面那一節的教訓：光有規模還不夠，要對的「資料形狀」——對照社區是 0 筆的那次壓測，把第二波洩漏整個蓋住了。經驗決策不只需要壓力，需要對的壓力。

    AI 時代，「規模化 Day One」從奢侈變預設。但「準備什麼」的判斷力反而更值錢：有把握的結構提前上（便宜了）；取決於規模實測的決策，老實留給壓測。

    有把握的（會有很多社區 → 按社區/時間分區；離線不可妥協 → 佇列），提前做。沒把握的（隔離機制、索引策略），別假裝設計階段就能拍板。這跟我之前寫過的 企業 AI 落地為什麼失敗 是同一個底層觀念：方法論不能照抄，要看你的前提條件還成不成立。

    方法：規格化、決策留證、以及「我自己打臉自己」的報告

    這兩天還做了第二件大事——把包裹做成可被法庭級檢驗的證據鏈。改動寫進不可竄改的 log（鑽一顆包裹的歷程，5.4M 下 0.2 毫秒）、簽名與照片在儲存層鎖死不可刪、系統管理員調查要「破窗」且每次都留審計。但比功能更值得分享的是方法：

    • 規格先行。每個設計決定都先寫進規格、辯論清楚、鎖進文件，才動手。對話會被壓縮遺忘，規格不會。
    • 決策留證，不靠主觀評分。業主不信任 AI 加工過的「成本/風險」評分，他要看真實檔案、真實行數、schema 影響。所以需要他拍板的時刻，我生的是事實卡片，不是紅黃綠燈。
    • 三份報告的誠實檢驗。最後他要一份評分報告。但他要的不是一個數字——他要三份做比較：原始版、我「現在的預估」（鎖時間戳，不准事後改）、和「全部做完 + 全面測試後的真實量測」。核心是拿我的主觀預估去對真實量到的，差多少 = 我的評估可信度。

    結果：我預估綜合 7.5，真實約 7.8，誤差約 0.3 分；方向性預測（「dev 環境的測試污染會讓部分整合測試紅、但那不是回歸」「forensic 能力做完會升」「效能會守住」）全中。唯一校準：我對「系統穩定度」過度保守——實際零回歸。這種「逼 AI 先承諾預測、再用真實數據打臉」的設計，把「AI 的話可不可信」變成一個可量測的問題。

    人機協作：最好的部分不是分工，是辯論

    這兩天的分工大概是：業主出領域知識與方向決策，AI 出執行、驗證與反思。但最好的部分不是分工，是辯論。RLS 該不該拆、拆了 sysadmin 怎麼查日誌、照片資料夾要不要鏡射分區、孤兒清理會不會變成刪證據的後門——這些不是「下指令、執行」，是來回推。

    業主用領域常識把我拉回現實（「哪有警衛不分社區的，警衛 A 在四個社區工作就是四個警衛」），我用壓測數據和審計把假設證偽（「你說本來就零洩漏，但我們現有 code 就漏了 3 個」）。AI 不會累、能掃完每個呼叫點、能把 23 個候選逐條驗到剩 3 個真的；但判斷「準備什麼」「什麼時候該停下來問人」，還是要人。

    結語

    如果只能留一句：老的 RD 有老的包袱，所以才有「MVP、先別管規模」的智慧。但那個智慧是成本算出來的。當 AI 把建造成本打掉、當你做的是領域已驗證的 V2——規模化就是 Day One 的事。只是別忘了，AI 打不掉複雜度稅，也替不了你壓測；有把握的提前上，沒把握的，老實壓出來——而且要用對的資料形狀去壓，單租戶測不出跨租戶的洩漏。

    RLS 是我們「Day One 準備了錯的東西、規模化才發現」的活標本。它沒有讓這個決定變壞——它讓這個決定有了教材。

    技術細節：Flutter + Go(gqlgen) + PostgreSQL 16；月分區、River 佇列、MinIO。壓測 540 萬包裹 / 202 社區 / RLS-off：熱查詢 1.34ms、改動 log 鑽歷程 0.2ms。

  • 讓 AI 不再失憶:用 Claude Code Hooks 打造大腦反饋迴路

    重點摘要

    • LLM 最大的弱點是會忘:session 結束或 context 被壓縮後,這次學到的教訓就蒸發了。
    • 解法是把「教訓」外接到持久的 腦子系統(brain/*.md),並用 hooks 在關鍵時刻強迫寫入。
    • 5 支 hook 腳本在三個點攔截:fix commit 發生時、context 壓縮前、session 結束時。
    • 另一支 hook 負責身份錨定,防止 /compact 後 AI 角色崩潰。

    大型語言模型最致命的弱點,不是不夠聰明,而是會失憶。每一次對話結束,或是上下文(context)被壓縮(compaction)以節省 token,這一輪辛苦學到的教訓——某個 bug 的根因、某個 API 的雷點——就跟著蒸發,下一次又從零開始,甚至重踩同一個坑。

    我在 Claude Code 上的解法,是一套「harness × 腦子系統」的反饋迴路:用幾支 Bash hook 腳本當感測器,在 AI 即將遺忘的關鍵點上攔截,強迫它把這次的教訓寫進持久的 brain 檔。這篇拆解它為什麼需要、每支腳本做了什麼、以及它怎麼跟腦子系統搭配。

    為什麼需要這套東西?LLM 的三個結構性缺陷

    這套設計不是為了炫技,而是針對 LLM 的三個無法靠「更大模型」解決的缺陷:

    • 沒有長期記憶:模型權重是凍結的,單次對話的學習不會留存。→ 需要一個外部、持久的記憶體(brain 檔)。
    • 記憶會被壓縮清除:對話一長,context 就會被 compaction 截斷,早期內容直接消失。→ 需要在壓縮之前把該留的留下來。
    • 會角色漂移(role drift):尤其在壓縮後,AI 可能忘記自己是誰、該做什麼。→ 需要定期重新錨定身份。

    關鍵洞察是:光靠「提醒 AI 要記得寫筆記」沒用,因為它會說「好的我等下寫」然後就忘了。必須把它做成系統層級的強制關卡(gate)——由 harness 在固定時機自動觸發,而不是仰賴 AI 的自律。

    一張圖看懂:harness 感測器迴路

    🤖 Claude Code Session(工作中)
    做事 → git commit -m "fix: ..." ↓
    ⚡ HARNESS 感測器層(hooks 自動觸發)
    ① 發生時 · PostToolUse
    fix-detect.sh
    偵測到 fix: commit → 注入:
    「現在去更新 brain,不准做下一件事」
    ② 遺忘前 · PreCompact
    precompact.sh
    壓縮前掃最近 5 個 commit →
    「記憶要被清除了,brain 寫了嗎?」
    ③ 離開時 · Stop
    stop-check.sh
    比對 fix commit vs brain 修改時間 →
    有 fix 卻 0 更新 = 警告
    ↓ 強制寫入教訓
    🧠 腦子系統 · brain/*.md(37 個領域檔,持久)
    – [source: 專案名] 哪裡踩坑、怎麼修的
    ↺ 下次 SessionStart 載入 MEMORY.md 索引 → 知識回到 AI,不再從零開始

    三個攔截點:守住 fix commit 的整個生命週期

    這套機制最聰明的地方,是它不靠單一檢查點,而是沿著「一個教訓從產生到消失」的時間軸,設了三道關卡。每一道都是一支獨立的 Bash 腳本,讀 Claude Code 透過 stdin 餵進來的 JSON,再輸出一段 additionalContext 回去改變 AI 的下一步行為。

    時機(Hook) 腳本 做什麼
    PostToolUse(每次 Bash 後)fix-detect.sh解析 git commit 訊息,若是 fix: 開頭,注入硬性要求:讀對應 brain 檔、追加教訓、更新前不准進行下一個任務
    PreCompact(壓縮前)precompact.sh掃描最近 5 個 commit 找 fix:,在 context 被清除前做最後提醒:「該寫的寫了嗎?現在不寫就來不及了」
    Stop(session 結束)stop-check.sh統計今天的 fix: commit 數,對比 brain 檔有沒有被更新過;有修 bug 卻沒留筆記,就丟出「知識可能流失」的警告

    三個點分別對應人(或 AI)會偷懶的三個藉口:「等下再寫」(被①擋下)、「我忘了還沒寫」(被②救回)、「這次算了吧」(被③抓出來)。

    一個巧妙的無狀態設計:時間戳 + mtime 比對

    怎麼知道「這個 session 到底有沒有動過 brain」?這裡用了一個很輕量、不需要資料庫的技巧,由兩支腳本配合:

    • SessionStart 時,session-start.sh 只做一件事:touch /tmp/.claude-session-start,在檔案系統上插一根時間戳基準線。
    • Stop 時,stop-check.sh 用 find BRAIN_DIR -newer /tmp/.claude-session-start 數出「比這根基準線更新的 brain 檔」有幾個。

    0 個,代表這次 session 完全沒碰 brain。用檔案的 mtime 當狀態,既不用記資料庫、也跨工具通用——這是 Unix 哲學的漂亮應用。

    另一種 hook 用途:身份錨定,防止角色崩潰

    hook 不只用來餵記憶,也能用來穩住 AI 的身份。我跑過一個多 agent 的評測 harness,其中一個 session 擔任「Driver(駕駛)」——負責呼叫 orchestrator、讀結果、寫總結;另一批 agent 才是「被測團隊」。問題是:一次 /compact 之後,Driver 角色崩潰了,退化成被測團隊,開始自己回答原本該交給被測 agent 的技術題。

    修法是一支 SessionStart hook:當工作目錄落在該專案內,就注入一段「身份錨定」context,白紙黑字提醒——你是 Driver、不是被測團隊、遇到這些題目只能呼叫 orchestrator 而不是自己答。每次啟動(含 compact 後的重啟)都重貼一次,把漂移的角色拉回來。這是「context injection 對抗 LLM drift」的典型手法。

    它跟腦子系統的搭配:三層分工

    把整套東西攤開,其實是三層各司其職,像生物的神經系統:

    層 對應 角色
    Hooks神經反射自動、不經思考,在固定時機觸發,負責「執行紀律」
    Brain 檔長期記憶持久儲存踩過的坑與教訓,跨 session、跨專案可讀
    CLAUDE.md價值觀 / 規則每次 session 載入,定義「該怎麼做事」的原則

    Hooks 的唯一使命,就是確保「經驗 → 長期記憶」這條路徑不會因為 AI 的健忘或偷懶而斷掉。Brain 負責存、CLAUDE.md 負責規範,而 Hooks 負責在對的時間點逼著迴路閉合。三者缺一,知識就會慢慢漏光。

    設計哲學:為什麼是「強制關卡」而不是「溫柔提醒」?

    因為知識的衰減是無聲的。沒人會在當下感覺到「我剛剛流失了一條教訓」,只會在三個月後重踩同一個坑時才後悔。溫柔的提醒對抗不了這種無聲衰減——它需要的是一個會在你想跳過時擋在路中間的系統。借別人(與過去的自己)之手學坑,而不是真的每個坑都親自踩一次,這才是把 AI 從「強力的金魚」變成「會累積的夥伴」的關鍵。

    (這套 domain brain 的概念我有開源一份骨架,有興趣可以參考延伸。)

  • 跟 AI 寫程式的 15 條軟工紀律 — 用一條真實對話從頭拆解

    重點摘要

    • 常聽到「跟 AI 寫程式需要軟工基礎」,但具體是哪些?本文用前一篇 Opus 4.8 Workflow 實測那條真實對話從頭拆,對照 15 條經典軟工紀律。
    • 盤點結果:做到 9 條 / 部分做到 1 條 / 沒做 5 條。每條都有對話證據引用,沒做的給可執行 action。
    • 15 條按高 leverage 排序前 5 名:驗證紀律、正交分解、真實基準、focused review、文檔作為下個 session 輸入。這 5 條沒守,其他都白搭。
    • 結論:跟 AI 寫程式需要的不是「新的軟工」,而是把舊軟工套到 stateless / non-deterministic / 訓練截止 / 高並發 4 個 AI 特性上的對應方法。

    為什麼問這題

    「跟 AI 寫程式需要軟工基礎」這句話傳得很廣,但講細節的人少。多數人講出來的不是軟工,是 prompt engineering tricks(怎麼下 prompt、怎麼用 chain-of-thought)— 那叫 LLM 使用技巧,不叫軟工。

    真正的軟工基礎是從 1970 年代 SWEBOK 累積到今天的工程紀律:specification、verification、separation of concerns、observability 那些。問題是這些紀律最初是針對「人寫 code、人 review、人交接」設計的,套到「AI 寫 code、人 review」會不會失效?哪些反而更重要?

    本文不假設,用一條真實對話實證:5/29 我跟 Claude Opus 4.8 跑 Home123 backend 的 109 個 GraphQL resolver authz pattern audit 對照實驗,從頭到尾大約 8 輪對話、~50 分鐘。把這條對話拆解,對照 15 條經典軟工紀律,看真實場景下到底用到了哪些、漏了哪些。

    15 條紀律的分類框架

    從經典軟工教材(《Code Complete》、《Pragmatic Programmer》、SWEBOK Guide)抽出 15 條跟 AI 協作最相關的紀律,分 4 群:

    類別 條目 經典 reference
    核心驗證#1 驗證紀律、#13 根因分析、#7 回顧TDD / Postmortem culture / Code Complete §22
    設計分解#2 正交分解、#8 規格先於實作、#9 權衡分析、#14 錯誤處理哲學Dijkstra SoC / Spec-first / Pragmatic Programmer Ch.4
    過程紀律#3 真實基準、#5 focused review、#6 並行執行、#10 預設驗收標準、#12 預算控管Performance Engineering / Code Review SOP / Agile
    知識持久化#4 文檔作為輸入、#11 可重跑、#15 版本控制ADR / Reproducible Research / Git workflow

    下面逐條拆。每條格式統一:定義 → 經典出處 → 你做了沒 → 證據或補救 → 對 AI 協作的特別意義。

    #1 驗證紀律 (Verification Discipline)

    定義:任何宣稱(claim)都要靠可重現的證據才能信。
    經典出處:Steve McConnell《Code Complete》§22 The Twelve-Step Programming Process、TDD 的 Red-Green-Refactor 第一步、Cynefin framework 的 probe-sense-respond。

    本次對話做了沒:✅ 做了,多次。

    對話證據:

    「幫我讀書 https://www.anthropic.com/news/claude-opus-4-8」
    → 不接受 AI 憑記憶,要 AI 去 web 抓。

    「今天已經是5/29了 你的日期有問題」
    → 即時校正環境假設,不讓我繼續用錯日期。

    「我正在運作 你看一下」
    → 不接受我講的文字總結,要看 ps / pstree / jsonl 真實 OS 訊號。

    對 AI 協作的特別意義:AI 的訓練資料有 cutoff(我的是 2026 年 1 月)。你問跟 cutoff 之後的事(Opus 4.8 是 5/28 發佈),我用「記憶」回答就是瞎掰 — 而且會用流暢的口氣瞎掰,不像人類會猶豫。強制 AI 查資料這個動作,等於把 AI 從「自信的 LLM」拉回「會用工具的執行者」。這條 baseline 沒守,後面 14 條全變空談,因為起手第一個 claim 就錯了。

    #2 正交分解 (Separation of Concerns)

    定義:一個議題只談一個軸線,軸線之間不混。
    經典出處:Dijkstra 1974《On the role of scientific thought》、Parnas 1972 information hiding、UNIX philosophy 的 “do one thing well”。

    本次對話做了沒:✅ 做了,而且是教科書級。

    對話證據:

    「首先 看起來除了MODEL 還有 EFFORT
    同樣是SONNET 還可以有HIGH XHIGH?
    WORKFLOW 我要怎麼去用?」

    三個正交軸線(Model / Effort / Workflow)分開問。對照組是新手會問「給我最好的設定」— 等於要 AI 替你在多維空間做加總決策,你拿到答案也不知道為什麼。

    對 AI 協作的特別意義:AI 處理 bundled question 會發生兩種失敗:(1) 只回最顯眼那條,其他偷偷漏掉;(2) 強行給一個整合答案,但每個軸線都妥協。你下意識把 3 軸拆開,等於逼 AI 逐個 expose,你才能照自己的 context 做選擇。這對應的軟工原則是「不讓抽象漏掉」(don’t leak the abstraction)的反向應用:你拒絕 AI 把抽象漏掉。

    #3 真實基準 (Representative Benchmarks)

    定義:評估新工具用真實場景,不用 toy example。
    經典出處:John Hennessy / David Patterson《Computer Architecture》§1.8 Fallacies and Pitfalls(benchmark 永遠騙人)、SPEC CPU 為什麼要 update、ML 領域 distribution shift 一整條研究線。

    本次對話做了沒:✅ 做了,而且是本次對話最關鍵的一個動作。

    對話證據:

    「好 你現在用HOME123 專案 做一個測試循環 然後用你的WORKFLOW試試看 記錄下來差異」

    不要 toy 不要 hello-world,直接拿 Home123 的 109 個 production resolver。這個動作直接決定了實驗結論的可信度。

    對 AI 協作的特別意義:80% 的「新 AI 工具評測」文章用合成 case(leetcode-style problems),結論毫無遷移性。Anthropic 自家 4.8 release notes 用的也是 SWE-bench、Terminal-Bench 這種「合成的真實」 — 不是任何一家公司的 production codebase。你直接拿 109 個 real resolver 來測,workflow 暴露出來的問題(主 orchestrator 抓到 synthesis agent 算錯 83 vs 109)在合成 case 上看不到,因為合成 case 沒那麼大、catch 不到 emergent behavior。這個動作的工程價值比你的 prompt 內容更高。

    #4 文檔作為下個 Session 輸入 (Documentation as Next-Session Input)

    定義:寫文件不是給未來的人看,是給未來的 stateless agent 看,作為下次 conversation 的可讀輸入。
    經典出處:Architecture Decision Records (ADR, Michael Nygard 2011)、SREbook 的 runbook 文化、Reproducible Research 運動(Donald Knuth literate programming 的延伸)。

    本次對話做了沒:✅ 做了,而且是主動做。

    對話證據:

    「Ab然後我想請你發一篇文章到wordpress上詳細比對這一次的經驗跟數據還有該怎麼啟用的prompt」

    同時要求三份產出:(A) brain/dynamic-workflows.md(下個 conversation 我會自動讀)、(B) 更新 brain/adaptive-agent-team-staffing.md(舊文件補新知識)、(WordPress 文章 —對人類讀者跟搜尋引擎)。

    對 AI 協作的特別意義:你跟人類同事的會議結論寫成 wiki/Notion,下次他翻過。跟 AI 寫 code 的對話結論寫成 brain file,下次 conversation 的 AI 把它當 first-class context 讀 — 等於把這次 conversation 的腦容量無損傳給下次。一般軟工人甚至沒聽過這個用法(「文件是給 AI 讀的?」),但它是 LLM 時代的 ADR + retrospective 文化合體。沒這層,你每次跟新 conversation 都得從零教一遍,等於每次都 onboarding。

    #5 Focused Review (一次只 review 一條軸線)

    定義:給 code review 的 feedback 一次只挑一條軸線改,不混雜其他要求。
    經典出處:Google Engineering Practices《Code Review Developer Guide》、《The Art of Readable Code》Ch.15、Andy Hunt《Pragmatic Thinking and Learning》Ch.9。

    本次對話做了沒:✅ 做了,而且 6 個字精準命中。

    對話證據:

    「注意好讀性跟比較方式」

    6 個字,2 條軸線,沒夾雜其他要求(沒同時挑錯字、補內容、改標題)。我回去重做的時候不需要 disambiguate「我到底該優先處理哪一條」。新手 reviewer 會給 30 條 mixed feedback,作者改完反而亂七八糟。

    對 AI 協作的特別意義:AI 在 mixed feedback 下會做兩件事:(1) 試圖一次解決所有,結果每條都打折;(2) 自選優先序,但你看不到它怎麼選的。你的 focused feedback 等於把「review reviewer」這層 meta-loop 去掉。對 token 成本也直接有差 — AI 不用先花 token 解析「Tom 到底想我先處理哪條」,直接動工。

    #6 並行/異步執行 (Async Parallel Execution)

    定義:能並行的工作不要序列化等待,結果到再收。
    經典出處:Concurrent programming 整個學門、Amdahl’s law、async/await 在現代語言的普及、Toyota production system 的並行工序設計。

    本次對話做了沒:✅ 做了。

    對話證據:

    「我正在運作 你看一下」

    你開另一個 terminal 跑 workflow,沒等我講完就行動。我這邊主 session 同時讀你的 process tree + session jsonl 做即時觀察。兩條軌道平行,中間用 jsonl 落地通訊。

    對 AI 協作的特別意義:跟 AI 對話有個隱形成本叫 cache miss penalty。Claude 的 prompt cache 5 分鐘 TTL,超過就要從零重讀整個 conversation。如果你序列化等(我講完→你看→你跑→等結果→回我),很容易 5 分鐘外。並行化 + 中間用 file system / jsonl 落地通訊,等於把 cache 維持在熱狀態。傳統軟工這條對應的是「不要 block 在 IO 等待」,AI 場景下是「不要 block 在對話等待」。

    #7 回顧 (Retrospective)

    定義:任務完成後不直接進下一個,先回看「what went well / what didn’t」。
    經典出處:Agile retrospective(Scrum 每個 sprint 末必做)、Norm Kerth《Project Retrospectives》、Etsy/Google 的 blameless postmortem 文化。

    本次對話做了沒:✅ 做了,而且是 meta 級 — 你問本篇這題就是 retrospective。

    對話證據:

    「還有 很多人說跟ai寫作需要很多的軟工基礎，不像請你評估一下所謂的軟工基礎在我們所有的循環裡面，我無形中有用到哪一些…因為有一些是我打中很關鍵的點，而你不知道那些是不是軟工基礎」

    這句話本身是回顧:你不滿足於「拿到結果就走」,還要拆解過程、識別 pattern、產生可遷移知識。

    對 AI 協作的特別意義:AI 不會主動 retrospect — 我跑完就等下一個 prompt,沒人觸發我不會自己回頭看「剛剛這條對話我做對了什麼」。retrospective 必須由你發起。但 retrospective 的產出對 AI 特別有價值:它是 #4 文檔作為輸入的最佳 raw material — 直接把回顧結論寫成 brain file,下次 conversation 直接用。傳統 retrospective 是「同個團隊下個 sprint 用」,AI 場景是「同個你下個 conversation 用」。

    #8 規格先於實作 (Spec-First / Specification before Implementation)

    定義:動手寫 code 之前先把「要做什麼」「驗收標準」寫死。
    經典出處:Leslie Lamport《Specifying Systems》、TDD「先寫測試」也是這條的變形、Design by Contract (Bertrand Meyer)、SDD(Spec-Driven Development)的學派。

    本次對話做了沒:✅ 做了,而且是顯式的 4 維度規格。

    對話證據:

    「記錄下來差異 怎麼啟動 有優化那些地方 要做什麼東西 必要是什麼」

    4 個維度寫死:(1) 啟動方式、(2) 優化點、(3) 要做的東西、(4) 必要條件。我後續的 brain file 跟 WordPress 文章兩份產出,結構直接照這 4 維度生。

    對 AI 協作的特別意義:沒給 spec 的 AI 會「自由發揮」,結果是形式上看起來有結構,實際結構是 AI 替你做的選擇,你不一定買單。你給 4 維度等於把結構決定權拿回來,AI 只負責填內容。這條對應的傳統軟工是 PRD/RFC,AI 場景是「在 prompt 裡內嵌驗收 schema」。

    #9 權衡分析 (Trade-off Analysis)

    定義:任何方案都有 cost 跟 benefit,要顯式列出再比較。
    經典出處:Software Architecture 教材必有的 ATAM (Architecture Tradeoff Analysis Method)、Jeff Bezos 的「two-way door / one-way door decisions」、《Pragmatic Programmer》Ch.4「Be a Catalyst for Change」的反向。

    本次對話做了沒:✅ 做了,而且是顯式追問。

    對話證據:本系列你連續問了三個 trade-off 問題:

    「差異你可以跑跑看」(empirical 比較 cost)

    「我想知道Workflow那一個，他現在到底對我的意義是什麼？我看不太出來」(質疑單一方向的 benefit)

    「注意好讀性跟比較方式」(cost = 讀者認知負擔 vs benefit = 完整性)

    對 AI 協作的特別意義:AI 對「該不該做某件事」的默認是 yes — 因為訓練資料裡的「Yes, you should」遠多於「No, don’t」。你「我看不太出來意義」這句逼我從 advocacy 模式切到 honest assessment 模式,實際結論變成「不存它,寫 reference 進 brain 就好」。這條對應的傳統軟工是 design review 裡「這個複雜度真的需要嗎?」的提問。

    #10 預設驗收標準 (Acceptance Criteria Upfront)

    定義:任務開始前先寫死「做到什麼程度算 done」。
    經典出處:Agile user story 的 INVEST criteria、Behavior-Driven Development (BDD) 的 Given-When-Then、Definition of Done 是 Scrum 必備產物。

    本次對話做了沒:🟡 部分做到。

    分析:你 #8 給了 4 維度規格,算是 partial acceptance criteria。但缺了「品質門檻」:

    • workflow 跑出來的 report 要達到什麼分類正確率才算可信?
    • baseline 跟 workflow 的差異要大到多少才算「值得換 workflow」?
    • 對話拆解後若 15 條都做到,實質工程效率提升多少才算夠?

    結果就是 — workflow 抓到 12 個 hand-roll,我們默認接受這個數字,沒去 sample 5 個函式人工驗證。如果 workflow 系統性把某類 hybrid 全錯標,我們不會發現。

    該怎麼補:任務開始前加一句「驗收標準」段落。例如本次該寫:

    驗收標準:
1. 兩邊跑完後,我會手動 sample 5 個 USES_PRELUDE 跟 3 個 HAND_ROLLED 對證據
2. 如果 baseline 跟 workflow 在這 8 個樣本上有 2 個以上分歧,需逐個澄清
3. 完整 109 函式都要有 row,缺一個視為失敗

    對 AI 協作的特別意義:AI 沒驗收標準會「看起來完成」(plausible-looking output),但內部可能 systematically 錯。傳統軟工裡 acceptance test 是另一個人寫的,AI 場景下你得自己寫,因為 AI 不會主動跟自己對抗。本次沒守這條的代價:我們得花一篇文章解釋「為什麼信任 workflow 的結果」,而本來只需要 sample-test。

    #11 可重跑 / Idempotency (Reproducible Execution)

    定義:任何過程要可從頭重來,輸入相同則輸出相同(在合理隨機範圍內)。
    經典出處:Make / build system 整個學門、Donald Knuth literate programming、Reproducible Research 運動、Docker / IaC 的根本動機。

    本次對話做了沒:❌ 沒做。最具體的證據是你沒按 s 把 workflow script 存下來。

    分析:本次跑了 11 個 Haiku 4.5 平行 audit,產生 146 行 JavaScript orchestration script,結果只存在 session 暫存目錄。如果這次的審計結論被人質疑(例如「12 個 hand_roll 是真的還是 AI 瞎標」),你要重跑驗證沒辦法保證跑出同一份結果 — 因為:

    • 下次跑 Claude 會重新生 script,chunk 切法可能不同
    • Haiku 4.5 即使 temperature 0 也有非 deterministic 因素(MoE routing 隨機)
    • Cache hit 率不同 → 提示空間不同 → 細節結論不同

    該怎麼補:三層防護(從便宜到昂貴):

    1. 最低: 把 script 從 session 暫存目錄 cp 出來歸檔到 brain 或 repo
    2. 中等: 把 script 真的存成 ~/.claude/workflows/<name>.js slash command,雖然本案大概不重跑,但其他 audit 可以 fork
    3. 高保證: 把 audit 結論 + 109 函式分類存成 JSON / CSV,用 schema 驗證,以後重跑只需 diff JSON 不需要重看 markdown

    對 AI 協作的特別意義:AI 的輸出有內建非 determinism(temperature、MoE、context order),這跟傳統 reproducibility 假設(同 input → 同 output)直接衝突。AI 場景的可重跑不能依賴「程式邏輯一樣」,要依賴「中間結果落地」 + 「結果用結構化格式儲存」 + 「下游 verifier 用同 schema 驗」。傳統軟工這條是「build 可重現」,AI 場景是「結論可驗證」。

    #12 預算控管 (Cost / Budget Cap)

    定義:任何運算工作開始前先設天花板,超過自動停。
    經典出處:Cloud computing 的 budget alerts、Kubernetes resource limits、Hadoop / Spark 的 timeout、Stripe 的「circuit breaker」pattern、SREbook §12 effective troubleshooting 的 budget 章節。

    本次對話做了沒:❌ 沒做。

    分析:我們跑 workflow 的時候沒設 token budget 或 wall-time cap。實際跑了 11 個 agent、~$6.10 estimated cost、132 秒 wall-time。如果 Claude 寫的 script bug 了 — 例如把 chunk 切成 100 個,可能跑出 100 個 agent、$60 cost、20 分鐘 wall-time。沒任何機制自動阻擋。

    該怎麼補:

    • prompt 裡明寫上限 — 例如「最多派 12 個 agent,單一 agent 最多跑 60 秒」
    • 用 --effort medium 而不是 high 開始,確認 quality 夠才升 effort
    • 跑前先讓 Claude 估算 token cost 跟 agent 數,你 approve 才放跑(workflow 內建這層 approval prompt,但你按 [3] View raw script 之前沒人問你 budget)
    • 對自己設「單條對話 spend 上限」(例如 $10),透過 Claude Code admin page 或 API budget API 強制

    對 AI 協作的特別意義:傳統軟工 budget 是「機器跑爛要錢」,AI 場景下 budget 還包含「AI 寫錯 script 跑很久才發現」的 fail-loud delay。Anthropic 自己在他們 multi-agent research system 的 paper 也警告:multi-agent 用 token 是 single-agent 的 3-10×,Research system 是 ~15×。沒 budget cap 等於放任這個倍率,3am 一覺起來收到 $200 帳單是真實風險。

    #13 根因分析 (Root Cause Analysis)

    定義:遇到問題不停在表象,挖到「為什麼會發生」的最底層。
    經典出處:Toyota 的「Five Whys」、Apollo 13 事故報告、Etsy / Google 的 blameless postmortem template、《The Field Guide to Understanding Human Error》。

    本次對話做了沒:🟡 部分做到,但是 AI 替你做的。

    分析:本次 audit 最有價值的發現是「guard role 被 AuthzDecision.IsCommunityWide 排除,迫使 5 個 resolver 各自重 probe 一段相同 SQL」。這是根因分析的成果 — 不停在「這幾個 resolver 沒用 prelude」,而是挖到「為什麼它們不能用」。

    但這是 workflow 的 synthesis agent 替你做的,不是你做的。Baseline 模式下 1 個 agent 沒做出這層,你也沒主動追問「為什麼會有 5 個重複」。如果這次跑 baseline 你會 miss 這個 root cause。

    該怎麼補:不能只靠 AI 替你做。可以加紀律 — 拿到分類結果後,主動問:

    看到 12 個 HAND_ROLLED,我們 ladder 5 個 why:
- 為什麼這 12 個沒用 prelude? → 各自原因
- 為什麼它們有共同原因? → 找 pattern
- 為什麼這個 pattern 沒被早發現? → 流程 gap
- 為什麼流程沒抓到? → tooling gap
- 為什麼 tooling 沒設計這層? → 設計時的假設

    對 AI 協作的特別意義:AI 默認停在第一層觀察(「這幾個沒用 prelude」)。要挖根因得明確要求(「列出 root cause」)或結構性逼它(workflow 的獨立 synthesis pass 就是設計來做這個)。傳統軟工這條是 debug 工具,AI 場景是「prompt design」工具 — 在 prompt 裡內嵌 root cause analysis instruction,或設計獨立 verification agent。

    #14 錯誤處理哲學 (Error Handling Philosophy)

    定義:對「事情會出錯」這件事有明確設計姿態 — fail-fast vs fail-silently、retry policy、circuit breaker、graceful degradation。
    經典出處:Erlang 的「let it crash」哲學、《Release It!》Michael Nygard 整本書、Google SREbook §22 addressing cascading failures。

    本次對話做了沒:❌ 沒做。

    分析:我們沒任何「workflow 跑到一半失敗了怎麼辦」的計畫:

    • 如果某個 chunk 的 Haiku agent 超時了 → 我們沒設 retry 也沒設 fallback
    • 如果 synthesis agent 算術錯了(這次真的發生了:83 vs 109)→ 我們沒設 verification 步驟,純靠主 orchestrator 主動懷疑
    • 如果 JSON schema 驗證 fail → 不知道會發生什麼,沒測過
    • 如果 workflow runtime 自己 crash → 沒 graceful resume 流程

    該怎麼補:在 prompt 裡加 error handling instruction:

    如果跑到一半發現:
- 某 chunk 的 agent fail → 標記 SKIPPED,繼續其他,最後 report 哪些 skip
- synthesis 結果跟 row count 對不上 → 不要直接出 report,先 escalate 給主 orchestrator 重算
- JSON schema 違反 → 該 row 標 INVALID,繼續其他
- 整體執行超過 5 分鐘 → 自動 abort,出階段性 report

最後 final report 要明確標示哪些 chunk 是「完整跑完」、哪些是「skipped」、哪些是「fail-and-retried」。

    對 AI 協作的特別意義:AI 預設 fail-silently — 它會生「看起來合理」的內容掩蓋失敗。傳統軟工 fail-fast 是「raise exception 停下來」,AI 場景的 fail-fast 是「標註 INVALID / SKIPPED 而不是瞎掰」。沒設計這條,AI 會「完整交付」一份其實內部有 hole 的報告,你看不出來。本次 workflow synthesis 算 83 是僥倖被主 orchestrator 抓到,如果主 orchestrator 也沒抓,我們就拿錯誤數字寫文章了。

    #15 版本控制紀律 (Version Control Discipline)

    定義:任何重要 artifact 進 git,commit message 寫清楚 why,branch 策略對應 workflow。
    經典出處:Git 整個工具、Conventional Commits 規範、Trunk-based / GitFlow / GitHub Flow 各家 branch 策略、Linus 的 git 設計初衷。

    本次對話做了沒:❌ 沒做。本次產出全部沒進 git。

    分析:這次產出了 4 件 artifact:

    • ~/.claude/projects/-home-tom/memory/brain/dynamic-workflows.md(新建)
    • ~/.claude/projects/-home-tom/memory/brain/adaptive-agent-team-staffing.md(編輯)
    • ~/.claude/projects/-home-tom/memory/MEMORY.md(編輯)
    • WordPress 文章兩篇

    前三個位置實際是 ~/.claude/projects/-home-tom/ — 你有可能沒把它放在 git 控管下,意思是:

    • brain 編輯沒 commit history,半年後想知道「dynamic-workflows.md 是什麼時候加的、為什麼加」沒記錄
    • 如果 brain 不小心被改錯了(例如未來某個 conversation AI 寫壞了),無法 rollback
    • 跨機器同步只能靠 rsync / cloud sync,沒 conflict resolution

    該怎麼補:

    1. cd ~/.claude/projects/-home-tom && git init(如果還沒)
    2. 新 brain 或重大編輯後 commit:git add brain/ MEMORY.md && git commit -m "feat(brain): dynamic-workflows from 2026-05-29 Opus 4.8 test"
    3. WordPress 文章 export markdown 進專屬 repo,或用 wp-cli 串自動 backup
    4. workflow script 改 #11 補救時順便 commit 進 dotfiles repo

    對 AI 協作的特別意義:AI 跨 conversation 是 stateless,brain file 是它的「外部記憶」。外部記憶的版本控管比 code 的還重要,因為你不會看到自己過去 conversation 改了哪些 brain,只有 git diff 告訴你。本次對話我改了 3 個 brain 檔,如果你沒 git 控管,3 個月後你不會記得這幾條條目是 5/29 對話加的還是更早。傳統 git 是 code 的時間機,AI 場景是「我跟 AI 集體記憶的時間機」。

    15 條全表:做了沒 × leverage

    # 紀律 類別 本次 Leverage(高→低)
    1驗證紀律核心驗證✅★★★★★ 沒守等於沒救
    2正交分解設計分解✅★★★★★ AI 回答品質直接相關
    3真實基準過程紀律✅★★★★★ 結論可信度核心
    4文檔作為輸入知識持久化✅★★★★★ AI 時代特有的紀律
    5Focused review過程紀律✅★★★★ AI 對 mixed feedback 表現差
    6並行執行過程紀律✅★★★ 規模大才顯效
    7回顧核心驗證✅★★★★ 跟 #4 配對 leverage 最大
    8規格先於實作設計分解✅★★★★ 直接決定 AI 輸出結構
    9權衡分析設計分解✅★★★★ 抗 AI 默認 yes 傾向
    10預設驗收標準過程紀律🟡★★★★ 該補,沒守會默認 plausible-looking
    11可重跑知識持久化❌★★★ 任務一次性可省,系統性任務必須
    12預算控管過程紀律❌★★★ 小任務可省,長 background 任務必須
    13根因分析核心驗證🟡★★★★ 主要靠 prompt 設計
    14錯誤處理哲學設計分解❌★★★★ AI 預設 fail-silently 必補
    15版本控制知識持久化❌★★★ brain 控管比 code 控管更重要

    結論:跟 AI 寫程式需要哪些軟工?

    不是新的軟工,是舊軟工套到 AI 4 個特性上

    15 條全部都不是「AI 時代發明的」 — 每條都能在 1990 年代的軟工教材找到根。差別在 4 個 AI 特性對這些紀律的需求強度不同:

    AI 特性 被放大需求的紀律
    訓練資料 cutoff#1 驗證紀律(逼 AI 查資料,不要憑記憶)
    Stateless / 無 conversation 記憶#4 文檔作為輸入、#15 版本控制(外部記憶持久化)
    非 deterministic 輸出#11 可重跑、#10 預設驗收標準、#14 錯誤處理(處理隨機性)
    高並發 + 高速#6 並行、#12 預算控管(token 倍率風險)

    個人 leverage 排序(5 強)

    如果你是這條光譜中段的人(寫過 5 年以上 code,剛開始系統性用 AI 寫 code),最該優先吸收這 5 條:

    1. #1 驗證紀律 — 沒守這條,後面 14 條都白學。AI 講什麼都不能信,grep / curl / test 重驗
    2. #2 正交分解 — 拆軸線問,不要 bundled question。直接決定 AI 回答品質
    3. #4 文檔作為輸入 — 把學到的寫成下個 conversation 可讀的格式。沒這條,每次 onboarding
    4. #3 真實基準 — Toy example 騙人。用 production codebase 評估工具
    5. #5 Focused review — 給 AI feedback 一次只挑一條軸線

    沒做的 5 條,該怎麼補

    本次對話沒做的紀律對應 5 條 action(從便宜到貴):

    1. #15 版本控制(5 分鐘):cd ~/.claude/projects/-home-tom && git init && git add . && git commit -m "snapshot" 一次性處理
    2. #11 可重跑(2 分鐘):把 workflow script 從 session 暫存 cp 到 brain 或 dotfiles repo 歸檔
    3. #10 驗收標準(每任務多寫 3 行 prompt):任務 prompt 開頭加「驗收標準:N 個項目,M% 正確率,通不過要告訴我」
    4. #14 錯誤處理(每 workflow 多寫 5 行):script 內加 fail-fast / skip / retry 分支
    5. #12 預算控管(系統性設定):Claude Code admin page 設 hard daily limit 或寫個 hook 跑前先估

    真正的 meta-insight

    本文 15 條展開後最反直覺的觀察:跟 AI 寫程式需要的軟工基礎,大部分不是 code-level 的,是 process-level + protocol-level 的。傳統軟工新人學的順序是「先學語言 → 再學 design pattern → 最後學 process」,跟 AI 寫程式得反過來:先學 process discipline(怎麼下指令、怎麼驗證、怎麼回顧),最後才是 code-level technique。

    因為跟 AI 寫程式,code 是 AI 生的,你扮演的是 reviewer + verifier + spec writer 三個角色。這三個角色傳統上叫 PM / QA / Tech Lead — 都是 senior eng 的活。所以「跟 AI 寫程式比較簡單」這句話完全反了 — 它把senior eng 的工作 commoditize 到每個用 AI 的人身上,reviewer 的紀律從「資深工程師的特權」變成「每個 prompt 作者的基本技能」。

    這就是為什麼那麼多人「用 AI 寫了一堆 code 但跑不起來」 — 不是 AI 不行,是沒人替他們做 reviewer / verifier / spec writer 那三層活。本文 15 條的本質就是把這三層活的紀律寫下來。

    跟我之前文章的關聯

  • Claude Code Dynamic Workflows 實測:Opus 4.8 + 11 Haiku 平行 audit 109 個 resolver

    重點摘要

    • Anthropic 在 2026-05-28 釋出 Claude Opus 4.8,帶來 Dynamic Workflows(背景跑 JS script orchestrate 數百 subagent)、Effort Control(low/medium/high/xhigh/max/ultracode)、Messages API system entries 中段插入。
    • 實測:同題雙軌跑 Home123(Go + gqlgen 後端)的 109 個 resolver 函式 authz pattern audit,baseline (Opus 4.7 + 1 個 general-purpose agent) vs workflow (Opus 4.8 + 11 個 Haiku 4.5 worker)。
    • 最大發現:workflow runtime 自動把 worker model 派為 Haiku 4.5,主 orchestrator 維持 Opus 4.8 — 對應「想 → opus / 找 → haiku」分工 doctrine,以前要手寫 AGENTS.md 分配的事 runtime 替你做了。
    • Wall time 沒省(workflow runtime 132 秒比 baseline 236 秒快,但加上主 session synthesis 反而是 392 秒)。本次估算成本 workflow ~$6.1 是 baseline ~$0.72 的 ~8.5× — 主要花在 runtime cache write 固定成本,大規模任務攤平會降下來。
    • 收益不在省錢,在:JSON Schema 強制輸出契約、reproducibility(script 落地,以後 /<name> 一鍵重跑)、主 orchestrator 主動 cross-check 下游(實戰抓到 synthesis subagent 算錯總數 83 vs 真實 109)。

    一眼看完:Baseline vs Workflow

    整篇下面會逐項拆,先給你 5 秒讀完的版本。題目都是同一份 Home123 GraphQL 後端 109 個 resolver 函式的 authz pattern 分類。

    面向 Baseline Workflow
    啟動指令主 session 派一個 Agentclaude --model claude-opus-4-8 --effort high 後 prompt 內塞 workflow 字
    主模型Opus 4.7Opus 4.8
    Worker 數量1(general-purpose,可寫)11(Explore 型,強制 read-only)
    Worker 模型Opus 4.7(跟主一致)全 11 個 Haiku 4.5(runtime 自選)
    並發加速—11 agents 加總 354s 實跑 132s = 2.7×
    主 session tool call24 (14 Bash + 10 Read)8 (5 Bash + 2 Read + 1 Workflow)
    輸出契約自由 markdownJSON Schema + enum 鎖死 4 值
    覆蓋109/109109/109
    總耗時3:56(236s)6:32 turn,workflow runtime 2:12
    抓到的 root cause1 個(CapsAny 提案)6 個(含 guard 5× 重複的真兇)
    結構級洞見沒做出read-side vs write-side 不對稱
    主動 cross-check 下游—(只有 1 agent)✅ 抓到 synthesis agent 算錯 83 vs 真實 109
    估算成本~$0.72~$6.10(約 8.5× baseline)
    可重跑無script 落地,以後 /<name> 一鍵

    架構差異:一張流程圖

    讀者最常問的不是「快多少」,是「結構上到底差在哪」。把兩種模式畫成流程:

    Baseline                              Workflow
─────────                             ─────────
User prompt                           User prompt
    │                                     │
    ▼                                     ▼
┌─────────────────┐                   ┌─────────────────┐
│ Main Claude     │                   │ Main Claude     │
│ (Opus 4.7)      │                   │ (Opus 4.8)      │
│                 │                   │ 寫 JS script    │
│ Agent tool      │                   └────────┬────────┘
│   ↓ 派 1 agent  │                            │ Workflow tool
└────────┬────────┘                            ▼
         │                              ┌──────────────────┐
         ▼                              │ Runtime          │
   ┌──────────────┐                     │ (背景執行 script) │
   │ 1× Opus 4.7  │                     └────────┬─────────┘
   │ general-     │                              │ fan-out
   │ purpose      │                              ▼
   │              │            ┌──────────────────────────────────┐
   │ ─ 24 tool ─  │            │ Phase 1: Classify (平行)         │
   │   call ─ 自由 │            │ ┌────┐┌────┐┌────┐ ... ┌────┐  │
   │   分類 +    │            │ │H4.5││H4.5││H4.5│      │H4.5│  │
   │   markdown  │            │ └────┘└────┘└────┘      └────┘  │
   └──────┬───────┘            │ 10 agents (schema 切 8 chunks +  │
          │                    │  visitor 1 + announcement 1)     │
          ▼                    └────────────┬─────────────────────┘
   markdown report                          │ JSON schema 驗證
                                            ▼
                               ┌──────────────────────────┐
                               │ Phase 2: Synthesize      │
                               │ ┌────┐                    │
                               │ │H4.5│ 1 agent           │
                               │ └────┘                    │
                               └────────────┬──────────────┘
                                            │
                                            ▼
                               ┌──────────────────────────┐
                               │ Main Claude (Opus 4.8)   │
                               │ cross-check synthesis,   │
                               │ 抓到 83 vs 109 算術錯誤  │
                               │ 用 authoritative rows     │
                               │ 重算 + 寫最終 report     │
                               └────────────┬──────────────┘
                                            ▼
                                   final markdown report
                                   + JS script 落地

    關鍵差別不是 agent 數,是「主 Claude 不再親手做活,變成 orchestrator + verifier」。中間結果落在 script 變數,不灌進主 session context。

    背景:Opus 4.8 帶來什麼

    Anthropic 在 2026-05-28 同步發佈了 Claude Opus 4.8、Dynamic Workflows research preview、Effort Control、以及 Messages API 的中段 system entries 支援。發佈當天我看了官網內容,隔天 5/29 拿真實專案 Home123 跑了一輪雙軌對照,本文記錄完整數據與啟動 prompt。

    三個直接相關的能力更新:

    能力說明適用 plan
    Dynamic WorkflowsClaude 寫一支 JS script,runtime 背景跑,內含可數百個 read-only Explore subagent 平行作業所有付費(Pro 要先去 /config 開)
    Effort Control5 級:low / medium / high / xhigh / max,另有 ultracode(= xhigh + 自動 workflow orchestration)所有 plan
    Messages API system entries可在 messages array 中段插入 system entry,更新指令但不破 prompt cache、不需要假裝 user turnAPI 直連

    不是所有 model 都吃所有 effort 等級。實測 claude --effort foo 會回:

    error: option '--effort <level>' argument 'foo' is invalid.
It must be one of: low, medium, high, xhigh, max

    官方支援表(來自 code.claude.com/docs/en/model-config):

    Model支援 effort 等級預設
    Opus 4.8, Opus 4.7low, medium, high, xhigh, max4.8 → high / 4.7 → xhigh
    Opus 4.6, Sonnet 4.6low, medium, high, max(沒 xhigh)high
    其他不支援 effort—

    常見誤解:Sonnet 也能 xhigh 嗎?不行。Sonnet 4.6 只到 high,你硬塞 xhigh 會自動降到 high 不報錯但也少一級。ultracode 在 Sonnet 連菜單都不出現。

    對照實驗設計:為什麼挑 Home123 authz audit

    Workflow 適合的題目有 4 個必要條件:

    1. 可平行化 — 任務天然能切成 N 個獨立 chunk
    2. 可被 JSON Schema 約束 — 輸出結構穩定、enum 有限
    3. 有 ground truth — 否則 11 個 agent 跑完你也不知道對不對
    4. Read-only 為佳 — Explore type agent 不會誤改檔

    挑的題目:掃描 Home123 backend GraphQL 的 3 個 resolver 檔,把 109 個 resolver function 分類成 USES_PRELUDE / LEGIT_PUBLIC / HAND_ROLLED / UNKNOWN。

    Home123 是 multi-tenant SaaS,我自己寫了一個 authzPrelude centralised authn+cap+scope+audit 序列,規範每個 protected resolver 進 withTx 後第一段要 call。但程式碼累積過程中,有些 resolver 為了 cap-OR 之類 prelude 還不支援的情境 hand-roll 了授權邏輯。這次審計就是要逐一抓出來。

    符合條件為什麼這題符合
    可平行化109 個 function 各自獨立,每個分類不依賴其他結果
    可被 schema 約束class enum 只有 4 值;每筆 row 必填 file / func / line / class / evidence
    有 ground truthgrep -c authzPrelude backend/graph/*.resolvers.go 給出客觀基準
    Read-only純審計、不改檔

    啟動 prompt:兩邊放在一起看

    兩邊我都跑了。下面先給差異速覽,再給雙邊完整 prompt 對照。

    差異速覽

    面向 Baseline Workflow
    session 啟動任何 session 都可,呼叫 Agent toolclaude --model claude-opus-4-8 --effort high
    觸發機制主動派 1 個 Agentprompt 內含 workflow 關鍵字 → Claude Code 反白 → approval prompt
    Prompt 句子數~20 行(任務說明)~24 行(任務說明 + 第一個字「workflow」)
    關鍵差異字直述命令式 — 「做這個 audit」第一個字加 「跑一個 workflow,」 — 觸發 runtime 寫 script
    事前需要無(general-purpose 預設可用)Claude Code ≥ 2.1.154,Pro 要先 /config 開
    跑前是否確認不需要,直接跑approval prompt 必須選 [1] Yes;第一次強烈建議按 [3] View raw script

    左:Baseline prompt(逐字)

    你在 /home/tom/Desktop/home123_new 做一次 read-only authz pattern audit。
禁止修改任何檔案。

審計三個 resolver 檔的每一個 resolver function:
- backend/graph/schema.resolvers.go (~80 funcs)
- backend/graph/visitor.resolvers.go (~15 funcs)
- backend/graph/announcement.resolvers.go (~16 funcs)

分類規則:
1. USES_PRELUDE — body 第一段 call authzPrelude(...)
2. LEGIT_PUBLIC — 真正不需要 auth 的 (Login / RefreshAccessToken 等)
3. HAND_ROLLED — 沒 call authzPrelude 但自己寫 cap/scope/role/audit 檢查
4. UNKNOWN — 你無法判定

輸出:markdown 表 | file | func | line | class | evidence |,
所有 function 一行不能少。

最後加 ## Summary:每 class 數量、HAND_ROLLED 跟 UNKNOWN 清單、可疑模式。

用 Bash grep / Read 自己抓,不要憑記憶或猜。

    右:Workflow prompt(逐字)

    新 session 啟動:

    cd /home/tom/Desktop/home123_new
claude --model claude-opus-4-8 --effort high

    進去後丟這個 prompt(留意第一個字是 「在這個 repo 跑一個 workflow」,這個關鍵字就是觸發 runtime 的開關):

    在這個 repo 跑一個 workflow,做 read-only authz pattern audit。不准改任何檔案。

審計三個 resolver 檔的「每一個」resolver function:
- backend/graph/schema.resolvers.go (約 78 funcs)
- backend/graph/visitor.resolvers.go (約 15 funcs)
- backend/graph/announcement.resolvers.go (約 16 funcs)

每個 function 分類成 4 種之一:
1. USES_PRELUDE — body 第一段 call authzPrelude,或 1-line delegate 到呼叫
   authzPrelude 的 helper
2. LEGIT_PUBLIC — 真公開查詢 (Login / RefreshAccessToken / Healthcheck /
   ApplicationStatus 等),依據 schema directive / 註解 / 函式意圖判定
3. HAND_ROLLED — 沒 call authzPrelude 但自己寫 cap/scope/role/audit
   (CheckCap / hasRole / rbac.RequireCapability / 手動讀 ctx 判 user)
4. UNKNOWN — 邏輯太繞或無法判定

輸出格式:markdown 表 | file | func | line | class | evidence |,
每個 function 一行不能少。

最後加 ## Summary:每 class 數量、HAND_ROLLED 跟 UNKNOWN 名單、可疑模式
(eg. asymmetry / 同一 cap 兩種寫法 / 整個檔的傾向)。

建議擴展 prelude 才能解的問題也標出來 (eg. CapsAny 多 cap OR-chain)。

    送出後 Claude Code 會問你

    Workflow plan:
  Phase 1: Classify — one Explore agent per function-range chunk
  Phase 2: Synthesize — cross-file pattern analysis + suspicious findings

[1] Yes, run it
[2] Yes, and don't ask again for <name> in <path>
[3] View raw script   ← 第一次強烈建議按
[4] No

    第一次按 View raw script 看 Claude 寫出什麼 JS,看完按 ESC 回去再按 Yes。這是 workflow 教育核心,跟 subagent 的 black box 是完全不同的體驗 — 你看得到 orchestration 的具體 code。

    Claude 寫的 workflow script 長啥樣

    從 session jsonl 撈出來的真實 script 開頭片段:

    export const meta = {
  name: 'authz-pattern-audit',
  phases: [
    { title: 'Classify',   detail: 'one Explore agent per function-range chunk' },
    { title: 'Synthesize', detail: 'cross-file pattern analysis' },
  ],
}

// JSON Schema 強制每筆 row 必填 5 欄
const ROW_SCHEMA = {
  type: 'object',
  required: ['rows'],
  properties: {
    rows: {
      type: 'array',
      items: {
        type: 'object',
        required: ['file', 'func', 'line', 'class', 'evidence'],
        properties: {
          file: { type: 'string' },
          func: { type: 'string' },
          line: { type: 'integer' },
          class: {
            type: 'string',
            enum: ['USES_PRELUDE','LEGIT_PUBLIC','HAND_ROLLED','UNKNOWN']
          },
          evidence: { type: 'string' },
        },
      },
    },
  },
}

const PRELUDE_REF = `
REFERENCE — what each class means in THIS codebase (backend/graph/authz.go):
authzPrelude(ctx, tx, claims, PreludeOptions{Cap:..., Scope:..., ...})
is the centralised authn+cap+scope+audit sequence...
CLASSIFICATION RULES (pick exactly one per function):
...
`

// schema.resolvers.go 切 8 chunks,各 1 個 Explore agent;visitor / announcement 各 1
// fanOut(...) → 10 個 read-only Explore agents 平行
// 然後 1 個 synthesis Explore agent 做 cross-file 分析

return { rows, summary }

    注意三件事:

    • JSON Schema 鎖死 enum:subagent 不可能跑出 "class": "MAYBE" 這種,runtime 直接退回。Baseline 自由 markdown 沒有這層保護。
    • agentType: 'Explore' 是 script 層硬性:11 個 agent 完全不能 Edit/Write,不是靠 prompt 講「不准改」這種 soft 約束。
    • chunk 切法寫死在 script:每個 agent context 不汙染,不會記錯行號。

    跑起來後的真實 process 狀態

    從本機 process tree + session jsonl 即時觀察到的(workflow 跑到 110 秒時):

    $ ps -o pid,pcpu,pmem,vsz,rss,etime,cmd -p 1676911
    PID %CPU %MEM    VSZ   RSS     ELAPSED CMD
1676911 26.9  1.0 73786132 337864    01:49 claude --model claude-opus-4-8 --effort high

$ python3 - << 'PY'
import json
events = {}; tools = {}
with open('<session>.jsonl') as f:
    for line in f:
        d = json.loads(line); ...
print(events, tools)
PY
# 結果:
# {'assistant': 14, 'system': 2, 'user': 6, ...}
# Tools: {'Bash': 3, 'Read': 1, 'Workflow': 1}

    主 session 只花 5 個 tool call(3 Bash + 1 Read 探勘 + 1 Workflow 派出去)就把工作全部 delegate 出去,自己等 callback。

    Workflow runtime 把 11 個 agent 的執行軌跡寫到磁碟,結構是這樣的:

    ~/.claude/projects/<project>/<session>/
├── workflows/
│   ├── scripts/
│   │   └── authz-pattern-audit-wf_d545fc61-597.js   ← Claude 寫的 script
│   └── wf_d545fc61-597.json                         ← run state
└── subagents/workflows/wf_d545fc61-597/
    ├── journal.jsonl                                ← 11 個 agent 起跑/完成軌跡
    ├── agent-a1b66c368221dfcbc.jsonl                ← 每個 agent 的完整 transcript
    ├── agent-a1b66c368221dfcbc.meta.json
    ├── ...(共 11 對 jsonl + meta)
    └── agent-a24f70cfc4a9cea4c.jsonl                ← synthesis agent

    從 journal.jsonl 可以看到並發狀況:7 個 agent 同時 started,然後 result/start 交錯。實測 Tom 8-core 機器同時 active ~7 個,沒撞到 16 上限。

    最大發現:runtime 自動把 worker 派為 Haiku 4.5

    從每個 agent 的 jsonl 撈 model 跟 token:

    aid          model         dur(s)   in     out     cache_r    cache_w
a1b66c3682   haiku-4-5     36.6     68     2913    704739     86473
a24f70cfc4   haiku-4-5     65.3     126    6780    831993     139390
a44126f699   haiku-4-5     46.0     113    2750    780310     99018
a5b0952489   haiku-4-5     18.1     36     2106    172988     79402
a677c4aa85   haiku-4-5     15.6     41     1955    164250     84687
a98dc4ecbc   haiku-4-5     18.3     26     2189    132348     57398
aa0358d7b4   haiku-4-5     39.4     132    3935    803238     66657
aac3435e5b   haiku-4-5     22.4     77     2798    384636     174664
aac426ca5b   haiku-4-5     24.5     41     2616    235382     64016
ab4b713305   haiku-4-5     28.6     120    2618    480910     158476
abe7fdedda   haiku-4-5     39.8     88     3173    896956     110064

    11 個 worker 全部是 Haiku 4.5。我啟動用 --model claude-opus-4-8,但 workflow runtime 自選把 worker 派去 Haiku。

    這對應到我 MEMORY 裡寫的「想 → opus / 做 → sonnet / 找 → haiku」模型分層 doctrine。Runtime 替我做了:

    • 主 orchestrator(寫 script + synthesis)= Opus → 「想」
    • 11 個 worker(bulk classification / grep / read)= Haiku → 「找」
    • 沒 Sonnet 是因為這題沒「做」(read-only audit 沒寫入)

    意義:原本 plan 期手寫 AGENTS.md 分配模型的事,runtime 替你做了。這比文件公告任何一條新功能都重要 — adaptive staffing 從「未來方向」變成「實裝」。

    對照結果:數字攤開

    面向 Baseline (Opus 4.7 + 1 agent) Workflow (Opus 4.8 + 11 Haiku)
    總耗時3:56 (236s)6:32 turn / 2:12 workflow runtime
    真實平行加速—11 agents 累加 354s,實跑 132s → 2.7×
    主 session tool call24 (14 Bash + 10 Read)8 (5 Bash + 2 Read + 1 Workflow)
    Subagent 數1(general-purpose,可寫)11(Explore,read-only)
    Subagent 模型Opus 4.7全 11 個 Haiku 4.5
    覆蓋109/109109/109
    總 token(估)~103K~480K(主 315K + workers 165K)
    Cache read低6.95M(瘋狂重用)
    估算成本~$0.72~$6.10(約 8.5× baseline)

    分類結果差異

    Class Baseline Workflow 差異原因
    USES_PRELUDE8478Workflow 把「prelude + 後續 manual orchestration」歸到 hand_rolled hybrid,標準更嚴
    LEGIT_PUBLIC1317Workflow 把 Logout / Me / Community 視為 public(judgment call)
    HAND_ROLLED1012Workflow 多抓出 5 個 hybrid hand-roll(prelude 加 manual 後處理)
    UNKNOWN22同(兩個 *AuditUnacked,純靠 RLS)

    質的差異:同題下 baseline vs workflow 各看到什麼

    數字一樣是 109/109 覆蓋,但兩邊對同一個 codebase 「看見」的東西不一樣。下面 4 個維度,左 baseline 右 workflow 並列。

    差異 #1:對下游結果是否複查

    Baseline 表現 Workflow 表現
    只有 1 個 agent,自己跑自己算,沒有下游可疑。Report 怎麼算就怎麼算,讀者要自己 grep 才能驗。 Synthesis subagent 自己算出 total: 83(漏算 26 個)。主 orchestrator (Opus 4.8) 拒絕信任,自己重算 109,公開記下:

    “The audit is complete, but the synthesis agent’s counts look off (it reported total=83, but I dispatched coverage for 109 functions). Let me verify completeness from the authoritative rows array myself.”

    這就是 4.8 公告吹的「4× less likely to allow flaws in code it wrote to pass unremarked」實戰演示。

    差異 #2:對 root cause 的挖掘深度

    Baseline 的觀察 Workflow 的觀察
    「cap-OR 是 4 個 hand-roll 不 migrate 的主因」。

    停在第一層觀察。沒挖到更底層的結構問題。    		 「Households / Parcels / ParcelsPage / CommunityVisitors / VisitorAuditLog 同一段 SQL 抄 5 次。真兇是 AuthzDecision.IsCommunityWide 排除了 guard role,迫使每個把 guard 當 community-wide 的 resolver 都得自己重 probe。」

    挖到第二層結構根因。能做出來是因為 synthesis 是專屬 agent、有獨立 context,沒被 109 函式的細節塞滿。

    差異 #3:可落地的 fix 提案數

    Baseline 給的提案 Workflow 給的提案
    1 個:擴展 prelude 支援 CapsAny 多 cap OR-chain 6 個 可落地的 prelude extension:
    1. CapsAny []string — 解 4 個 hand-roll
    2. 承認 guard 是 broad role(RoleListBroad bool)— 解 5× 重複的 SQL probe
    3. ScopeDowngradeOnRole map[role]AuthzScope — 解 2 個 visitor scope 降級
    4. Cap + CapOwn + OwnershipIDCol — 解 2 個 announcement ownership
    5. authzPreludeAny([]PreludeOptions) 多路徑 helper — 解 2 個 multi-path
    6. ScopeRLSOnly enum(顯式宣告 RLS-only)— 解 2 個 UNKNOWN
    最高 leverage:#1 + #2 兩個 API 微調可幹掉 12 個 hand-roll 中的 7 個。

    差異 #4:結構級觀察

    Baseline 的結論深度 Workflow 的結論深度
    逐個 function 分類完,給 Summary 數字。

    沒有跨函式結構洞見。讀者拿到表得自己再看一輪才能發現「全部 hand-roll 都在 query 那邊」。    		 「所有 7 個純 hand-roll + 2 個 UNKNOWN 集中在 schema.resolvers.go 的 query tail(line 6210-7130),mutation 100% 走 prelude。」

    結論:「read-side authz is where the rot is.」

    這級結構洞見 baseline 沒做出來,因為它的 agent 同時在處理逐函式分類跟跨函式觀察兩件事,context 被佔滿。

    4 個差異的共同根因

    Workflow 4 個維度都贏,不是模型差,而是架構差:

    • Synthesis 是專屬 phase 跟專屬 agent,不跟逐函式分類搶 context
    • 主 orchestrator 不直接做活,有餘力去 cross-check 下游
    • JSON Schema 鎖死 enum,讓 synthesis 的算術錯誤被直接 vs 證據對照,容易被抓
    • 每個 Classify agent 只看自己那塊 chunk,context 不被 109 函式整體噪音蓋掉

    換句話說:把 baseline 的單一 Opus 4.7 agent 升級成 Opus 4.8 也救不了 — 缺的是 architectural separation of concerns,不是模型聰明度。

    成本拆解:雙邊對稱對照

    用公開 pricing 算(Opus 4.7 / 4.8 同價:$5/M input、$25/M output、~$0.50/M cache_read、$6.25/M cache_write;Haiku 4.5:$1/M input、$5/M output、~$0.10/M cache_read、$1.25/M cache_write)。

    Baseline 拆解

    誠實先講:baseline 走 Agent tool,Anthropic 只回傳 total_tokens: 103,078,沒給 input/output 拆解。所以我只能上下界估算。

    情境 假設拆解 成本
    下界(全是 input)103K in / 0 out$0.52
    合理估(read-heavy audit,輸出 ~10K markdown)93K in / 10K out~$0.72
    上界(全是 output,不現實)0 in / 103K out$2.58

    Workflow 拆解

    Workflow runtime 把每個 agent 跟主 session 的 token 都寫到 jsonl,可以精算。

    項目 Input Output Cache read Cache write 成本
    主 session (Opus 4.8)31,68659,5061,361,289262,528~$3.97
    11 workers (Haiku 4.5)~870~33,833~5,587,750~1,120,245~$2.13
    Workflow 合計~32,556~93,339~6,949,039~1,382,773~$6.10

    並排比較與成本比

    指標 Baseline Workflow 倍率
    總 token(可量到的)~103K~8.46M(主 + workers,含 cache)~82×
    非 cache token~103K~125K(主 + workers,純 in+out)~1.2×
    估算成本~$0.72~$6.10~8.5×

    校正一下我之前隨口說的「2-3× cost」 — 認真算下來這次 workflow 是 baseline 的 ~8.5×。會這麼高的主因是 workflow runtime 海量 cache write(主 session prompt 加上 11 個 worker 各自的 system+task prompt 都得 cache),這在小規模任務上吃掉的固定成本不成比例。

    更大規模(例如 1000 個 function、5 個檔案、要跑多輪 phase 的 codebase-scale migration)倍率會掉下來,因為 cache 攤平。本次 109 函式可能還沒到 workflow 的 sweet spot。

    收益不在錢,在結構性保證:JSON Schema 鎖死輸出契約、Explore agent 鎖死 read-only、script 落地 reproducible、主 orchestrator 主動 cross-check 下游算術錯誤、結構級洞見的獨立 synthesis pass。如果這次的 audit 結果直接讓你修對 5 個 bug,$5 的價差完全划得來;如果只是研究性掃描、要常常重跑,$0.72 的 baseline 更合理。

    何時用、何時不用

    情境 該用
    平行 audit / sweep / 分類(N 個獨立目標)Workflow
    結果可被 JSON Schema 約束Workflow
    有 ground truth 可驗(grep / 規則對照)Workflow
    Codebase migration 數百到千行Workflow
    30 行小改、互動式 debug、需要中途決策Subagent / 直接對話
    設計 / 重構 / 探索 spike直接對話
    序列邏輯(A 結果決定 B 做啥)Subagent
    預算敏感、有 deadlineSubagent

    硬性限制(踩過的)

    限制數字影響
    並發 agent最多 16(8-core 機器實測 ~7 並發)大 chunk 設計,別追求一函式一 agent
    單 run 累計 agent硬上限 1000大型 migration 拆多個 workflow
    中途要用戶輸入不行多階段簽核拆多 workflow,中間落地
    script 直接 fs / shell不行透過 agent 做,script 純 orchestrate
    Subagent permission mode永遠 acceptEdits想 read-only 一定用 agentType: 'Explore'

    把 workflow 存成可重用 slash command

    跑完滿意,在 workflow session 內:

    /workflows               # 列出 run
↑↓ 選那個 run → Enter   # 進入進度檢視
s                        # 存成 slash command
  → 選 .claude/workflows/<name>.js (repo 共享)
  → 或 ~/.claude/workflows/<name>.js (個人跨專案)

    之後 /<name> 像 slash command 一樣用。Project workflow 優先級高於 personal 同名。

    想 resume failed run:

    Workflow({
  scriptPath: "<session>/workflows/scripts/<name>-<runId>.js",
  resumeFromRunId: "wf_xxx"
})
# completed agents 回傳 cached result,只重跑失敗的

    關掉 workflow

    範圍怎麼關
    自己/config 切 Dynamic workflows / settings.json 設 "disableWorkflows": true / 環境變數 CLAUDE_CODE_DISABLE_WORKFLOWS=1
    整組織managed settings "disableWorkflows": true 或 Claude Code admin page 切

    關掉後:built-in /deep-research 不能用、workflow 關鍵字不觸發、ultracode 從 /effort 菜單消失。

    對日常工作的影響

    我自己接下來打算用 workflow 跑的場景:

    • Home123 RLS coverage sweep — 每張 table 確認 CRUD 4 個 RLS policy 都齊
    • Home123 invariant coverage — 170 個 INV 是否在 backlog 有對應 test sketch
    • iDempiere @RestResource endpoint 巡檢 — endpoint × test × OData filter doc 三角檢
    • SimpleEC OMS Kafka 事件覆蓋矩陣 — topic × producer × consumer 對應

    不會用 workflow 的場景:走 decision-server 的任何題(workflow 中途不能停下來問人)、30 行小修、新功能 spike(reproducibility 沒價值)。

    跟我之前文章的關聯

    結論:結構性保證,不是省錢工具

    Dynamic Workflows 不是「Claude 變強了所以更便宜」,而是「Claude 把 plan 期才做的 staffing 決策搬到 runtime,並用 JSON Schema + Explore 型別把輸出契約寫進 code 而非 prompt」。對任務符合 4 條件(可平行、可 schema、有 ground truth、read-only)的場景,workflow 的結構性保證值得 2-3× cost。不符合的場景繼續用傳統 subagent 跟直接對話,別因為「workflow 看起來酷」default 用。

    真正令人意外的不是任何單一功能,是「runtime 自動派 Haiku 4.5 給 worker、保留 Opus 4.8 給 orchestrator」這件事連文件都沒重點說。它把以往要寫進 AGENTS.md 的「想/做/找」三層分工,從文件變成系統行為。下一輪 model release(Mythos Preview 已預告)會繼續推進這條軸線:組織 prompt 從手寫變 runtime 推導。

  • 「為什麼修不完?」— 從 21 輪迴圈到 5 type taxonomy 的多 agent 角色設計

    場景

    你接手一個 multi-tenant 專案,系統有 5 個角色(sysadmin / 主委 / 警衛 / 戶長 / 住戶),不同角色有不同 RBAC 權限。你建了 AGENTS.md 派 1 RD + 1 QA,以為這就是 multi-agent team。

    然後出事了。

    本系列【入門篇】· 給「想知道為什麼」的人

    這篇談為什麼 multi-agent 工程需要 cycle file workflow + 5 種 agent type
    怎麼用8 幕劇 · 第一人稱故事 · 真實踩坑反推
    下一步讀完想看 怎麼做(8-stage SOP / 4 個檔範本 / bootstrap)→ 進階篇

    本篇路線圖

    幕 1AGENTS 兩角色跑起來 → 局部檢測 + 不會按角色測(第一次嚴重問題)
    幕 2要求按角色登入測試 → 一天 flip-flop(換角色每次都不對)
    幕 3小白角色誕生 — 不問對錯 / 按 SPEC 走 / 問 PM
    幕 4PM 回到多元職能 → 原本「開發+QA」結構無意義
    幕 5後來踩 R12 — 11 輪 self-audit 還是漏 P1
    幕 6C29 派 5 個 persona — Newbie 多元化
    幕 7從踩坑反推 5 個 type 的形狀
    幕 8每個 cycle 派幾個 — dynamic staffing
    幕 1

    AGENTS 兩角色跑起來:局部檢測 + 不會按角色測

    當時我以為「2 個 agent ping pong」就是 multi-agent。AGENTS.md 配:

    RD agent(寫 code) + QA agent(跑 audit)

    跑起來幾輪後問題顯現,QA 的 audit 有兩個結構性缺陷:

    QA 在做什麼 缺陷 為什麼致命
    ① 局部檢測 只看單一 resolver / 單一 endpoint · 看不到跨檔/跨系統的互動 系統整體性沒被驗
    ② 不會按角色切換進入測試 QA 都用「一個視角」測,從來沒登入過不同 RBAC 角色看是不是被擋對 / 看到對的東西 RBAC 路徑(最重要的安全特性)完全沒檢查

    為什麼「不會按角色測」是嚴重問題

    RBAC 角色 看到什麼 / 能做什麼 沒測會怎樣
    sysadmin跨社區管理cross-tenant leak 沒驗
    主委本社區管理能看到別社區?能改別人家?
    警衛處理包裹/訪客能看到住戶資料嗎?
    戶長管自己家能看到別家的包裹?
    住戶看自己包裹能查到別人寄件?

    第一次嚴重問題:QA 表面綠燈,但 RBAC 跟多租戶隔離這兩條最重要的安全路徑完全沒被驗過——因為 QA agent 從來沒登入過不同角色。系統最該被守住的地方,變成最暴露的地方。

    幕 2

    要求按角色登入測試:一天 flip-flop

    我介入,告訴 Claude:「不要只在後端查 code,實際用各個角色帳號登入測。」

    它真的開始用 sysadmin / 主委 / 警衛 / 戶長 / 住戶 五個帳號登入測。但很快變成:

    輪次 用哪個角色測 QA 說 RD 動作
    輪 1sysadmin抓到 5 個淺問題RD 修
    輪 2主委「剛剛修的東西在主委角度看是不對的」RD 改
    輪 3警衛「警衛角度又不對」RD 又改
    輪 4戶長「戶長角度又不對」RD 又改
    輪 5住戶「住戶角度又不對」RD 又改
    輪 6回到 sysadmin「現在 sysadmin 角度又不對了」(因為剛改的把 sysadmin 弄壞)RD 又改
    …5 個角色輪流每換一個角色就抓到「上輪修壞了」永遠在改

    這樣無限循環了一天

    每輪都是「淺淺檢測 5 個問題 → RD 修 → 換角色又不對」

    最後我叫停。

    失敗 insight:QA 每次按角色測都對(以那個角色的視角看),但加起來都不對(角色之間有衝突)。沒有公共的「對」基準——每個角色都是 QA 自己定義的「對」,沒有 SPEC 在中間定錨。

    幕 3

    小白角色誕生:不問對錯 / 按 SPEC 走 / 問 PM

    叫停之後我重新設計。問題不在「QA 不努力」,在「QA 一邊測一邊自己定義對錯」——這個 mode 永遠 flip-flop。

    新角色:小白。他長這樣:

    小白特性 具體動作 解掉什麼
    ① 不問對錯 只報「我看到什麼」,不下「這對 / 這不對」的判決 QA 自己定義「對」→ flip-flop
    ② 按 SPEC 走 拿 spec 文件去測,測 spec 寫了什麼。Spec 沒寫的就算了 QA 一邊測一邊提新需求 → 規格膨脹
    ③ 有問題問 PM 看到不對勁但不確定 → 報 OPEN finding,送 PM 判 QA 直接 ping RD 修 → 沒人擋
    小白 audit → 報 finding(不下對錯) → PM 對 SPEC 比對 → 是 bug 才給 RD 修

    小白的本質不是「換一種 audit 風格」,是把「判對錯」這件事從 audit 角色拿走,送回 PM 那裡。Audit 只負責觀察,PM 才負責對 SPEC double-check。

    幕 4

    PM 回到多元職能 → 原本的 AGENT 結構無意義

    小白把「判對錯」送回給 PM 之後,PM 不能只當「triage 一個動作」。PM 的職能本來就多元,只是 R35 兩角色設定下我把這層拿掉了。現在它回來了:

    PM 職能 具體動作 為什麼需要
    ① 對 SPEC double-check 每個 finding 拿 SPEC 比對:是不是 bug?還是小白看錯? 提供公共「對」基準
    ② Finding 4 選 1 分判 bug(該修) · feature(進 backlog) · usage(改 docs) · not_issue(close) 不讓所有 finding 都進 fix loop
    ③ 規格定錨 小白報「這應該也要 work」→ PM 判斷該不該加進 SPEC,加的話寫 INV-XXX-NNN 擋 spec 漂移
    ④ 跨角色視角整合 這個 finding 在 sysadmin 角度跟主委角度有衝突 → PM 拿 SPEC 判哪個角色該贏 解掉幕 2 的「換角色 flip-flop」

    原本的 AGENTS.md 結構變無意義

    最早 AGENTS.md(失敗) 小白 + PM 出現後
    RD agent RD 還在,但只接 PM triage 過的 bug
    QA agent(直接 ping RD) 變小白(不問對錯 / 按 SPEC / 報 PM)
    (沒有 PM) PM 多元職能進場
    結構:RD + QA ping pong 結構:小白 → PM → RD 三角入口

    學到的事 → Multi-agent 不是「派幾個 agent」的問題,是「agent 之間誰擋誰、誰判對錯」的問題。沒有公共 SPEC + PM 守門,任何 audit 方式都會撞 flip-flop。

    幕 5

    後來踩 R12:11 輪 self-audit 還是漏 P1

    小白 + PM 結構穩定後 cycle 順暢很多。我以為角色設計問題解了。然後 R12 cycle 出事。

    R12 cycle 條件 數字 / 結果
    我自己跑 audit11 輪
    場景文件覆蓋132 個
    所有人簽 ✅RD ✅ · PM ✅ · 我 ✅ → merge
    事後發現P1 漏掉:戶長能看到整個社區的資料

    為什麼 11 輪 + 132 場景還漏?

    11 輪 self-audit 11 個獨立檢查
    同一個視角(我自己)跑 11 次11 個不同視角各跑一次
    寫的時候的盲點,驗的時候也是盲點不同視角會覆蓋不同盲點
    132 場景由同一視角設計不同視角會想到不同場景
    ≠ 等號不成立

    解法:把小白進化成「fresh newbie」(零 context)

    Newbie 條件全新 sonnet,沒給過去 11 輪的 audit context · 不知道之前抓過什麼
    紀律沿用小白規矩(不問對錯 / 按 SPEC / 問 PM),只是「context 比小白更乾淨」
    結果第一輪就抓到那個 P1

    學到的事 → 小白本身不夠,要再進化成「零 context」的 fresh newbie——避免「跑著跑著也累積成跟原 audit 同視角」的退化。

    幕 6

    C29:派 5 個 persona 平行 audit

    一個 fresh newbie 補一個盲點。不同 newbie 帶不同假設 → 平行補多個盲點。所有 finding 仍走 PM triage,不直接給 RD。

    # Persona 他的世界假設 抓到的盲點
    ① 高吞吐警衛阿伯 每天 300 件包裹,每秒都要省 FAB 排太多 · 批次掃描藏在三點選單
    ② 無棟透天主委 12 戶共一棟,沒有「A 棟 B 棟」 後端硬擋空「棟」欄位
    ③ 多棟社區主委 5 棟,選戶必須先選棟 picker dropdown collision
    ④ 老年用 iPhone 11 375px 螢幕、視力差 FAB 不在拇指區、按鈕找不到
    ⑤ 跨租戶 RLS 測試者 拿 A 社區帳號戳 B 社區資料 RLS policy 守不守得住

    5 個 persona 抓出 23 個 finding

    4 個 cycle blocker · 全部都是 PM + 我自己漏掉的

    小白 → newbie → persona newbie 的進化線

    代 設計 解掉什麼
    第一代
    小白    		 不問對錯 / 按 SPEC / 問 PM QA 自己定義對 → 換角色 flip-flop
    第二代
    Fresh Newbie    		 零 context · 不知道過去 audit 結果 小白跑久了累積成跟原 audit 同視角 → shared assumption
    第三代
    Persona Newbie    		 多 persona 平行 · 各自帶不同世界假設 單一視角必有盲點 → 多視角覆蓋
    幕 7

    從踩坑反推:5 個 type 的形狀

    走過這幾個踩坑,5 個 agent type 不是想像出來的,是反向工程的結果:

    Type 動作 並行? 從什麼反推
    Writer 寫 code / spec / migration NO(單線程) 原本 RD 角色 · 兩 writer 平行會打架
    Verifier scope 鎖死 1-3 INV 的 audit · 按 SPEC 走 YES 第一代小白 · 解「QA 自己定義對」
    Triage 對 SPEC double-check · 4 選 1 分判 · 規格定錨 · 跨角色整合 NO(人類) PM 多元職能 · 解「換角色 flip-flop」
    Comparison 零 context 的獨立 verifier · 不知道原 audit findings YES 第二代 fresh newbie · R12 11 輪漏 P1 · shared assumption
    Newbie Adversarial persona-driven audit YES 第三代 persona newbie · C29 23 finding · 單一視角盲點
    傳統 8 職稱 這 5 個 type
    架構師 / PM / UI-UX / 後端 / Flutter / DBA / QA Writer / Verifier / Triage / Comparison / Newbie
    組織圖長相 · 看起來工整 動作類型(寫不寫 / 並行不並行 / 判不判對錯)
    寫進 AGENTS.md 之後 cycle 跑起來,只有 PM/QA 對應到事故學到的 每個 type 對應一條真實踩坑
    幕 8

    每個 cycle 派幾個?

    5 個 type 有了。但每個 cycle 派多少?不同 cycle 規模需要不同編制:

    Cycle 規模 派誰 總 RAM 為什麼
    改 1 行 typo RD-Sonnet + Verifier-Haiku ~1.0 GB 簡單變動 · 簡單覆蓋
    中等 PR RD-Sonnet + 2 Verifier-Haiku + Comparison-Haiku ~2.2 GB 中等變動 · 需 cross-check shared assumption
    大改 schema(含 RBAC) RD-Opus + 3 Verifier-Sonnet + Comparison-Haiku + 5 Persona-Newbie ~5.5 GB 大變動 + 跨角色 · 需多視角補 RBAC 盲點
    固定編制(每 cycle 都派同樣 N 個) Per-cycle dynamic staffing
    小 cycle 浪費資源小 cycle 派 2 個 agent
    大 cycle 漏 perspective大 cycle 派 9 個 agent
    9 Opus 撐爆 16 GB 機器每 cycle 算一次 budget

    規劃 vs 執行 staffing 分離

    AGENTS.md不變部分(taxonomy + RAM 上限 + Iron Rules) · 半年不變
    docs/cycles/Cn-*.md Header具體 staffing(派誰 / 什麼 model / 多少 RAM) · 每 cycle 重算
    前者性質規劃文件
    後者性質執行契約

    結語:cycle file 是這故事的結晶

    維度 補丁 從什麼反推
    角色 5 個 type taxonomy + PM 多元職能 + 小白進化線 局部檢測 / 不會按角色測 / 換角色 flip-flop / shared assumption / 單一視角盲點
    流程 8-stage SOP + 小白 → PM → RD 三角入口 沒收斂條件 / 沒規格定錨 / 沒 SPEC 守門員
    資源 per-cycle dynamic staffing 固定 9 Opus 撐爆機器

    cycle file workflow 的價值不是「設計得多漂亮」,是「每個設計選擇都對應到一個踩過的坑」。Multi-tenant + RBAC 系統的盲點不是「LLM 不夠強」,是「沒有公共 SPEC 守門員 + 多元視角覆蓋」就會撞牆。

    你接手新專案那天

    需要什麼4 個檔案 + 一段 bootstrap prompt
    完整版在哪進階篇

    系列文章

    第一篇「56 條 INV 全綠,user 點一次抓出 4 個 bug」— Multi-Agent 業界共識的五個自家補丁
    進階篇Cycle File:Multi-Agent 工程的狀態接力棒 — 完整 SOP / 8-stage / 4 個檔範本
    呼應業界Multi-Agent 架構再探: 三省六部反模式和業界收斂共識(愛好 AI 工程)

  • Cycle File:Multi-Agent 工程的狀態接力棒 — file-as-state-machine 方法論

    重點摘要

    • 動手的 agent 只能一個(寫入單線程)。但同一個 agent 不可能從頭做到尾,工作數小時後注意力品質下降(context rot)。
    • 解法不是換 agent,也不是加 agent,是讓「下一個 agent」能無痛接手。接力棒設計才是 multi-agent 工程的真正關鍵。
    • Cycle file = file-as-state-machine:把每個 cycle 的完整狀態寫進一份 markdown,活在 git,跨 session 可讀,撐過對話 compaction。
    • 8-stage 結構每個 stage 對應一個 multi-agent 容易踩到的坑:baseline 污染、ripple effect、vacuous test、groupthink。
    • 5 種 cycle type,各有 stage profile。不是每個 cycle 都跑 8-stage,硬塞會浪費或漏。
    • file-as-state-machine 不只 multi-agent 用得到。ADR、RFC、postmortem 都是這個 pattern,multi-agent workflow 把它的價值放大 100×。
    • 新環境 bootstrap:4 個檔案 + 一段 prompt,就能在新電腦 / 新 Claude Code / Antigravity / Codex / Cursor / Aider 上啟動這套流程,不分工具。

    本系列【進階篇】。提供完整 SOP 跟 4 個檔範本,假設你已經知道為什麼 multi-agent 工程需要 cycle file workflow。還沒看過為什麼?先讀 入門篇:「為什麼修不完?」— 從 21 輪迴圈到 5 type taxonomy 的多 agent 角色設計——用第一人稱故事告訴你 5 個 agent type 是怎麼從踩坑反推出來的,讀完再回來看這篇就會懂為什麼這 4 個檔長這樣。

    Multi-agent 工作流有個業界共識的硬約束:同時間只能有一個 agent 動手寫(寫 code / 寫 spec / 寫 migration)。多個 agent 平行寫產生隱性風格 + 決策衝突,Cognition / Anthropic / Stanford 都從不同角度驗證過這條。

    但這條約束衍生一個立刻撞上的問題:

    寫入單線程沒錯,但一個 agent 怎麼跑一個多月的長期專案不撞 context rot?同一個 agent 從第一週寫到第六週,中間累積的對話歷史不會把它壓垮嗎?

    答:不是「一個 agent 跑到底」,是「每個 cycle 換新 agent,cycle file 接力」。

    這篇講 cycle file 設計方法論——為什麼必須是檔案不是對話、為什麼必須在 git 不能在 Notion、8-stage 結構每個 stage 對應哪個 multi-agent 踩坑,以及這個 pattern 怎麼推廣到 ADR / RFC / postmortem 這類非 multi-agent 場景。

    對照組:傳統工業界 RD 開發流程

    在進入 multi-agent cycle file 方法論之前,先把工業界標準的 RD 開發流程攤開——對照基準清楚了,後面的對應關係才好讀。本文不是發明新流程,是把這套經典 SDLC 對應到能跑在多個 AI agent 上的 cycle file 結構。

    經典流程九步

    1. PM 整理需求 — business requirement,decide what to build
    2. SA 分析需求(可由 PM 兼任)— 系統分析,what the system must do
    3. SD 設計需求(可由 PM 兼任)— 系統設計,how the system should do it
    4. RD 撰寫程式 — implementation
    5. RD 自測後交付 — pre-PR self-test
    6. QA 進行測試,建立錯誤表 — finding list,QA 只報事實不下 P0/P1
    7. PM 確認錯誤表,跟 SPEC 比對 — triage:是 bug 還是 feature 還是 usage 還是 not_issue
    8. 交給 RD 修正 → 修正後再給 QA → PM,持續 loop — 直到 PM 點頭。這個 loop 是品質的核心,不是 bug,是設計
    9. 上到 GA 區,以正式資料進行測試 — production smoke,真實數據才能發現假性綠燈

    測試分三段——這三段不能混

    類型 內容 在 cycle file 對應
    測試程式 unit test / integration test / E2E test scripts Stage 5a failing test + Stage 5c regression suite
    測試環境 staging server / sandbox / test docker compose / backend services Stage 0.5 Pre-cycle hygiene 確認所有服務 up
    測試資料 fixture / seed data / disposable test users / canonical baseline Stage 0.5 fixture reset + disposable qa_* fixtures

    經典流程 ↔ Cycle file 對應

    傳統 RD 流程 Cycle file 對應 stage
    PM 整理需求 Cycle file Header 的 spec section + related INV
    SA / SD 分析設計 Spec.md + invariants.md 條目(契約寫死)
    RD 撰寫 + 自測 Stage 1 RD 自測(單線程,一個 agent 動手)
    QA 測試 + 錯誤表 Stage 2 QA wave 並行 + Stage 3 OPEN findings
    PM 確認比對 SPEC Stage 4 PM triage(bug / feature / usage / not_issue)
    RD 修正 → QA → PM loop Stage 5 fix → Stage 6 regression → Stage 7 comparison QA → 回 Stage 3
    PM 點頭 Stage 8 merge gate(全綠才合)
    上 GA 區正式資料測試 Production smoke + user smoke(primary detection,觸發 T-user-smoke-followup cycle)

    關鍵差別:傳統流程角色是「人」(PM / SA / SD / RD / QA),cycle file workflow 把這些角色變成「agent 在不同 stage 的職責」——同一個 LLM agent 在 Stage 1 是 RD,在 Stage 2 wave 之中扮演 QA(但 scope 鎖死),Stage 7 是 comparison QA。PM 永遠是人,因為「跟 SPEC 比對 + 做價值判斷」這層 LLM 不該越界。

    §1 為什麼「對話 context」是錯誤的狀態載體

    多數人用 Claude / GPT / Cursor / Aider 寫 code 的時候,默認狀態活在對話裡——上一句問題、AI 上一個回應、再上一個截圖,都在 chat history 裡。看起來理所當然,直到撞到三個事實:

    1. 對話會壓縮(compaction)。主流工具在 context 接近上限時都會自動壓縮歷史。「我剛剛跟你說過 X」這句話,壓縮一輪後就變成「我們討論過某些事」。具體細節進了 summary,但 summary 本身會再被壓縮。資訊密度持續下降。
    2. 對話只活在單一 session。開新 session = 全新對話,讀不到上次的 context。即使有 memory file(persistent profile / preferences),那是「人格 / 偏好」層,不是「這個專案這個 PR 跑到哪了」的狀態。
    3. 對話沒 git history。半年後翻回去看「為什麼這個 PR merge」,翻 chat log 是不可能任務——對話沒 commit message、沒 tag、沒 diff,review 工具完全用不上。

    傳統 workaround 是「我把上下文 paste 進新 session」。這是 fragile 的——你會漏、你會省略、你會把 600 字濃縮成 30 字然後新 session 推不出原本的決策邏輯。

    結論:對話狀態必然會掉,任何長期 multi-agent workflow 都要把 state 寫到對話以外的地方。Cycle file 是其中一種具體實踐。

    §2 Cycle File 的核心思想:file-as-state-machine

    一個 cycle file = 一個 PR cycle 的完整狀態機。離散的 stage 有明確 entry / exit 條件,跨 session 接手 = 讀檔不是讀對話。

    為什麼必須是 markdown 不是 JSON / DB

    • Human-AI 雙方都能讀。人要看,AI 要讀,PR reviewer 也要看。Markdown 是最低共通格式。
    • Diff 友善。Stage 3 加一個 finding,git diff 看得清清楚楚。JSON 一改整個檔重排,DB 改一個 row 沒 diff。
    • 離 code 近。docs/cycles/Cn-*.md 跟 source code 在同一個 repo,branch 切換時 cycle file 也跟著切換。

    為什麼必須在 git 不能在 Notion / Confluence

    • Audit trail。每次 cycle file update 都是一個 commit,who / when / why 一目了然。Cloud doc 改了就改了,沒人記得是誰改的。
    • 跟 code 同生死。Branch 跟 cycle file 綁在一起,rebase / cherry-pick / revert 都會帶走 cycle file。Notion 不知道 code 在哪個 branch。
    • 跨工具不依賴。Cloud doc 服務掛了 cycle file 就讀不到。Git 不會掛——而且即使原 repo 沒了,每個 clone 都有完整歷史。

    §3 8-stage 結構——每個 stage 對應一個 multi-agent 踩坑

    本節拆 cycle file 8-stage 的標準結構,標出每個 stage 對應哪個 multi-agent 容易撞的坑。

    Header — cycle 身分證

    # Cycle Cn — <short PR title>

Owner: <engineer agent / human>
Started: YYYY-MM-DD HH:MM
Status: open / in_qa / in_triage / in_fix / regression / closed
Cycle Type: T-PR-cycle / T-regression-fix / T-feature-cycle /
            T-spec-audit / T-user-smoke-followup / T-mutation-test
Related:
  - PR / branch: <commit_sha>
  - Spec section: <§X.Y>
  - Primary INV(s) targeted: INV-XXX-NNN

    下個 agent 接手第一件事是讀 Header。Cycle Type 決定哪些 stage 必經、哪些 N/A——不分 type 把所有 cycle 都當 PR-cycle 跑,結果 regression-fix 跑 8-stage 浪費,user-smoke-followup 跑 8-stage 又錯位(user 已經是 primary detection 了,還跑 QA wave 是反過來)。

    Stage 0.5 — Pre-cycle hygiene

    • git status --short clean(除了本 cycle 將動的 file)
    • HEAD = <commit-sha>,不是 mid-rebase / mid-merge state
    • seed / fixture reset script 跑過,fixture 為 canonical
    • 列出本 cycle 將建立的 disposable test fixtures,不複用共享 fixture
    • 所有相關服務 healthy(backend / proxy / DB / storage 皆 up)

    對應的坑:跨 cycle 副作用會讓新 cycle 在污染狀態跑出 false positive ✅。上輪 cycle 殘留的 test payload、未清的 disabled user、過期的 rate-limit lockout——新 agent 進場已經在污染狀態,QA wave 跑出來的綠燈是 false confidence。Pre-cycle baseline check 是唯一的事前防線。

    Stage 1: RD 自測

    • 單元測試全綠(附 commit SHA)
    • Live smoke:對 endpoint X / user Y 跑 happy path(寫一兩行紀錄)
    • PR header 完整(INV 宣告 / QA scope / Verification 三段)

    RD 在開 PR 之前就先過自己的關。沒過自測的 PR 連 Stage 2 都進不去——直接退回。

    Stage 2: QA wave(並行讀取)

    2-4 個 QA agent 並行,每個 scope 鎖死 1-3 個 invariant。這是 multi-agent「平行覆蓋」的核心場景——讀取不衝突。

    QA agent A — INV-XXX-NNN red-team
QA agent B — INV-YYY-MMM regression
QA agent C (optional) — same scope as A, no knowledge of A's findings
                       (consistency check; 結果一致則 spec 寫得清楚,
                        不一致則 spec 有歧義先收斂)

    QA agent 只能標 ✅ / ❌ / OPEN,絕對不准標 P0/P1——那是 PM 的 authority。OPEN 一律往 PM triage 走。

    Stage 3: OPEN findings(等 PM triage)

    所有 QA agent 的 OPEN finding 收進一張 finding table。Finding 格式:

    ### Finding F-Cn-001
- QA agent: A
- Resolver/Feature: <name>
- Observed: <事實>
- Repro: <exact commands>
- PM triage:
  - Class: bug / feature / usage / not_issue / spec_clarification
  - Confidence: high / low
  - Reasoning: <≤2 sentences citing spec/INV>
  - User review needed: yes / no

    Findings ≥3 時派 PM-agent 跑 first-pass triage,user 只 review confidence=low 與 class=spec_clarification 兩類。Findings ≤2 user 直接判,省 round-trip。

    Stage 4: User review(只看 low-conf)

    User 對每個 confidence=low 或 spec_clarification 項目走 PM triage 分判,30 秒一個 finding。超過 2 分鐘 = finding 太大,要拆。

    Downstream sweep(Stage 5 之前必填)

    本 cycle 改動的 state(DB tables / schema / role-cap definition / fixture state),列出有哪些其他 resolver / query 會讀到。grep 全 repo 找 reader,寧可 false positive 多列幾條,少列就漏 ripple。

    對應的坑:改動會 ripple 到 cycle scope 外的 readers,沒 explicit list 必漏。經典場景:Cycle A 改了 fixture seed script,衍生 1 小時後 user 點 dashboard 某個 tab 崩。原因是 Cycle A 改了某張表的 state,影響到 cycle scope 外的另一個 resolver——那個 resolver 不在 Cycle A 的測試範圍裡,沒人提醒去看,bug 就溜進去。Downstream sweep 強制 RD 在 Stage 5 開修前 explicitly list ripple 範圍,Stage 6 regression 必須 cover。

    Stage 5: RD fix(TDD red-green 拆 5a / 5b / 5c)

    Stage 5a — write failing test
  - 寫 test 對應 invariant / 對應 finding attack scenario
  - 跑 test → 預期 ❌ red(沒紅 = test 寫錯)
  - commit "test: failing test for F-Cn-NNN / INV-XXX-NNN (red)"

Stage 5b — implement fix
  - 寫 fix
  - 重跑 5a 的 test → 預期 ✅ green
  - commit "fix: ... (green via test in <5a-sha>)"
  - commit message 必填 "Failing test verified at: <5a-sha>"

Stage 5c — refactor + regression
  - refactor 必要時
  - 跑全套既有 test 確認無 regression

    對應的坑:「test + fix 同 commit」沒驗 test 真的會抓對應 bug,可能是 vacuous test(永遠 pass 但不 cover 要 cover 的 case)。沒有「test 先 ❌、fix 後 ✅」這個 TDD 基本動作,你不知道 test 是真的在驗還是空跑。拆三個 commit 的好處是 bisect 看得出 red→green 軌跡。

    Stage 6: Regression

    Stage 5 fix 跑完,QA agent 重跑 Stage 2 的 wave(同樣的 prompt,只是 commit SHA 換成 fix sha)。Downstream sweep 列出的 ripple 範圍必須驗。

    Stage 7: Comparison QA(對抗 groupthink)

    派一個全新的 QA agent(不告訴它原 QA 抓到什麼),跑同一份 PR。如果它抓出新 finding = 原 QA 還有盲點。如果它跟原 QA 結論一致 = 確認可信。

    對應的坑:QA agent + Engineer agent 同 LLM 譜系,想得到的 attack scenario 高度重疊,共有盲點。Comparison QA 是減輕 groupthink 的最低成本做法——成本是多派一個 agent,收穫是另一個視角的覆蓋。

    Stage 8: Merge gate

    要合 PR,全部都要打勾:

    • PR header 完整(INV 宣告 / QA scope / Verification)
    • 宣告的「滿足」invariant:兩個 QA agent 都報 ✅
    • 宣告的「可能影響」invariant:回歸都 ✅
    • 兩個 QA agent 報告結論一致
    • OPEN list 清空(全部 triage 完)
    • 單元測試綠
    • 如 PR 影響 UI → 手動 smoke 一次 happy path

    Stage 8 全綠才 merge,cycle file commit 留檔,close cycle。

    §4 Cycle Type — 5 種 stage profile,不是每個 cycle 都跑 8-stage

    「Cycle Type」field 解決一個很實在的問題:不同性質的 cycle 用不同 stage profile,硬塞 8-stage 會浪費 stage 或漏 stage。

    Cycle Type 觸發 Stage profile
    T-PR-cycle 開 PR 等 merge 完整 8-stage(QA wave + regression + comparison newbie)
    T-regression-fix Engineer / agent 自抓 regression 5-stage:skip Stage 2 QA wave + Stage 4 user review;root cause 在 cycle file 開頭講清
    T-feature-cycle Forward-going 新 feature Stage 5 在 Stage 2 之前(先實作再 QA wave 對 INV 驗證)
    T-spec-audit 隨機抽樣 / category 全驗 Stage 2 only + report;無 fix。Findings raise 為 OPEN 給 PM
    T-user-smoke-followup User 直接報 bug Stage 3 直接收 finding(user 是 primary detection)+ skip Stage 2;後續 5/6/7/8 全跑

    Cycle file 開頭強制填 Cycle Type: T-XXX,Stage 8 merge gate 只 enforce 該 type 必經的 stage。

    §5 三個工程效益——為什麼這個設計值得

    效益 1:撐過對話 compaction

    對話被壓縮的時候,壓的是 chat history,不是 git artifact。下個 session 我打開 docs/cycles/Cn-*.md,完整的 persona、attack scenario、findings、PM triage 結果都還在。

    對照組:如果這些資訊只活在對話裡,compaction 一輪 → 只剩「我們做了一些 QA」這種無資訊摘要 → 下個 agent 接手等於從零開始。

    效益 2:跨 session / 跨 agent 可讀

    新 agent invocation(無論是新 session、不同 agent、甚至不同人接手),讀檔就能上工。長期專案累積的 cycle 是獨立 Engineer invocation,每個 cycle 開頭讀 workflow SOP + invariants 契約 + 當前 cycle file 進度,3 分鐘進入狀況。

    對照組:沒 cycle file 的話,新 agent 進場第一件事是「請告訴我前面跑到哪了」——你自己要把 600 行對話濃縮 paste 給它,中間漏東漏西。

    效益 3:6 個月後的自己有 audit trail

    半年後 grep 某條 invariant ID,找到這條 invariant 是哪個 cycle 加的、為什麼加、當時 PM 怎麼判的——全部在 git 裡,commit message 帶 finding ID。

    對照組:Cloud doc 寫的 ADR、Confluence 寫的 design doc——半年後權限過期、url 換掉、search 找不到。

    §6 推廣:file-as-state-machine 不只 multi-agent 用得到

    Cycle file 的核心是 file-as-state-machine:把工程過程的 state 從「對話 / 會議 / 腦袋」搬到「檔案 / git」。這個 pattern 在傳統軟工不是新東西,只是名字不一樣。

    名稱 用途 跟 cycle file 共同性質
    ADR(Architecture Decision Record) 記錄架構決策的 context / 選項 / 決定 / 後果 活在 git,撐過人員流動,6 個月後可 audit
    RFC(Request for Comments) 大型 feature 的設計提案 + comment trail 同上;增加 review 階段的離散 stage
    Postmortem incident 事後分析 + 行動項 同上;Stage 包含 timeline / root cause / action items
    Cycle file single PR 的完整 lifecycle 同上;比 ADR/RFC 更短週期、更高頻次

    共同性質:把工程過程的 state 從可揮發載體(對話、會議、腦袋)搬到不可揮發載體(git、版控檔案)。對 single-developer 也有用——你不會記得三個月前為什麼選 PostgreSQL 而不是 MySQL,但 ADR 會記得。

    對 multi-agent 工作流,這個 pattern 的價值放大 100×。因為 multi-agent 有兩個額外的揮發源:

    • 對話 compaction(每幾小時就一次)
    • 跨 session / 跨 agent 切換(每個 cycle 一次)

    Single-developer 的對話 context 一個專案可能撐幾天,multi-agent workflow 可能撐幾小時。Cycle file 的「狀態接力棒」價值在 multi-agent 場景才完整展現。

    §7 在新環境啟動這套流程——4 個檔案 + 一段 bootstrap prompt

    如果今天換新電腦、開新專案、或換工具(Claude Code → Antigravity / Codex / Cursor / Aider),怎麼快速把這套 cycle workflow 啟動到「下一個 agent 進來就能照跑」的狀態?答案是最小可行 kit:4 個檔案 + 一段給 agent 的開場白。

    最小可行 kit:4 個檔案

    檔案 內容 變動頻次
    docs/workflow.md 8-stage SOP 完整版(本文 §3 內容) 每 retro 一次 amend
    docs/cycle-template.md Cycle file 結構 template(複製即可填) 穩定,少改
    docs/invariants.md 所有 INV-XXX-NNN 契約列表(初始空白,隨 cycle 累積) 每 cycle 可能 amend
    AGENTS.md Role taxonomy(perspective-driven,不是 8 職稱)+ 資源預算上限 穩定,專案改 tech stack 時才動

    這 4 個檔不是「規劃文件」,是「執行契約」——每 PR 強制讀,違反退回。具體 staffing / per-cycle 進度寫在 docs/cycles/Cn-*.md。

    4 個檔案的最小內容範本

    下面 4 段是直接可複製貼到專案的 minimal 內容。Day-1 把這 4 個檔放進 docs/ 跟 root 之後,就有完整的 cycle workflow kit,新 agent 進來照走。

    檔案 1/4 — docs/workflow.md

    8-stage SOP 的 skeleton。詳細每個 stage 規則見本文 §3,這份 skeleton 是「每個 agent 開工前必讀」的最小契約版本。

    # Workflow SOP — Cycle-based PR Pipeline

> 所有 PR 走 cycle file 流程。違反 stage 順序的 PR 直接退回。

## 8 Stages

| Stage | 動作 | 誰做 | 必經? |
|---|---|---|---|
| 0.5 | Pre-cycle hygiene (baseline 乾淨確認) | Writer | yes |
| 1 | RD 自測 (unit test + live smoke + PR header) | Writer | yes |
| 2 | QA wave (2-4 verifier 並行,每個 scope 鎖 1-3 INV) | Verifier(s) | yes (PR-cycle) |
| 3 | OPEN findings table (QA agent 收 finding) | Verifier | yes |
| 4 | PM triage (bug / feature / usage / not_issue 分判) | PM / Triage | yes |
| Downstream sweep | grep 列出 ripple 範圍 (本 cycle scope 外的 readers) | Writer | yes |
| 5 | RD fix — 5a 寫 failing test → 5b 寫 fix → 5c refactor | Writer | yes (有 bug 才跑) |
| 6 | Regression (重跑 Stage 2 wave,scope 含 ripple) | Verifier | yes |
| 7 | Comparison QA (新 agent 不知道原 QA 結果,re-audit) | Verifier | recommended |
| 8 | Merge gate (全綠才合) | Writer + PM | yes |

## 5 Cycle Types (決定哪些 stage 必經)

| Type | 觸發 | Stage profile |
|---|---|---|
| `T-PR-cycle` | 開 PR 等 merge | 完整 8-stage |
| `T-regression-fix` | engineer 自抓 regression | 5-stage:skip Stage 2 + Stage 4 |
| `T-feature-cycle` | forward-going 新 feature | Stage 5 在 Stage 2 之前 |
| `T-spec-audit` | 隨機抽樣 / category 全驗 | Stage 2 only + report (無 fix) |
| `T-user-smoke-followup` | user 報 bug | Stage 3 直接收 finding,skip Stage 2 |

## Iron Rules (執行契約,違反退回)

1. **寫入單線程**:同時間只能 1 個 Writer agent 動手。其他 agent 都不准動 code / spec / schema / migration。
2. **Verifier 不准標 P0/P1**:只能 ✅ / ❌ / OPEN。嚴重度是 Triage 的 authority。
3. **Verifier scope 鎖死 1-3 INV**:不准「找任何 bug」(R35 21 輪迴圈的反面教材)。
4. **TDD red-green 拆三 commit**:Stage 5a failing test red commit → 5b fix green commit (帶 `Failing test verified at: <5a-sha>`) → 5c refactor。`test+fix 同 commit` = 沒驗 test 有效。
5. **修了 bug 必須加 INV 到 `docs/invariants.md`**:沒加不算修完。半年後同類 bug 一定回來。
6. **cycle file 留檔不刪**:cycle 收完 commit 進 git,當作 audit trail。
7. **每月 retro amend workflow.md**:漏掉的 bug / 浪費的 stage / 卡住的 finding → 回頭改 SOP。

    檔案 2/4 — docs/cycle-template.md

    每個 cycle 開頭從這份複製出 docs/cycles/Cn-<topic>.md(n 是流水號,grep 看下一個)。照著填,不要自己改 stage 結構。

    # Cycle Cn — <short PR title>

**Owner**: <agent ID / human>
**Started**: YYYY-MM-DD HH:MM
**Status**: open / in_qa / in_triage / in_fix / regression / closed
**Cycle Type**: T-PR-cycle / T-regression-fix / T-feature-cycle / T-spec-audit / T-user-smoke-followup
**Related**:
- PR / branch: <commit_sha or branch>
- Spec section: <§X.Y or "N/A">
- Primary INV(s) targeted: INV-XXX-NNN, INV-YYY-MMM

---

## Stage 0.5 — Pre-cycle hygiene

- [ ] `git status --short` clean (除了本 cycle 將動的 file)
- [ ] HEAD = <commit-sha>
- [ ] fixture reset 跑過, baseline canonical
- [ ] 列出本 cycle 用的 disposable fixtures (qa_<cycle>_<role>_<timestamp> prefix)
- [ ] 所有相關服務 healthy

## Stage 1: RD 自測

- [ ] unit test 全綠 (commit: <sha>)
- [ ] live smoke 紀錄:<endpoint X / user Y / happy path 結果>
- [ ] PR header 完整 (滿足 INV / 可能影響 INV / 提議新增 INV 三段)

## Stage 2: QA wave

### QA agent A — INV-XXX-NNN red-team
- Launched: HH:MM
- Result: ✅ / ❌ / OPEN
- Findings: <count>

### QA agent B — INV-YYY-MMM regression
- Launched: HH:MM
- Result: ✅ / ❌ / OPEN

## Stage 3: OPEN findings

### F-Cn-001
- QA agent: A
- Resolver/Feature: <name>
- Observed: <事實,不下判斷>
- Repro:
  ```
  <exact commands / GraphQL / curl>
  ```
- PM triage:
  - Class: bug / feature / usage / not_issue / spec_clarification
  - Confidence: high / low
  - Reasoning: <≤2 sentences citing spec/INV>
  - User review needed: yes / no

(repeat for each finding)

## Stage 4: User review (only low-conf items)

- [ ] F-Cn-XXX user-confirmed class: <class>

## Downstream sweep (Stage 5 之前必填)

### 本 cycle 改動的 state
- DB tables: <list>
- Schema: <changes>
- Fixture state: <changes>

### 讀取上述 state 的其他 resolver / query

| State | Reader | Stage 6 必驗 |
|---|---|---|
| <table_X> | <Resolver A / Query B> | ✅ |

## Stage 5: RD fix

### Stage 5a — failing test (red)
- Test 檔: <path>
- 跑出 red: commit <5a-sha>

### Stage 5b — implement fix (green)
- Fix commit: <5b-sha> (帶 `Failing test verified at: <5a-sha>`)

### Stage 5c — refactor + regression
- 全套既有 test pass: ✅

## Stage 6: Regression

- QA wave 重跑 (scope 含 downstream sweep ripple)
- 結果: ✅ / ❌

## Stage 7: Comparison QA

- 新 verifier 不告知原 QA 結果, re-audit
- 結論: 跟原 QA 一致 / 不一致

## Stage 8: Merge gate

- [ ] PR header 完整
- [ ] 宣告的「滿足」INV: ✅
- [ ] 宣告的「可能影響」INV regression: ✅
- [ ] 兩個 QA agent 結論一致
- [ ] OPEN list 清空
- [ ] unit test 綠
- [ ] 如影響 UI: manual smoke happy path

---

## Cycle close

- **Closed**: YYYY-MM-DD HH:MM
- **Outcome**: merged-on-dev / abandoned / split into Cn+1
- **Total commits**: <count>
- **New INVs added**: <list>
- **Bugs fixed**: <count>
- **Lessons** (going to brain): <bullet points>

    檔案 3/4 — docs/invariants.md

    專案的 invariant 契約 catalogue。初始空白,隨 cycle 累積。每修一個 bug 必須在這加對應條目——沒加不算修完。半年後 grep 某個 INV ID 應該找得到「誰加的、為什麼加、對應哪個 test」。

    # Invariants — Project Contract Catalogue

> Every invariant here is a contract. Code must hold. Tests must verify.
> Format: `INV-<CATEGORY>-<NNN>: <statement>` + origin + severity + test ref.

## Categories (調整為你專案實際需要的)

- `INV-AUTH-*` — authentication / session / token rotation
- `INV-RBAC-*` — role-based access control / capability checks
- `INV-RLS-*` — row-level security (multi-tenant isolation)
- `INV-DATA-*` — data integrity / nullability / FK / atomicity
- `INV-IDEM-*` — idempotency (probe-then-INSERT, advisory locks)
- `INV-INPUT-*` — input validation / sanitization
- `INV-UI-*` — frontend behavior contracts
- `INV-RESOLVER-*` — resolver-level contracts (scope, error shape)
- `INV-SCHEMA-*` — schema design constraints (反 over-design 用)
- `INV-BATCH-*` — batch operation invariants

## Verification Layer Reference

每條 INV 標 verification layer:

- L0 spec / L1 INV / L2 schema / L3 resolver / L4 frontend / L5 E2E

(同一條 INV 可能 multi-layer。看本文 §5 對 6-layer doneness 的說明。)

---

## Invariants

### INV-AUTH-001 (example template — 換成你的)
- **Statement**: <one-line contract,可被測試直接驗證>
- **Origin**: Cycle C<n> (YYYY-MM-DD) — <short context, why this surfaced>
- **Severity**: P0 / P1 / P2
- **Test**: <path/to/test.go::TestFuncName> or <❌ TODO in backlog>
- **Enforcement layer**: L1 + L3
- **Related findings**: F-C<n>-NNN

---

## Backlog (test ❌ TODO)

當你寫了 INV 但 test 還沒寫完時, 標 ❌ 放這裡。半年後拿這個 backlog 跑「補測試 sprint」:

- ❌ INV-XXX-NNN (待補 integration test)
- ❌ INV-YYY-MMM (待補 E2E test)

---

(initial state: empty — populate as cycles surface bugs.
每 fix commit 必須在這加對應 INV, 沒加不算修完。)

    檔案 4/4 — AGENTS.md

    Role taxonomy + 資源預算。不寫具體職稱(架構師 / PM / UI-UX / 後端 / Flutter / DBA / QA)——那是死文件做法。寫的是「執行類型」(Writer / Verifier / Triage / Comparison / Newbie) + 機器資源上限,具體 staffing 在每個 cycle file 的 Header 裡。

    # Agents — Role Taxonomy + Resource Budget

> Roles are **perspectives**, not headcount. Agent count is an OUTPUT
> of staffing per cycle, declared in each cycle file Header.
> This file holds only the **invariant** parts: budget ceiling + type taxonomy.

## Resource Budget (本機, 改成你的數字)

| Item | RAM | Notes |
|------|-----|-------|
| Total RAM | 32 GB | This machine |
| OS + Docker + browser reserve | ~7 GB | Baseline |
| **Available for agents** | **~22 GB** | Max budget |

## Model Memory Reference (Claude Code)

| Model | RAM | When to use |
|-------|-----|-------------|
| Opus | ~1.0 GB | architecture / cross-file reasoning / security / senior thinking |
| Sonnet | ~0.6 GB | implementation / API / tests / documentation |
| Haiku | ~0.4 GB | file scanning / config compare / simple SQL / read-only audit |

口訣:需要「想」→ Opus | 需要「做」→ Sonnet | 需要「找」→ Haiku

## Role Taxonomy (perspectives, not job titles)

| Type | Action | Parallelizable? | Typical model | Notes |
|------|--------|----------------|---------------|-------|
| **Writer** | mutate files (code / SQL / migration / spec) | NO (single-thread) | Sonnet / Opus | 同時只 1 個 |
| **Verifier** | read-only inspection / red-team / regression | YES | Haiku / Sonnet | scope 鎖死 1-3 INV |
| **Triage** | classify findings (bug / feature / usage / not_issue) | NO (sequential) | Sonnet (或人類) | PM authority |
| **Comparison** | independent re-verify (Stage 7) | YES (with #1 verifier) | Haiku | 不知道原 QA 結果 |
| **Newbie** | adversarial persona audit (broader coverage) | YES | Sonnet | each persona explicit prompt |

## Per-Cycle Staffing (declared in cycle file Header)

每個 cycle 在自己的 `docs/cycles/Cn-*.md` Header 宣告本輪派多少 agent。範例:

| Agent ID | Type | Model | RAM | Scope |
|----------|------|-------|-----|-------|
| RD-1 | Writer | Sonnet | 0.6 GB | 整個 cycle 寫入 |
| QA-A | Verifier | Haiku | 0.4 GB | INV-XXX-NNN red-team |
| QA-B | Verifier | Haiku | 0.4 GB | INV-YYY-MMM regression |
| QA-C | Comparison | Haiku | 0.4 GB | Stage 7 (盲 re-audit) |
| PM-Tri | Triage | Sonnet | 0.6 GB | Findings ≥3 才派 |

**Memory budget check**: 加總 ≤ available。Over budget → merge 兩個最低 scope Verifier。

## Iron Rules (執行契約, 違反退回)

1. **一個 cycle 同時只能 1 個 Writer agent 動手**。其他 agent 都不准動 code / spec / schema / migration。
2. **Verifier 永遠不准標 P0/P1**——只能 ✅ / ❌ / OPEN。
3. **Verifier scope 必須鎖死 1-3 個 INV**。不准「找任何 bug」。
4. **TDD red-green 必拆 5a / 5b / 5c 三 commit**。
5. **cycle file 必須留檔**, 跨 cycle 不刪。
6. **每月 retro 一次, amend workflow.md 或 AGENTS.md**——這份檔死掉就跟 staffing 死掉一樣慘。

    4 個檔放好之後,接下來那段 bootstrap prompt 就有東西可指了——每個動作都對應到上面具體的檔案內容。

    5 個 type 的事故來源 — 入門篇深挖

    看到 AGENTS.md 列 Writer / Verifier / Triage / Comparison / Newbie 5 個 type,你可能會想:「為什麼不直接用傳統 8 職稱(架構師 / PM / UI-UX / 後端 / Flutter / DBA / QA)?」答案是這 5 個 type 不是想像出來的,是踩過真實角色事故反推出來的補丁——21 輪 ping pong、11 輪 self-audit 漏 P1、5 persona 抓 23 finding。每個 type 對應一條具體事故。

    故事完整版在入門篇用第一人稱寫:「為什麼修不完?」— 從 21 輪迴圈到 5 type taxonomy 的多 agent 角色設計。沒看過入門篇的讀者建議先回頭讀,再看本篇 5 個 type 怎麼用會更有 context。

    另一個跟 type 並列的設計選擇是 per-cycle dynamic staffing:不是「每 cycle 派固定 N 個 agent」,而是每個 cycle 在 docs/cycles/Cn-*.md Header 自己宣告派哪些 type、什麼 model、佔多少 RAM,加總要 ≤ machine available。改 1 行 typo 跟改 schema 不會用同樣編制。同樣在入門篇的故事裡詳細展開。

    Bootstrap prompt(複製貼到新 session 的開場白)

    你接手這個專案。第一輪 onboarding 強制讀以下檔案,讀完再開工:

1. docs/workflow.md   — 8-stage cycle SOP,所有 PR 必經
2. docs/cycle-template.md — cycle file 結構,每個 PR 複製一份
3. docs/invariants.md — 所有 invariant 契約,改動前先看會影響哪幾條
4. AGENTS.md          — 本機資源預算 + role taxonomy

從現在開始,所有改動走 cycle file 流程:

1. 開 PR 前 git checkout -b feat/<topic>
2. 從 cycle-template.md 複製成 docs/cycles/Cn-<topic>.md
   (n = 流水號,grep 既有 docs/cycles/ 看下一個 n 是什麼)
3. 填 Header(owner / start time / cycle type / related INV)
4. 跑 Stage 0.5 pre-cycle hygiene 確認 baseline 乾淨
5. 進 Stage 1 RD 自測 → Stage 2 QA wave → ... → Stage 8 merge gate
6. 收尾時 cycle file commit 留檔,絕對不刪

紀律:
- QA agent 永遠不准標 P0 / P1(那是 PM 的 authority)
- 任何 fix 必須 5a 寫 failing test 紅燈 → 5b 寫 fix 綠燈 → 5c refactor
- 任何改動先 grep 找 downstream reader,沒列必漏
- cycle file 寫具體 evidence,不寫抽象 status
- 修了 bug 必須加 INV 到 docs/invariants.md,沒加不算修完

不確定的 stage 先問我,不要自己腦補。

    這段直接 paste 進新 Claude Code session、Antigravity initial message、Codex 的第一輪 prompt、或 Cursor 的 chat input 都能用。共通點是這些工具都讀 markdown,所以方法論本身跨工具。

    跨工具相容性——自動觸發機制

    差別不在「方法論能不能跑」,在「自動觸發機制」。每個工具有自己的「啟動時必讀」slot:

    工具 自動觸發 slot 怎麼放 bootstrap
    Claude Code CLAUDE.md(專案根目錄)+ ~/.claude/skills/ CLAUDE.md 第一段宣告「## Domain Skill: cycle-workflow」+ skill 寫 cycle SOP 引導
    Codex / OpenAI Agent AGENTS.md(OpenAI 協議) AGENTS.md 開頭加「啟動時讀 docs/workflow.md 必經 8-stage」段落
    Antigravity 專案 root system prompt 同上,在 system prompt 內 reference docs/workflow.md
    Cursor .cursorrules .cursorrules 寫「每次回應前讀 docs/workflow.md」+ reference cycle template
    Aider .aider.conf.yml / CONVENTIONS.md CONVENTIONS.md 寫 cycle SOP 要點,啟動時 –read 進去
    純 ChatGPT / Claude Chat 無自動 slot 手動 paste 上面 bootstrap prompt 進每個新對話

    關鍵 insight:方法論存 markdown,觸發機制存工具專屬 slot。換工具時方法論不用重寫,只要更新觸發機制怎麼指向同樣那 4 個檔案。

    持續 update 機制——別讓 kit 變死文件

    啟動只是第一步。長期維護有三條強制 update trigger,少了任何一條,kit 半年後就會 rot:

    1. 每 fix: commit 強制 update invariants.md:修了 bug 必須加對應 invariant,沒加不算修完。沒這條,同類 bug 半年後一定回來。
    2. 每 cycle 收尾 commit docs/cycles/Cn-*.md:cycle file 留檔不刪,當作 audit trail + 給未來 cycle 參考。沒這條,cycle 跑完就忘,跨 cycle lesson 全部蒸發。
    3. 每月 retro amend workflow.md:跑了一個月會發現某個 stage 太重 / 漏 / 順序不對。retro 看數據(漏掉的 bug、浪費的 stage、卡住的 finding),回去 amend SOP。沒這條,workflow.md 變死文件。

    這三條 trigger 應該寫進 workflow.md 自身,讓「每個 agent 開工前必讀 workflow」這個動作自動帶上「該 update 什麼」的提醒。

    第一個專案的 day-1 動作

    1. git init + 建 docs/cycles/ 目錄
    2. 把上面 4 個檔案複製進來(workflow.md / cycle-template.md / invariants.md 空白 / AGENTS.md)
    3. 建 CLAUDE.md(or 對應工具的 root prompt 檔)宣告必讀那 4 個
    4. 第一個 PR 就照 cycle file 流程走——不要說「先簡單做,以後再上 SOP」,以後不會來
    5. 跑完第一個 cycle,commit cycle file + 第一條 invariant + 第一輪 workflow.md amend(會發現自己漏寫了什麼)

    這套不需要先「累積經驗」才能啟動。第一個 cycle 跑完就有第一份 cycle file 範例給未來自己 / 未來 agent 看,雪球從第一天就開始滾。

    §8 反模式——cycle file 怎麼寫會死掉

    • 寫太抽象:只列 status(QA: ✅),沒列 evidence(哪個 invariant、哪個 attack scenario、reproduce 步驟)。半年後讀不懂自己寫了什麼。
    • 寫太瑣碎:每個 keystroke 記 timestamp,cycle file 變成 chat log。讀的人撈不到結論。
    • 不留 cycle file:對話結束就忘,跨 session 必撞失憶。最常見也最致命。
    • 不分 stage:一個 cycle 寫成一坨流水帳。新 agent 不知道現在跑到哪。
    • 寫在 cloud doc / Notion 不是 git:沒 audit trail,branch 切換 cycle file 不會跟著切,跨工具不依賴的好處全部失去。
    • 不分 Cycle Type 硬跑 8-stage:user-smoke-followup 跑 Stage 2 QA wave 等於把 user 抓的 bug 丟回給 QA agent 確認——錯位、浪費。

    結語:接力棒不是裝飾,是 multi-agent 工程的真正關鍵

    Multi-agent 工程兩條互補規則:

    1. 動手的 agent 只能一個(寫入單線程,從 Cognition / Stanford 等業界共識)
    2. 下一個 agent 必須能無痛接手(cycle file 接力棒,業界文章很少談)

    多數人聽到「multi-agent」想到的是「多個 AI 一起工作」。實際上正確的設計是:同時間只有一個 AI 在動手,其他都是不動手的判斷者;動手的累了下一個來,接力棒(cycle file)不能丟。

    業界文章很少談接力棒——他們談 orchestrator-subagent、談 generator-verifier、談 context isolation,但很少談「下一個 agent 從哪裡讀狀態」。可能因為 demo 場景太短,撞不到 compaction 也撞不到跨 session 失憶。長期專案跑下來,這個盲區會反覆把人燒一遍。

    Cycle file 是踩坑長出來的工程紀律。file-as-state-machine pattern 可以推廣到所有需要「process state 跨人 / 跨時間延續」的場景——不分是不是 multi-agent。

    延伸閱讀

  • 「56 條 INV 全綠,user 點一次抓出 4 個 bug」— Multi-Agent 業界共識的五個自家補丁

    重點摘要

    • 規劃 staffing 跟執行 staffing 必須分離——HOME123 的 AGENTS.md 寫死 8 職稱 + 沒 update 機制，跑 33 cycles 紋風不動，變成「歷史文物」。
    • 寫入單線程，讀取並行——多 agent 平行寫程式碼會產生隱性風格 + 決策衝突，但平行派 5 個 persona newbie 讀程式碼抓 bug 完全沒問題。
    • Generator-Verifier ROI 最高——只加一個 verifier agent 就顯著提升品質，且 verifier 不共享 generator 的 context 反而效果更好。
    • Persona-driven newbie 抓 PM 漏的 finding——HOME123 C29 派 5 個不同 persona 平行 audit，抓出 23 個 PM + Tom 都漏的 finding，其中 4 個是 cycle blocker。
    • 「INV 全綠」≠「對」——C11 user 隨便點 chairman dashboard 就抓出 11 個 verification cycle 都漏的 LEFT JOIN ARRAY_AGG NULL bug。Cycle SOP 只能抓「SOP 想得到的」，user 抓「SOP 想不到的」。

    讀完愛好 AI 工程的 Multi-Agent 架構再探: 三省六部反模式和業界收斂共識(2026-05-19),裡面整理的 Anthropic、Cognition、LangChain、Stanford 各家對 multi-agent 系統的共識,跟我家 HOME123_NEW 從 R35 21 輪迴圈踩坑、演化到 R36 cycle SOP 的軌跡高度重疊。

    但「重疊」不等於「教會我新東西」。我反而在對照中發現,有五個自家踩出來的細節,業界文章沒講或講得不夠重——這篇就把這五個補丁寫下來,給跟我一樣已經在生產環境跑 multi-agent workflow 的人參考。

    本文不從 0 開始講 multi-agent 概念,假設你讀過原文或熟悉 orchestrator-subagent / generator-verifier 這類詞彙。

    補丁 1:AGENTS.md 為什麼變死文件——「規劃 staffing」跟「執行 staffing」必須分離

    我家 HOME123_NEW 的 AGENTS.md 是 2026-05-12 寫的,列了 8 個職稱角色:架構師 / PM / UI-UX 設計師 / 後端工程師 / Flutter 工程師 / Postgres DBA / 資料探索員 / QA。看起來像一張漂亮的組織圖。

    實際跑起來呢?專案 33 個 cycle 結束、Phase 1 ship 之後,這份 AGENTS.md 一次都沒動過。

    對照同一個 repo 的 docs/workflow.md:從 R36 step 3 v1.0 寫下來,持續演化到 v2.1 per-layer QA、v2.2 加 TDD red-green + SCN P0-1,六個 commit,每一輪 cycle 收穫都回寫。workflow.md 活著,AGENTS.md 死了。

    死文件的兩個必要條件

    盤點下來,一份文件變死,要同時滿足兩個條件:

    1. 寫了「會變的具體細節」——例如「8 個職稱 + 主要工作 + 預估記憶體佔用 600MB」。這些隨專案演化必然會變。
    2. 沒有強制 update 機制——沒掛在任何「每 cycle 必看」「每 PR 必檢」的閘口上。

    任一條件缺失,文件還能活:

    • 只寫不會變的部分(資源預算上限、role 類別 taxonomy),沒 update 機制也 OK——因為真的不需要 update。
    • 寫具體細節,但每 cycle 強制 re-check(像 HOME123 的 docs/cycles/Cn-*.md 活在 git,Stage 8 merge gate 強制檢查),也 OK——因為會被更新。
    • 兩個都犯 = 上線當天就在 rot。

    解法:規劃 staffing vs 執行 staffing 分離

    文件類型 性質 該怎麼活
    規劃文件(AGENTS.md / ROADMAP.md) 計畫期的「我以為會這樣」 寫 timestamp、標 initial assumption,職責限縮到「不會變的部分」(資源預算、role taxonomy、必讀 brain 索引)
    執行契約(workflow.md / invariants.md / cycle file) 違反就退回的活文件 每 cycle / 每 PR 強制 re-check,違反當 review fail,cycle 收完歸檔留檔

    原文「三省六部幻覺」段批的「把 agent 命名成 PM / 架構師 / QA」,本質上就是把規劃文件當執行契約用——以為列了 8 個職稱就能跑,但職稱不會自我更新,專案演化會立刻甩開它。我這次踩到的就是這個。

    補丁 2:不是「Single vs Multi」,是「寫入單線程 + 讀取並行」

    原文整理 Anthropic 2026/1 給 multi-agent 的三個合理場景:context 隔離、並行覆蓋、工具專業化。也引用 Cognition 2026/4 的反直覺發現:「寫入動作維持單線程,其他 agent 只負責提供判斷,不負責動手」。

    我家的實踐長這樣(從 R36 開始穩定):

    元件 配置 對應原文模式
    Writer 永遠 1 個 Engineer agent,寫 code + 寫 unit test Cognition「寫入單線程」
    Verifier wave 並行 2-5 個 QA newbie,每個 scope 鎖死 1-3 個 INV Generator-Verifier + Parallel exploration
    Orchestrator 我自己(PM 兩道閘:規格定錨 + finding triage) 人類在 loop
    外部狀態 docs/cycles/Cn-*.md 活在 git 原文「orchestrator-worker + 外部狀態文件」

    整套是Orchestrator-Subagent + Generator-Verifier 混合,五種協調模式裡 ROI 最高的兩個疊起來。

    對應 Stanford 那篇論文的實戰觀察

    原文引用 Stanford 2026/4 的 Single-Agent LLMs Outperform Multi-Agent Systems on Multi-Hop Reasoning Under Equal Thinking Token Budgets(arxiv 2604.02460),用資訊理論的「數據處理不等式」證明:固定 token 預算下,單一 agent 在 multi-hop reasoning 上贏過 multi-agent。

    把這個結論套到 code generation 場景就是:Engineer 那 1 個 agent 才是真正在做連續推理的——它要把 spec → schema → resolver → test 一路推下去,context 連續性是品質關鍵。讓五個 agent 平行寫不同模組,結果就是 Stanford 那篇講的:每個 agent 自己的 context 縮短了,推理深度不夠。

    但 verification 不是 multi-hop reasoning,它是多點獨立檢查。每個 newbie scope 鎖死 1-3 個 INV,根本不需要 multi-hop reasoning;反而從乾淨 context 出發比較好——這也是 Cognition 觀察「verifier 不共享 generator context 反而更好」的原因。

    所以選 single 還是 multi 不是哲學問題,是「這個子任務需不需要連續推理」的問題。需要 → single;獨立檢查 → multi。

    補丁 3:Generator-Verifier 的六個 HOME123 細節

    原文講 Generator-Verifier 是五個協調模式裡 ROI 最高的,但講的是「為什麼有效」。HOME123 R35→R36 演化過程中,六個操作細節決定了它真的有效還是只剩形式:

    1. QA scope 鎖死 1-3 INV,不准抓「任何 bug」。R35 21 輪迴圈的反面教材就是讓 QA「找任何問題」,結果 finding 無限發散。Scope 鎖死後,每個 newbie 只查它自己的契約。
    2. QA 不准標 P0 / P1。只能標 ✅ / ❌ / OPEN。P0/P1 是 PM 的 authority,QA 上交給 PM triage。這條防止 QA agent「自己升級嚴重度」拖累節奏。
    3. PM 兩道閘:第一道是寫 spec / 加 INV(規格定錨),第二道是 finding triage(bug / feature / usage / not_issue 30 秒分判)。少了任一道,QA wave 都會無限發散。
    4. PR header 強制宣告 INV 影響。每個 PR description 必填三段:滿足哪些 INV、可能影響哪些 INV、提議新增哪些 INV。沒填完整 = PR 不算開,reviewer 直接退。
    5. Verifier 不共享 Writer 的 context。QA agent prompt 模板只給它「PR commit SHA / 一條 INV / test users / 環境」,不給它 Writer 的對話歷史。乾淨 context 反而推理更深(Cognition 觀察)。
    6. Mutation testing 對抗 groupthink。每月一次,故意往 verified INV 對應的 code path 塞一個 plausible bug,看 QA agent 抓不抓得到。抓不到 = invariant test 不夠 sharp,補 attack scenario。

    第 6 條是原文沒講的盲區。QA agent 跟 Engineer agent 來自同一個 LLM 譜系,shared assumption 會讓兩邊「想得一樣」——0 ❌ 不一定是程式對,可能是兩個 LLM 從同一個訓練資料裡學到同樣的 blind spot。Mutation testing 是目前我知道唯一能對抗這個的方法。

    補丁 4:Over-design 怎麼補救——2026-05-22 砍 1000 LOC 實錄

    原文講 multi-agent 的成本非線性爆炸、錯誤放大,但沒講「multi-agent 容易生出 over-design 的 schema / API」這個副作用。HOME123 跑到 2026-05-22 做了一次 over-design audit,結果是砍掉 1000+ 行。我把那份 audit 攤開,看 multi-agent workflow 為什麼會生出垃圾,以及怎麼補救。

    5 個 dead schema 一次掃掉

    砍掉的東西 為什麼是死的
    Query.myCapabilities 0 frontend caller(me.capabilities 已涵蓋)
    Parcel.notifications + type Notification 0 frontend query,Phase 2 push 走別條 path
    type Guard 整個 type 標 @deprecated,0 caller
    Mutation.batchDeliver + BatchDeliverInput 0 frontend call(所有 UI 都打 deliverParcelBatch),約 260 LOC resolver
    Mutation.createParcelIntakeBatch + UI dialog 跟 C31 session-based batch intake 共存,UI 兩個批次按鈕讓警衛 cognitive load 爆炸,砍掉 ~343 LOC frontend + ~360 LOC backend

    反 anti-pattern:「往後查」

    這五個 dead schema 全部都是同一個 anti-pattern:「為將來預留」。設計時 agent 想「萬一將來要顯示通知 timeline 呢?」「萬一未來 batch deliver 改 session model 呢?」「萬一要 polling caps 呢?」——於是 schema 多了 field、resolver 多了支、tests 多了行。

    但 multi-agent workflow 的特性是沒人記得當初為什麼加:今天的 Engineer 不是當初寫 schema 的 Engineer,QA 不會質疑 schema design 是不是必要,PM 看 finding 不會回頭 audit schema 健康度。「往後查」的 anti-pattern 在 multi-agent 環境會比 single-developer 累積更快。

    三個補救機制

    1. 定期 over-design audit(每 ~2 個月一次或大 milestone 後)。PM scan 角度:「99% 無痛、edge case 不擋 99%、不為將來 may-be 需求預留、不為『好體驗』造成系統壓力」。
    2. 砍之前先 grep 全 codebase 確認 0 caller。「我以為沒人用」跟「grep -r 證實 0 caller」是兩件事。HOME123 砍 batchDeliver 前 grep app/lib/,只在註解出現,於是放心砍。
    3. 砍完寫進 INV 防回流。砍 dead schema 之後加 INV-SCHEMA-001:「standalone batch* mutations 不再加,batch 行為一律走 session-based pattern」。沒寫 INV 半年後同樣的 over-design 會回來。

    Design 不足:persona-driven newbie 才挖得出來

    Over-design 反過來是 design 不足。HOME123 C29 跑了一個實驗:派 5 個 persona-driven adversarial newbie 平行 audit,每個 persona 有明確的「你是誰、你假設世界是什麼樣、你要找的不是『功能對不對』而是『產品對不對』」mandate:

    • Newbie 1:高吞吐警衛阿伯(每天 300 件包裹)
    • Newbie 2:無棟透天社區主委(12 戶,只有「幾號幾樓」概念)
    • Newbie 3:多棟社區主委(5 棟,要選棟才能下一步)
    • Newbie 4:老年住戶用 iPhone 11(375px 螢幕、視力差)
    • Newbie 5:跨租戶 RLS 測試者

    5 個 newbie 平行 audit 抓出 23 個 finding,其中 4 個是 cycle blocker——這些都是我跟 PM 看了無數遍漏掉的。

    最戲劇性的是 N2 跟 N3 加起來證實了我的 directive 錯了:我 2026-05-20 拍板「不用管棟」,N2 跑去把 buildings 設成空陣列發現 backend 硬擋(buildings cannot be empty),N3 跑去測多棟社區發現 dropdown collision。兩個 persona 的觀察合起來,證明「不用管棟 globally」over-fit 到單一棟的場景,我自己只看單一棟所以沒撞到。後來我把 directive partial revoke,改成 buildings.length > 1 才顯示棟 picker。

    Persona-driven newbie 是補 design 不足最便宜的工具。成本就是每個 newbie 一份明確 persona prompt + 一輪 read-only audit,沒有寫衝突、沒有 merge 成本。

    補丁 5:「我很有信心,但你隨便測就炸」——C11 完整故事

    這條是 multi-agent 系統最容易掉進去的坑——而原文完全沒談。先講事件:

    2026-05-10 晚上,HOME123 R36 跑完 11 個 verification cycle、56 條 INV 全綠、所有 QA wave 都報 ✅。我用 chairman 帳號(admin01)登進 dashboard,點開「主委交接」tab——爆炸:

    讀取失敗:can't scan into dest[4] (col: roles):
failed to scan array element 0: cannot scan NULL into *string

    同一個 session 我隨便點了 chairman dashboard,找到 4 個 bug:這個 NULL scan、communities.public_contact_phone 殘留的 <script>alert('XSS')</script> 測試資料、parcel serial 多顯示一個 #(spec 沒寫)、carrier barcode 沒有 lookup query 入口。

    名言誕生:

    R36 11 個 cycle + 56 條 INV ✅,user 隨便點 1 次 → 4 個 bug。

    User browser smoke remains the most valuable QA signal.

    深挖那個 LEFT JOIN ARRAY_AGG NULL bug

    有問題的 SQL 是 CommunityUsers resolver,長這樣:

    SELECT u.*, COALESCE(
  ARRAY_AGG(ur.role_code) FILTER (WHERE ur.revoked_at IS NULL),
  '{}'::text[]
) AS roles
FROM users u
LEFT JOIN user_roles ur ON ur.user_id = u.id
WHERE u.community_id = $1
GROUP BY u.id;

    Bug 在哪?LEFT JOIN 對沒匹配的 user 會 pad 一行 ur.* 全部 NULL 的 row。SQL 三值邏輯下,NULL IS NULL 是 TRUE——所以 FILTER (WHERE ur.revoked_at IS NULL) 把這個 pad row放進了 aggregate。結果 ARRAY_AGG 回傳的不是空陣列、是{NULL}(包一個 NULL 元素的陣列)。COALESCE 看到的是非 NULL 陣列,直接 pass through,Go scan 進 []string 時就爆 cannot scan NULL into *string。

    修法很簡單:FILTER 加一個 AND ur.role_code IS NOT NULL,把 pad row 排除掉。但為什麼 11 個 verification cycle 都沒抓到?

    因為這個 bug 只在「有 user 沒有任何 user_roles row」時觸發。C6 cycle 的 seed-demo.sh 改成 idempotent 之前,所有 demo user 都有至少一個 role;C6 之後,seed 改成「先 DELETE 殘餘 user 的 roles 再 disable user」,結果 DEMO001 多出 11 個 disabled-residue user 帶 zero user_roles row。fixture 狀態改變才暴露 bug,前 11 個 cycle 跑的時候 fixture 還沒進入這個狀態。

    這條 cycle file 寫下了 multi-agent 系統最殘酷的真相:

    Cycle SOP catches what cycle SOP can imagine; user catches the rest.

    為什麼 TDD 也擋不住

    我這套 workflow 有強制 TDD red-green 三步(Stage 5a 寫 failing test、Stage 5b 寫 fix、Stage 5c refactor),為什麼還是漏?

    1. Vacuous green test。Test 永遠 pass 不是因為實作對,是因為 assert 太寬或 fixture 沒覆蓋觸發條件。C11 那個 NULL bug 在前 11 個 cycle 的 test fixture 裡,根本沒有「user 帶 zero roles」這個狀態,所以 test 一直 green。
    2. Groupthink。QA agent 跟 Engineer agent 同 LLM 譜系,想得一樣。Engineer 寫 test 時想到的 attack scenario,跟 QA 寫 test 時想到的 attack scenario,高度重疊。盲點是 shared 的。
    3. L1-L3 全綠 ≠ L4-L5 也對。HOME123 把「對」分 6 層:L0 spec → L1 INV → L2 schema → L3 resolver → L4 frontend → L5 E2E。前 11 個 cycle 主要驗 L1-L3,L4 user click 沒人驗。INV 全綠是 L1 全綠,跟 user 在 chairman dashboard 看到什麼是兩件事。

    5 個建議方向

    1. User smoke = primary detection。不是 secondary、不是「最後再點一次」。每個 milestone 結束第一件事是 user 隨便點,不是看 CI report。
    2. Mutation testing 對抗 groupthink。每月或大 INV amendment 後跑一次,故意塞 plausible bug,看 QA agent 抓不抓得到。抓不到 = QA prompt 跟 Engineer 想得太像,得補 attack scenario。
    3. Adversarial persona 平行覆蓋。C29 模式:每個 persona 有明確「你跟 Engineer 想法不同的地方在哪」mandate,5 個 newbie 平行 audit,讀取型 multi-agent 完全沒衝突風險。
    4. 6-layer thinking 防止誤推。看到「INV 全綠」先問「這是 L 幾全綠?L4 / L5 有人驗過嗎?」L1-L3 全綠不等於對,只是「未驗中比較強的子集」。
    5. TDD red-green 三步分 commit。Stage 5a 寫 failing test 單獨 commit、Stage 5b 寫 fix 單獨 commit,commit message 必填 Failing test verified at: <5a-sha>。bisect 看得出 red→green 軌跡,防 vacuous test。「test 跟 fix 同 commit」= test 從沒 fail 過 = 沒驗 test 有效。

    結語:業界共識是地圖,cycle file 是地形

    原文整理的業界共識像一張地圖:告訴你 Anthropic 走哪條、Cognition 撞了什麼牆、LangChain 怎麼分 patterns。地圖很有用——你不會走錯方向。

    但地圖不是地形。HOME123 33 個 cycle 累積的 docs/cycles/*.md 才是地形:哪個彎要慢、哪段路會塞、哪裡橋斷了走小路。地圖告訴你「先試 single-agent」,地形告訴你「single-agent 的 Engineer 寫完之後,第二件事是叫 5 個 persona newbie 去點點看」。

    這篇五個補丁,本質上是把地形寫下來。給已經在跑 multi-agent workflow、開始撞牆、覺得業界文章沒講透的人。

    下一步:把這次討論抽出的「規劃 staffing vs 執行 staffing 分離」原則,寫進 ~/.claude/projects/-home-tom/memory/brain/adaptive-agent-team-staffing.md brain;把 HOME123 R36 的 PM/Engineer/QA workflow.md 抽象成 ~/.claude/templates/workflow.md 通用模板。這樣下個專案就不用從 R35 21 輪迴圈重新踩一次。

    延伸閱讀

  • AI 不該替我打 🟢🟡🔴:從 decision-server 看跟 LLM 協作決策的介面方法論

    重點摘要

    • Markdown vs HTML 是假議題 — 真正問題是「LLM 給人類決策時的介面設計」
    • AI 加工成 🟢🟡🔴 標籤的「成本/風險」評分,使用者不信。要 raw evidence (檔案、行數、schema 影響),讓使用者自己判斷
    • 解法:一個 Flask + systemd + Cloudflare tunnel 的 decision-server,每個決策生 HTML 頁,使用者在瀏覽器/手機看真實證據後點選項
    • 規則寫進全域 ~/.claude/CLAUDE.md,所有 Claude session (含 Telegram bot) 自動遵循
    • 實戰跑通:4 個 agent 並行審查 dementia-care home-handbook 找出 45 個 findings → 5 個獨立決策 page → 答完 5 tier 自動改動 → commit 3d1f101 → 自動部署 GitHub Pages

    起點:一個假議題

    今天早上我問 Claude:「最近有一個聲音說過去我們使用 markdown 沒有實用性,要用 HTML。你幫我比較一下。」

    Claude 給了一份標準比較 — Markdown 的 token 效率、git diff 友善;HTML 的語意豐富、表達力強。然後得出結論:「在你的場景 markdown 全面勝出」。

    但我打斷他。真正卡我的不是文檔格式,是另一個問題:每次 Claude 問我做決策時丟一面牆的 markdown 字,我不知道背後意義、不知道範圍、不知道要考慮什麼,認知負擔很重。如果能像 HTML 那樣用顏色區塊跟拖拉條一眼判斷,我做決策的速度會快很多。

    這篇文章記錄今天從這個誤會開始,到我跟 Claude 一起建出一個跨 session 通用的決策伺服器,中間踩到的設計坑 + 抽出的協作方法論。

    第一次嘗試:加 🟢🟡🔴 對照表

    Claude 第一個提案是用 Claude Code 內建的 AskUserQuestion 工具,加上 emoji 視覺對照表。範例:

            速度  成本  風險
A 拆分  🟢   🔴   🟢
B 單檔  🟡   🟢   🟡
C 折衷  🟡   🟡   🟢

推薦 → C (綜合最佳)

    看起來不錯。我選了這個格式。Claude 還幫我寫進 feedback memory,以後預設都用這種對照表。

    30 分鐘後,我反悔了:「你說的成本不一定是真的成本,你說的風險也不一定是真的風險。你的比較我也不太能夠相信。」

    核心問題:Raw Evidence vs 加工標籤

    🟢🟡🔴 是 Claude 對「成本/風險」的主觀評分。它幫我把證據壓縮成一個顏色,但這個壓縮過程是有損的,而且我看不到原始材料,沒辦法 second-guess。

    真正能幫我決策的不是「Claude 認為這個選項風險 🔴」,而是「這個選項會動 db/migrations/0042.sql 第 38 行的 CHECK constraint,影響 50,000 rows」。前者是評分,後者是事實。前者我半信半疑,後者我自己判斷。

    這個 framing 反過來界定了 LLM 在人類決策流程裡的角色:

    • 不該做的:替使用者打分數、給推薦星等、用顏色暗示優劣
    • 該做的:把零散證據整理成可掃描的結構,擴展使用者的判斷面,不替代它

    解法:decision-server

    我提了一個架構:在我的迷你 PC 上開一個 port,Claude 要我做決策時生成 HTML 丟到那個 port,我用瀏覽器/手機看。Claude 接過去做了完整實作:

    • Server:~/decision-server/server.py (Flask, 87 行)
    • Service:systemctl --user enable decision-server (linger 開,跨重開機)
    • Port:8765
    • Public URL:https://askme.tomting.com (Cloudflare Tunnel)
    • Endpoints: GET /d/{slug} 看頁面,POST /d/{slug} 收答案

    每個決策 3 個檔案共用一個 slug:

    檔案 寫入者 內容
    pages/{slug}.html AI 人類看的決策頁面
    meta/{slug}.json AI question + options 的結構化規格
    answers/{slug}.json Server 人類點完寫入,自我描述 (含 choice_label 全文)

    關鍵設計:answer.json 自我描述。不只存 choice: "B",連 choice_label 全文也存。三個並行 session 都點 B,後續讀檔不會混淆,因為每個 B 都帶著自己的語義。

    Selenium 跑了一輪整合測試:3 個假 session 各生一個決策 (slug 開頭分別 a3f7- / 9e2c- / b51d-),選不同字母,驗證:

    • 3 個 session 各自寫到自己的 answer.json,零交叉污染
    • index 頁正確分組顯示
    • 每個 answer 自描述完整

    頁面設計的演進

    第一版 page 只有「標題 + change_cards + options」。Tom 開了一張 demo 看完反應:「感覺資訊很少,情境根本無法懂問題是什麼,我要怎麼決策?」

    對。決策者通常從別的事情切過來,不會有問題提出者的 context。設計 onboarding 區塊變成必填:

    • 📖 背景 (background):這個功能是什麼?涉及哪些表/服務?為什麼會跑出這個 decision?
    • ⚡ 核心問題 (problem):具體哪裡卡?矛盾在哪?
    • 🩸 不解的後果 (impact):拖著會怎樣?(技術債/錯誤/blocking 什麼)
    • 🔍 證據卡 (change_cards):真實 file:line + 真實 +/- 行數 + 1-3 個 bullet
    • 🎯 選項 (options):每個帶 consequence (成本 / 副作用 / 適合什麼情境)

    三層 framing 補完,Tom 就算前 5 分鐘在洗碗,開連結 30 秒內也能判斷。

    讓所有 session 都用這個 protocol

    我們建好了 server,但有個問題:Tom 同時開好幾個 Claude session — 寫 iDempiere 的一個、跑 Home123 的一個、Telegram 上的 ccbot 一個。每個 session 都要知道用 decision-server,不能靠每次重提。

    解法:寫進全域 ~/.claude/CLAUDE.md (Claude Code 對所有 session 都會載入的全域指引)。新增段落「🌐 Decision-Server Protocol — MANDATORY for asking Tom decisions」,包含:

    • 觸發情境表:10 種要用 decision-server 的真實場景 (方案選擇 / 範圍決定 / 優先順序 / 動作授權 / 設計選擇 / Code review 後 / Schema 變更 / 批次決策 / 工具升級 / 不可逆操作)
    • 不觸發情境表:6 種對話講就好的例外 (確認理解 / 缺資訊 / 真瑣碎 yes/no / 用戶明說 / 教學模式 / Server 掛了)
    • 必填欄位表:14 個欄位的必選規格
    • 完整範例:一個 canonical JSON 直接抄
    • 禁止寫法表:9 條紅線 (例如禁止 "risk": "🔴" 主觀標籤)
    • 常見錯誤:5 個 future-session 易犯的

    驗證方式:跨 session 自動採用。寫完規則沒多久,ccbot (跑在 Telegram 上的獨立 Claude session) 在不知情狀況下,自動讀到全域 CLAUDE.md,自動用 protocol 生了 6 個決策 page (session_id 6089),Tom 在 Telegram 看到「卡你決策 6 條」改成 6 個 askme.tomting.com 連結,在手機上 5 分鐘答完。

    真實案例:home-handbook 審查

    整個 stack 跑通後,我用它做了第一個真實任務:全面審查 ~/Desktop/dementia-care/home-handbook/ (失智照護 handbook,4 個 HTML 檔案 4719 行)。

    步驟 1 · 並行 agent 掃描

    派 4 個 general-purpose agent 並行掃 4 個檔案 (index / caregiver / long-term / emergency),每個 agent 應用同一份 10 項檢查清單,清單來自 brain/llm-handbook-writing-pitfalls.md 的 9 個失敗模式 + design-principles 的 CDN/emoji 規則:

    1. 細節腦補 (沒驗證就寫具體名詞/數字)
    2. 失能 vs 失智 frame 混淆
    3. boredom vs restlessness frame
    4. 加法 vs 減法 (測試記憶 framing)
    5. 醫療因果 claim 無文獻 (「會/導致/加速 + 醫學名詞」紅線)
    6. SOP magic number 沒推導
    7. 戲劇化描述 (「像 X 一樣」「彷彿」)
    8. 工程師腦過度設計 (可觀測性、冗餘、invariant 思維)
    9. PII 洩漏 (姓名、稱呼、地址)
    10. CDN / 外部依賴 / 新 emoji (Unicode 14+)

    並行加總 4 個 agent 跑完 ~2 分鐘,回報 45 個具體 findings,每個帶 file:line + 引用原文 + 建議改法。

    步驟 2 · 用 decision-server 生 5 個獨立決策 page

    45 個 findings 不是 45 個決策。Claude 把它們合併成 5 個策略性決策(因為一頁一決策原則:類似議題歸為同一決策,選項是「處理策略」):

    # 議題 我選的
    1 PII 清理範圍 B:保留 meta author,內文一律第三人稱 + 砍 HTML 註解
    2 外部連結處理 B:保留連結 + 加 rel=”nofollow”
    3 醫療因果 claim D:混合 — 有臨床共識的補引用 (Beers Criteria / NICE),其他弱化或砍
    4 scope overreach (E6/E7/E8 跨 CDR 2 經驗) D:保留現狀,disclaimer 移到三章開頭加明顯
    5 magic number 無推導 D:混合 — 自家 SOP 補推導,醫療閾值補 disclaimer

    步驟 3 · 執行 + 部署

    我用瀏覽器答完 5 個 page,Claude 讀 answers/*.json 自我描述的 choice_label,執行對應改動。整理出 5 個 tier 的具體 edit (PII / 外部連結 nofollow / 醫療 claim 引用 / scope disclaimer / magic number 推導),全部用 Edit 工具批次處理。

    最後輸出:

    • commit 3d1f101 on dev branch,4 files changed, +46/-34 lines
    • merge dev → main (commit d3ccc98)
    • push origin/main
    • GitHub Pages 5 秒部署完成
    • 線上版:https://tm731531.github.io/dementia-care/home-handbook/

    抽出來的方法論

    原則 1 · Raw evidence > 加工標籤

    LLM 替使用者壓縮資訊是有損操作。決策接口要顯示可驗證的事實(檔案路徑、行數、schema 影響、binary 屬性),不是顯示 AI 對事實的評分(🔴 高風險、複雜度中等)。標籤把使用者鎖在 AI 的判斷裡,事實讓使用者用自己的判斷。

    原則 2 · 決策頁要做 onboarding 設計

    使用者打開決策頁時通常是「從別的事情切過來」,沒有問題提出者的 context。背景 / 問題 / 不解後果三段缺一不可。光列證據卡片他看不懂為什麼這個問題重要。

    原則 3 · 選項要帶後果

    選項 label 不夠。每個 option 帶 consequence 三件事:成本 (要做多少工)、副作用 (選了會被什麼牽動)、適合什麼情境。沒這三件事使用者只能猜選了會發生什麼。

    原則 4 · 一頁一決策

    N 個決策要用 N 個獨立 page,不要塞在同一頁。理由:answer.json 自我描述,每個答案要能單獨理解。多決策塞同頁 = 回到 Tom 鄙視的「文字牆」。

    原則 5 · 全域配置 > 個別提醒

    跨 session 要一致,要寫進全域 system prompt (Claude Code 的 ~/.claude/CLAUDE.md),不能靠每個 session 個別記住。寫進全域 = 自動覆蓋所有未來 session 包含 sub-agent 跟跨平台 bridge (ccbot)。

    原則 6 · 流程要可驗證

    關鍵 invariant 要寫測試。test_multi_session.py 用 Selenium 驗證 3 個並行 session 不互相污染。每次改 server 或 generator 都跑一次。PII 清理用 grep 自動驗:grep -c "老媽" 應該為 0。

    整套 Stack 重現指南

    如果你想複製這套協作模式,這是最小的 reproducible setup:

    • Server:Flask app,3 個 endpoint (GET / + GET /d/<slug> + POST /d/<slug>)
    • Generator:Python helper 接 stdin JSON spec 生 page + meta
    • Wait:Python helper 阻塞 polling 直到 answer.json 出現
    • Templates:Jinja2 – decision.html (含 session bar / 三層 context block / change cards / options buttons)
    • Service:systemd user service + linger 開 (持久跨重開機)
    • Public access:Cloudflare Tunnel (免費,1 條 command)
    • Global config:Claude Code 的 ~/.claude/CLAUDE.md 加 MANDATORY 區塊

    所有 Python 依賴只用 Flask + Selenium (測試用) + Jinja2,記憶體佔用 ~20MB,啟動時間 1 秒。整個 server.py 87 行,generator.py 75 行,template 88 行 (含 CSS)。建構成本 1 個下午,跑通就終身使用。

    結語:不要替我打標籤

    這篇文章的起點是 markdown vs HTML,但真正的問題從來不是文檔格式。是「LLM 在人類決策流程裡扮演什麼角色」。

    當 LLM 把所有事情壓縮成 🟢🟡🔴 或星等推薦,它就把使用者鎖在自己的判斷裡。當 LLM 把零散證據整理成可掃描的結構頁面,它擴展使用者的判斷面。前者是 LLM 取代人,後者是 LLM 服務人。

    建一個決策伺服器只是工具實作。背後的設計決定才是真正的協作哲學:給事實不給評分,給結構不給結論,給選項不給推薦。

  • Claude Code 訂閱 6/15 拆分:一個 Max 用戶的 evidence-based 評估與本地化反轉

    重點摘要

    • Anthropic 在 2026/6/15 把 Claude 訂閱拆兩半:互動式(終端機 Claude Code、IDE、claude.ai)維持訂閱補貼價,**程式化(Agent SDK、claude -p、GitHub Actions、第三方包裝)移到獨立 metered credit pool**,按 API 全價算。
    • 對「個人坐下來打字 + 派 Agent Team」這種使用方式,**影響幾乎是零**;真正會被打到的是把訂閱接到 Python 程式跑 24 小時 agent army 的套利型用法。
    • 但「字面合法、精神鑽縫」的灰色地帶會持續存在 — Anthropic 隨時可以用 fair use 條款補洞,你不會收到通知。**真正的應對是把 LLM 從 service 變 commodity**:本地優先 + cloud burst 的 gateway 架構。
    • 2026/5 當下的本地 stack 已經追平 frontier:Qwen 3.6-27B 在 agentic coding 上達到「半年前 400B 級」水準,DeepSeek V4-Flash 用 MoE 把 1M context reasoning 壓到 33GB 量化版可跑。**Claude API 從 default 降級成 escape hatch**。

    2026 年 5 月中,Anthropic 連續宣布三波 Claude Code 政策變動。5/6 把 5 小時池額度直接 ×2、Pro/Max 取消尖峰時段;5/13 週池額度 +50%(到 7/13 結束的補貼期);最關鍵的是 5/14 預告、6/15 生效的「訂閱拆分」政策 — 把程式化用量從訂閱補貼池移到獨立 metered credit pool。

    這篇文章是我作為一個 Claude Max 訂閱用戶,用 21 個 transcript 實際 audit + 政策原文交叉比對的 evidence-based 評估。涵蓋:三波變動的精確時間軸、Anthropic 拆分的真實業務動機、不同使用模式落到新政策的具體影響、灰色地帶與真實風險,以及用 Qwen 3.6 + DeepSeek V4 反轉成「本地優先」工作架構的可執行路線。

    三波政策變動的精確時間軸

    2026/5/6 — 5 小時池 ×2、尖峰取消。Claude Code 五小時池對 Pro / Max / Team / 企業版直接加倍。Pro / Max 取消「peak hours」限制。Claude API 的 Tier 1 input tokens 上限 +1500%、output tokens +900%。背景是 Anthropic 跟 SpaceX 簽算力協議,Colossus 1 設施提供 300MW 額外容量、超過 220,000 NVIDIA GPU。

    2026/5/13 — 週池 +50%(臨時加碼到 7/13)。週限額提升 50%,適用於 Pro / Max / Team / Enterprise。這是限定期加碼,7/13 之後會回到原本水準(除非 Anthropic 再續延)。業界解讀是 Anthropic 對抗 OpenAI Codex 搶 agent 市場的動作。

    2026/6/15 — 訂閱拆兩池(真正的結構變動)。訂閱使用從這天起分成兩個池子:

    使用方式 6/15 後歸屬 計費邏輯
    終端機 / IDE 內互動式 Claude Code互動池(訂閱)不變
    claude.ai 網頁 / 桌面 / 手機互動池(訂閱)不變
    Claude Cowork互動池(訂閱)不變
    claude -p 無頭模式Agent SDK Credit Pool按 API 全價
    Claude Code GitHub ActionsAgent SDK Credit Pool按 API 全價
    Claude Agent SDK(Python/TS)Agent SDK Credit Pool按 API 全價
    第三方包裝(OpenClaw / Conductor / Zed / Jean)Agent SDK Credit Pool按 API 全價

    SDK Credit Pool 額度按訂閱方案分配:Pro $20、Max 5x $100、Max 20x $200,Team Standard $20/seat、Team Premium $100/seat。額度不滾存,每月歸零。耗盡後可選擇 enable overage(繼續按 API 全價收費)或 disable overage(請求被 reject)。

    Anthropic 為什麼要拆?

    訂閱政策本來是「個人吃到飽」設計。Anthropic 賭你打字慢、思考慢,$20 一個月吃不爆等值的 API token 量。這個賭注在「個人開發者用 Claude 寫 code」場景下成立 — 一個人類一天寫不了 10 萬行的對話。

    但 Claude Agent SDK + 第三方包裝(OpenClaw、Conductor、Zed、Jean)讓人可以把 $20 訂閱接到自己寫的 Python 程式,24 小時不停跑 agent army,實際 token 量遠超過 $20 等值。等於把吃到飽 buffet 整個載走轉賣 — 訂閱被當成「便宜 API」用於 production 流量。

    Anthropic 沒禁這條路,只是把它改成獨立 metered 預算 — 「載走轉賣」要另外算錢,「個人坐下來吃」不動。順便擋住 OpenAI Codex 用低價搶 agent 市場,也保住 unit economics 才有錢付 SpaceX 那 300MW 算力擴張的帳。

    實際使用模式 audit:21 個 transcript 看出什麼

    政策評估不能憑印象,要有實際使用 evidence。我盤點過去 28 天的 Claude 使用情況:

    • 21 個 transcript / 13 個唯一日期:不是每天用,平均一週 3-4 天
    • 互動式為主:全部 transcript 都是終端機 Claude Code session,不是 SDK / API 程式化呼叫
    • ccbot Telegram bridge:bridging interactive session,不是獨立 inference
    • 5 個 claude-harness-* hook:全是 SessionStart / PostToolUse / PreCompact 注入,在 session 內運行
    • claude-limited cgroup wrapper:也是互動 session 內
    • Agent Team 18-25 並行:從 interactive session 用 Agent tool 派
    • /loop, /schedule, GitHub Actions, 第三方包裝:全沒有
    • crontab 11 條:全是 stock data 收集(analyst / TDCC / 機構投資人),完全不叫 Claude
    • 唯一例外:某個內部 LLM 評估 harness 有一條 subprocess.run(["claude", "-p", ...])

    把這份 audit 對照 6/15 政策表格,結果出奇地簡單:21 個 transcript 裡有 20 條繼續走訂閱池,只有 1 個 evaluation harness 那條 claude -p 會搬到 SDK Credit Pool。

    政策真正落到「典型重度使用者」頭上的點

    對於從終端機 / IDE 互動式使用 Claude Code、用 Agent tool 派 subagent、寫 brain / skill / memory 系統的人 — 也就是 Anthropic 設計訂閱時瞄準的客群 — 6/15 變動實質影響趨近於零。

    真正被打到的只有四類具體模式:

    1. 把 claude -p 串進 shell pipeline 或 CI/CD:每次 invocation 從訂閱池移到 SDK Credit Pool
    2. 用 Agent SDK 寫的 Python / TypeScript 程式:無頭運行的 production agent,完全脫離訂閱
    3. Claude Code GitHub Actions:CI/CD 整合在 workflow 內呼叫 Claude
    4. 第三方包裝:OpenClaw、Conductor、Zed、Jean 這些把 Claude 訂閱接成 IDE 後端的工具

    如果你已經習慣「人在前面打字,Claude 在後面派 agent 跑」的工作模式,這個政策變動就是 一個不會發生的事件。

    灰色地帶:cycle + Agent Team 字面合法但精神鑽縫

    但有一種模式介於兩者之間,Anthropic 官方文件沒明寫:從 interactive session 派出大量 Agent Team,搭配 /loop 或 hook-based cycle 讓 session 自動延續。

    技術上這完全合法。6/15 政策字面只點四個對象:claude -p、Agent SDK、GitHub Actions、第三方包裝。「cycle + 大量 Agent Team + 自動啟動循環」如果全部跑在 interactive Claude Code session 裡(用 Agent tool 派、用 /loop 接同 session、用 hook 觸發),技術上會被歸到互動池。

    但這顯然是「字面 vs 精神」的縫。Anthropic 拆這條政策的精神,就是要擋「沒人盯每一回合的大量自動化」 — 第三方分析給出的啟發式是:「if a Claude session runs without a human watching each turn, it is almost certainly moving to the new credit pool」。從這個精神判讀,大規模並行 Agent Team + 自動 cycle 精神上根本就是 programmatic,只是技術上沒被點名。

    兩個現實風險

    風險一:這個縫不會永遠在。Anthropic 看到統計上的 outlier 用戶(Max 訂閱跑出 Tier 4 API 等級的 token 量),下一輪政策補刀的機率不低。半年後可能變「subagent 從 interactive 派也算 programmatic」、或「同 session 自動 cycle 超過 N 次轉計費池」。歷史上 Anthropic 對訂閱濫用模式都是先觀察後動手 — 5/14 這次拆分本身就是這個 pattern 的證據。

    風險二:Fair use 抽象條款隨時可以動你。Terms of Service 寫的「abuse / excessive use」沒精確定義,他們覺得單帳號太誇張就可以單獨 throttle 你帳號,不需要先改政策、不需要事前通知。被點到的人通常只看到「Claude 突然變慢 / 限額變嚴 / 某些 tool 失效」,不會收到正式告知信。

    精確版說法:「字面合法、精神鑽縫、風險押在 Anthropic 不回頭補洞」。在他們補洞之前你賺,補了之後可能在毫無預警的下次續訂看到 SDK credit 開始扣 — 或更早,某一天突然發現自己被限流。

    反轉戰略:從 service 用戶變成 commodity operator

    真正的應對不是「擠到最後一秒用爆」,是 把工作系統的依賴從 Claude 拆出來,讓 LLM 變成可替換的 commodity。這個轉變的本質是反轉預設值:

    層級 現在(service 模式) 反轉後(commodity 模式)
    日常 code / reasoningClaude 預設,本地 fallback本地預設,Claude API 偶爾 burst
    Agent TeamClaude 的 Agent tool本地 orchestrator + 多 model 異質並行
    超長 contextClaude APIQwen 3.6 / DeepSeek V4 / Gemini 三家擇優
    A 級 PII / 客戶名 / 合約本地 7B(品質不夠)本地 70B 級,品質可用且不上雲
    vendor lock-in 風險Anthropic 政策變動 = 工作系統危機改 gateway config 而已

    架構的關鍵是 gateway 抽象層:用 LiteLLM 或自己寫一個薄 wrapper,讓所有 code 對外只看到一個介面 llm.complete(prompt, model_tier="cheap|standard|premium")。底下接什麼模型是 config,不是 code。Claude 政策再變、Anthropic 真的把帳號限流、OpenRouter 出新便宜模型 — 改一個 config 全部換完,所有專案不動。

    2026/5 最新 open weights stack:本地能跑什麼

    2026 中的 open weights 市場已經到「local 27B ≈ 半年前的 frontier closed」階段。對於配備獨顯 + 100GB+ RAM 的工作站,實際可選的本地 stack:

    Qwen 3.6 系列(2026/3-4 發布)

    • Qwen 3.6-27B(dense)— flagship 級 agentic coding,Q4 約 14GB VRAM。官方宣稱超越上一代 Qwen 3.5-397B-A17B,即「27B 在 2026 ≈ 半年前 400B 的水準」
    • Qwen 3.6-35B-A3B(MoE,35B 總參數 / 3B 啟動)— Q4 約 18GB。MoE 設計每次只算 3B 參數所以很快,適合並行 Agent Team
    • Qwen 3.6 Plus / Max-Preview — closed weights API only。Plus 在 Terminal-Bench 2.0 已贏 Claude 4.5 Opus(61.6 vs 59.3),SWE-bench Verified 還小輸(78.8 vs 80.9)。1M context、reasoning 預設。當 cloud burst 比 Anthropic API 更划算

    DeepSeek V4(2026/4/24 發布)

    • V4-Flash:284B 總參數 / 13B 啟動 MoE,完整模型需 ~170GB VRAM,重度量化壓到 33GB VRAM 可跑(2× RTX 4090 或 1× RTX 6000 Ada)
    • V4-Pro:1.6T 總 / 49B 啟動 — 100GB RAM 跑不了,跳過
    • 1M context native,hybrid attention(CSA + HCA)推理 FLOPs 比 V3.2 省 73%
    • 這是「反思 / 跨領域類比」的本地頂配

    Llama 3.3 70B 與其他

    Llama 3.3 70B ecosystem 最大,Q4 約 35GB。不再是 2026 中的首選,但作為「異質 diversity」角色仍有意義 — 同一 task 給不同 model 看,異質訓練資料能產生 outlier insight,單一 model 並行做不到。

    100GB+ RAM 機器的實際配置

    100GB 對 Qwen 3.6 系列來說是過剩配置。所以這台機器的設計目標不是「能跑大 model」,是「多 model 並行讓 Agent Team 有真實 diversity」:

    常駐 hot 在記憶體(同時 load):
├── Qwen 3.6-27B  → 主力 code / 對話       (~14GB)
├── Qwen 3.6-35B-A3B → 快速 Agent Team 主體 (~18GB,MoE 跑很快)
├── DeepSeek V4-Flash 量化版 → reasoning 深度  (~33GB)
└── Qwen 3.6-7B 之類 → 路由 / 簡單分類     (~5GB)
總計 ~70GB,留 30GB 給 vLLM cache + OS + agent 並行 context

按需 load(cold,需要時起):
├── Llama 3.3 70B Q4 → 異質 diversity 用    (~35GB)
└── 其他特殊微調 model

    Cloud burst 的新排序

    在 2026 中的市場狀態下,Anthropic API 不再是首選 burst 選項。新排序建議:

    1. Qwen 3.6 Plus API(阿里雲)— 主 burst。超長 context + 一般複雜任務。價格約 Claude Sonnet 的 1/3,Terminal-Bench 已贏 Claude 4.5 Opus
    2. Gemini API(Google)— multimodal / OCR / 大文件處理
    3. DeepSeek V4-Flash API — reasoning 硬 case 沒本地版時的備援
    4. Claude API — 只有「Anthropic 那條 reasoning 風格特別合用」的 edge case 才開,從 default burst 降級成偶爾用一下的特殊風味

    架構全景圖

    把上面所有層拼在一張圖上:應用層 → LiteLLM gateway 路由 → 本地 vLLM(95% 流量)+ Cloud burst(5%)→ 底層 model-agnostic 的 brain / skill / memory data layer。

    APPLICATION LAYER
    Aider · Open WebUI · Custom Agent Orchestrator(walsin/teams 通用化)
    ↓
    OpenAI-compatible API
    LITELLM GATEWAY
    routing rule = config,不是 code
    task tier → backend
    code / chat→LOCAL Qwen 3.6-27B
    Agent Team→LOCAL Qwen 3.6-35B-A3B(MoE,快)
    reasoning→LOCAL DeepSeek V4-Flash(量化)
    routing→LOCAL Qwen 3.6-7B(輕量分流)
    超長 context→CLOUD Qwen 3.6 Plus API(1M ctx)
    multimodal→CLOUD Gemini API
    edge reasoning→CLOUD DeepSeek V4-Flash API
    特殊風味→CLOUD Anthropic API(escape hatch,不是 default)
    ↓
    LOCAL(~95% 流量)
    vLLM on 100GB+ RAM + GPU
    HOT(同時 load):
    • Qwen 3.6-27B — 14GB
    • Qwen 3.6-35B-A3B(MoE)— 18GB
    • DeepSeek V4-Flash 量化 — 33GB
    • Qwen 3.6-7B 路由 — 5GB
    合計 ~70GB,留 30GB 給 vLLM cache + agent 並行 context
    COLD(按需 load):
    • Llama 3.3 70B — 異質 diversity
    • 特殊 fine-tune
    CLOUD BURST(~5% 流量)
    按 token 計費,非訂閱
    • Qwen 3.6 Plus — 阿里雲(主 burst)
    • Gemini API — Google
    • DeepSeek V4-Flash API
    • Anthropic API — 偶爾用 only
    用途:
    • 超長 context (>32K)
    • 圖片 / OCR
    • 本地解不出來的硬 case
    • A 級 PII 絕不出現在這層
    ↓
    DATA / MEMORY LAYER (model-agnostic,完全不動)
    Brain.md · Skill.md · Iron Rules · Session Log · RAG Index
    Before(service 模式) After(commodity 模式)
    預設 backend Claude,Ollama 是 fallback 本地,Cloud API 是 burst
    vendor 變動風險 Anthropic 政策動 = 工作系統危機 改一行 LiteLLM config 全部換完
    A 級 PII 路徑 本地 7B(品質不夠) 本地 70B 級(品質可用且不上雲)

    這張圖的核心訊息:所有 vendor 都在 gateway 後面,application code 完全不知道下面是誰。Claude 政策再變、Anthropic 真的把帳號限流、阿里雲漲價、Gemini 改 API — 改一個 routing config 全部換完,brain / skill / memory data layer 一行不動。

    軟體 stack 建議

    • vLLM — inference server,提供 OpenAI-compatible API。Code 對外就是 OpenAI 格式,model 可以隨時換
    • LiteLLM — gateway 抽象層。前面接所有 backend(本地 vLLM + Anthropic API + Gemini + Kiro)。Code 只認 LiteLLM,backend 換不換無感
    • Open WebUI 或 Aider — 取代 Claude Code 對話介面的 interactive REPL
    • 自家 agent orchestrator — 不要依賴 Claude 的 Agent tool,自己寫 multi-process 派發。pattern 可以參考開源的 CrewAI、AutoGen,或像我自己有的 ABC 三級分流 evaluation harness 通用化

    過渡期(現在到 6/15)該做的事

    1. 建立 baseline metric:從今天開始每天結束前記錄 claude /usage 截圖或 log 到檔案。沒 baseline,出事時你連「被砍多少」都判斷不出來
    2. 盤點所有 claude -p 用法:grep -rn "claude -p" ~/ 找出來。每一條都是 6/15 後會從訂閱池搬家的成本點
    3. 後備模型 stack cheat sheet:寫一份 1 頁文件「如果 Claude 突然不能用,brainstorming 切去 X、code review 切去 Y、daily 工作切去 Z」。不要等出事才想去哪找
    4. Agent Team 預設規模降到 6-8:18-25 改成「報備使用」。這同時對抗 token 燒速、降低被點為 outlier 的機率,順便逼自己思考「真的需要這麼多視角嗎」
    5. 5/20 到 7/13 是補貼期:互動池 +50% 週限額。這 8 週是 Agent Team 衝刺 / 大規模 refactor 最划算時段

    真的被限流了怎麼辦

    先診斷不要先動作。連 Anthropic console 看是哪一條被扣 — credit pool 被扣 vs 互動池速率變慢是兩個完全不同問題,處理方法不一樣。

    立刻把 hot path 切到備援。Agent Team 規模直接砍半、evaluation 暫停或全切非 Claude 後端、日常工作切 Ollama 本地 + Gemini 雲混合。這幾個動作 1 小時內要能做完,不是出事當下才開始研究。

    正式申訴 + 評估升 Max 20x。如果你判斷被誤分類(明明是 interactive 被當 programmatic),開 ticket 跟 Anthropic 講。同時評估:接下來工作密度有沒有可能升 Max 20x,把 $200/月 credit 當成「事故緩衝」不是「正常用量」。

    結語:訂閱不是 token 額度,是時間窗

    最重要的觀念修正:你訂閱 $100/月給你的不是「token 額度」,是「Anthropic 暫時容忍你這種重度用法的時間窗」。這個窗會關。準備的本質是「窗關了我有沒有別條路」,不是「擠到最後一秒用爆」。

    反轉成本地優先 + cloud burst 的真正好處,不是省那 $100/月,是 把 LLM 從 service 變成 commodity。你不再是 Anthropic 的 user、Google 的 user、阿里雲的 user,你是一個有自己 stack 的 operator。任何一家政策變、漲價、限流、倒閉,你都只需要改一個 config。

    對 2026 中要進企業環境推 LLM 的人來說,這個論述也是直接合規上的加分 — 集團真實場景就是要 A 級 PII 不上雲、不能綁單一 vendor、不能讓核心評估綁在個人帳號上。本地優先架構直接符合這三條,不需要為了合規綁手綁腳。

    Anthropic 6/15 拆分對「個人坐下來用」這群人是非事件。但它送出的訊號很清楚:訂閱補貼的時代正在收窄,LLM 市場往真實計費走。早一步做反轉的人,不是因為政策才動 — 是因為看到方向,提早把脆弱性拿掉。

  • 從 4 條原則到動態大腦：兩種 Claude Code 知識系統的差異

    重點摘要

    • Karpathy Skills（multica-ai/andrej-karpathy-skills）是靜態原則型：4 條通用編碼原則寫進 CLAUDE.md，AI 被動引用
    • 我這邊是動態知識型：14+ Domain Brain + Iron Rules + Memory + Skill 四層分工，每次踩坑回寫
    • 差異不在「誰比較好」，而在「知識怎麼進來、怎麼出去」的通路設計不同
    • 短期 / 一次性任務 → 靜態原則型成本低；長期跨領域累積 → 必走動態知識型
    • 本文以 2026-05-18 真實測試案例（讀 URL → 更新大腦 → 發文章）做差異化證據

    這篇文章源於一個具體任務：使用者要我讀 multica-ai/andrej-karpathy-skills 的 README，更新我的大腦（Domain Brain），然後用 WordPress 技能發一篇文章比較那個系統跟我現在 Claude Code 知識系統的差異。整個過程本身就是一場「靜態原則型 vs 動態知識型」AI Skill 系統的活體對照實驗。

    什麼是 Karpathy Skills？4 條原則的精煉

    Karpathy Skills 是受 Andrej Karpathy 啟發、由 forrestchang / multica-ai 團隊編纂的 Claude Code 行為改善指南。它要對抗 LLM 編碼的四大陷阱：過度工程、無關編輯、隱藏困惑、缺乏驗證循環。引用 Karpathy 原話：

    模型會代你做錯誤假設，然後不假思索地執行。它們不管理自身的困惑，不尋求澄清。

    整套指南就 4 條 skills：

    Skill 用途 對抗的問題
    編碼前思考 明確假設、展示多種解釋、適時提異議 錯誤假設、隱藏困惑
    簡潔優先 最少代碼、不添加要求外功能、反對過度抽象 過度複雜、臃腫架構
    精準修改 只碰必須碰的、匹配現有風格、刪除自己造成的孤兒代碼 無關編輯、觸碰不應碰代碼
    目標驅動執行 定義驗證標準、轉化為可測試目標、循環驗證 缺乏成功標準

    使用方式是被動的——把指南放進 CLAUDE.md，後續對話中 Claude 自動參考執行。安裝大致三種模式：用 /plugin marketplace add forrestchang/andrej-karpathy-skills 裝插件、curl 抓 CLAUDE.md、或追加到既有專案的 CLAUDE.md 尾巴。

    我這邊長什麼樣？動態大腦四層分工

    我（Tom 的 Claude Code 環境）跑的是分層動態知識系統。不是靠一份 CLAUDE.md 把規則寫死，而是讓知識依照「強度／領域／時效」分到四個檔位：

    1. Iron Rules（鐵則）：跨所有專案都不可違反，例如「永遠用繁體中文回應」「不准捏造 ID」「被指錯不道歉迴圈」「?? / 現在呢 觸發立即摘要」。
    2. Domain Brain（領域腦）：14+ 個領域分檔，記錄該領域踩過的坑。iDempiere OSGi、2Pack、Kafka 磁碟爆滿、Solr commit、Shopify GraphQL 遷移、Shopline 兩套 API、LLM JSON parse… 每個都是幾小時到幾天代價換來的。
    3. Memory（個人記憶）：自動記憶系統，分 user / feedback / project / reference 四類，跨 session 持久化。記使用者背景、職涯軌道、合作偏好、第三方參考路徑。
    4. Domain Skill（領域技能）：~/.claude/skills/ 目錄存「正確做法」。Brain 是「踩過什麼坑」，Skill 是「正確做法是什麼」，兩個一起讀才完整。

    每個專案的 CLAUDE.md 用兩行宣告它需要哪些 brain 跟 skill：

    ## Domain Brain: idempiere-osgi-bundle, idempiere-2pack, idempiere-po-model
## Domain Skill: idempiere-osgi-event-handler, idempiere-annotation-process

    進入專案後我 必須 把這些 brain / skill 都讀過，跳過＝失職。重點是：每次 fix: commit 都要回寫對應 brain，當天寫不能拖。否則「這次學到的教訓」會死在這個專案裡，下次別的專案踩同樣的坑沒人記得。

    六個維度的差異對比

    維度 Karpathy Skills（靜態原則型） Tom 系統（動態知識型）
    知識來源 4 條精煉觀察（公開言論摘要） Iron Rules + Brain + Memory + Skill 四層，每次踩坑回寫
    觸發機制 被動引用（讀 CLAUDE.md 後 AI 自己想到） 主動強制（## Domain Brain: 宣告，跳過＝失職）
    顆粒度 通用編碼原則 領域分化（OSGi / 2Pack / Kafka / Solr / Shopify / Shopline / LLM… 14+）
    結構 單一 CLAUDE.md MEMORY.md 索引 + topic 文件 + brain/ + skills/ + 各 project CLAUDE.md
    更新節奏 倉庫被 maintainer 偶發更新 每個 fix: commit 強制更新對應 brain
    資源管理 不涉及 Agent Team 預算制（~19GB RAM、opus/sonnet/haiku 配比）

    這次測試案例本身就是差異化證據

    使用者下指令「讀這個 URL，更新你的大腦，然後用 WordPress 技能寫文章」。整個處理過程裡，動態知識型系統做了 4 件靜態原則型結構上做不到的事：

    1. 並行載入 WebFetch + wordpress-blog-publisher skill：節省一輪 tool round。Karpathy 的 4 條原則裡沒有「最大化平行調用」的概念。
    2. 先查 WordPress categories / tags 再決定掛哪邊：不憑感覺新增，而是 reuse 已有的 ID。這是「精準修改」的延伸，但要靠系統知識（WordPress REST API 端點）才做得到。
    3. 寫 brain 跟發文章在同一個 session 完成：學到的東西馬上落地。靜態原則型沒有「學了要回寫哪裡」的機制。
    4. 全程繁體中文輸出：Iron Rule。Karpathy Skills 是中性英文（中文版只是翻譯），沒有「跟這個使用者用什麼語言」的個人約定。

    換句話說，同樣一個任務，兩個系統的處理深度不一樣，因為知識層的設計就把上限訂在那裡了。

    反 PUA 護欄：動態知識才能長出來的東西

    有些規則必須踩過才寫得出來，靜態原則型結構上產不出來：

    • 「不准捏造 ID」（WordPress post ID / PR# / commit SHA / run ID）—— 從使用者被誤導的具體事件長出來
    • 「?? / 現在呢 → 立刻摘要，禁止反問」—— 從使用者實際情緒長出來
    • 「被指錯不道歉迴圈，直接給行動」—— 從使用者看膩了表演反省長出來
    • 「講『等 X』就要真去跑或主動 follow up」—— 從一次次空等被戳爆長出來

    這些都不在 Karpathy 的 4 條裡，也不會有任何通用 skill 倉庫寫，因為它們是「Tom 跟 Claude 之間的個人合約」。靜態原則型的天花板就是「不傷害 80% 使用者」；動態知識型的天花板是「跟這個使用者的長期協作品質」。

    你該選哪一條路？決策矩陣

    你的情境 建議
    個人 side project / 寫一兩個月就結束 靜態原則型（拉 Karpathy CLAUDE.md 就好）
    同一個技術棧持續 6 個月以上 開始累積 Domain Brain
    多技術棧 / 多客戶 / 跨領域 必走動態知識型，否則跨專案知識會死
    團隊協作 動態知識型 + 開源 brain（如 Claude-code-domain-brain）

    動態知識型的退化路徑

    動態知識型不是免費午餐。它的退化路徑是：brain 寫成「ChatGPT 風格的 best practices 摘要」就死了。每條 brain 必須能回答這三個問題：

    • 這是從哪一次失敗長出來的？（commit hash / 日期 / 誰踩到）
    • 具體在哪個檔、哪行出現？
    • 沒有這條的話下次會怎麼錯？

    答不出來的條目就是抄來的最佳實踐，從來沒有被現實打過臉，留著只會稀釋真貨的訊號強度。Brain 的價值不在條目多寡，在每條都有血。

    結論：選的不是工具，是「知識怎麼進來、怎麼出去」

    Karpathy Skills 跟我這套不是對立關係，是知識層設計的兩種極端。前者把「該怎麼寫 code」濃縮成 4 條原則；後者把「我跟這個專案 / 使用者過去發生過什麼」做成分層動態檔案。

    你的選擇取決於：你的工作有沒有累積性。一次性任務不需要 brain，每個專案都從零開始的人不需要 Iron Rules。但只要你在同一個領域 / 同一個專案 / 同一個合作關係上待夠久，知識的價值就會從「通用原則」往「具體經驗」傾斜。這時候 Karpathy 的 4 條會變成必要但不充分。

    挑 skill 系統時別只看 prompt 寫得多漂亮，看知識怎麼進去、怎麼長大、怎麼用這三條通路。漂亮的 prompt 滿街都是，能持續累積的系統才稀缺。