codebase-memory-mcp（下稱 cbm）的核心定位是「把整個 codebase 預先解析成可被 LLM 廉價查詢的知識圖譜」。它要替代的是 agent 在不熟悉的 codebase 上「拿 grep / glob / read 連環翻檔」的探索 pattern——人類用 IDE 編輯、agent 用 cbm 探索、兩者服務不同的工作流。

設計上跟其他「graph + LLM」工具的關鍵分野，在於它不內嵌任何 LLM 做自然語言 → 查詢轉換：

Other code graph tools embed an LLM for natural language → graph query translation. This means extra API keys, extra cost, and another model to configure. With MCP, the agent you’re already talking to is the query translator.

所以 cbm 自己只是個提供高品質 graph 查詢 API 的 server，「翻譯自然語言」這件事直接讓呼叫端的 agent 做。這個取捨對 Claude Code 這類 host 是理想的，因為 host 端已經有一顆夠強的模型在跑。

部署形態決定它的甜蜜點

cbm 是單一靜態 binary，所有依賴（155 種 tree-sitter grammar、SQLite、tokenizer）都在 binary 內，安裝後沒有外部 runtime 依賴。

這個取捨直接影響它的甜蜜點：

• 跨平台分發成本低，CI 上跑也方便
• 不需要為個別語言裝 toolchain（不像 LSP 路線要對應 language server）
• 但代價是「能力上限」被 binary 內附的 grammar 跟自寫的 type resolution 算法綁住，無法靠 IDE 生態的成熟度借力

知道這個取捨之後，後面所有能力差異都解釋得通：能做的事多半是「靜態可推導」的，需要 query 外部 toolchain（如 IDE language server）的場景多半要靠別的工具補。

索引架構：多 pass + RAM-first

cbm 的索引流程是 RAM-first 的多 pass pipeline，pass 之間有明確的責任分工：

執行期用 LZ4 壓縮的記憶體 SQLite 加速，所有 pass 跑完一次性 dump 成持久化 DB（路徑 ~/.cache/codebase-memory-mcp/，WAL mode）。team 共享情境下可加跑 zstd 壓縮（best tier 用 zstd -9 + index strip、fast tier 用 zstd -3 走 watcher 增量），匯出成 .codebase-memory/graph.db.zst artifact 給 CI / 隊友共用。

Pass 排序遵循明確的依賴關係：calls 一定在 definitions 之後（因為 call edge 要連到已被建出來的 function / method node）、HTTP links 一定在 calls 之後（需要先有 call edge 才能比對 route 跟 handler）、configuration / tests 是 cross-cutting 的最終層（前面的結構與 call graph 都齊備、它們才能掛上 CONFIGURES / TESTS edge）。實務影響：HTTP links pass 在「單 service repo」上等於 no-op、configuration pass 在「缺 IaC manifest」的 repo 上也是 no-op、這兩個 pass 的價值高度依賴 repo 結構。

這個架構的副作用是：單次完整 index 速度快（README 聲稱 Linux kernel 3 分鐘），但增量更新採背景 git polling（IDE-style file watcher 是即時觸發、cbm 是定期掃描），對「邊改邊查」的工作流會有秒級延遲。

11-signal 語意搜尋：cbm 最強的差異化

如果只看 README 寫的「BM25 全文搜尋」，會嚴重低估 cbm 的搜尋能力。實際上 search_graph 的 ranking 是 11 個 signal 的加權組合：

表格列了 9 個明確 signal、README 另說有 11 個（剩 2 個是 implementation detail 沒公開細節）。實務上 11-signal 的價值在於幾個高權重 signal 各自負責不同 query 類型——權重分配有明顯的高低差：

• RRI 是 cbm 對「重要符號優先」的 graph 結構 prior。一個被大量檔案 import 的核心 class、即使在 query 字串裡只有間接匹配、RRI 也會把它往上推。這層對「找這個 codebase 的入口 / 主要抽象」類 query 特別重要。
• Data flow 是 cbm 對「概念上接近、但符號名沒共字」的 query 的關鍵 signal。例如查「金額顯示」、formatAmount 跟 _buildPriceDisplay 在符號名上沒共字、但 data flow 能捕捉「formatAmount 的回傳值流入了 _buildPriceDisplay 的 widget」這層連結。
• Graph diffusion 是 cbm 對「擴散式相關性」的最終 boost——已經被前面 signal 推到高分的符號，會把分數擴散到 graph 上鄰近的符號。實務影響：monorepo 上效果最強（跨 module 鄰近性有意義）、單一檔案的小專案上幾乎沒效果。

加上一層 cbm_camel_split tokenizer：對 getMoneyField 這類 identifier 做 camelCase / snake_case 切詞，所以查 money field display 能命中 getMoneyField、MoneyFieldRenderer 之類符號。

這套組合的判讀價值在於：對「我不知道精確符號名」的概念性查詢，cbm 是少數能給出合理 top-N 的工具。例如查「金額顯示相關」、結果裡會出現 formatAmount 實作 + _buildPriceDisplay + getBalanceDisplay，這些都跟「金額顯示」業務概念相關、不會被 displayName / displayTags 這種只共享 display 子字串的雜訊淹沒。

下一步路由：要看實測案例，見 三 MCP 工作流與 Dart 實測。

Hybrid type resolution：只給五個語言的特殊待遇

cbm 對 Go / C / C++ / TypeScript / JavaScript（JS 含 JSX、TS 含 TSX）額外跑一層 type resolution，README 描述是：

Clean-room reimplementation of tsserver / typescript-go’s type resolution algorithms — parameter binding, return-type inference, generic substitution, JSX component dispatch, JSDoc inference for plain JS files.

換言之，這幾個語言的 CALLS edge 在 syntactic match 之上多了一層 type-aware dispatch resolution，效果接近 LSP。其他 149 個語言只跑純 tree-sitter pass，能力會降到「結構抽得到、call edge 抽得很有限」。

實測對照（在某 Dart 商業專案上）：

1cbm 索引完成統計：3,038 nodes、6,355 edges
2其中 CALLS edge 總數：2（整個專案僅 2 條）

這個數字反映 cbm 的設計選擇——hybrid resolution 名單只涵蓋 5 個語言、Dart 在名單外——所以 trace_call_path 對 Dart symbol 一律回 0 caller，這個 0 屬於 by design 行為。對 Go / TS 主力專案，這個能力上限會完全不一樣。

判讀訊號：開發前先確認自己的主力語言在不在那五個語言內。在的話 cbm 是準 LSP；不在的話它只是個「結構 + 全文搜尋」工具，呼叫鏈相關問題要靠別的 MCP 補。

跨 service 鏈接：first-class HTTP_CALLS edge

cbm 的另一個差異化能力是把 REST / gRPC / GraphQL / tRPC route 當 first-class node，建立跨 service 的 HTTP_CALLS edge：

• Route 偵測：對應主流 web framework（Express / NestJS / FastAPI / Gin / Rails 等）的 route 定義語法
• Call site 比對：以 route pattern 比對 client 端的 URL 字面值或變數，附 confidence score
• 額外的 channel edge：Socket.IO / EventEmitter / 各種 pub-sub 的 EMITS / LISTENS_ON

這層能力對單一 monorepo 內的多 service 架構（microservice repo / BFF / API gateway pattern）特別有價值——可以查「這個前端 API call 對應哪個後端 handler」這種跨 service 問題。對單一 service 的單體 repo，這層能力派不上用場。

實際使用前提：要 index 的 repo 必須同時包含 client 跟 server 端，分散在多 repo 的話 cbm 不會自動跨 repo 連邊。

Cypher 子集：支援的查詢與邊界

cbm 提供的 query_graph 是 Cypher 的真子集——覆蓋大部分 read-only query 語法、省略 mutation 與部分 aggregation 語法：

支援：

• MATCH 含 label / relationship type / 變長路徑
• WHERE 含比較 / regex / CONTAINS
• RETURN 含 property access、COUNT、DISTINCT
• ORDER BY、LIMIT

不支援：

• WITH（不能多階段 pipeline）
• COLLECT（不能 aggregate 成 list）
• OPTIONAL MATCH（不能 left-join）
• labels(n) / type(r) 等函數呼叫
• AS 別名
• 任何 mutation（純讀）

幾個限制各自踩到的事故型態：

• WITH 缺席：所有需要「先 match 一組、再 filter / aggregate」的二階段 query 都寫不出來。例如「列出每個 module 內最常被呼叫的 function」這種 Top-K per group 的 query、在 Cypher 是 MATCH ... WITH module, COUNT(*) AS c ORDER BY c LIMIT 1、在 cbm 要拆成「先 list modules、再對每個 module 跑一次 callers query、外層排序」。
• OPTIONAL MATCH 缺席：left-join 場景做不到。例如「列出所有 class、附上它的 supertype（若有）」這種「主結果不該因為某個關係缺失就丟掉」的 query 寫不出來。cbm 上的做法是先抓全部 class、再對每個 class 跑一次 supertype query、在 client 端合併。
• labels(n) 缺席：拿不到 graph 內所有 node label 種類的清單。想做「我的 graph 裡有哪幾類 node」這種 schema 探索類 query、得退回 get_graph_schema 拿固定的 schema 介紹、看不到 instance 層真實分布。
• AS 別名缺席：query 結果直接是 node / relationship object、沒法 rename 欄位給 downstream consumer。

這些限制的共通實際影響：想做 group-by-count 類的 graph stats 查詢得退回 search_graph 逐 label 抽。例如「列出每個 file 有幾個 method」這種一行 Cypher 在標準 Neo4j 能寫的、在 cbm 上要拆成多次 query 在外層彙整。

判讀訊號：若 query 需要 WITH ... COLLECT(...) AS xs 這類二階段語法，先別硬寫 Cypher，改用 search_graph 加 client 端聚合。

安裝行為與兩個要注意的小坑

cbm 的 install.sh 對 ~/.claude/settings.json 動的範圍比 README 寫得多。實際安裝會：

• 下載對應平台 binary、剝 macOS quarantine、ad-hoc sign
• 自動偵測 11 種 coding agent，逐一注入 MCP server config
• 對 Claude Code 寫入 .claude/.mcp.json、4 個 Skill、PreToolUse hook
• Hook 名稱：cbm-code-discovery-gate，攔截 Grep / Glob 注入結構化 context

兩個實際踩過的小坑：

Hook matcher 與 README 不一致。README 描述「intercepts Grep/Glob — never Read」，實際安裝版本 matcher 是 "Grep|Glob|Read|Search"，連 Read 也被擋。修法：手動把 matcher 改成 "Grep|Glob|Search"。注意 codebase-memory-mcp update 可能會把這行改回原樣，每次升級要重新確認。

uninstall 不清 hook。卸載 binary 不會主動把 ~/.claude/settings.json 裡的 hook 條目移除。決定不再用 cbm 時要手動清掉 PreToolUse 下的 cbm-code-discovery-gate 條目，否則之後安裝其他工具或除錯時會看到神祕的 BLOCKED 訊息。

14 個 MCP tool 的分類

特別值得提的兩個：

• manage_adr：把 Architecture Decision Records 當持久化資源管理。對長期專案有累積架構決策需求的場景有用，但若團隊已用 ADR-tools 或 Notion 管 ADR，這層會重複。
• ingest_traces：餵 runtime trace 進來驗證 HTTP_CALLS edge 是否反映實際的 runtime 調用。可以把靜態推測的 cross-service edge 與真實 runtime 行為對齊。實務上要先有 distributed tracing 基礎建設才開得了，門檻偏高。

適用 / 不適用情境的判讀

適用情境：

• 主力語言在 Go / C / C++ / TS / JS 名單內 → 享受 hybrid type resolution。判讀方法：對 5 個熱門 class 跑 trace_call_path、若 caller 數跟 IDE「Find Usages」結果對得上、表示 hybrid 正常工作。
• 概念性 / 自然語言搜尋需求高 → 11-signal scoring 是少數能勝任的 MCP。判讀方法：對「我只記得功能類別、不記得名字」的 query 跑 cbm 跟其他工具的 search、若 cbm top-10 命中率明顯高、值得當主要入口。
• 跨 service 的 monorepo → first-class HTTP_CALLS edge 抽得到 cross-service 鏈。判讀方法：repo 內若有多個 service 用 HTTP / gRPC / GraphQL 互相呼叫、又分散在同一個 git tree 內、cbm 能跨 service 連邊；若只是單 service repo 這條沒效。
• 偏好單 binary 部署 → 不想為個別語言裝 toolchain、cbm 是少數零外部依賴的選項。

不適用情境：

• 主力語言不在 hybrid resolution 名單（如 Dart / Swift / Kotlin）且核心需求是 caller / blast radius 追蹤。判讀方法：在自己 repo 跑 cbm trace_call_path 對 5 個熱門 class、若 caller 數明顯偏低或 0、表示 cbm 在這語言只剩結構抽取、要靠 LSP 工具補。
• 要 symbol-level 編輯（rename / replace_symbol_body）— cbm 純讀、沒這層。判讀方法：要做「rename method 並更新所有 reference」這類 atomic refactor 時、cbm 完全幫不上忙、要走 LSP 工具。
• 要編譯 diagnostic 整合 — cbm 不接 LSP、沒法把 type error / unused import 拋給 agent。

搭配建議：在不在 hybrid resolution 名單的語言上，cbm 通常需要配合一個 LSP-based MCP（如 serena）做 caller / impact 補位，加上一個 tree-sitter call graph 工具（如 codegraph）做日常結構查詢。三者怎麼分工見 三 MCP 工作流與 Dart 實測。

結論

cbm 的核心價值在三件事：單 binary 部署、11-signal 語意搜尋、跨 service HTTP/RPC 鏈接。前兩件對任何語言都成立，第三件對微服務 monorepo 特別有意義。

它的能力上限被 hybrid type resolution 的語言名單卡死——名單內等於準 LSP，名單外只是個結構抽取器。評估時第一個要問的問題是：「我的主力語言在不在那五個（Go / C / C++ / TS / JS）？」答案決定 cbm 是主刀還是輔刀。

codegraph 的設計動機很具體：Claude Code 探索 codebase 時 spawn 的 Explore agent 會用 grep / glob / read 連續刷檔，每個 tool call 都吃 token。codegraph 把這層探索預先做好，agent 直接查預建好的 graph。

When Claude Code explores a codebase, it spawns Explore agents that scan files with grep, glob, and Read — consuming tokens on every tool call. CodeGraph gives those agents a pre-indexed knowledge graph — symbol relationships, call graphs, and code structure.

跟 cbm 比，codegraph 的 scope 更窄、更專注：不做跨 service 鏈接、不做 ADR / runtime trace 管理、不做 11-signal 語意搜尋，只把 call graph 跟 symbol relationship 做好。這個取捨讓它的 MCP tool 只有 10 個、每個責任都很單一。

技術架構：tree-sitter + per-language query + FTS5

codegraph 的核心 pipeline：

1tree-sitter parse → per-language query 抽 nodes/edges
2                  → 解析 reference（import / extends / implements / calls）
3                  → 寫進 SQLite + FTS5

關鍵設計：對每個語言寫專屬的 tree-sitter query——比起通用 AST visitor 路線、這個設計能對特定語言的 dispatch pattern 抽到更精確的 node 跟 edge。

Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements).

這個設計選擇直接決定了 codegraph 對非主流語言（如 Dart / Svelte / Liquid）的支援深度——因為每個語言都有專屬 query，所以 19+ 語言裡的 Dart 真的有 working call graph，不像純 tree-sitter wrapper 那樣只能抽結構。

實際支援的 19+ 語言：

TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Scala、Dart、Svelte、Vue、Liquid、Lua、Luau、Pascal/Delphi。

過濾規則：「Files larger than 1 MB are skipped」（generated bundle / minified JS / vendored blob 自動忽略）。

Auto-sync：native OS file watcher + 2s debounce

codegraph 預設啟用 file watcher、用 native OS 事件（macOS FSEvents / Linux inotify / Windows ReadDirectoryChanges）：

• Debounce window：2 秒（避免快速連續存檔重複觸發）
• 過濾範圍：只看 source 檔案（按副檔名）
• 行為描述：「Incremental sync. The graph stays current as you code — no configuration needed」

這層比 cbm 的「背景 git polling」更貼近 IDE — 改完檔案 2 秒內 graph 就同步好，「邊改邊問」工作流更順。

判讀訊號：剛存完檔立刻問 caller 還是漏，等 3 秒再試一次；持續漏的話跑 codegraph status 看 indexed 數字對不對得上預期。

Call graph 抽取的能力與聲稱

codegraph 對 caller / callee / impact / trace 這四個查詢的覆蓋是它的主賣點。README 對 codegraph_trace 的聲稱是：

Follow dynamic-dispatch hops (callbacks, React re-render, interface→impl) that grep can’t.

實際機制 README 沒詳細寫，從 source 推測是「對某些常見動態 dispatch pattern 寫了專屬 query」——比如 React component 的 JSX → component definition 解析、interface method → implementation 對應這類。

這個 claim 在實測上有但有限——對 type-inferred receiver 仍會漏。例如 Dart 上（Money 在該專案是 extension type）：

1final Money samplePrice = ...;
2samplePrice.multiplyByRate(rate);   // ← codegraph 抽不到這條 edge

samplePrice 是 local variable，要做型別推斷才知道 receiver 是 Money。tree-sitter 看到的只是 <identifier>.multiplyByRate(...)、不知道 samplePrice 的型別、無法 dispatch 到 Money.multiplyByRate。

判讀訊號：對「靠型別解析才能找到的 callsite」會漏。如果專案大量使用 generics、type aliasing、factory pattern 隱藏型別、duck typing，codegraph 的 caller 數字會系統性偏低。重要 refactor 別只看它的數字決策。

下一步路由：實測對照數字見 三 MCP 工作流與 Dart 實測。

Caller 跟 callsite 的計數單位差異

codegraph 的 codegraph_callers 採用的計數單位是「caller symbol 數」（同一個 method 內呼叫目標兩次仍然只算 1 個 caller）——跟「callsite 數」屬於兩種不同的統計方式。

這個設計的影響：跟 LSP-based 工具（如 serena）對比時，數字會看起來「少」，但這是計數規則的差異、跟精度差距屬於兩個不同議題。寫實測 baseline 時要把這個單位寫死，避免「codegraph 回 3、serena 回 9」被誤判成「codegraph 漏 6 個」。

實際上這 3 vs 9 的差距要分兩段看：codegraph 抓到的 3 個 caller symbol 對應 6 個 callsite（同一個 method 內有多處呼叫、被計數規則合併成 1 caller）、剩下的 3 個 callsite 在第 4 個檔案（product.dart）、是真的漏（type-inferred dispatch）。算術：6 callsite（codegraph 算 3 caller）+ 3 callsite（真的漏）= serena 的 9。要拆開看才知道哪部分是計數差異、哪部分是能力差距。

14 web framework 的 route 識別

codegraph 內建對 web framework 的 route 識別：

Django、Flask、FastAPI、Express、NestJS、Laravel、Drupal、Rails、Spring、Gin / chi / gorilla / mux、Axum / actix / Rocket、ASP.NET、Vapor、React Router、SvelteKit。

README 標稱「14 個」、實際展開後是 15 條（Gin / chi / gorilla / mux 跟 Axum / actix / Rocket 各算一組路由生態）。這個小落差源自分組計數方式、不影響功能。

這層的角色是讓 codegraph_search 能用 URL pattern 找到對應 handler，不必去猜 handler 函式名。但跟 cbm 的 first-class HTTP_CALLS edge 不一樣，codegraph 沒做「client URL 字面值 → server route 比對」，所以單一 service 內找 handler 可以、跨 service 鏈接做不到。

判讀訊號：純前端 / 純後端 repo 上這層夠用；要跨 service 追 cross-service call 仍要靠 cbm 或別的工具。

10 個 MCP tool 的責任分工

設計上有四個值得單獨展開的 tool：

codegraph_explore 是為了省 tool call — 不用對 N 個 symbol 各呼叫一次 codegraph_node、一次拿到所有 source。這直接呼應 codegraph 整體「省 token / 省 tool call」的設計目標。

codegraph_trace 單一 call 涵蓋整個路徑、每一跳的 function body 直接 inline 在結果裡。對「X 怎麼影響到 Y」這種多跳問題，傳統做法要 N 次 codegraph_callers + N 次 codegraph_node，trace 把這壓成 1 次。代價是若兩個 symbol 之間沒有 static-resolvable 路徑（如 type-inferred dispatch 中斷），會直接回「No direct path」、不會主動找替代解釋。

codegraph_context 跟 codegraph_explore 的責任差別常被搞混。codegraph_explore 是「我已經知道要看哪幾個 symbol」、一次拿原始碼；codegraph_context 是「我有個 task description、不知道相關 symbol 是哪些」、由它從 task 內容拉出可能相關的 graph 鄰域。前者是「精確檢索」、後者是「概念性彙整」。實務上 task agent 開新任務時用 codegraph_context、debug 細節時用 codegraph_explore。

codegraph_impact 是 blast radius 工具、但它的精度被 tree-sitter syntactic 限制卡住——跟 caller / callee 同源、type-inferred dispatch 的影響範圍會漏。實務影響：對「rename method 會影響什麼」這類重要 refactor 不能單看它的數字、要走 LSP 工具 cross-check。判讀訊號：codegraph_impact X 回的 affected symbol 數明顯少於預期、且 X 是被廣泛使用的 type / method 時、blast radius 多半有漏、要補 LSP 驗證。

Token efficiency benchmark：方法論與限制

README 聲稱「~35% cheaper · ~70% fewer tool calls · 100% local」、median 跨 7 codebase：

• Cost: 35% reduction
• Tokens: 57% fewer
• Time: 46% faster
• Tool calls: 71% fewer

方法論：

Claude Opus 4.7 run headlessly. WITH = CodeGraph’s MCP server enabled, WITHOUT = empty MCP config. Same question per repo, 4 runs per arm, median reported.

7 個 benchmark codebase：

幾個要注意的解讀偏差：

Benchmark 集中在 codegraph 強項語言。VS Code / Django / Tokio 都是 codegraph 的核心支援語言、且 LSP 生態成熟。Dart / Svelte / Liquid 這類 long-tail 語言沒列在 benchmark 內，token 節省效果在那些語言上是否成立不知道。

Empty MCP config 的對照組不一定貼近實務。沒裝任何 MCP 時 agent 的 baseline 探索行為跟「裝了其他 MCP」不同。實務 stack 通常多個 MCP 並用，這個 35% 對「加裝 codegraph 進已有 MCP stack」的邊際效益會打折。

判讀訊號：benchmark 數字當「值得試」的參考、不當「裝了就省 35%」的硬保證。實際省多少要在自己的 stack 上跑同樣 question set 才知。

安裝行為

1npm i -g @colbymchenry/codegraph
2codegraph install --target claude --location global -y
3cd your-project && codegraph init -i

codegraph install 會把 MCP server 條目寫進 ~/.claude.json 的 mcpServers、codegraph init -i 在當前 repo 建 .codegraph/codegraph.db、啟動 watcher。

跟 cbm 不一樣：codegraph 不寫 PreToolUse hook、不攔截 Grep/Glob。它純粹當 MCP server 提供 tool、決策權留給 agent，對既有工作流的干擾較小。

CLI mode 是另一個方便點：所有 MCP tool 在 CLI 都有對應指令（codegraph callers X / codegraph trace X Y），不必等 Claude Code 重啟載入 MCP 就能先在 terminal 驗證效果。

適用 / 不適用情境的判讀

適用情境：

• 主力語言在 19+ 支援列表內，且需要可靠的 caller / impact / trace 查詢
• 「邊改邊問」工作流（auto-sync 2s debounce 比較貼近 IDE）
• 希望 MCP 保持原生 grep / glob 行為、把決策權留給 agent 自主判斷（避開 hook 層強制介入）
• 要 CLI 跟 MCP 雙管道使用（CLI 可先試、MCP 給 agent 用）

不適用情境：

• 語言不在支援列表（codegraph 不像 cbm 一次 vendor 155 個 grammar）
• 需要跨 service 的 client URL → server route 鏈接（codegraph 只認 route definition）
• 需要 symbol-level atomic edit（codegraph 純讀、沒 rename / replace_symbol_body）
• 重要 refactor 要保證不漏 callsite（tree-sitter syntactic 上限會漏 type-inferred dispatch）

搭配建議：對 type-inferred dispatch 漏的部分，可以靠 LSP-based 工具（如 serena）補位。對概念性自然語言搜尋，cbm 的 11-signal scoring 比 codegraph 的 symbol pattern match 更強。三者怎麼分工見 三 MCP 工作流與 Dart 實測。

結論

codegraph 的核心價值是用 per-language tree-sitter query 把 call graph 做成 19+ 語言通用的 MCP 服務，加上 auto-sync 跟 CLI 雙管道。它的 scope 聚焦在 call graph、比 cbm 窄很多、但聚焦範圍內品質很高。

它的型別解析靠 tree-sitter syntactic：receiver 是顯式型別宣告或 literal 的 callsite 解得好、receiver 要靠型別推斷的 callsite 會漏。判斷 codegraph 在自己專案上的可信度，先估專案有多少比例的 call 是 type-inferred receiver——比例高就要配 LSP 工具補位、比例低就放心用。

serena 的核心定位是「把現成 LSP 生態包成適合 agent 用的高階抽象」。它不自建 type system、不自寫 parser，直接 spawn 各語言對應的 language server（Dart 用 dart analysis_server、TS 用 tsserver、Rust 用 rust-analyzer 等），把 LSP 的能力轉成 MCP tool。

設計哲學是 README 自己歸納的「agent-first tool design」：

Involves robust high-level abstractions, distinguishing it from approaches that rely on low-level concepts like line numbers or primitive search patterns.

換言之，serena 的所有編輯都是 symbol-level——讓 agent 直接用 symbol 語意操作（「把 X function 的 body 整個換掉」、「在 Y class 後面插一段」、「rename Z」），跳過 line number 跟 text patch 這層 raw text 處理。對應的是 LSP 路線本來就有的 symbol 結構與 reference 追蹤。

跟 tree-sitter 路線的本質分野：tree-sitter 只給結構、不給型別；LSP 給的是「IDE 等級的真型別系統」。代價是 LSP 要每個語言裝對應 language server、執行期 spawn process、per-session 維護狀態。

部署形態：兩個 backend、執行期 spawn LSP

serena 提供兩個 backend：

Language Server backend 是 OSS 用戶會接觸的路線。serena 透過 LSP 抽象涵蓋 40+ 語言、實際能力依各語言 LSP 成熟度而定——Python / TypeScript / Go / Rust / Java / C# / Dart 等主流語言由 serena 內建 bootstrap 自動下載 server、冷門語言（如 Liquid / Pascal）需要使用者自己準備 server binary、無 server 的語言視同 fallback 到純文字工具。判讀訊號：跑 activate_project 後若 serena 沒在背景 spawn 對應 LSP、表示該語言走 fallback 路線、find_referencing_symbols 等型別敏感 tool 不可用。

對 Dart 而言：serena 啟動時 spawn dart analysis_server、跟 Flutter SDK 內附的同一隻。所以 serena 對 Dart 的能力等同 dart analysis_server 暴露的能力——比 tree-sitter 路線高一個量級。

Per-session 模型與 activate_project

serena 的 LSP backend 是 per-session 的：

• 沒有持久化 graph DB（不像 cbm / codegraph 把結果寫進 SQLite）
• 每個 session 啟動時要 activate_project、spawn 對應 language server、warm up index
• Session 結束 server 也跟著 terminate，下次重來

activate_project 的角色是告訴 serena「這個 session 接下來要分析哪個 project root」，serena 才知道要 spawn 哪幾個 language server、index 哪個 workspace。一個 session 內可以切多次 project，但同時只 active 一個。

這個模型的取捨很清楚：

• 好處：永遠拿到當下最新狀態（不會有 stale index 問題）、不必管 watcher / debounce
• 代價：每次 session warm-up 有秒級至分鐘級延遲（大專案 LSP indexing 慢）、跨 session 不能重用結果

判讀訊號：第一次查詢回得慢、之後快——這是 LSP indexing warm-up。若每次查都慢、檢查 LSP 是否因記憶體不足重啟。

Symbol-level atomic edit 的價值

serena 的 editing tool 都是 symbol-level：

• replace_symbol_body：取代某個 function / method / class 的 body
• insert_after_symbol / insert_before_symbol：在指定 symbol 前後插入內容
• safe_delete_symbol：刪除 symbol 並檢查 reference
• rename_symbol：rename symbol、自動更新所有 reference（LS backend 限 symbol 範圍、JetBrains backend 額外支援 file / directory 層級重命名）

對比 Edit tool 用「old_string / new_string」做 text-level patch：

實務上的價值：type-sensitive refactor 的事故率大幅降低。改 method 不會手抖把 indentation 改錯、rename 不會漏改 reference。代價是 symbol 路徑必須寫成包含父層的完整形式（ClassName/methodName）。

判讀訊號：寫 replace_symbol_body 後若 LSP 報 syntax error、先 get_diagnostics_for_file 看具體錯在哪、別直接 retry 同個 patch。

find_referencing_symbols：LSP 路線的型別精確 caller 來源

對 Dart / Swift / Kotlin 這類 tree-sitter 工具支援薄弱的語言，find_referencing_symbols 是少數能拿到「型別精確的 caller 清單」的 MCP tool。

實測對 Dart Money.multiplyByRate（某商業專案、Money 是 extension type）：

1serena find_referencing_symbols → 4 個檔案、9 個 callsite
2codegraph callers              → 3 個 caller symbol（漏 3 個 callsite）
3cbm trace_call_path            → 0 callers（Dart 不在 hybrid resolution 名單）

差距來源就是型別解析：samplePrice.multiplyByRate(...) 這種 receiver 是 local variable 的 callsite，要知道 samplePrice 的型別是 Money 才能 dispatch 到正確 method。LSP 走 dart analysis_server 拿到完整型別資訊，所以這層 dispatch 是精確的。

下一步路由：對照數字與 5 個實測實驗見 三 MCP 工作流與 Dart 實測。

30+ MCP tool 的分類

serena 的 tool 數量比 cbm / codegraph 都多、覆蓋更廣的工作流：

幾個值得單獨展開的類別：

檢索類是 serena 跟 LSP 黏最緊的入口——find_symbol / find_declaration / find_implementations 走 LSP 的 textDocument 命令、find_referencing_symbols 是 LSP references 的 wrapper。這層是 serena 不可替代的核心、所有需要型別精確的查詢都從這走。

get_diagnostics_for_file 是把 LSP 的編譯診斷直接暴露給 agent。改完 code 不必跑 build 就能知道有沒有 type error / unused import / missing await。對 type-sensitive refactor 是必備。

Symbol-level edit vs text-level edit 的選用：symbol-level（replace_symbol_body / insert_after_symbol / safe_delete_symbol / rename_symbol）對「有明確 symbol 邊界的修改」最穩、不會踩到 indentation 或 escape 問題；text-level（replace_content / search_for_pattern）保留給「跨 symbol 邊界、或非 code 內容」的場合（如改 markdown、config、log 字串）。判讀訊號：要動的內容能不能用「ClassName/methodName」這種 symbol path 定位？能就走 symbol-level、不能就 text-level。

execute_shell_command 是 LSP-only 工具裡的「逃生門」——LSP 本身不執行命令、但實務上 agent 需要跑 test / build / git status / 任意 CLI 工具來驗證自己的修改。這條等於把 LSP-based 工具補成「能 query 又能執行」的完整 workflow 工具。安全考量：因為它能跑任意 shell command、Claude Code 對 serena 的 trust level 要跟 Bash tool 對齊看待、不要假設它「只是讀取工具」。

Memory system 採用「跨 session 的 markdown 筆記檔」形式、屬於自由格式存儲。用途接近 agent 的本地長期記憶——存「這個專案的 setup 注意事項」、「上次 refactor 的決策紀錄」、「常用的 codebase pattern」。跟 cbm 的 manage_adr（結構化 ADR）走相反取向：serena 把 schema 留給使用者自定、manage_adr 給定 ADR 欄位結構。

Project 類（activate_project / get_current_config / onboarding / initial_instructions）是 serena 對「agent 第一次接觸新專案要先讀什麼」的明確協議。onboarding 讓 agent 主動 read 專案 onboarding doc、initial_instructions 給 agent 一份 serena 自己的使用手冊、activate_project 切 project root、get_current_config 暴露當前 session 的配置給 agent debug。這層降低盲目探索成本、是把 serena 從「LSP wrapper」抬升到「agent-first」的關鍵。

Per-session 與持久化 graph 的搭配問題

serena 的 per-session 模型在「單純查 caller / refactor」工作流很合適，但對「自然語言搜尋 / 跨 session 累積 graph context」就不夠。

實際差距：

• 想用「金額顯示相關」這種概念性 query 找 symbol → serena 沒有 BM25 / 11-signal scoring、只有 search_for_pattern（regex / literal）跟 find_symbol（exact name match）
• 想跨 session 累積「這個 codebase 有哪些 module」的整體 inventory → serena 每次重 index、沒有持久化的 graph 可查
• 想做跨 service HTTP_CALLS 鏈接 → serena 沒有這層

判讀訊號：搜尋需求若是「我知道某個 symbol 的精確名稱、要找它的 references」就用 serena；若是「我不知道精確名稱、用概念找」要配合 cbm。

安裝行為

serena 在 Claude Code 是 plugin 形式：在 plugin marketplace enable 即可，不需要單獨 npm i。Plugin 啟動時 serena 會 spawn LSP，第一次 activate 某個 project 時 indexing 完成才能跑 query。

跟 cbm / codegraph 的差異：

• 不寫 PreToolUse hook、不攔截既有 grep / glob 行為
• 不在 ~/.claude.json 直接加 mcpServers（plugin 機制管理）
• 每個 project 要顯式 activate——第一次 session 進新 project 時 agent 要主動跑 activate_project 或在 plugin config 預設 project root

要注意的點：

Language server 缺失時的失敗模式。對冷門語言（如 Liquid / Pascal）若環境沒裝 language server、activate_project 會回失敗但不會主動裝。需要使用者自己準備 server binary。Dart / TS / Python / Go / Rust 等主流語言 serena 會 bootstrap 處理。

JetBrains backend 是付費。OSS 用戶只能用 LS backend、得不到 debug 整合那組能力。

適用 / 不適用情境的判讀

適用情境：

• 主力語言有成熟 LSP（Dart / TS / Python / Go / Rust / Java / C# 等）
• 型別敏感的 refactor 場景（rename / extract method / 跨檔 reference 更新）
• 要編譯 diagnostic 即時反饋（取代 build / test cycle 的部分功能）
• Symbol-level atomic edit 的可靠性比 graph 持久化重要

不適用情境：

• 主力語言 LSP 不成熟或不存在（serena 沒得借力）
• 需要概念性 / 自然語言搜尋（用 cbm 的 11-signal scoring）
• 需要跨 session 累積的 graph context（serena per-session、不持久化）
• 需要跨 service HTTP/RPC 鏈接（serena 沒這層）

搭配建議：serena 是「型別精確 + 編輯出口」的角色。在它擅長的語言上做 caller 追蹤 / refactor、把概念性搜尋讓給 cbm、把日常結構查詢讓給 codegraph。三者怎麼分工見 三 MCP 工作流與 Dart 實測。

結論

serena 的核心價值在三件事：直接借 LSP 拿型別精確的 reference、symbol-level atomic edit 的可靠性、編譯 diagnostic 即時整合。前兩件對任何成熟 LSP 語言都成立，第三件對「改完 code 想立刻驗 type error」的工作流特別重要。

它的能力上限取決於「目標語言 LSP 成熟度」——LSP 強的語言上 serena 是強工具、LSP 弱的語言上 serena 也跟著弱。它的能力下限取決於「持久化 graph 與自然語言搜尋」這兩層空白——這兩層要靠別的 MCP 補齊。

評估 code intelligence MCP 不能只看 README benchmark：每個工具的 benchmark 都選自己擅長的 codebase 跟語言，readme 數字只能參考、不能直接套到自家 stack。

這次選一個 Dart 商業專案做對照場域有兩個理由：

• Dart 是三個工具的「中間地帶」——cbm 不在 hybrid resolution 名單、codegraph 列為 full support、serena 借 dart analysis_server 有完整 LSP。三條技術路線在同一語言上的能力差距會被最大化。
• Dart 大量用 extension type、generic、factory pattern，這些是 type-inferred dispatch 的高發場景，能逼出每個工具的真實精度差。

在 Go / TypeScript 上跑同樣對照，結論會反過來——cbm 的 hybrid resolution 在那裡會接近 LSP 精度，三刀流的必要性會降低。所以這篇結論限定「LSP 成熟但 cbm 不在 hybrid resolution 名單」的語言。

本質差異：tree-sitter syntactic vs LSP type-aware

三個工具在 Dart 上的能力差距，根源是兩條技術路線的本質落差：

tree-sitter syntactic：只看語法結構。看到 a.b() 知道有個 method call、不知道 a 是什麼型別、不知道 b() 連到哪個 declaration。對 receiver 是 literal 或顯式型別宣告的 callsite 可以解、對 local variable / parameter / 推斷型別的 callsite 會漏。

LSP type-aware：走 language server 內建的型別推斷引擎。跟 IDE 用同一套後端、能解出 a 的真實型別、再從 type declaration 找到對應的 method。所以 reference 是型別精確的。

cbm 的 hybrid type resolution（限 Go / C / C++ / TS / JS）是把 LSP 的型別解析算法 clean-room 重寫進 binary、所以那幾個語言上 cbm 等於有 LSP 級精度但沒 LSP 依賴。Dart 沒得到這個待遇，所以 cbm 在 Dart 上只剩純 syntactic 結構抽取。

判讀訊號：看一個工具對某語言的能力強弱，問「它在這語言上做型別解析嗎？」——做的話接近 LSP，不做的話只是個結構抽取器。

這個 framework 建立後、下節展開到 9 個維度的設計對照。

三個工具的設計差異對照

三個工具雖然都是「code intelligence MCP」，設計取向互補：

這張表的判讀重點：三者擅長的事不重疊。cbm 強在「找東西」、codegraph 強在「日常 call graph + auto-sync」、serena 強在「型別精確 reference + 編輯出口」。

對照表的維度很多、但實務上踩到事故的多半集中在三個維度，把它們各自展開：

Type resolution 決定 caller 數字的可信度。Dart / Swift / Kotlin 這類「LSP 完整、但 cbm 走純 syntactic 路線」的語言上、tree-sitter 工具回的 caller 數字是 lower bound（實際值通常更高）。samplePrice.multiplyByRate(...) 這種 type-inferred receiver 是這層差距的主戰場。判讀訊號：對熱門 class 跑同一 query、若 tree-sitter 工具 caller 數比 LSP 工具低過半、type-inferred dispatch 在這語言是主流模式、tree-sitter 結果只能當 starting point。

Sync 機制決定「邊改邊問」是否可用。codegraph 的 native OS file watcher + 2s debounce 最貼近 IDE、cbm 的背景 git polling 有秒級至分級延遲、serena 的 session warm-up 是「啟動時等一次、之後即時」。事故型態：在 codegraph 改完檔案立刻問 caller 多半 OK、在 cbm 立刻問會拿到 stale graph。判讀訊號：問完 query 對結果存疑時、先檢查工具的 sync 狀態（cbm 跑 index_status、codegraph 跑 codegraph_status、serena 直接重 query）。

持久化模式決定跨 session 的累積成本。cbm / codegraph 寫 SQLite、跨 session 重用；serena per-session、每次 spawn LSP warm up。對「短任務反覆 ad-hoc 查詢」cbm / codegraph 邊際成本更低、對「會做 symbol-level edit 跟 diagnostic」serena 的 per-session warm up 是必要 cost。判讀訊號：第一次 query 慢、之後快——LSP indexing warm up、正常；每次 query 都慢——LSP 可能因記憶體不足重啟、需排查。

下面的實測是這張表在 Dart 上的數字驗證。

Dart 實測對照：同題不同工具

實測環境：

1專案類型：Dart 商業專案（POS / 零售領域）
2Branch：refactor/money-value-object
3索引規模：
4  cbm:        3,038 nodes,  6,355 edges（Dart 沒 CALLS edge）
5  codegraph:  6,244 nodes, 12,223 edges（含 CALLS edge）
6  serena:     per-session、無索引統計

cbm 跟 codegraph 的 nodes 約 2x、edges 約 2x，差異關鍵不在 nodes（cbm 缺 import / enum_member 等次要 node）、而在「有沒有 CALLS edge」——這直接決定 caller / impact 類查詢能不能用。

實測數字的適用範圍：本節的所有 callsite / caller / impact 數字（含查詢 1-5）都是單一 Dart 商業專案的內部 baseline、不保證跨專案重現。Dart 上 type-inferred receiver 比例高的專案會放大三個工具的差距、比例低的專案會縮小差距。換到 Swift / Kotlin / Rust 等語言上、絕對數字會不同但「tree-sitter syntactic vs LSP type-aware」的差距方向通常一致。讀者要套用結論時、先在自家 repo 跑一遍同題對照、看自己的數字落差。

查詢 1：誰呼叫了 Money.multiplyByRate

codegraph 漏掉的 3 個 callsite 共同特徵：

1// lib/data/models/product/product.dart
2final Money samplePrice = ...;
3samplePrice.multiplyByRate(Decimal.parse('0.9'));
4samplePrice.multiplyByRate(Decimal.parse('0.6'));

samplePrice 是 local variable、要型別推斷才知道是 Money。tree-sitter 看到的只是 <identifier>.multiplyByRate(...)、解不出 dispatch target。

serena 透過 dart analysis_server 拿到完整型別資訊、知道 samplePrice 宣告是 Money、能精確 dispatch。

查詢 2：誰呼叫了 LocaleSymbolConfig.formatAmount

這題 codegraph 跟 serena 的差距比較小——formatAmount 在很多地方是用顯式 receiver 呼叫（如 LocaleSymbolConfig.cny.formatAmount(...)），tree-sitter 對顯式 receiver 解得到。

兩邊數字的差異主因是 caller symbol 數 vs callsite 數的計數單位差：

• codegraph 算 caller symbol（一個 method 內呼叫幾次都算 1）
• serena 算 callsite

寫實測 baseline 時這個單位要寫死、否則 3 vs 9 看起來像精度差距、實際上一部分只是計數規則不同。

查詢 3：Money 符號的內部結構

Dart extension type 是相對新的特性、tree-sitter grammar 對它的支援深度不一。serena 走 LSP 直接拿到 dart analysis_server 對 extension type 的完整解析。

對需要「列出某 class / extension 所有 member」的場景、serena 是 Dart 上 LSP 級精度最可信的選項（其他 MCP 在 Dart extension type 上做不到完整 member 列舉）。

查詢 4：概念性搜尋「金額顯示」相關函式

對「我不知道精確名稱、只記得功能類別」這種 query：

前 4 名兩邊都抓到核心 formatAmount 實作，第 5 名後分歧明顯：

• cbm 補進的 getBalanceDisplay / _buildPriceDisplay / connectExternalDisplay 都跟「金額顯示」概念相關（顯示金額 / 顯示餘額 / 外接顯示器）
• codegraph 補進的 displayName / displayTags 只是符號名含 “display” 子字串、跟金額無關

差異來源是 cbm 的 11-signal scoring + cbm_camel_split 對 camelCase 切詞做語意切分（getMoneyField → get + money + field）。codegraph 的 search 是 symbol pattern match、沒對自然語言 query 做語意處理。

這題的判讀很關鍵——cbm 在「找東西」的角色不能被 codegraph 取代。即使 codegraph 在 Dart 上有可用的 call graph、它的 search 仍然贏不了 cbm 的概念性 query。

查詢 5：Money 的 impact 範圍 / cross-symbol trace

Money 是該專案大量使用的 value object、實際被使用的檔案橫跨 receipt_data 實作、settlement、cart_item、order_dto 等業務模組。codegraph 只回 1 個檔案 5 個 symbol、嚴重低估 blast radius。

漏掉的原因跟查詢 1 同源——something.multiplyByRate(...)、Money 在 factory 內被隱式構造這些都不在 tree-sitter 能解的範圍。MoneyFieldRenderer 之所以被抓到、是因為它的 field 顯式宣告為 Money，這是少數 tree-sitter syntactic 能抓的場合。

對 cross-symbol trace：

1codegraph_trace(from: "Money/multiplyByRate", to: "ProductSpecification")
2→ "No direct path"、建議跳到 dynamic dispatch

graph 上根本沒這條 edge（漏掉的 product.dart 那 3 個 callsite 正是這條 trace 的關鍵跳）、所以 trace 直接失敗。

判讀訊號：重要 refactor 不能單看 codegraph 的 impact 數字。要走 serena find_referencing_symbols 二次確認；對 cbm 不在 hybrid resolution 名單的語言、blast radius 必須用 LSP 工具驗證。

三刀流工作流

實測結論：cbm / codegraph / serena 各有不可替代的角色，組合使用才是 Dart 主力專案的合理 stack。

 1找東西（不知道精確名稱、概念性 query）
 2  → cbm search_graph(query="...")           ← 11-signal scoring 對概念性 query 最強
 3
 4知道精確名稱、找 caller / callee
 5  → codegraph_callers / codegraph_callees   ← auto-sync 2s 反應最快
 6  ↓
 7  發現結果可能不完整（type-inferred dispatch 多的場合）
 8  → serena find_referencing_symbols         ← LSP 完整精度補位
 9
10重要 refactor 確認 blast radius
11  → serena find_referencing_symbols         ← 不能單靠 codegraph_impact
12
13符號層級的編輯
14  → serena replace_symbol_body / rename     ← symbol-level atomic edit
15
16跨 service HTTP/RPC 鏈接（若 monorepo 含 client + server）
17  → cbm HTTP_CALLS edge                     ← 三個工具中只有 cbm 有這層

幾個關鍵的判讀原則：

入口跟出口要分清楚：cbm 是「廣度索引 + 模糊搜尋」的入口、拿到 qualified name 後轉給 serena 做精確查詢與編輯。codegraph 補在中間、做日常結構查詢。

重要 refactor 必走 serena 補位：codegraph 的 caller / impact 在 Dart 上系統性偏低、不能單看數字判斷影響範圍。決定 rename 或大幅修改 method 之前、用 serena 跑一次 find_referencing_symbols 對齊。

Hook 不要打架：cbm 會寫 PreToolUse hook 攔截 Grep / Glob / Read / Search（README 描述只擋前兩者、實裝版本含 Read / Search）、codegraph / serena 都不寫 hook。同時用三個工具時、注意 cbm hook 是否誤判把正常的 markdown grep 也擋掉（實測有 false positive）。

對其他語言 stack 怎麼變化

這個三刀流結論限定 Dart。不同語言 stack 的真實壓力不一樣、推薦組合也跟著變——把幾個常見 stack 各自展開。

Go / TypeScript / C / C++ 主力

這層是 cbm 的甜蜜點：hybrid type resolution 涵蓋這四個語族、CALLS edge 抽得到、cbm 的 caller / blast radius 精度接近 LSP。實務影響是「cbm 在 Dart 上需要 codegraph + serena 補位」的場景大幅縮小——cbm 自己就能處理 caller / impact、加上它原本就強的 11-signal 概念搜尋跟跨 service HTTP_CALLS，等於一個工具撐住「找東西」「caller / impact」「cross-service」三層。

serena 在這個 stack 仍是 symbol-level edit 跟 compile diagnostic 的關鍵來源——cbm 純讀、沒 rename / replace_symbol_body、沒 LSP 診斷整合。所以合理組合是「cbm + serena 雙刀流」、codegraph 的角色被 cbm 取代掉。判讀訊號：在自家 repo 跑 cbm trace_call_path 對 5 個熱門 class、若 caller 數跟 serena 的 find_referencing_symbols 對得上、codegraph 確實可以省下。

Swift / Kotlin / Rust 主力

這層跟 Dart 場景結構接近：serena 透過 sourcekit-lsp / kotlin-language-server / rust-analyzer 能拿到完整型別解析、cbm 不在 hybrid resolution 名單只剩純 syntactic。所以「三刀流」的論證仍適用。

但 codegraph 在這三個語言的 query 品質要實測——19+ 列表內這幾個都列為 supported、實際解析深度因語言成熟度而異。Swift 特別容易踩坑的點是 Objective-C interop（dispatch table 跨語言）跟 protocol extension 的型別推斷、Kotlin 則是 reified generics 跟 inline function、Rust 是 trait method 跟 macro 展開後的 callsite。判讀訊號：對自家專案最常用的 dispatch pattern 寫一個 minimal example、跑 codegraph callers、看抓不抓得到。

Python 主力

三個工具的 Python 支援都成熟、但著力點不同：cbm 對 Python 有完整 hybrid resolution、codegraph 對 Python 是核心支援語言之一（VS Code benchmark 在它的 7 codebase 列表內）、serena 透過 pyright / pylsp 拿型別資訊。

Python 的特殊壓力是 dynamic dispatch（duck typing / monkey patching / metaclass / getattr）——這層任何 static 工具都會漏。判讀訊號：對自家 codebase 跑「找 X class 的所有 method 呼叫」、若大量真實 callsite 在 type annotation 缺失的位置、所有工具都只能給 lower bound。實務組合多半雙刀（codegraph + serena）夠用、cbm 對 Python 的不可替代價值在 cross-service HTTP_CALLS（Django / FastAPI 跨 service 場景）。

冷門語言 / DSL（Liquid / Pascal / Svelte template 等）

這層 serena 多半沒 LSP 可借（除非自備 server）、cbm 純 syntactic（hybrid 名單外）、codegraph 是少數仍有 query 的工具——但 query 品質要看 codegraph 對該語言投入多深、Pascal / Delphi / Liquid 這類列表末段的支援度可能只到 symbol 抽取、callsite 不一定有。

實務上對這層語言、退回 grep + codegraph 比強推三刀流合理——caller / impact 用 codegraph 試、不夠就 grep 補、別期待 LSP 級精度。判讀訊號：若 codegraph status 顯示 indexed file 多但 edges 數明顯偏低（< 1 條 edge per file）、call graph 多半沒抽起來、視同純 syntactic 工具用。

共通的評估方法

無論哪個 stack、第一次裝 MCP 前在自家 repo 跑「找重要 class / function 的所有 caller」這個基準題、把不同工具的數字並列比較、再決定組合。README benchmark 是行銷數字、自家 stack 跑出的數字才是真實 baseline。

評估新 MCP 工具的 checklist

從這次踩三個（含一個跳過實裝的 GitNexus）的經驗回推、未來評估新 code intelligence MCP 要先確認：

License：商業專案要 MIT / Apache 2.0 / BSD。PolyForm Noncommercial 之類限制商業使用的 license 直接刷掉。這條最便宜、最早做、最少人記得做。

目標語言的 call graph 支援：README 寫「full support」要實測。tree-sitter wrapper 通常只到「結構抽得到」、沒到「call edge 抽得到」。同樣是「有 CALLS edge」、有 type-inferred dispatch 的 syntactic 工具跟有完整 LSP 的差距可能 2-3x callsite 數。

MCP tool 數量不等於能力：14 個 tool 不一定贏過 10 個。看 caller / impact / find_referencing_symbols 這類核心功能有沒有、品質好不好、勝過 tool 多寡。

是否會自動改 ~/.claude/ 設定：大多會。先看 install script 動了哪些檔案、能不能還原、uninstall 是否徹底（cbm uninstall 不清 hook 是踩過的坑）。

是否有 CLI 模式：有的話本 session 就能實測、不必等 Claude Code 重啟載入 MCP。CLI mode 對「驗證 baseline」特別重要——拿 CLI 結果當 ground truth、再對 MCP 結果做差異比對。

Auto-sync 機制：file watcher / git polling / 純手動 reindex 差異很大。「邊改邊問」工作流對 sync 延遲很敏感、選錯會踩到 stale graph 的事故。

結論

對 Dart 主力專案：三刀流（cbm + codegraph + serena）是合理 stack。三者擅長的事不重疊、互相補位有明確角色：

• cbm：概念性搜尋入口、跨 service HTTP/RPC 鏈接
• codegraph：日常 80% 的結構查詢、auto-sync 反應最快
• serena：型別精確 reference、symbol-level atomic edit、編譯 diagnostic

對其他語言 stack、cbm 進入 hybrid resolution 名單後組合會收斂、但 serena 的 symbol edit 跟 diagnostic 角色仍不可取代。

評估方法的更普遍結論：README benchmark 只是起點、要在自己的 stack 上跑同樣的基準題才算數。每個工具的 benchmark 都選自己擅長的語言跟 codebase、跨語言遷移結論需要重新驗證。用 5 個查詢做 baseline、把 CLI 數字當 ground truth、再對 MCP 結果做差異對比、是現階段最低成本的工具評估法。

寫教學文章時、純靠 LLM 自生內容會踩到兩個系統性盲點：

1. Scope 盲點：內容停在「教科書級」結構、漏掉真實事故才會浮現的失敗模式跟設計取捨。
2. 準確性盲點：把通用 best practice 包裝成「[case] 揭露」、把案例沒講的細節寫成案例事實。

本文整理在 backend/01 至 backend/07 batch 1 七個模組撰寫過程中浮現的五階段流程：

1. 完整閱讀案例庫、抽 findings — 用案例驅動「該寫什麼」、不只是 LLM 自生
2. 基於 findings 建立內容 — findings 分布到章節、避免硬塞模板
3. Agent team 平行多輪審查 — 用 3 個專責 reviewer 補 LLM 自盲點
4. 修正循環 — 按檔案批次修 high + 重要 medium、reviewer 抓出問題各章節對應修
5. Polish pass — 跨檔系統性 pattern 集中處理（負向骨架掃描、編號漂移、用語不一、cross-link 補漏）

實作數據：7 個模組（backend/01-07 batch 1）、~45 章 / 385 個 review issue、case fidelity 落在 70-93% 區間、修正後品質升至 0 critical 編造、cross-link 全綠、規範違反 polish pass 後降到單位數低 issue。06 模組後方法論工具化為可觸發 skill、stage 1-5 流程跟 reviewer prompt template、self-scan regex 都封裝成可重用元件。07 模組驗證下「章節已有 routing layer skeleton」的特殊處理（在現有結構內補 case-driven 深化段、不擴成厚重章節）。

問題：LLM 自生內容的兩個盲點

純靠 LLM 寫教學章節、容易產出兩種品質風險：

Scope 盲點：LLM 從訓練資料抽出的內容偏 普遍性、是「教科書 + 部落格 + 文件」的綜合。但真實工程議題的判讀條件常常來自 特定事故揭露、不是普遍知識。例：

• 「DynamoDB GSI 在 backfill 完成前查不到完整資料」這種具體陷阱
• 「Super Bowl +50% no sweat 的工程意義是 headroom 提前預留、不是 vendor 神奇」這種反直覺判讀
• 「99.99% → 99.999% 是指數成本、遠超直覺的 10x 線性想像」這種規模對照

純技術知識推導不出來、要看真實案例才會浮現。

準確性盲點：LLM 寫到「對應 [case]」時、容易把通用 best practice 包裝成案例事實、或把案例沒提到的細節擴寫成「案例揭露」。例（從本文討論的實作中抓出的真實 issue）：

• Snowflake 案例描述「異常查詢偵測維度（query 體積 / IP / 跨 schema scan）」、LLM 自生內容寫成「query 體積從 1MB / 天跳到 10GB / 天、來源 IP 從 office network 變 unknown VPS」— 具體數字是 LLM 加上去的、案例沒寫
• Tixcraft 案例策略段建議「composite key」、LLM 自生內容寫成「Tixcraft 用 user_id 分散、不是 event_id」— 案例沒揭露 Tixcraft 實際 partition key 設計

這兩類盲點都不容易在 self-review 時抓到、因為 LLM 看不出自己內容是否真的對應案例。

階段 1：完整閱讀案例庫、抽 findings

為什麼要完整閱讀、不能只看 title + description

只看 title + description 能做 承接（建立 link）、但無法做 scope 擴展（揭露 LLM 不會自生的議題）。case 的 findings 通常埋在 body 的「判讀」段、不在 description 裡。

實作中的對照：第一輪 audit 6 個 case、每 case 平均揭露 2.3 個 finding；其中約 7 成是 description 跟 title 看不到、要讀完整 body 才能抽出。例如 DraftKings 案例的「讀寫雙峰錯位」（比賽中讀爆量、payout 時寫爆量）— description 只說「financial ledger」、要讀「核心負載形狀」段才看到雙峰結構。

邊際遞減的判斷

不是所有 case 都要讀。實作中觀察到的遞減曲線：

第三輪開始 純新議題 比例下降、重複 frame 出現（vendor dogfood 在 3 個 case 都揭露、benchmark 對照基準在 3 個 case 都揭露）。這是停止 audit 的訊號。

判讀條件：

• 繼續 audit：每 case 至少 1.5 個純新議題、且重複 frame 不超過 30%
• 停止 audit：純新議題 < 1 個 / case、重複 frame > 50%、累積 finding 數已涵蓋目標章節主要議題

實作中 11/94 cases（~12%）時邊際遞減訊號明顯、16/94 cases（~17%）時停止 audit、抽出 ~42 個 unique findings、足以支撐 6 個章節的 scope 擴展。

Findings 抽取方法

讀 case 時、把每個段落看成可能的 finding 來源、問三個問題：

1. 這段揭露什麼判讀條件？（是不是純技術推導不易浮現的議題）
2. 這段揭露什麼數字 / 設計細節？（規模、percentile、partition key 數量、replication lag 量級）
3. 這段揭露什麼失敗模式？（事故當下會出什麼問題、有什麼反直覺結論）

寫進 findings 列表時、要附上 case 來源 跟 該對應到哪個章節。例：

Finding: 線性擴展是 OLTP 設計最高目標、coordinator 是傳統 OLTP 的擴展瓶頸 來源: 9.C10 Spanner 案例「2 nodes → 45K reads/sec, 4 nodes → 90K reads/sec」段 章節: 1.11 全球分散式 OLTP

不寫來源跟章節定位、findings 會變成抽象列表、寫稿時用不上。

Case 類型的承接策略

不同 case 類型適合不同承接深度、誤判類型會引發 over-extrapolation 問題。實作中觀察到的兩類 case：

Rich case（典型：09/07 案例庫中含具體數字、設計細節、遷移路徑的長篇 case）：

• 內容深度：50-200 行、含具體數字、業務情境、引用源
• 承接方式：可直接引用為事實、case 揭露的具體數字（RPS、延遲、TPS、stale window）可放進章節
• 例：9.C5 Amazon Ads「90M RPS + 5M writes/sec + 99.999%」可直接寫進 1.10 KV 章節
• 例：9.C6 Tinder「4700 萬 MAU 配對引擎、cache 是主要服務面」可直接做為 2.1 high-concurrency 的判讀依據

Medium case（06 模組新發現的類別、典型：模組內部 case 庫中含結構化「決策機制」+「可觀測訊號」表、但無具體數字的中篇 case）：

• 內容深度：30-50 行、結構化 5 段（問題場景 / 決策機制 / 可觀測訊號 / 常見陷阱 / 下一步路由）、含 mechanism + 訊號名稱、但不給具體數字
• 承接方式：用 case 直接列出的 mechanism 名稱 精準引用、比 skeleton 精準、但比 rich 保守
• 承接句型：「對應 [case]：揭露 N 個機制 — A、B、C、D」
• 例：6.C1 Amazon Shuffle Sharding 揭露 cell boundary / shuffle sharding / static stability / constant work 四機制、可直接引用機制名稱、但不擴寫到「具體 shard 數量」「具體 cell 大小」等 case 沒提的實作細節

Skeleton case（典型：模組內部 N.Cx 案例庫中只有 frame、無具體數字的短篇 case）：

• 內容深度：10-30 行、只給方向、無具體數字 / taxonomy
• 承接方式：作為「視角 / 方向」、可引用為「case 揭露 X 議題」、但不引用為「case 揭露 X 具體場景數量」
• 例：2.C1 Meta Cache Consistency 只有「promotion、shard move、故障恢復」三個方向、不引用為「具體 inconsistency window 數字」
• 例：3.C9 反例只給「依賴特定 offset / 重試節奏 / idempotency」三個方向、不引用為「4 個具體誤配場景」

判讀條件：

• 看 case 行數 + 內容密度判斷類型
• skeleton case 的 finding 寫成「對應 [case] — 揭露 X 方向、以下展開基於通用工程知識補充」
• medium case 的 finding 寫成「對應 [case]：揭露 N 個機制 — A、B、C、D」、用 mechanism 名稱精準引用
• rich case 的 finding 可寫「對應 [case] — XXX 具體數字 / 設計」

實作中（01/02/03 三個模組驗證）、skeleton case 寫成 rich case 對應是 case fidelity reviewer 抓出 over-extrapolation 的主要來源（02 / 03 各 3-4 個 critical 編造都來自此陷阱）。誤判類型 → 編造 case 沒寫的細節 → reviewer 抓出 → 修正成本高。stage 1 抽 findings 時就要 標明 case 類型、stage 2 寫作時依類型決定承接深度。

Rich case 引用的反向風險（04/05 模組新發現）：rich case 雖然可以引用具體數字、但 case 內常含「觀察層」（具體 fact）跟「判讀層」（作者推論）兩段、引用時要分開處理。05 模組驗證時 case fidelity reviewer 抓出 4 個 high issue 都來自把「判讀層作者推論」寫成「case 揭露的 fact」：

• 9.C12 Riot Games：5.2 寫「揭露 35ms latency 反推 region 部署」、實際 case 的「35ms」是觀察層、「反推 region 部署」是作者判讀層
• 9.C34 GCP 130K：5.2 寫「揭露 Spanner 替 etcd 才是 K8s 規模極限的關鍵」、實際 case 用更保守的「control plane 極限取決於 storage backend、GCP 用 Spanner 替換 etcd」分兩個點寫
• 9.C12 Riot：5.2 引用「single-tenant per game 的多 cluster 策略」、漏掉 case 揭露的關鍵歷史轉折「從 multi-tenant cluster 模型改成 single-tenant per game」

修法：rich case 引用時、用「揭露 X 觀察 + 作者判讀 Y」分層標明、避免把推論寫成 fact。或在引用後補一句「（case 中 X 屬作者判讀層、本章引用此推論）」明示分層。

兩類 case 的引用紀律可總結成一個 fact vs derive 分層原則：

• Skeleton case：絕大多數內容是 derive（方向 / 議題）、引用時不擴寫成 fact
• Rich case：含 fact（具體數字 / 設計）跟 derive（作者判讀）、引用時分層標明、避免把 derive 升級成 fact

階段 2：基於 findings 建立內容

Findings 分布到章節

抽完 findings 後、按章節主題分類、看哪個章節缺口最大、哪個 finding 該寫去哪。實作中的分布：

• 1.1 高併發：7 findings
• 1.5 紅隊：8 findings
• 1.9 reconciliation：4 findings
• 1.10 KV：6 findings
• 1.11 全球分散式：10 findings（最大缺口）
• 1.6+1.12 migration：5 findings

涉及多軸取捨的章節（1.11 一致性 / 可用性 / 成本 / 延遲）暴露最多缺口、純流程章節（1.9）暴露最少。這是 章節結構性質 的差異、不是寫得好壞。

Stage 2 寫作前先定 SSoT 對應

當同一 finding 或 frame 在 多個章節 都有用、要在開始寫之前 先定 SSoT 對應、否則 case-driven 擴章必然出現 frame 重複展開。

實作中觀察到的反例（02 / 03 模組都遇到過）：

• 02 cache：「cache 角色變化」frame 在 2.1 主寫但實際屬模組層級、應在 _index；Tubi 案例在 2.1 / 2.2 / 2.8 三章各自展開 mini-finding；Snap KeyDB 在 2.1 / 2.7 / 2.8 三章重複
• 03 message-queue（最嚴重）：「三層語意（delivery / processing / recovery）」在 3.4 / 3.6 / 3.8 三章各自定義；「Slack Kafka+Redis 拓樸」在 3.4 跟 3.8 兩章逐字重複；「規模對照（小 / 中 / 大型）」在 3.4 / 3.6 / 3.8 三章拆用、結論散落讀者拼不出總圖

SSoT 對應的判讀順序：

1. 列出所有 cross-chapter findings（出現在多章的 frame）
2. 每個 frame 指定 一個 主寫章節（SSoT）
3. 其他章節 只 link、不展開
4. SSoT 章節要有完整論述、被引用章節保留簡述跟 cross-link

SSoT 選擇標準：

• frame 涉及 跨模組層級概念 → 寫進 _index.md
• frame 涉及 單章核心責任 → SSoT 為該章
• frame 涉及 跨章交接點 → 選最相關章節為 SSoT、其他章節 link

漏掉這步、reviewer 跨章一致性會抓出 5-10 個 frame 重複 issue、修正成本高（要把已展開內容收斂回 SSoT）。Stage 2 前花 30 分鐘做 SSoT 對應、能省下 Stage 3 數小時的重構工。

避免硬塞模板

最大的反模式是把多個 findings 硬塞成同一個 table、每 row 一短語、失去情境敘事。

實作中的反例：1.9 章新增「Dual-track IC 5 個角色表」、本來想用表格整齊呈現、但 reviewer 抓出「5 角色平鋪、責任只一行、未展開每角色在真實事故的決策樣態」。修正後拆成：

• 主表格（5 個角色快速對照）
• Overall IC 跟 Tech IC 的差異獨立段（300 字）
• Data IC 的特殊角色獨立段（300 字、含「為什麼不能讓 Tech IC 兼任」的失誤對照）
• 事先準備 4 項各自延伸（不只列項目、解釋失效樣態）

這樣 每個項目都是情境 而非 硬塞的欄位、符合 AGENTS.md「表格不是終點」原則。

情境敘事的判讀條件

每段內容寫完後、問三個檢查問題：

1. 首句是不是核心原則？（不是「某 case 揭露 X」、是「X 是什麼、承擔什麼責任」）
2. 是不是用否定句主導？（「不是 X」「不只 X」開段要回到正向陳述）
3. 這個 finding 在不同情境下是否會變義？（一個 finding 套到多個情境、要分情境寫、不是套同模板）

案例引用的準確性

寫「對應 [case] — XXX」時、要回 case 原文驗證 XXX 是否真的出現。實作中常見的失分：

• 把 case 沒提到的數字補進去（「30-90 天 baseline」、「1MB→10GB / 天」）
• 把通用 best practice 寫成案例事實（「Snowflake 之後改為預設強制 MFA」— case 只說「資料平台應預設強制 MFA」、不是描述後續行動）
• 公開事實但 case 沒寫（「MOVEit 跨上百家客戶」、「LastPass master password 弱可被離線爆破」）

寫稿當下不容易抓、要靠階段 3 的 case fidelity reviewer 對照。

階段 3：Agent team 平行多輪審查

為什麼要 agent team、不能交給單一 reviewer

單一 reviewer 有兩個限制：

1. 維度盲點：一個 reviewer 同時看寫作規範、案例準確性、跨章一致性、容易 維度互相干擾、最後每個維度都看不深
2. Context 污染：reviewer 讀完整 commit + 所有案例 + 所有章節後、自身 context 就被佔滿、給的建議會 對應主 context 也跟著沉重

解法是用 3 個專責 reviewer、平行 background 跑、各自獨立報告、主 context 只看精煉摘要。

三個維度 reviewer 分工

實作中使用的三個 reviewer：

Reviewer A：寫作規範審查（AGENTS.md 核心原則）

• 對照核心原則先行、正向陳述優先、商業邏輯先於 case、表格不是終點、情境優先於模板、可操作判準等八原則
• 找首句用否定句切入、表格 / bullet 平鋪沒延伸、表格項硬塞模板等
• 實作中抓出 25 個 issue

Reviewer B：案例引用準確性

• 對照原始 case 內容、驗證「對應 [case] — XXX」斷言是否真的來自案例
• 識別編造數字、過度推論、把通用 best practice 寫成案例事實
• 實作中抓出 9 個 issue、包含 3 個 critical 編造

Reviewer C：跨章一致性

• 跨多章找重複 frame、矛盾說法、失效 cross-link、章節邊界錯位
• 識別「該在 A 章卻寫在 B 章」、「frame 重複展開沒整併」
• 實作中抓出 13 個 issue

平行 background 跑、不佔主 context

關鍵設計是 3 個 reviewer 並行、各自 background、各自寫 output file、不污染主 context：

• 主 context 只看到「啟動 reviewer」跟「reviewer 完成的彙整報告」
• Raw output 跟 reviewer 的 deep dive 留在 output file、需要時 SendMessage 繼續對話
• 3 個 reviewer 完成時間 ~5-15 分鐘、可以同時跑、不必等

實作中 3 個 reviewer 平均 2-3 分鐘完成、主 context 增量 ~3K tokens（彙整 + 47 issue 清單）、相比把所有案例跟章節塞進主 context 做 review 節省 ~80% context。

Reviewer issue 數量的 baseline

7 個模組（01 / 02 / 03 / 04 / 05 / 06 / 07 batch 1）驗證後、每模組 reviewer 抓到的 issue 數量在 standards reviewer 抓 pattern 越來越細的趨勢下持續擴大、可作為流程預期：

模式觀察：

• 每模組 issue 數隨 standards reviewer 抓 pattern 越來越細而擴大：01-03 穩定在 47-55、04/05 推到 51-59、06 推到 71、07 batch 1 回到 52（章節已有 routing skeleton、擴章規模小）。趨勢來自 standards reviewer 抓的 pattern 越來越廣（從負向骨架 → 「核心責任不是」變體 → 「沒有 X 會 Y」鏈式 → 「case 引用段首」框架 → 「case 引用句構同質化」）。
• Case fidelity 準確率分布更廣：04 的 92.9% 來自 skeleton case 嚴守「揭露方向、通用補充」紀律；05 的 80% 因引用 09 rich case 加入「fact vs derive 分層」新失分模式；06 的 88% 屬 medium case 紀律首次套用、揭露「實作層擴寫過頭」失分；07 batch 1 的 81% 揭露「跨 case 合成 frame」新失分類型（reviewer B 2 high 都屬此類）
• Consistency reviewer 抓到的 frame 重複跟章節數成正比：02 / 03 / 04 都有 ~13-18 個一致性 issue、05/06 跨模組 cross-link 密度高仍維持在 baseline 內、07 batch 1 因 7 章規模、issue 13 個落在 baseline 下緣

Stage 3 修正成本估算：

• Critical（編造、矛盾）：~每個 5-10 分鐘修正、佔 0-5 個（04/05 都 0 critical、紀律已成熟）
• High（重複 frame、章節邊界、判讀層 vs fact）：~每個 10-20 分鐘修正、佔 5-14 個
• Medium / Low（規範細節、cross-link 補）：~每個 2-5 分鐘修正、佔 35-45 個
• 總計 ~1.5-2.5 小時 / 模組

Stage 4 修正後仍會有 ~30-40% issue 殘留（low / medium 的 cross-link、編號漂移、用語不一）、屬於系統性 pattern、適合在 Stage 5 polish pass 集中處理（見後段）。

為何要多輪 review、不是一次到位

第一輪 review 的目的是 找問題、不是 修問題。問題清單列出後、要做兩件事：

1. 分類優先序：critical / high / medium / low、按嚴重度跟修改成本排序
2. 修正循環：批次修正、避免一個一個改散開、修完再跑驗證

修正後可選擇性做第二輪 review、檢查：

• 修正本身有沒有引入新問題
• 之前 reviewer 漏掉的維度（例：教學性、讀者路徑、實作可行性）
• 跨 commit 一致性

實作中第一輪足夠處理 47 個 issue、第二輪沒進行、留到未來模組（02 cache、03 message queue）累積經驗後再評估是否必要。

修正循環的執行原則

47 個 issue 分布到 6 個章節、修正時 按檔案批次、不是按 issue 編號順序。每個檔案一次修完所有相關 issue、減少切換成本：

• 1.5 紅隊章（12 issue）：含 2 個 critical 編造、優先處理
• 1.10 KV（7 issue）：含 1 個 critical 編造
• 1.11 全球分散式（5 issue）
• 1.12 大規模遷移（10 issue）：表格密度最高、最多延伸
• 1.1 高併發（4 issue）
• 1.9 reconciliation（5 issue）

每個檔案修完後跑一次 mdtools fmt --fix + mdtools cards + mdtools lint、確認該檔內部一致、再進下一檔。最後跑一次跨檔驗證、確認 cross-link 全部對齊。

階段 5：Polish pass（04/05 模組後新增）

Stage 4 修完 high + 重要 medium 後、仍有 ~30-40% 的 low / medium 殘留、屬於系統性 pattern（負向骨架、編號漂移、cross-link 缺漏、模板化）。這些 issue 不適合按章節批次修、適合用「跨檔系統性掃描」處理 — 這是 polish pass 的核心責任。

Polish pass 的觸發條件

Stage 4 後出現以下任一訊號、就該排 polish pass：

• Standards reviewer 抓出的「不是 X、而是 Y」段首結構超過 5 處（屬寫作習慣、單章修改無效率）
• Consistency reviewer 抓出「編號漂移」「失效 link」「用語不一」多處（屬跨檔規範問題）
• 自掃描漏掉的 pattern 出現在 reviewer report（例：04 自掃描說 pass、reviewer A 抓出 31 個 issue、暴露自掃描 regex 不夠寬）

Polish pass 不該做的事

• 不重寫章節結構：polish pass 是把現有內容修得更貼合規範、不是重新組織。重寫的觸發條件應該回到 stage 2、不是 polish pass。
• 不擴大 scope：原本 4.20 / 5.4 等不在擴充範圍的章節、polish pass 也不動。Polish pass 邊界 = stage 4 修改過的章節集合。
• 不追求 0 issue：reviewer 抓的 ~15 個 low 通常可保留為下次擴章節時自然處理。Polish pass 處理「系統性 pattern」、不處理「孤立 issue」。

Polish pass 的標準工序

按系統性 pattern 分批處理、每批跑一次自掃描確認：

1. 負向骨架掃描修正：用更寬泛的 regex 不是 |而不是|沒有.*[，、]會 掃描、把「不是 X、而是 Y」「而不是 X」改成正向陳述 + 後置邊界提醒。技術約束敘述（「多人共用 IP 無法區分」）保留。
2. 編號漂移統一：把 04.X 風格 plain text 改成 [4.X title](url) markdown link、跟 _index 對齊。
3. 表格延伸段補強（關鍵段）：選 2-3 個最高 impact 表格（判讀訊號表的爭議列、Buffer / Sampling 等選型表）補延伸子段、不全部補（避免擴展超出 scope）。
4. 模板化拆敘事（代表性段）：選 1-2 個最明顯的「四步驟模板套不同情境」段、拆成情境化敘事、其他保留為下次。
5. Cross-link 補漏 + ownership 邊界補強：reviewer C 報告的所有 cross-link 缺漏一次補完、用同一個批次跑 mdtools 驗證。
6. 用語不一統一 + 失效 link 修正：簡轉繁、/knowledge-cards/ vs /section/ URL 統一、失效 link 改規劃中或正確路徑。
7. 最終驗證 + commit：跑 mdtools fmt --fix && mdtools cards && mdtools lint、確認全綠、commit。

Polish pass 的實作成本

實作中（04 / 05 polish pass 合併 commit 1072087）：

• 處理範圍：11 個檔案、+44 / -29 行
• 修正項目：~35 個 issue（10 個負向骨架、2 個模板化、3 個編號漂移、3 個表格延伸段、3 個 cross-link、1 個 case 引用結構）
• 時間：~30-45 分鐘（不重寫、只 pattern match）
• 剩餘 ~15 個 low 保留下次

Polish pass 的 ROI 來自「系統性 pattern 一次處理 vs 散在各章一個個改」的效率差異。每個 pattern 在多章重複出現時、用 grep / rg 跨檔修一輪比每章單獨修快 3-5 倍。

自掃描盲點更新

04 流程暴露了一個 self-scan 盲點：原 regex 不行|不可以|不要|無法|不能 漏掉「核心責任不是 X、而是 Y」這個變體段首。修正建議：

• 加 ^[^|].*責任(不是|並非) 抓「核心責任不是 X」變體
• 加 ^[^|].*[，,]而是 抓「X、而是 Y」結構（已是正常陳述、但段首位置仍是負向骨架）
• 加 ^[^|].*[，,]不是 抓「X、不是 Y」結構

把自掃描 regex 視為持續演進的工具、每個 reviewer 抓出新 pattern 就更新一次、避免在下個模組重蹈覆轍。

適用情境跟限制

適用情境

• 長期累積的教學模組：6+ 章、跨章引用密集、規範遵循重要
• 有現成 case 庫：07/09 累積的 100+ 案例是這套流程的前提、沒案例庫做不到 case-first
• 品質高於速度：完整三階段約 3-4 小時 / 模組（stage 2 寫作 ~1.5-2hr + reviewer ~15 分鐘 + stage 3 修正 ~1.5-2hr）、適合長期累積的內容、不適合 one-off 文章
• 主 context 容量敏感：reviewer 平行 background 是節省 context 的關鍵設計

不適用情境

• 新主題沒案例庫：要先建案例庫、不能直接套這流程
• 單篇短文：流程的固定成本（讀案例 + 跑 reviewer）對短文 ROI 低
• 快速迭代原型：流程偏向 寫一次寫好、不是 快速修改
• Routing layer / 導讀性質章節：已含完整 threat scope + 引用標準 + 問題節點表、case 庫不對應或缺位、應跳過本流程、用標準引用 + 通用工程知識補充承接（07 LLM / 治理章節驗證）
• Standard framework 比 case 庫成熟的領域：見下段「Standard-driven 取代 case-driven」

Standard-driven 取代 case-driven（07 LLM 章節驗證）

在標準框架比 case 庫成熟的領域、case-driven 不是預設選擇。LLM 安全章節跑完 5 章驗證後浮現一個 finding：當該領域的 標準框架（如 OWASP LLM Top 10 2025 / NIST AI RMF 1.0 / MITRE ATLAS）已涵蓋 threat 分類、且 case 維護半衰期短於 standard、章節應 用 standard-driven 取代 case-driven。Standard-driven 跟 case-driven 是平行選項、依領域特性選用 — 兩者沒有退化 / 進階關係。

判斷該用哪種策略的四維度：

典型對照：

• Case-driven 領域：分散式系統 / 安全控制面 / 可靠性 / 訊息佇列（backend/01-07 batch 1 都屬此類、案例公開充分、半衰期 5+ 年）
• Standard-driven 領域：LLM 安全（OWASP LLM Top 10 / MITRE ATLAS 已成型、案例 6 個月過時）、新興 compliance（NIST AI RMF）、cloud-native 標準（CNCF baseline）

Standard-driven 章節的寫作策略：

1. 章節對齊 standard framework 分類：用 framework 章節 ID 標明（如 OWASP LLM01 / NIST AI-1.1）取代「對應 [case] —」斷言
2. 加 Last reviewed cadence：每 quarter 重評估 standard 版本跟章節對應、寫進 frontmatter
3. 「案例觸發參考」段標明「公開案例累積中、值得追蹤的方向」：不寫「對應 [case] 揭露」斷言、避免引用源不穩定
4. 引用標準時用版本號：OWASP LLM Top 10 2025 / NIST AI RMF 1.0 / MITRE ATLAS continuous — framework 改版要 trigger 章節重審

實證：07 LLM 章節 5 章已套用 standard-driven 策略：

• 章節 113-137 行、含完整 threat scope + 問題節點表 + 風險邊界
• 引用 OWASP LLM Top 10 + NIST AI RMF + MITRE ATLAS 取代個別 case 引用
• 加 Last reviewed: 2026-05-12 cadence
• 「案例觸發參考」段寫「公開案例累積中、值得追蹤的方向」+「事實查核註」
• 完全不寫「對應 [case] —」斷言、不存在 case fidelity reviewer 該抓的準確性問題

對照 backend/01-07 batch 1 的 case-driven 章節、LLM 章節是 用不同方法達到同樣品質 — scope 涵蓋真實 production 議題（KV cache 跨租戶、shared prefix optimization、batch 推論順序敏感）、不停在教科書級內容。

何時要從 standard-driven 轉回 case-driven：

• 該領域累積 5+ 個高可信度 case（vendor disclosure + academic paper + CVE 三來源交叉）
• 跨章 frame 重複出現、case-driven mechanism 深化能解 SSoT 衝突
• 出現「等級類似 SolarWinds」的 incident、案例本身夠重、單一 case 即可支撐章節擴章
• 讀者反饋章節太抽象、需要具體 case 才能理解 mechanism

不滿足任一條件時、繼續走 standard-driven、不勉強建 case 庫。

對 case-first-module-workflow skill 的補強：

skill 之前的「不適用情境」寫「沒 case 庫的新主題（要先建 case 庫）」— 這暗示缺 case 庫一定要先補。07 LLM 章節驗證了第三條路：用 standard-driven 取代、適用 standard framework 比 case 庫成熟的領域。這個 finding 已補進 skill 的「不適用情境」段。

限制

• Reviewer 維度有限：當前 3 個 reviewer 沒覆蓋「教學性」「讀者路徑」「實作可行性」、若主題需要這些維度、要加 reviewer
• 修正可能引入新 issue：第一輪 review 後修正、修正本身可能違反規範、若大量修正最好做第二輪
• Case 庫品質決定 findings 品質：case 寫得淺、findings 也淺；case fidelity reviewer 也只能驗證「跟 case 一致」、不能驗證「case 本身對不對」
• 依賴 LLM agent 平台能力：流程預設可平行跑 background agent、不是所有 LLM 平台都支援

7 個模組驗證後的反覆陷阱

01 / 02 / 03 / 04 / 05 / 06 / 07 七個模組執行下來、以下陷阱在 多數模組都重複出現、屬於 LLM case-driven 寫作的系統性失分點。本流程下次套用前要 主動防範、不能依賴 stage 3 reviewer 補救（雖然 reviewer 都會抓到、但修正成本高）。

陷阱 1：Skeleton case 擴寫成 case 事實

當 case 內容簡短（10-30 行、只有 frame 沒有具體數字 / taxonomy）、LLM 寫作時容易把通用知識（具體數字、攻擊向量列表、設計細節）寫成「對應 [case] —」斷言。實際 case 沒寫的。

實證：

• 01 紅隊：Snowflake「30-90 天 baseline」編造、Tixcraft「partition key 用 user_id」編造
• 02 cache：Tubi 三層 cache 具體 latency（L1 < 1ms、L2 < 10ms、L3 10-100ms）編造、Redis「100K-200K ops/sec」無來源、KeyDB「5-10x throughput」其實是 case 判讀段非引用源
• 03 messaging：PayPay「broker 寫入 3K msg/sec」實際 case 寫的是「DynamoDB 寫入 3K msg/sec」（PayPay 用 DynamoDB 不是傳統 broker）、3.C9 case 三個方向被擴寫成「4 個誤配場景」、3.C10 case 「大型服務 DLQ 是診斷入口」完全編造

防範：

• Stage 1 抽 findings 時 標明 case 類型（rich vs skeleton）
• Stage 2 寫 skeleton case finding 時、用「對應 [case] — 揭露 X 方向、以下展開基於通用工程知識補充」這種 fact vs derive 標記
• 不要為了「整齊的 4 個攻擊面」「3 個攻擊向量」「5 個誤配場景」這種數字感、把 case 沒寫的 taxonomy 寫成 case 揭露

陷阱 2：Frame 重複展開（SSoT 不清）

同一概念在多章 case-driven 擴章時各自展開、形成 frame 重複。讀者跨章讀會踩到重述、結論散落拼不出總圖。

實證：

• 01：容量三口徑 frame 在 1.1 跟 1.12 重複展開、storage / compute 分離 frame 在 1.1 跟 1.11 重複
• 02：cache 角色變化 frame 在 2.1 主寫但屬模組層級、應在 _index；Tubi 案例在 2.1 / 2.2 / 2.8 三章 mini-展開
• 03（最嚴重）：三層語意（delivery / processing / recovery）在 3.4 / 3.6 / 3.8 三章各自定義；Slack Kafka+Redis 拓樸在 3.4 跟 3.8 兩章逐字重複；規模對照在 3.4 / 3.6 / 3.8 三章拆用

防範：

• Stage 2 寫作前花 30 分鐘做 SSoT 對應（見前面「Stage 2 寫作前先定 SSoT 對應」段）
• 列出 cross-chapter frames、指定唯一主寫章節、其他章節只 link
• 寫每章前問「這個 frame 主寫在哪？我現在寫的是主寫還是 link？」

陷阱 3：負向陳述 + 模板化（規範系統性失分）

「不是 X、是 Y」推進論證、L1/L2/L3 三層平鋪、三選一表格、四步驟流程。這兩個原則違反在每模組都重複出現、是 LLM 寫作的反覆模式、stage 3 standards reviewer 每模組會抓 10-20 處。

實證：

• 01 規範 violation：表格不延伸（7 處）、負向陳述（5 處）、首句結構（4 處）
• 02 規範 violation：原則 8 模板化（6 處）、原則 2 負向陳述（6 處）、原則 4 表格不延伸（4 處）
• 03 規範 violation：原則 2 負向陳述（12 處最嚴重）、原則 1 首句結構（5 處）、原則 6 用語節制（2 處）
• 04 規範 violation：原則 2 負向陳述（12 處最嚴重、含「核心責任不是 X、而是 Y」變體段首）、原則 1 首句結構（9 處）、原則 4 表格不延伸（9 處）
• 05 規範 violation：原則 2「不是 X、而是 Y」+「沒有 X、會 Y」（10 處）、原則 8 四步驟 / 四層並列模板（7 處）、原則 3 case 引用框架取代商業邏輯先行（6 處）

防範：

• Stage 2 寫完後 寫稿端就跑掃描、不等 reviewer：
  • rg -n "不行|不可以|不要|無法|不能" <module-path> 找負向骨架（技術約束敘述例外）
  • rg -n "^[^|].*責任(不是|並非)" <module-path> 找「核心責任不是 X」變體段首（04 模組新發現的 pattern）
  • rg -n "^[^|].*[，,]而是|^[^|].*[，,]不是" <module-path> 找對比骨架開段
  • 自查表格：每個 bullet 是否有後文延伸？
  • 自查首句：是否「核心原則先行」而非「對應 [case] 揭露」
• 模板化（L1/L2/L3、三選一）出現時、先問「這三項是真的對等？還是業務情境不同？」— 不同情境的話拆敘事段、不用表格

陷阱 4：Rich case 判讀層被當 case fact 引用（04/05 模組新發現）

引用 09 / 07 等 rich case 時、case 內常含「觀察層」（具體 fact）跟「判讀層」（作者推論）兩段。LLM 寫作時容易把兩層壓縮成「揭露 X」、把作者判讀升級為 case fact。

跟陷阱 1（skeleton case 擴寫成 case 事實）的差別：

• 陷阱 1：case 沒提的細節（具體數字、taxonomy）被寫成 case 揭露
• 陷阱 4：case 有提、但屬作者判讀層的內容被寫成 case fact

實證：

• 05 / 9.C12 Riot：5.2 寫「揭露 35ms latency 反推 region 部署」、實際 case 的「35ms」是觀察層、「反推 region 部署」是作者判讀層
• 05 / 9.C34 GCP：5.2 寫「揭露 Spanner 替 etcd 才是 K8s 規模極限的關鍵」、實際 case 用更保守的「control plane 極限取決於 storage backend、GCP 用 Spanner 替換 etcd」分兩個點寫、章節壓縮 + 強化成硬性結論
• 05 / 9.C12 Riot：漏掉 case 揭露的關鍵歷史轉折「從 multi-tenant cluster 模型改成 single-tenant per game」

防範：

• 引用 rich case 前、先把 case 內的「觀察段」跟「判讀段」分開讀、抽 finding 時各自標明來源層
• 引用時用「揭露 X 觀察 + 作者判讀 Y」分層寫、或在引用後補一句「（case 中 X 屬作者判讀層、本章引用此推論）」
• 避免使用「才是 / 必須 / 一定」這類強化詞、保留 case 原文的條件性表述
• Stage 3 case fidelity reviewer 的 prompt 要特別點出「判讀層 vs 觀察層」的分界、把這當作 high 級 issue 抓取

陷阱 5：自掃描盲點累積（04/05/06 模組持續顯現）

自掃描的 regex 跟 reviewer 抓的 pattern 會逐漸脫節。每個模組 reviewer 會發現新 pattern、self-scan regex 跟著演進、但 reviewer 仍會發現下一個。

實證：

• 04 自掃描用 不行|不可以|不要|無法|不能 跟「不是 X、是 Y」掃描通過、但 reviewer A 抓出「核心責任不是 X、而是 Y」變體段首（佔 12 處）
• 05 自掃描通過、但 reviewer A 仍抓出「沒有 X、會 Y」鏈式負向句構 + 「四步驟模板」+ 「case 引用框架取代商業邏輯先行」三類新 pattern
• 06 self-scan 加了「不是 X、而是 Y」變體 + 「沒有 X 會 Y」、仍漏掉「對應 [case]：揭露 N 個機制」段首取代核心概念句的 pattern（reviewer A 抓 45 issue、其中 11/12 新段都犯這個錯）

防範：

• 每個模組 reviewer 抓出新 pattern 後、回頭更新 self-scan regex
• 把 self-scan 視為持續演進的工具、不是固定 checklist
• Stage 5 polish pass 是處理自掃描盲點累積的標準入口（見前段）
• 06 模組後 self-scan 加 rg -n "^對應 \[" <module-paths> 抓段首 case 引用框架

陷阱 6：Case 引用段首取代核心概念句（06 模組新發現）

LLM 從 case 反推內容時、容易把 case 揭露當概念出發點、寫成「對應 [case]：揭露 N 個機制 — …」段首結構。讀者尚未理解概念就被丟入案例細節、且跨章讀同句構會感同質。

實證：

• 06 模組 12 個新段中 11 個用「對應 [case]：揭露 N 個機制」相同句構作為 section 第二段
• 概念定義句被推到第二段或更後、商業邏輯先於 case 的原則被推翻

防範：

• 把 case 引用視為「三段式」結構：概念定義句 → case 引用 → 通用展開
• 寫每段時、先確認段首是「該概念是什麼、承擔什麼責任」、case 引用退到第二位置
• Case 引用句構應變化：寫多章時刻意避免同句構連續超過 3 次
• 詳見 skill 內部原則卡 principles/case-citation-three-part（對應檔案 .claude/skills/case-first-module-workflow/references/principles/case-citation-three-part.md、屬 skill 內部 reference、不對外暴露）

陷阱 7：Medium case 實作層擴寫過頭（06 模組新發現）

Medium case（30-50 行、結構化但無具體數字）首次套用時、容易把 case 沒提的具體實作層擴寫進章節、把通用工程知識掛到 case 名下。

實證：

• 06 模組 6.12 idempotency-replay 從 S1「key 設計要跟業務邊界一致」一條方向擴寫成「key 來源 / TTL / fallback / 偽造防護 / 5 個 observability 欄位」5 條實作判讀、case 沒提這些細節
• 06 模組 6.14 dependency-reliability-budget 從 M1 region failover 擴寫成「thundering herd」機制名 + 「先恢復核心 region 最小集合」具體步驟、case 沒提這兩個

防範：

• Medium case 引用用 mechanism 名稱 精準引用、不擴寫到 case 沒提的具體實作細節
• 引用後若要展開實作層、用「以下實作層判讀屬通用工程知識展開、case 本身只給 X 方向」明示分層
• Case fidelity reviewer 的 prompt 要特別點出 medium case 的「實作層擴寫」失分類型

陷阱 8：跨 case 合成 frame 升級成 case 揭露（07 模組新發現）

當段落把多個 case 的失效訊號抽象為更高層 frame（如「跨工具回查壓力」「平台責任切分」）、LLM 會把章節合成的 frame 包裝成 case 揭露。讀者回查 case 時會發現章節說的「case 揭露 X」實際是章節 derive、不是 case 原文框架。

跟陷阱 1（skeleton case 擴寫成 case 事實）跟陷阱 4（rich case 判讀層當 fact）的差別：

• 陷阱 1：case 沒提的細節（具體數字、taxonomy）被寫成 case 揭露
• 陷阱 4：case 有提、但屬作者判讀層的內容被寫成 case fact
• 陷阱 8：case 單獨 寫的訊號被章節 跨 case 合成 抽象為更高層 frame、frame 本身不在任一 case 原文

實證（07 batch 1 reviewer B 抓的 2 個 high issue）：

• 7.7 跨工具回查壓力：Uber 失效控制面寫「告警串接不足」、Slack 寫「訊號未匯流」— 都是單工具內訊號、章節合成「跨工具回查」axis
• 7.7 平台責任切分：SolarWinds 失效控制面寫「更新來源信任過於單點」「行為監測難以區分合法元件」— 都是供應鏈信任議題、章節合成「平台 vs 產品 audit 責任分離」frame

防範：

• 段落把多 case 抽象為更高層 frame 時、要 explicit 標明「frame 是本章合成、case 原文沒有此 frame」
• 修法範例：「兩個案例分別在 X 層揭露同類失效訊號 — A case 標明 B、C case 標明 D。本章把兩者抽象為『XXX』是 YYY 視角的合成 frame、非 case 原文框架。」
• Stage 3 reviewer B prompt 要明示「跨 case 合成 frame 必須標為本章合成」是 high 級 issue 抓取項

陷阱 9：Case 引用句構同質化（07 模組新發現）

即使遵守 case 引用三段式紀律、跨章節 case 引用仍會出現句構同質化。13 處 case 引用 11 處用同一句構「揭露 N 層失效控制面 — A、B、C。案例『可落地檢查點』標明 mechanism 為 X、前提是 Y」。讀者跨章連讀時、會把 case 引用當儀式而非論證。

實證：07 batch 1 reviewer A 抓出 systemic medium issue (Issue 8.1)、13 段 case 引用 11 段用相同句構。Stage 5 polish pass 主動分流 4 處後狀況改善。

防範：

• 句構選擇要 跟著 case 類型走、不是隨機變化（case 直接列 N mechanism → 「揭露 N 層」；case 揭露單一壓力 → 「補的失效訊號是 X」；case 揭露對比 → 「揭露兩個層次的對照」）
• Stage 5 polish pass 加句構分流為標準工序之一（跟負向骨架同層級）
• 自掃描 regex ^對應 \[ 抓不到此類問題（這是符合三段式的引用、只是句構單一）、要靠 stage 5 主動 scan：rg -c "揭露[^。]*失效控制面" <module-paths> 看同句構出現次數、超過 5 處要分流

「章節已有 routing skeleton」的特殊處理（07 模組新發現）

07 模組跟 06 / 09 不同之處：章節在 stage 2 前已有完整 routing layer 結構（threat scope / 從本章到實作 / 問題節點表 / 風險邊界 / 案例觸發 / 路由）— stage 2 是在現有結構內補 case-driven 深化段，而非空白擴章。

這個情境下：

• SSoT 衝突更容易發生：新段落要跟既有章節結構協調、不只是新增內容。07 batch 1 三個 H issue（C-H1/H2/H3）都是 frame 跟既有章節 / 其他章節新增段衝突
• 章節寫作邊界要先確認：補強段聚焦在「現有問題節點表的 mechanism 深化」、不擴成厚重 case-driven 章節（避免章節結構失衡）
• Cross-link 密度顯著上升：補強段要明示「本節聚焦 X 視角、canonical 在 Y 章」、否則 reviewer C 會抓 frame 重複展開

判讀條件：

• 章節已有 threat scope / 問題節點表 / 案例觸發段 → 走「補強段」策略、不空白擴章
• 章節是 routing layer / 導讀性質、不適合 case-driven 深化 → 跳過本流程
• 章節有 case 庫但 case 主要是 skeleton 型（30 行 frame） → 補強段嚴守「揭露 X 方向、通用補充」紀律、不擴寫實作層

衍生 insight：reviewer 維度沒覆蓋的部分

3 個模組跑下來、發現現有 3 reviewer 維度（規範 / 案例準確性 / 跨章一致性）有未覆蓋的問題：

• 教學性 / 讀者路徑：章節之間的閱讀順序是否合理？讀者讀完 A 章能不能銜接 B 章？目前沒 reviewer 檢查
• 判讀條件可操作性：寫了判讀訊號、但實際工程師能不能用這些訊號做決策？沒 reviewer 驗證
• 實作可行性：建議的設計是否真的能落地？跨團隊協調是否現實？需要懂業務的 reviewer

未來 6 / 7 / 8 模組執行時、可以考慮加第 4 個 reviewer 維度（教學性 + 實作可行性）。

跟其他寫作流程的差異

跟「LLM 自生 + 人工 review」比、本流程的差異：

跟「LLM 自生 + 自我 review」比：

• 自我 review 抓不到自生內容的盲點（self-blindness）
• Agent team 是 不同 instance、不共享 context、能扮演獨立 reviewer

下一步

本流程在 backend/01 至 backend/07 batch 1 七個模組驗證後（共 ~45 章 / 385 review issue / case fidelity 70-93% 區間）、方法論已工具化為 case-first-module-workflow skill（內部檔 .claude/skills/case-first-module-workflow/、含 stage 1-5 流程、reviewer prompt template、self-scan regex 跟 5 個原則卡）、後續套用到：

• backend/07 batch 2 LLM 安全：case 庫缺位（OWASP LLM Top 10 + agent injection 公開事件未累積成模組 case）、要先建 LLM case 庫再走 case-first
• backend/07 batch 3 治理章節：routing 層 / 導讀性質、case-driven 深化適用度低、做標準 polish pass 即可
• backend/08 incident response：跟 04 / 06 / 07 cross-link 密度最高、SSoT 對應規劃壓力最大
• 其他模組依此類推

06 模組是首次套用工具化 skill 的模組、驗證 skill 對 stage 1-2 加速有效、但 reviewer A 仍抓出 45 issue（高於 05 之前 baseline 20-30、推動 v1.2 把 standards reviewer baseline 擴大到 20-45）— 揭露 skill 改進方向（self-scan regex 需要持續演進、case 引用段首結構是 LLM 系統性傾向）。

07 batch 1 驗證下「章節已有 routing skeleton」情境的處理策略：補強段不擴成厚重 case-driven 章節、聚焦 mechanism 深化 + cross-link 對齊。揭露兩個新陷阱（跨 case 合成 frame 升級成 case 揭露、case 引用句構同質化）、補進 skill 跟方法論。

流程本身會在每個模組後 retrospective、看 reviewer 維度是否該調整、findings 抽取方法是否該強化、polish pass 處理 pattern 是否該擴充。目前已知改進方向：

• 加 reviewer：教學性審查（讀者路徑是否清楚、判讀順序是否合理）
• 強化 findings 抽取：標註 finding 的 泛化程度、避免把 case-specific 細節推為通用結論
• Rich / Medium case 引用紀律：把「fact vs derive」分層 + 「mechanism 名稱精準引用」寫進 stage 1 抽 findings 模板、stage 3 case fidelity reviewer prompt 也明示此分界
• 自掃描 regex 持續演進：每個模組 reviewer 抓出新 pattern 後、回頭加進 self-scan 工具、避免在下個模組重蹈覆轍。06 模組後加 ^對應 \[ 抓段首 case 引用框架。07 模組後標明 ^對應 \[ 在三段分離結構下會 false positive、要靠 awk 看 prev line context
• Case 引用三段式：把「概念定義 → case 引用 → 通用展開」當段落結構紀律、避免段首被 case 引用取代（06 模組最大宗 systemic 違規）
• Case 引用句構分流：07 模組後 stage 5 polish pass 加句構分流為標準工序、避免跨章 13+ 段同句構讀感儀式化
• 跨 case 合成 frame 紀律：07 模組後 reviewer B prompt 明示「跨 case 合成 frame 必須標為本章合成」是 high 級 issue
• 加修正後自動 lint：修完不只跑 mdtools、加跑「找首句否定句」「找表格沒延伸」「找模板化並列點」「找段首 case 引用」的自動掃描

跟其他寫作協議的整合：本流程跟 compositional-writing skill 互補（後者管 單篇 寫作的原子化跟意圖、本流程管 跨章模組 的 scope 跟一致性）、跟 requirement-protocol skill 互補（後者管 對話協議、本流程管 內容生產）。

Statusline 相容設計的核心責任是把「資料輸入契約」和「畫面渲染邏輯」分開。Claude Code 已經提供 command-backed statusline，會把 session JSON 丟進命令的 stdin；Codex 目前公開的設定則是 tui.status_line 字串項目陣列，契約停在內建 footer item 的排列與選擇。

這個差異讓「同一個 statusline 工具同時支援兩邊」要從輸入契約對齊開始。真正要做的是先建立一層輸入正規化：Claude JSON、Codex 既有或未來 JSON、手動測試 JSON 都先轉成同一個內部狀態，再交給同一套 renderer。

Case-first 觀察

Case-first 查詢的目的，是先看社群實際卡在哪裡，再決定要改工具還是改使用方式。本次查詢到的案例集中在 OpenAI Codex repo issue 與官方文件，顯示需求已經存在，但 Codex 的 command-backed statusline 仍屬提案或缺口。

WRAP 判讀

Anchor Check：目標是讓 cc-statusline 的核心能力可被兩種工具共用。使用者真正需要的是少維護一套 statusline 邏輯，並在 Codex 具備 command-backed 入口時保留既有 renderer。

Step 0 資料充足度：足以做工具內部改造，尚不足以宣稱 Codex TUI 目前能直接執行 cc-statusline。官方文件只保證 tui.status_line 是字串陣列；社群 issue 裡的 command JSON 仍是提案階段。

Widen Options：可選方案有三種。

Reality Test：目前 Codex 的公開設定停在內建 item 排列，所以 B 的立即價值是讓工具「具備 Codex 相容輸入能力」。反向驗證是：若未來 Codex 最終採用完全不同的 command JSON，B 的 normalization 層仍只需新增一個 mapper，renderer 可維持同一套。

Attain Distance：B 的長期成本最低，因為 statusline 最容易變動的是輸入欄位名稱，最穩定的是使用者想看的資訊：專案、環境、輸入法、模型、context、rate limit、git worktree。把欄位差異收斂在 normalization 層，能避免每加入一個工具就複製一次畫面邏輯。

Prepare to be Wrong：若 Codex 不採納外部 command statusline，這次改造仍可用於手動測試、tmux status、其他 wrapper，且不影響 Claude Code 原始入口。若 Codex 採納但欄位名稱不同，新增 mapper 即可。

Tripwire：當 OpenAI Codex 文件把 tui.status_line 從 array<string> 擴充為 command 或 table schema 時，重新檢查 cc-statusline 的 Codex mapper。若 Codex issue #17827 關閉並附帶實作 PR，也應重新校準欄位名稱。

實作策略

相容設計的正確切點是輸入正規化層。cc-statusline 應維持一個內部狀態模型，並接受多種外部 payload：

這個切點保留了 Claude Code 既有功能，因為原本的欄位不需要改名，也不需要改設定檔。新增行為只在非 Claude payload 進來時啟動，屬於向後相容的讀取能力。

操作路由

現在可立即使用的路由是 Claude Code 原設定：在 ~/.claude/settings.json 裡設定 statusLine.command 指向 cc-statusline。這條路由使用官方支援的 stdin JSON，適合日常使用。

Codex 目前可立即使用的路由是內建 footer item：在 ~/.codex/config.toml 設定 tui.status_line = [...]。這條路由使用 Codex 內建 renderer，能顯示 Codex 已支援的內建狀態。

未來 Codex 若支援 command-backed statusline，路由應該指向同一個 cc-statusline binary。工具端已經能接受 Codex / generic JSON 時，設定層只要補 command 指向，不需要重寫 renderer。

實測記錄（2026-05-14）

這次排查的核心責任是先確認「工具本身可用」還是「接入路由不對」。先把 binary 行為跟 TUI 設定拆開檢查，才能避免把路由問題誤判成程式 bug。

觀察

• cc-statusline 程式已支援 generic/Codex-style payload，手動餵 JSON 可正確輸出模型與 context 資訊。
• ~/.claude/settings.json 使用 statusLine.command 指向 /Users/mac-eric/go/bin/cc-statusline，Claude Code 路由成立。
• ~/.codex/config.toml 的 tui.status_line 是內建 item 陣列，這條路由不會執行外部 binary。
• Codex 內建 footer 的實際輸出已觀察到：gpt-5.3-codex medium · Context 100% left · ~/project/blog。

判讀

Codex 端「沒有生效」的主因是契約邊界：tui.status_line 只負責排列內建欄位，不負責執行 command。cc-statusline 的 renderer 相容能力屬於預留未來入口，不會在現有 Codex 內建 footer 流程自動觸發。

操作

為了讓 Codex 內建 footer 至少顯示模型與 context 資訊，已調整：

1[tui]
2status_line = ["model-with-reasoning", "context-remaining", "current-dir"]
3status_line_use_colors = true

這個設定可讓 Codex 使用內建項目顯示 model-with-reasoning 與 context remaining；格式由 Codex 內建 renderer 決定，不等同 cc-statusline 的自訂輸出字串。

驗證指令

1printf '%s\n' '{"model":"gpt-5.3-codex","reasoning_effort":"medium","project_root":"~/project/blog","context":{"remaining_percent":100}}' | /Users/mac-eric/go/bin/cc-statusline

預期結果是主行包含 gpt-5.3-codex medium，context 顯示為 Context 100% left。這一步驗證的是 binary 能力，不是 Codex 內建 footer contract。

檢查清單

• Claude Code 原本的 JSON payload 仍能輸出相同欄位。
• Codex / generic payload 不造成 parse error。
• model 同時支援 object 與 string。
• context 同時支援 used percentage 與 remaining percentage。
• rate limit 缺席時只省略對應 segment，不影響專案、模型、git worktree。
• README 明確標示 Codex 目前限制，避免讀者以為 Codex 已能直接執行外部 statusline command。

Claude Code GitHub Actions 讓 Claude 直接參與你的 GitHub 工作流程，主要功能：

• 互動式助手 — 在 PR/Issue 留言 @claude，Claude 會分析程式碼並回覆
• 自動 Code Review — PR 開啟時自動審查變更
• CI 除錯修復 — build 失敗時自動分析錯誤並修復

完整功能說明參考 官方文件。

設定方式

/install-github-app（推薦）

在 Claude Code 終端執行 /install-github-app，它會引導你完成所有設定。

流程中的關鍵步驟：

1. 選擇 repo — 指定要安裝的 GitHub repository
2. 安裝 Claude GitHub App — 自動安裝到指定 repo，授予 Contents、Issues、Pull requests 的 Read & Write 權限
3. 選擇認證方式 — 選擇 long-life token 會產生 OAuth token，自動寫入 GitHub Secrets 為 CLAUDE_CODE_OAUTH_TOKEN
4. 建立 workflow 檔案 — 自動建立並 push 兩個 workflow：
   • claude.yml — @claude 互動回覆
   • claude-code-review.yml — PR 自動 code review

完成後不需要額外設定。

手動設定（使用 Anthropic API Key）

如果不想用 /install-github-app，可以手動操作：

1. 前往 github.com/apps/claude 安裝 App 到你的 repo
2. 到 repo 的 Settings → Secrets and variables → Actions，新增 ANTHROPIC_API_KEY
3. 手動建立 workflow 檔案到 .github/workflows/

兩種認證方式的差異：

加入 CI 自動除錯

/install-github-app 建立的 workflow 只處理 @claude 互動和 code review。如果你想在 build 失敗時自動觸發 Claude 修復，需要修改既有的 deploy workflow。

首先，補上 Claude 需要的權限（原本可能只有 contents: read）：

1permissions:
2  contents: write        # Claude 需要寫入修復後的檔案
3  pull-requests: write   # Claude 可能需要建立 PR
4  issues: write          # Claude 回報結果
5  pages: write           # 原本的 deploy 權限
6  id-token: write        # 原本的 deploy 權限

然後在 build 步驟加入 Claude 除錯邏輯：

 1# 在原本的 build step 加上 continue-on-error 和 id
 2- name: Build
 3  id: hugo-build
 4  run: hugo --minify 2>&1 | tee hugo-build-output.txt
 5  continue-on-error: true
 6
 7# Build 失敗時觸發 Claude 除錯
 8- name: Claude Debug on Build Failure
 9  if: steps.hugo-build.outcome == 'failure'
10  uses: anthropics/claude-code-action@v1
11  with:
12    # 依你的認證方式擇一
13    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
14    # anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
15    prompt: |
16      Hugo build failed. Here is the error output:
17
18      $(cat hugo-build-output.txt)
19
20      Please analyze the error, find the problematic file(s),
21      fix the YAML front matter or content issue, and commit the fix.
22    claude_args: "--max-turns 10"
23
24# 修復後重新 build 驗證
25- name: Retry build after fix
26  if: steps.hugo-build.outcome == 'failure'
27  run: hugo --minify

核心設計：

1. continue-on-error: true — build 失敗不中斷流程，讓後續 Claude 步驟有機會執行
2. if: steps.hugo-build.outcome == 'failure' — 只在失敗時觸發，正常 build 不消耗 API 額度
3. 修復後重新 hugo --minify 驗證是否成功

計費方式

計費取決於你使用哪種認證方式：

OAuth token 的額度是共用的，GitHub Actions 跑多了會擠壓你日常在 claude.ai 和 CLI 的使用額度。如果 CI 觸發頻繁，建議改用 API Key 避免互相影響。

詳細的費率可參考 Claude 定價頁面。

降低成本的設定

搭配 CLAUDE.md

在 repo 根目錄建立 CLAUDE.md，Claude 會自動讀取作為上下文，提升修復準確度。

參考資料

• Claude Code GitHub Actions 官方文件
• claude-code-action GitHub Repo
• Setup Guide

社群裡有人分享了幾篇關於 Claude Code Hook 的文章，看完第一個反應是：「我低估了 hook 能做的事情。」

我知道 hook 的存在，但一直把它當成「跑幾個簡單檢查」的輔助工具。那幾篇文章讓我意識到，hook 可以是完整的品質控制基礎設施——在每個關鍵時機介入，執行那些「應該要做但忘記做」的檢查。

Hook 的執行時機

Claude Code Hook 有五個觸發點：SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop，涵蓋整個開發互動的生命週期。

有了這個框架，問題就變成：哪些規範應該在哪個時機點執行？

我們建立了哪些 Hook

Session 啟動檢查

每次 session 開始時自動確認：git 遠端是否有需要同步的變更、開發環境依賴是否完整、工作日誌狀態。這些檢查不阻止啟動，只是讓開發者一開始就有完整的情境。

任務逃避偵測

這是我們設計中比較有趣的一個 hook。它在每次 prompt 提交時執行，掃描內容裡是否出現「太複雜先跳過」、「暫時不處理」這類詞彙，同時也會檢查行為模式：程式碼變更了但測試沒有對應變更、技術債務累積超過閾值等。一旦偵測到逃避行為，會建立一個 block 標記檔案，後續所有工具呼叫都會被阻止，直到問題被正視。

程式異味即時偵測

每次檔案編輯後（PostToolUse），我們會即時掃描變更的程式碼。函數超過 30 行、巢狀超過 4 層、參數超過 5 個、依賴數超過 10 個，這些都會觸發記錄並建議重構。這個 hook 採用非阻塞設計——發現問題時記錄，但不中斷開發流程。

版本推進建議

在 Claude 完成回應時（Stop），hook 會分析當前的工作狀態：有沒有未提交的變更、工作日誌有沒有標記完成、TodoList 系列是否達成。根據這些狀態，自動建議接下來應該做小版本推進還是繼續開發。

文件同步提醒

程式碼變更後，hook 根據檔案類型判斷哪些文件需要同步更新。API 異動對應 API 文件，架構異動對應架構文件，這類規則很難靠人記，但 hook 記得。

一個反覆遇到的事故

hook 開發過程中出過同一個事故不只一次。

Claude Code hook 系統的設計是：任何寫入 stderr 的輸出都會被視為 hook error 顯示給使用者。Python 的 logging 模組預設輸出到 stderr，所以即使 hook 正常執行，只要有 logging 輸出，UI 上就會冒出 hook error 警告。

這個問題反覆出現，最後系統性地修復，確立了一條規則：hook 禁止寫入 stderr，所有輸出必須走 stdout。現在這條規則寫進方法論，新 hook 都有對應的驗證：

1grep -r "sys\.stderr" .claude/hooks/ --include="*.py"

這個指令應該永遠返回空結果。

模組化的演進

剛開始每個 hook 腳本都是獨立的，讀取輸入、處理邏輯、輸出結果各自實作。問題很明顯：讀取 hook 輸入、輸出決策結果這些通用邏輯，在每個腳本裡都重複了一遍。

後來重構引入了共用模組。.claude/lib/ 底下現在有幾個核心模組：hook_io.py 負責標準化 I/O，hook_logging.py 負責日誌，config_loader.py 載入配置，git_utils.py 封裝 git 操作。

帶來兩個好處：腳本結構變得簡潔，開發者只需要專注判斷邏輯；共用模組可以寫獨立的單元測試，以前 hook 的正確性很難驗證，現在有了。

幾個設計原則

非阻塞優先。大部分品質檢查不該阻止開發流程，而是記錄、追蹤、提示。只有真正關鍵的違規——任務逃避、阻止狀態——才完全阻斷操作。

漸進式強制。從警告到記錄到追蹤到阻止，給開發者理解和修正的機會，不是一刀切拒絕。

可觀測性。hook 系統自己也需要被監控。有一個 performance monitor hook 專門追蹤其他 hook 的執行時間，超過 5 秒視為需要立即優化。

配置外部化。品質規則的閾值、代理人分派規則，全部放在 YAML 配置檔，不硬編碼在腳本裡。需要調整只改配置。

現在的感受

把規範寫進文件和寫進 hook，是完全不同的感受。

寫進文件的規範靠人記。寫進 hook 的規範，在每個關鍵時機自動執行，開發者甚至可以不知道它存在——但規範確實在發生效用。品質基線從依賴個人紀律，變成由系統保證。