背景：我們怎麼管理版本和工作項目

我們的專案用 semver（語意化版本）管理發布節奏。每個版本（如 v0.3.0）有明確的功能範圍，由數個提案定義——每個提案描述一組要交付的功能和邊界。版本內部再拆成多個工作項目（ticket），按批次排序執行（類似 Sprint，但以依賴順序而非時間框分批）。

版本的生命週期很單純：planned → active → completed。一個版本的所有 ticket 完成後，跑發布流程、打 tag、標記 completed。

圍繞這個流程，我們自建了兩個 CLI 工具：

這兩個工具在設計時，都選擇了「彈性優先」——接受任何合法輸入，不對使用者的選擇做判斷。

這個選擇在後來被證明是錯的。

版本語意：大版本和小版本的分工

semver 的 MAJOR.MINOR.PATCH 有明確的語意分工：

版本號不只是標記——它決定了工作項目應該放在哪裡。一個 bug fix 放進 MINOR 版本，語意上等於說「這個 bug fix 和下一批新功能綁定發布」——多數情況下這不是你想要的。

版本管理只是其中一個場景——任何接受自由輸入的內部工具，只要輸入涉及分類或歸屬判斷，都可能有同樣的問題。我們的工具沒有表達這個語意，接下來的兩個事件是後果。

事件一：改善類工作放進了新功能版本

v0.3.0 發布了三個新功能。發布後的版本檢討發現了一個測試隔離問題，v0.3.1 做了 hotfix。

接下來要做根因分析和系統性防護。建立工作項目時，順手指定了 --version 0.4.0——v0.3.0 和 v0.3.1 都已發布，v0.4.0 是下一個功能版本，看起來是合理的選擇。

CLI 接受了這個輸入，沒有任何提示。

三張改善類的工作項目（根因分析、重構、規則文件）就這樣和 PostgreSQL Storage Backend（v0.4.0 的核心功能）混在一起。直到使用者檢視版本看板時才發現不對——改善類工作和新功能綁在同一個發布週期，語意混亂。

修正方式：建立 v0.3.2、遷移三張 ticket、重新發布。額外花了一輪操作成本。

事件二：已完成版本的幽靈

版本看板的異常不止一處。同一次檢視中，看板顯示 v0.2.0 有未完成任務。

查證後發現 v0.2.0（38 張 ticket 全部完成）、v0.2.1（7 張全完成）、v0.2.2（1 張已結案）三個版本在版本清單中仍標記為 active。它們在數個月前就該標為 completed，但沒有。

原因是版本發布工具的 pre-flight 檢查只看「當前版本的 ticket 是否完成」，不掃描「更早的版本是否有 active 殘留」。早期版本可能是手動發布的，跳過了狀態同步步驟。工具沒有補救機制，殘留就一直留著。

看板靜默地把這些版本顯示為「有未完成工作」，產生誤導。

為什麼會這樣：工具沒有 opinion

兩個事件的共通根因：工具在應該有立場的地方選擇了沉默。

建立工作項目時

ticket create --version 0.4.0 --type ANA --action "分析" — 工具知道這是一張分析類的 ticket，也知道 v0.4.0 的 scope 是 PostgreSQL Storage。但它不認為自己有責任判斷「分析類 ticket 放在新功能版本是否合理」。它只做格式驗證：版本號存在嗎？通過就建立。

發布版本時

發布工具的盲區更隱蔽。每次發布時，工具會檢查「這個版本的所有工作項目都完成了嗎？」——如果答案是「是」，就繼續打 tag、更新文件、推送。但它從不回頭看更早的版本：有沒有哪個舊版本的工作項目早已全部完成，卻一直沒被標記為「已完成」？這種殘留不影響當前發布，但會讓看板持續顯示「舊版本有未完成工作」，誤導每一個後續查看看板的人。

兩者都是「工具做了它被要求做的事，但沒做它應該做的事」。

工具什麼時候應該有 opinion？

不是所有情境都需要工具有立場。有一個簡單的判斷標準：

當存在一個「多數情況下正確的預設行為」時，工具應該把它表達出來。使用者可以覆蓋，但預設路徑應該引導正確做法。

這裡的 opinion 是建議而非阻擋——工具提示預設路徑，使用者可以覆蓋。這個區分很重要：阻擋式的 opinion（必須額外操作才能繞過）適合風險高的操作（如 force push to main、刪除生產資料）；建議式的 opinion 適合歸屬判斷。錯誤成本不對稱決定了形式：建議錯了，使用者覆蓋一次，幾秒鐘；沉默錯了，事後修正，幾小時。只要建議的正確率不是極低，建議就比沉默划算。

這個邏輯不限於 CLI。API 的預設參數、表單的預選值、自動化流程的預設路由——任何使用者需要做選擇的介面，都有機會用預設行為表達 opinion。

改善類 ticket 放 patch 版本，在多數情況下是正確的。「多數情況下對」已經足夠讓工具表達立場：

1$ ticket create --type IMP --action "修復" --target "retry test"
2[建議] 此 ticket 為修復類，建議放 v0.3.2（patch bump）
3       而非 v0.4.0（下一個功能版本）
4       使用 --version 覆蓋此建議

前版本 status 掃描也是。已完成版本仍為 active 在所有情況下都是異常——工具不需要猜，只需要報告：

1$ version-release check
2[WARN] v0.2.0：38 張 ticket 全部完成但 status 仍為 active

為什麼使用者是 AI agent 時問題更嚴重

這個 pattern 在人類使用者身上已經存在——人類也會走阻力最小的路徑。但人類有跨次記憶：「上次放錯版本被糾正過，這次注意一下。」

AI agent 沒有這個。

每個 session 是一個全新的 agent，它讀到的是：版本清單中 v0.4.0 是 active、CLI 接受 --version 0.4.0、沒有警告。於是它每次都會用最直覺的選擇——當前 active 的最大版本。

上次的教訓不會自動傳遞到下次。除非教訓被固化成工具行為。

這把「工具應該有 opinion」從「建議做法」升級為「必要條件」：

• 人類使用者：opinion 是提醒，有助於減少錯誤
• AI agent 使用者：opinion 是最可靠的防線，因為工具在操作當下的即時引導是離決策點最近的攔截

工具的預設行為，就是團隊的實際流程

工具的預設行為，就是團隊的實際流程。

文件上寫「改善類工作放 patch 版本」沒有用——如果工具不引導，使用者會走工具預設的路徑。人類和 AI 都是。文件說的和工具做的不一致時，工具會贏。

但文件不是敵人。文件定義「應該是什麼樣」，傳遞設計理由和架構決策；工具實現「實際是什麼樣」。兩者不一致時，優先修工具。

如果你希望使用者做 X，不要寫文件說「請做 X」——把工具的預設行為設成 X。

這個原則適用於所有內部工具設計，不限於版本管理：

每一個「寫文件提醒使用者遵守操作規範」都是一個信號——工具的預設行為還有空間改善。看到這個信號時，優先評估能否把提醒轉化為工具的預設行為。

Rails 的「Convention over Configuration」是同一個觀念的先驅表達：框架用約定引導開發者走正確路徑，省去不必要的配置決策。有 opinion 的工具在必要決策時引導方向。兩者共通的是把判斷成本從「每次使用時」前移到「設計工具時」——一次判斷，永久生效。

回去檢查你的工具

1. 列出你的工具中所有使用者需要做選擇的地方——CLI 參數、API 欄位、表單選項、流程分支
2. 對每個問：有沒有「多數情況下正確」的預設值或建議值？
3. 有的話，加建議式 opinion（提示預設 + 允許覆蓋）
4. 檢查工具的清理路徑：有沒有前一次操作應該同步但沒有同步的狀態？
5. 如果你的工具會被 AI agent 或自動化流程呼叫，上述每一項的優先級加倍——自動化沒有判斷力，它只走預設路徑

v0.3.0 發布後發現一個測試隔離問題，v0.3.1 做了 hotfix。接著要做根因分析和系統性防護（重構 + 品質規則更新）。

建立工作項目時指定了 --version 0.4.0——v0.3.0 和 v0.3.1 都已發布，v0.4.0 是下一個功能版本。工具接受了，沒有提示。

結果：三張改善類工作（根因分析、State Registry 重構、品質規則文件）和 PostgreSQL Storage Backend 混在同一個版本裡。改善和新功能綁定發布，語意混亂。事後建立 v0.3.2 遷移工作項目並重新發布。

根因：工具只做格式驗證

ticket create --version 0.4.0 被接受的條件是「v0.4.0 存在於版本清單且為 active」。工具不分析工作類型（分析 / 修復 / 重構 / 新功能）和版本層級（MINOR / PATCH）的匹配度。

semver 有明確的語意分工——MINOR 用於新功能，PATCH 用於修復和改善。這個語意可以被工具表達：

工具可以根據工作類型自動建議版本，使用者可以覆蓋。建議錯了，使用者多打一個參數；沉默錯了，事後遷移。

教訓

語意已經存在，工具有責任表達它。 semver 的 MINOR/PATCH 分工是廣泛認知的慣例。但「知道」和「每次建立工作項目時都記得套用」是兩件事。工具可以把這個「記得套用」的成本降到零：讀取工作類型，對照 semver 語意，輸出建議。

這個 pattern 適用於任何「輸入涉及分類判斷」的工具介面。工具不需要代替使用者做決策，但可以把分類規則從「腦中的知識」轉化為「介面上的提示」。同一次版本檢視中發現的另一個工具盲區（狀態殘留）見 version_status_residual_ghost。

多人（或多 agent）並行開發時，如果修改集中在同一個檔案，協調成本可能抵消並行的收益。以下是一個具體案例。

v0.3.0 的 JS SDK 開發中，五張 ticket 被並行派發給五個 AI agent：flush 邏輯、離線容錯、自動攔截、頁面生命週期、rate limiting。前四個都需要修改同一個檔案 monitor.ts。

結果：

• 三個 agent 回報 branch protection hook 阻擋 src 編輯
• 兩個 agent 回報 file modified since read 拒絕 Edit（另一個 agent 正在寫同一檔案）
• PM 花了多個回合協調 commit 策略：「你先 commit」「你等他完成」「你只 git add 你的檔案」
• 最終 PM 手動合併所有 agent 的變更，做了一個統一 commit

並行派發的目標是縮短總工時。但五個 agent 改同一檔案時，協調成本抵消了並行的收益。

根因：派發粒度錯在 ticket 層而非檔案層

派發決策看的是 ticket 的獨立性——五張 ticket 描述的功能確實獨立（flush、離線、攔截、生命週期各自有清楚的邊界）。但獨立的功能不等於獨立的檔案。五個功能的修改都集中在 monitor.ts 這一個檔案上。

ticket 獨立 =/= 檔案獨立。並行安全的判斷基準應該是後者。

教訓

派發前掃描 where.files：如果多張 ticket 的目標檔案有交集，序列化派發。前一張完成並 commit 後，再派下一張。

序列的代價比衝突的代價低：五個 agent 序列執行可能需要 5 倍時間，但每個 agent 在乾淨的工作區上操作，不需要協調。五個 agent 並行但衝突，PM 的協調時間加上 agent 的等待和重試，總成本可能更高。

Worktree 隔離不是萬靈丹：git worktree 讓每個 agent 有獨立的工作目錄，避免 working tree 衝突。但如果兩個 agent 修改同一檔案的不同區段，merge 時仍需人工判斷。Worktree 解決的是「同時寫同一個 working tree」的問題，不解決「同時改同一個檔案的語意衝突」。

適用場景

這個 pattern 不限於 AI agent。人類開發者在同一個 Sprint 中被分配修改同一個檔案的不同功能時，也會遇到 merge conflict。差異在於人類可以口頭協調（「我先改完你再改」），agent 目前缺乏這個即時溝通管道。派發者（PM 或 CI 系統）需要在派發時就做好檔案衝突預判。

版本看板顯示 v0.2.0 有未完成任務。查證後發現 v0.2.0 的 38 張工作項目全部完成、v0.2.1 的 7 張全部完成、v0.2.2 的 1 張已結案——但三個版本在版本清單中仍標記為 active。

這些版本在數個月前就完成了所有工作，但從未被標記為 completed。看板忠實地反映了版本清單的狀態，所以持續顯示「有未完成工作」。

根因：工具的檢查範圍太窄

版本發布工具在發布 v0.3.0 時，只做一件事：「v0.3.0 的所有 ticket 都完成了嗎？」答案是「是」，就繼續發布。

它從不問：「比 v0.3.0 更早的版本中，有沒有哪個版本的 ticket 早已全部完成，但 status 仍為 active？」

這個檢查加起來不難（遍歷版本清單、對每個 active 版本計算 ticket 完成率、完成率 100% 但 status 不是 completed 就報 warning）。但沒有人想到要加——因為在設計工具時，焦點在「當前版本的發布流程」，不在「全局狀態一致性」。

教訓

資料庫設計中，如果只在寫入時驗證單筆資料的格式而不檢查跨表一致性，orphan record 就會累積。版本管理工具的 pre-flight check 是同一個 pattern——它是內部流程的「外鍵約束」。範圍太窄，殘留就會累積。

工具只檢查當前版本，一致性就只在當前版本內維持。歷史版本的狀態漂移不會被發現——直到有人手動查看看板。

修正

在版本發布的 pre-flight check 加入全局掃描：

1$ version-release check
2[OK] v0.3.0：所有 ticket 完成，可發布
3[WARN] v0.2.0：38 張 ticket 全部完成但 status 仍為 active
4[WARN] v0.2.1：7 張 ticket 全部完成但 status 仍為 active

修正成本極低（一個迴圈 + 一個 warning），但能在問題累積前暴露。

JS SDK 的 Monitor class 在一輪並行開發中，三個開發者各自新增了 private 欄位：flushing（flush 併發 guard）、retryCount（重試計數）、lastHeartbeat（心跳時間戳）。三個欄位各自在功能邏輯中被正確使用，但都沒有加進 __reset() 方法。

測試框架在每個 test case 之間呼叫 __reset() 清理狀態。因為 retryCount 沒被重置，第一個 test case 把 retryCount 遞增到 1，第二個 test case 繼承了這個值，retry 邏輯提前觸發，測試失敗。

失敗的測試看起來像是 retry 邏輯有 bug，但實際上 retry 邏輯完全正確——問題出在測試隔離。

根因：隱含契約沒有顯性化

Class 的每個 private 欄位都有一個隱含契約：「所有生命週期路徑都知道你的存在。」這包括初始化（constructor / init）、重置（reset / dispose）、序列化（toJSON，如適用）。

新增欄位時，開發者通常會先在功能邏輯中使用這個欄位——因為那是他加欄位的目的。但「同步到 reset」不是功能邏輯的一部分，它是一個跨切面的維護動作。遺漏的機率隨欄位數和開發者數增加而上升。

多人（或多 AI agent）並行開發時問題更嚴重——每個人只看自己加的欄位，沒有人有動機去檢查 reset 的完整性。並行修改同一檔案的協調問題見 parallel_agent_same_file_conflict。

防護：State Registry Pattern

將所有 private 欄位的初始值集中宣告一次：

 1function initialState() {
 2  return {
 3    config: null,
 4    buffer: [],
 5    flushing: false,
 6    retryCount: 0,
 7    lastHeartbeat: 0,
 8    // 新增欄位加在這裡——init 和 reset 自動包含
 9  };
10}

reset 改用 Object.assign(this, initialState())。新增欄位只改一處，init 和 reset 自動同步。

配合一個 reset 完整性測試：reset 後 snapshot 比對 initialState 的所有 key——新增欄位但忘記加到 initialState 會因型別或 key 不一致而紅燈。

適用場景

任何有「重置到初始狀態」需求的 class：測試框架的 setUp/tearDown、物件池的回收、singleton 的 reinit。問題在「新增欄位」和「同步 reset」是兩個分開的動作（TypeScript、Go、Dart 都會遇到）——只要是分開的，就有遺漏的可能。State Registry 把兩者合併成一個動作。

官方文件查核放過的五類落差

content/cli/ 五類終端機工具文章（監控 / 圖表 / 多工器 / 檔案管理 / SQL 客戶端）在實機驗證時抓到、純靠 docs 查核會放過的落差：

1. 旗標改名

zellij web 文件寫有 --bind，實際 0.43.1 是分開的 --ip 與 --port。讀者照文件下指令會得到 unknown flag error、但不知道正確旗標是什麼。

2. 設定鍵 migrate

lazygit 的 pager 設定文件寫 git.paging.pager，新版 0.62.2 改成 git.pagers（list）。舊鍵啟動時會被自動 migrate、改寫設定檔 — 讀者照舊文件設定後發現設定檔被工具自己改掉。

3. 隱含 schema prefix

dblab 的查詢編輯器要 schema 限定（SELECT * FROM public.products），裸 products 會報 relation 不存在。原因是編輯器連線的 search_path 不含 public — 文件沒提。

4. 平台特定 segfault

nvtop 在 Apple Silicon mac 裝得起來，但 snapshot 模式直接 segfault。GPU 後端不穩。裝成功不代表能用 — 文件只說「支援 macOS」。

5. Driver 差異

同一個 Postgres，lazysql（Go pq driver）連無 SSL 的 DB 要 ?sslmode=disable，pgcli / harlequin（Python psycopg）不用。同樣的連線字串在不同工具會有不同行為、文件各自不提對方。

共通模式

這五類落差有個共通點：讀者照文件走會撞牆、卻在文件裡找不到答案。實機跑一次就現形，而且現形的正是文章最該寫的內容 — gotcha 段落省下讀者各自撞一次的時間。

官方文件的 fact-check 只能驗證「文件說的是否正確」，驗不了「文件沒說的是否存在」。實機驗證補的是後者。

相關連結

• Verification-driven CLI skill（.claude/skills/verification-driven-cli/）— 操作步驟
• 終端機圖形化工具總覽 — 用此流程生產的工具文章
• #199 一篇文章只承擔一種功能 — 本文精簡的依據

為什麼 migration playbook 需要自己的方法論

Migration playbook 跟 single feature deep article 是不同 content category：

關鍵差異：deep article 是 single direction implementation、migration playbook 是 bidirectional comparison + process。第一輪寫了 5 篇後發現結構完全不同；嘗試套 deep article 的固定結構都只對 1 種情境適用，於是用 diff dimension audit（寫前評估 source/target 在哪些維度差異最大）選對應的結構模板（Type A-F，依主導差異維度決定）。

第一輪 batch（5 篇）：Type A-E 浮現 + cadence collapse 3/5

第一輪寫了 5 篇跨 vendor migration playbook，每篇自然對映到一種 type（結構模板）：

• Splunk → Elastic Security — Type A phased translation
• Redis → DragonflyDB — Type B drop-in
• PostgreSQL → Aurora — Type C operational hybrid
• Datadog → Grafana Stack — Type D parallel streams
• Kafka ↔ NATS — Type E paradigm shift

Cadence collapse：前 3 篇被動寫作全部同質化

Cadence collapse 指批量寫作時、多篇文章的開場句型不自覺重複同一模式。

3/5 collapse — 主題語意 attractor「為什麼遷：X / Y / Z driver」在前 3 篇被動寫作下浮現。寫第 4 篇前發現問題、後 2 篇主動換 entry variant。

前 3 篇的 collapse 是 Stage 0 variant 規劃成為硬需求的直接證據。

Type A-E 怎麼浮現

5 篇寫完後比對結構、發現 5 篇結構完全不同，但都可以用「主導差異維度」解釋：schema 差為主 → phased translation、全 Low → drop-in、operational 差為主 → hybrid。Type A-E 從這 5 篇的歸納中浮現，第二輪 dogfood 再加上 Type F（topology re-layout）。

第二輪 batch（5 篇）：漏類驗證 + 多軸 High 實證

第二輪刻意選漏類場景驗證 self-aware limitation：

• PostgreSQL major version upgrade (14 → 17) — 漏類驗證（同 vendor）
• Redis cluster re-sharding — 漏類驗證（topology 重劃）→ Type F 浮現
• PostgreSQL → CockroachDB — 三維 High multi-axis 驗證
• MySQL → PostgreSQL — Type A 標準形態（263 行）
• MongoDB → Atlas — Type C 標準形態（349 行）

Stage 0 variant 規劃從第二輪開始全面啟用，cadence collapse 從 3/5 降到 0/5。

驗證成立的 4 項預測

1. 5 type 漏類確認：major version upgrade + re-sharding 結構跟 5 type 完全不同
2. 多重歸類 + tie-breaking 規則成立：PostgreSQL → CockroachDB 三維皆 High、按主導維度走 Type E + 高維度獨立段
3. Type A / Type C 標準形態仍適用：MySQL → PostgreSQL + MongoDB → Atlas 走標準模板
4. Stage 0 variant 規劃硬需求：第二輪 5 篇全主動 variant、collapse 0/5

浮現的 3 項新議題

1. 新 audit 維度（data topology）：re-sharding 揭露 5 維度沒「topology」軸 → 擴到 6 維
2. 「為什麼這篇不套」是漏類文章標準 frame：major-version-upgrade + cluster-resharding 都用這個 frame 開頭
3. 「高維度獨立段」升級為 multi-axis migration 標準結構元素

第三輪 batch（5 篇）：Type F dogfood + 候選軸驗證

第三輪驗證 data topology audit dimension 的 self-aware limitation 4 條 tripwire：

• PostgreSQL partition redesign（246 行）— Type F dogfood #2
• MongoDB shard + multi-DC expansion（291 行）— Type F dogfood #3 + parallel run 例外實證
• Vault → AWS Secrets Manager（272 行）— Identity axis 候選（45% 工作量）
• DynamoDB consistency model optimization（249 行）— Consistency axis 候選（85% 工作量）
• PostgreSQL multi-region GDPR rollout（238 行）— Residency axis 候選（40% 工作量）

第三輪維持 collapse 0/5，但 Type F 分裂出 sub-type（F-cluster vs F-multi-region），框架仍在演化。

累積 evidence

• Type F sub-type 浮現：F-cluster（單 cluster 內、不需 parallel run）vs F-multi-region（跨 region、需 parallel run）
• 3 軸候選確認可獨立：identity / consistency / residency 各帶 30-85% 獨立工作量；累積到 3-5 case / 軸後考慮升 audit 7-9 維
• Residency 是 cross-cutting constraint：不只是 driver、反向約束 topology + operational + application

三輪對照：方法論的演化軌跡

關鍵轉折是第一輪到第二輪：後續批次未再觀察到 collapse。

Self-aware limitation

本 methodology 從 15 篇 migration playbook dogfood 抽出 6 type；已知 limitation：

• 6 type 非窮盡：major version upgrade / merger consolidation 等情境不在 6 type 內
• 多重歸類常見：實際 source/target 配對很少完美對映單一 type
• 「主導維度」需 judgment：優先序是 audience-dependent heuristic、不是 universal 規則
• Collapse 歸因有共變因素：第二輪以後 collapse 消失，但同時作者已有第一輪經驗、且知道自己在測量 cadence（Hawthorne effect）。Stage 0 variant 規劃是介入手段之一，無法完全隔離歸因。N=5 的二項信賴區間也無法排除偶然
• 候選軸未 commit：identity / consistency / residency 各 N=1、累積到 3-5 case / 軸後才考慮升維

本 methodology 接受 evolution、不假裝穩定。

相關連結

• Migration Playbook Methodology skill（.claude/skills/migration-playbook-methodology/）— 操作步驟（6 維 audit、6 type、Stage 0 variant、4-reviewer）
• Vendor deep article methodology — sibling、處理 single feature implementation
• Case-first Agent Team Review Workflow — 教學模組級批次寫作流程
• #199 一篇文章只承擔一種功能 — 本文精簡的依據

背景

本 blog 的 backend 教學模組已完成多個 vendor overview。overview 層飽和後、自然的下一步是 overview 頁尾「預計實作話題」backlog 的深度文章。

寫了 deep article + migration playbook 後、確認 deep article 跟 overview 是不同產品、需要自己的方法論。差異見 migration playbook 方法論演化紀錄。

第一輪 batch（5 篇）：跨 vendor、5 種 entry framing

第一輪確認了結構 framework 成立、且章節名可隨主題調整。

6 段 framework 成立但章節名可變

6 段內容指引（問題情境 → 概念 → 配置 → 演練 → 容量 → 整合）在 5 篇都成立。但章節 1 的 framing 因主題本質不同自然分化 — 5 種 entry framing 都成立、章節 1 不必死守「問題情境」標題。

據此小修方法論：6 段 framework 是內容指引、不是章節標題模板。

Cadence collapse 0% — 主動 variant 有效

後 4 篇寫作前主動規劃 4 種 framing variant。跟 backend/07 的 51 vendor batch 對照：

Reviewer 單人足夠

deep article 焦點窄（單一 feature）、跨章 frame 重複風險低、case 引用密度低（1-2 個對照）。5 篇都採單一 reviewer 流程、未出現需要 multi-axis review 的盲點。

第二輪 batch（5 篇）：同 vendor sub-tool 系列、最高 collapse 風險

第二輪刻意選 cadence collapse 最高風險場景：5 篇 PostgreSQL sub-tool deep article、同 vendor / 同 article type / 同 audience / 同 6-section framework。

第二輪在最高風險場景（同 vendor sub-tool）仍維持 collapse 0%，且新增第五種 variant（lifecycle-driven）。

跨兩輪對照

關鍵驗證：

1. N=5 仍 0% collapse：5 種 variant 在最高風險場景（同 vendor sub-tool）仍完全錯開
2. 5 variant 不耗盡：5 種變體（lifecycle / pain / reverse / table / standard）對應主題自然進入方式、不是強制配對
3. cadence audit 最佳位置是進度 60-80%：進度 10-20% 只有 1 樣本訊號弱、60-80% 有 4 樣本對照訊號強

方法論演化小結

相關連結

• Vendor Deep Article skill（.claude/skills/vendor-deep-article/）— 操作步驟
• Migration Playbook 方法論演化紀錄 — sibling、處理 cross-vendor process
• Case-First Agent Team Review Workflow — 教學模組級批次寫作流程
• #199 一篇文章只承擔一種功能 — 本文精簡的依據

content/report/ 累積了 70+ 張原子化事後檢討卡片、.claude/skills/ 收錄三個 protocol skill。這些是用來指導下一輪實作、又會被下一輪實作的學習回流修正的活基礎建設。

本文把這套系統實際跑一輪的歷程紀錄下來、當未來「想用這套系統的人」的 onboarding case study。主軸是修一個 search filter bug — 看似一週工作、實際走完八輪迭代、產出 14 張新卡片 + 兩個 skill 的 v0.2 + 4 個 CI test、過程中還抓到自己的 dogfooding 失敗、回頭修一次。

起點：使用者問題

“我們搜尋頁的 標題/內文篩選功能現在雖然做出來了、但是還是有一個很嚴重的 BUG”

具體：Pagefind 分批 load、view 層 post-filter；切到 title-only 後、第二批 load more 的 8 筆全部 title 不含 query → 全 hidden、畫面閃但內容沒變、使用者看到「load more 沒效果」silent 失敗。

User 還明確補了一句：「所以除了用 JS 取巧解決畫面、但是實際功能面上怎麼配合跟實作 我們並沒有解決」— 這已經點到核心：問題不在畫面、在抽象層。

第一輪：拆卡片之前先想清楚

直接修 bug 是可選但不是 user 要的。User 強調：「先思考我的需求、然後思考各種狀況的邊界」。

依當時的兩個 skill — requirement-protocol（對話協議）跟 frontend-with-playwright（前端執行協議）— 把問題分解：

1. Bug 的結構性根因：filter 寫在視覺層、source 在資料層分批、兩層的「一筆」定義不一致 → silent 缺口
2. 解法策略空間：5 個合理選項（推進 query / 自動續抓 / 多 index / 誠實 UX / 明示縮小）— 每個機會成本不同
3. 跨領域通用性：這結構不只前端有 — 後端 middleware filter、map-reduce、SQL view 都同模式

User 的關鍵回應：「這部份可以補充 SKILL 中演算法不足的原因 … 卡片是經過多次迭代、擴充、然後分拆、再擴充、最後做連結」。

明確了協作方式：先建卡片、再灌進 skill、最後才修。卡片本身要走原子化拆解 → 補充 → 反向擴充 → 連結的多輪迭代。

14 張卡片的拆解（第一冷啟）

依 user 對 atomic 的標準（一卡一議題、一個議題多面向 OK、議題太多就拆），列出 10 張卡片提案：

冷啟版本一次寫完不求完美 — 約 1700 行、各卡 self-contained。

七輪迭代

迭代 1：抽 Pattern + 瘦身

寫完 #59 五策略後、發現 A/B/C/D/E 中 C（多 index）、E（明示縮小）沒對應 pattern 卡。抽出 #65 / #66 補完 pattern 卡組。同時瘦身 #59 → 純路由（細節留 pattern 卡）、#55 + #57 移除跟 #63 重複的「四類資料源」段。

迭代 2：補概念深度

回頭讀 #56 / #63 / #64、補抽象層的「為什麼」：

• #56 加「驗收的時間軸：四個 checkpoint」概念
• #63 加「形狀識別 protocol」+「形狀混合」+「形狀的可改造性」
• #64 加「跨領域通用的本質 = 資訊可見範圍」+「上推代價」

迭代 3：跨卡連結

新卡跟 #1-#54 既有卡互相補連結。例如 #55 ↔ #11 playwright、#57 ↔ #38 aria-live、#58 ↔ #21 decide-vs-confirm、#64 ↔ #43 minimum-scope + #44 SSOT。整個 collection 從兩個獨立輪次變一張互連網。

迭代 4：抽更高層原則

重讀新卡發現兩個議題夠 abstract、值得抽獨立卡：

• #67 寫作便利度跟意圖對齊反相關 — 從「為什麼層錯位 bug 容易寫出來」抽出。發現它是 #43 / #44 / #45 / #64 的共同上位原則：便利位置 vs 對齊位置永遠反相關
• #68 驗收的時間軸：四個 checkpoint — 從 #56 抽出獨立成卡

迭代 5：跨輪共骨

系統性掃 #1-#54 找跟新系列共骨的、加連結。例：#6 filter-order ↔ #58 / #59、#10 placeholder ↔ #68、#15 layout-test ↔ #68、#14 selector / #20 failure / #28 class-toggle ↔ #67。

迭代 6：#67/#68 加深

再讀兩張抽象卡、補「為什麼人會違反這條規則」的結構性解釋：

• #67 加「便利度的時間維度：當下便利 vs 未來便利反向」+「我等下會 refactor 是個謊言」
• #68 加「為什麼 Ship 前 checkpoint 最常被跳過」（沒便利路徑）+「瀑布原則：漏一層代價指數放大」

從「規則陳述」進到「結構性解釋」 — 不只說「該怎麼做」、也說「為什麼人會違反」。

迭代 7：compositional-writing 規範稽核

User 提醒「再做一次 compositional-writing 的檢查」。發現兩類違規：

1. Rule 7 違規：26 處「X 才合理的情境：實務上幾乎不存在」假反模式 — 改成「X 是反模式：理由」格式
2. 結構違規：#67/#68 是抽象層原則卡、不該寫設計取捨 ABCD（情境檢討卡的格式）— 改成「不該套用本原則的情境」（適用邊界）

修完 31 張卡片（含既有 #1-#54）。整個 collection 對齊 v0.6 規範。

灌進 Skills

把 #55-#68 系列接進兩個 skill：

• requirement-protocol v0.2：clarifying-ambiguous-instructions 加第 5 類「篩選類」+ 三問模板（呼應 #58）；SKILL.md 加「相關抽象層原則」段路由 #42-45 + #67-68
• frontend-with-playwright v0.2：新增第 7 份 reference data-flow-and-filter-composition（涵蓋 #55-#66 跨領域範例）；強調「不只前端、適用後端 / 演算法 / DB」

Skill 的角色 = 路由器、Reports = 深度內容 — 兩層分工不重述。

實作：策略 C + Phase 1-4

依 #59 + Pagefind 1.5.2 capabilities：

• A 推進 query：不可行（Pagefind 無 native title filter API）
• C 多 index：採用（最對齊意圖）
• B / D / E 是 fallback

Phase 1-4：

1. Makefile 跑 3 輪 pagefind（all / title / content）
2. single.html <content> → <div class="article-body" data-pagefind-body>
3. search.html 移除 view 層 post-filter、改 destroy + new PagefindUI(bundlePath)
4. 4 個 Playwright tests 固化

跑出來：make site 三 index 成功、make test 4/4 PASS、live 驗證 sparse case 顯示 explicit empty。看起來完工。

User 抓到 dogfooding 失敗 — 第 8 輪

User 問：「剛剛的過程我不確定、你開始修改之前有先寫測試確保符合預測狀態、然後才調整嗎？」

沒有。流程是：先修 → 才補測試 → 4/4 GREEN。沒走 RED。

這是 #67「便利驅動」+ #68「Checkpoint 2/3 內部協議」的 dogfooding 失敗。我寫了 #67/#68 教這些原則、自己卻違反。

依 user 規範：先建卡片再修。抽 #69 Test-First：先看到 RED 才相信 GREEN：

• 測試本身是程式、會有 bug（5 種失敗模式）
• 沒看過 RED = 不知道測試有沒有 catch 能力
• RED → GREEN 兩個訊號都看到 = 測試 + 修復都被驗證

retrospective 補驗證流程：checkout pre-fix commit → cherry-pick test → build → run（看 RED）→ restore → run（看 GREEN）。

跑下去 — 結果震撼：4 個測試只有 1 個真的 catch 到 bug、其他 3 個對 buggy code 也 PASS（placebo）。如果不做 retrospective、會帶著 3/4 placebo 測試 ship。

強化測試（network-level + structural assertion 替換弱 invariant）：buggy code 1 PASS / 3 FAIL、fixed code 4 PASS。RED-GREEN 真的 catch 到 bug + 真的解掉。

User 抓到第二個 dogfooding 失敗 — Checkpoint 1

我問 user 還有什麼該迭代。User 列了 7 項、選 1+2：

1. 補 Checkpoint 1（列使用者意圖完整集）
2. 跟 user 確認 known limitations

跑 Checkpoint 1 retrospective — 用 Playwright MCP 系統性測 5 維度（data / interaction / URL / a11y / performance）。發現 3 個 silent 缺口：

依 user 規範：先建卡片再修。抽：

• #70 URL 是 stateful UI 的儲存層 — 5 個儲存層特性對照 + 三問判準
• #71 Tab Order = DOM Order = Mental Model 三者對齊 — DOM 順序 = tab 順序、不對齊時優先重排 DOM
• 更新 #68 加「為什麼 Checkpoint 1 也常被跳過」段、用本次任務當 self-case

然後實作 — 依 #69 RED-GREEN 順序：

1. 寫 4 個 RED tests
2. 跑 → 4 個 fail（confirms RED）
3. 修 search.html（URL persist + DOM reorder + UI hint）
4. 跑 → 8/8 GREEN

CI + 自動化

最後補 CI 防護：

• .github/workflows/playwright.yml — push / PR 自動跑 8 個 tests
• deploy.yml 修 critical bug — production 一直只 build 單 index、現在 build 三份對齊本地
• make test + make verify-red-green PRE_FIX=<sha> — codify retrospective 流程、不需手動 stash / checkout / restore

數字總結

學到什麼

1. Cards-skills 系統是雙向的

不是「先寫卡片、再用卡片」。是「卡片指導實作、實作問題回流卡片」。每一輪迭代都把學到的東西反饋。本次 14 張新卡有 8 張是修過程中實際遇到的問題抽出來的、不是預先想的。

2. User 提問是「外部觸發」

我自己跑 #67 / #68 / Checkpoint 1 的機率低 — 因為這些都是「沒便利路徑」的工作。User 的兩次提問（「有先寫測試嗎」+「需求確認最重要功能」）剛好對應 #69 + Checkpoint 1 的觸發。結構性偏差需要外部觸發來修正、不能靠自我提醒。

3. Test 過 ≠ 對齊使用者意圖

第一輪修完、跑 4/4 GREEN、看起來完工。實際漏了：

• 3 個測試是 placebo（沒做 RED 不知道）
• 3 個 silent 缺口（沒做 Checkpoint 1 不知道）

任何「跑得通就 OK」的訊號都低資訊量。Real 訊號 = 對照「使用者意圖完整集合」逐一驗收。

4. 一個 bug 修完 = 一個 case study 起點

如果停在「bug 修了、test 過了」、這次任務 5 個 commits 結束。User 的兩次提問把它變成 30+ 個 commits 的 case study、產出 17 張新卡 + 兩個 skill 升級 + CI 補強。修 bug 是 trigger、不是終點。

適合 reuse 這個流程的條件

不是每個 bug 都該走這套。適合的訊號：

• Bug 修法不直觀、會碰到多種策略選項（→ 需要 #59 類取捨架構）
• 修法可能影響其他 feature 或產生新案例（→ 需要 Checkpoint 1）
• 需要長期 regression 防護（→ 需要 #69 RED-GREEN 驗證）
• 修的過程中發現新原則（→ 抽卡片）

不適合：純 typo / config / build 失敗 — 直接修。

對未來想用這套系統的人

進入點：

1. 讀 content/skills/_index.md — 三個 skill 的 routing table
2. 從你的問題情境找對應 skill：
   • 不確定怎麼跟 user 溝通 → requirement-protocol
   • 前端 / 資料流實作 → frontend-with-playwright
   • 寫文件 / 註解 / log → compositional-writing
3. Skill 路由你到 specific reference、reference 路由你到 content/report/ 深度卡片
4. 修問題過程中發現新原則 → 抽卡片回流

「卡片不是在實作之前一次寫完、是在實作之中持續累積」 — 這套系統的 leverage 在於「下一個類似問題能直接用、不用重新發明」。

結語

content/report/ 從 54 張長到 71 張、.claude/skills/ 從 v0.1 進到 v0.2、CI 從假 pass 變真防護、search bug 從 silent 失敗變到 8/8 regression test 守護。

過程不是線性。是「先做 → 抓到 dogfooding 失敗 → 抽卡片 → 回頭修 → 再被抓失敗 → 再抽卡片 → 再修」。每一輪都讓系統往對齊使用者意圖的方向多走一點。

User 的角色關鍵：兩次提問都不在「指出 bug」、是在「指出我跳過的 checkpoint」。這是純執行者看不到的盲點 — 自己的 dogfooding 失敗。外部 reviewer 是 cards-skills 系統的必要組件、不是 optional。

下次有類似情境的人 — 不需要把這條路再走一遍、直接用 #55-#71 + 三個 skill 起步。如果發現新 case、抽新卡回流。系統的價值在每次使用都會變強。