內容大致分六類：

自察與認知方法論 — 工作前 / 工作中的自我檢視框架。例：

• 5W1H 自察方法論
• AI 任務迴避偵測方法論
• 大規模重構方法論

設計判斷與選型 — 技術決策框架，避免過度設計與設計瑕疵的判斷標準（如 YAGNI 的真實適用條件、成本不對稱性下的選擇邏輯）。例：

• YAGNI 的真實適用條件
• SaaS 選型訪談方法論

敏捷 / 工程流程 — 敏捷實作、重構流程、文件分層。例：

• 敏捷編程方法論
• 敏捷重構方法論
• 5 層文件系統

寫作 / 溝通標準 — 驗收條件、寫作規範。例：

• 驗收條件方法論
• 經驗分享文章的寫作準則

文件與 API 設計 — function 文件分層、測試命名作為 spec、commit message vs source code doc 的職責邊界、型別取代 doc 等表達設計議題。例：

• 函式文件分層設計
• 型別取代 doc 的收益曲線
• 測試命名作為文件
• Commit message vs source code doc

AI 協作工具評估 — Claude Code / Codex / MCP server 等 AI 協作工具的設計拆解、能力邊界、選型對照。包含個別工具的 deep-dive 跟「同題不同工具」的實測。例：

• 三 MCP 工作流與 Dart 實測：cbm / codegraph / serena 的職責分工與三刀流（附三個工具各自的 deep-dive：cbm / codegraph / serena）
• LSP-first 開發方法論：LSP 路線跟其他 code intelligence 路線的取捨
• Background agent 並行研究：用 Claude Code background agent 平行做研究的工作流

跟其他資料夾的邊界

跟 report/ 的區別：record 是「方法論本身怎麼用」（教學 / 中性說明）、report 是「從某個 case 抽出來的原則」（事後檢討 / case-driven）。同一個議題若先有方法論再有 case、方法論寫 record、case 抽出的原則寫 report；若是先出問題再抽原則、直接寫 report。

底下自動列出本資料夾的所有文章、依日期排序。

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 結果做差異對比、是現階段最低成本的工具評估法。

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。

文章模板的責任是穩定作者流程，正文的責任是承載技術文章本身。讀者進入文章時，需要看到概念、判讀、取捨與路由；作者在寫作時，需要一組欄位檢查文章是否具備可維護的最低結構。

本 blog 同時由人類作者、Claude Code 與 Codex 協作產生內容。模板若只放在單一 agent 的設定裡，就會形成工具分岔；模板若直接放進 backend 正文，又會把作者工作流暴露成讀者負擔。因此模板的單一真實來源放在 content/posts/，作為本 blog 專屬的寫作設定記錄。

放置決策

模板放置位置的核心判準是讀者與維護者是否一致。backend 文章面向技術讀者，report 面向可重用事後檢討，posts 面向 blog 自身的規範、設計與工具鏈紀錄。

這個分工讓模板同時支援 Claude Code 與 Codex，也保留文章對讀者的自然技術敘事。

模板責任

模板是品質閘門，責任是讓文章保留關鍵判準。它要檢查文章是否具備責任、判讀、風險、邊界與下一步路由，正文仍用技術文章的推導順序排列。

模板欄位可以出現在文章大綱、作者檢查清單或 agent brief 裡。正文要以技術文章方式展開，讓讀者看到推導，作者填表痕跡留在工作流內部。

Backend 技術文章最小模板

Backend 技術文章的最小模板是「概念定位 → 核心判讀 → 判讀訊號 → 風險與邊界 → 交接路由」。這組欄位適合 04 / 06 / 08 這類語言無關的後端能力文章。

 1## 概念定位
 2
 3{概念} 是 {能力 / 流程 / 控制面}，責任是 {它在系統中承擔什麼問題}。
 4
 5這一頁處理的是 {抽象層級}。它跟 {相鄰章節} 的分工是 {邊界}。
 6
 7## 核心判讀
 8
 9判讀 {概念} 時，先看 {第一判準}，再看 {第二判準}。
10
11重點訊號包括：
12
13- {訊號 1}
14- {訊號 2}
15- {訊號 3}
16
17| 判讀面向 | 最小可用判準 | 常見失真 |
18| --- | --- | --- |
19| {面向} | {判準} | {失真} |
20
21## 判讀訊號
22
23- {真實服務中會看到的徵兆}
24- {工程團隊會踩到的操作問題}
25- {事故或演練會暴露的缺口}
26
27## 交接路由
28
29- {上游章節}：{承接內容}
30- {下游章節}：{下一步處理}

這份模板只定義文章最低結構。若某篇文章需要完整案例、方案比較或實作步驟，正文可以增加章節；增加章節時仍要保留責任、判讀、風險與路由。

案例前置欄位

案例前置欄位的責任是讓服務案例能回寫到文章系統。它屬於作者拆案例時的內部欄位，正文只吸收欄位背後的判讀與取捨。

04 / 06 / 08 的案例拆解可共用這組欄位，但正文仍要用技術文章敘事。欄位幫作者維持可比性，文章幫讀者理解機制。

Agent 共用方式

Claude Code 與 Codex 共用模板時，本文是 blog 內的穩定契約。.claude/ 與 .codex/ 可以引用本文的欄位與判準，但實際模板語意以本文為準。

這個安排避免 .claude/ 與 .codex/ 各自演化成不同模板，也避免把 agent 操作細節寫進 backend 讀者正文。

使用邊界

模板適合用在多篇系列文章、跨模組路由與案例回寫。單篇短文、事故紀錄或工具使用筆記可以採較輕的結構，只要仍能說清楚核心責任與下一步。

模板開始主導正文時，需要降級成作者檢查清單。文章完成後的檢查重點是讀者能否理解技術推導，並確認欄位已在文章背後支撐判讀。

完稿檢查

完稿檢查的責任是確認技術文章維持主線。檢查時先看正文是否能獨立閱讀，再看欄位是否完整支撐交接。

• 首段是否先說概念責任
• 判讀訊號是否來自真實服務情境
• 表格項目是否有延伸說明
• 交接路由是否指向具體章節
• 案例欄位是否能回寫到 04 / 06 / 08
• 正文是否保留技術推導，並把欄位轉成讀者可理解的判讀

隨著 blog 文章與知識卡片成長，純靠寫作紀律維持排版一致性越來越不可靠。反覆踩到的問題橫跨兩個層級：

結構與安全層級（這是工具鏈存在的主要理由）：

• 裸 URL 在段落與表格中爆版（MD034），降低閱讀體驗。
• 表格管線風格混用（MD060），同一張表格有的有空白、有的沒有。
• 平行模板章節重複標題（MD024），例如多案例文章的 ### 弱點環節 出現 13 次。
• 顯示文字與實際 href 不一致（反釣魚）— 不在標準 markdownlint 規則內，但紅隊教材脈絡下必要。
• 卡片雙向完整性（orphan 卡片、斷連結、K4 合規）— 跨文件檢查，現成工具做不到。
• Front matter schema — Hugo 依賴 YAML front matter 提供 title / date / weight 等欄位，缺失會破壞列表渲染、排序、SEO。

基礎格式層級（容易被忽略但影響 parser 穩定性或語義結構）：

• 正文禁止使用 H1（嚴於 MD025）— Hugo front matter title 已產生 H1。
• 標題前後需保留空行（MD022），parser 才能正確識別標題邊界。
• 標題結尾禁止標點（MD026）— 例如 ## 常見問題： 應改為 ## 常見問題。
• 禁止用 **bold** 段落當標題（MD036）— 破壞語義階層與 TOC 產生。
• 程式碼區塊需註明語言（MD040），影響 syntax highlighting 與 accessibility。
• 列表前後需空行（MD032）、fenced code block 前後需空行（MD031）— 否則部分 parser 會把列表吃進段落。
• 有序列表編號風格一致（MD029）— 全部 1. 或全部 1./2./3.。
• 檔案結尾需有換行（MD047），POSIX 規範。
• 行長度上限（MD013）— 預設關閉，中英混用技術寫作不適用 80-char 慣例。

前兩類混合在同一份寫作規範裡，因為都由同一個工具鏈檢查、都要落地到相同的 pre-commit hook。純靠紀律記住這十幾條在大型 repo 上不可行，純 regex 又無法穩定處理「平行結構下的標題重複」「卡片段落歸屬」這類語意判斷。因此 blog 專案採用 Go + goldmark AST 做自訂 linter：scripts/mdtools。本文是 linter 與寫作規範的對齊文件；AGENTS.md 引用本文作為排版規範來源。

1. 工具總覽

工具原始碼在 scripts/mdtools/，binary build 到 bin/mdtools（已 gitignore）。

作用範圍是 content/**/*.md。public/、themes/、node_modules/ 等輸出或第三方資源不檢查。

2. 標題規則

2.1 標題結構與格式規則

• 正文禁止使用 H1。Hugo 的 front matter title 會自動產生 H1，若正文再寫 # ... 會出現兩個 H1 並列，破壞語義階層與 SEO 訊號。正文一律從 H2 開始，最深到 H6。
• 同一父標題（直接上層）底下，子標題文字必須唯一（MD024 siblings_only 模式）。
• 不同父標題底下，子標題允許重名。
• 標題前後需保留空行（MD022），mdtools fmt --fix 自動補。
• 標題結尾禁止標點（MD026）— 禁用字元：.、,、:、;、。、，、：、；。允許 ?、！、？、! 作為語氣結尾。mdtools fmt --fix 自動去除結尾禁用標點。
• 禁止用粗體當標題（MD036）— 若段落整段只由 **文字** 或 *文字* 組成，視為視覺性標題濫用。mdtools lint 只報警、不自動修；作者需手動判斷正確的標題層級（通常是 H3 / H4）並改寫。

2.2 補充範例：MD026 與 MD036 的典型誤用

MD026（標題尾標點）常見誤用：

1#### 字型選擇說明：        ← 違規（結尾 `：`）
2#### 字型選擇說明          ← 合法

中文寫作習慣用冒號引入後續內容，這個模式在「段首句」合理、在「標題」就不合理 — 標題本身的存在就暗示了後續有內容，冒號變成冗餘訊號。

MD036（粗體當標題）常見誤用：

1**字型選擇說明**           ← 違規：整段只有粗體，視覺像標題但不是真標題
2
3這段內容...
4
5### 字型選擇說明           ← 合法：用正式的 H3 取代

差異看起來微小，實際影響包含：Hugo TOC 不會抓到、卡片反向連結失效、screen reader 無法跳轉。這是「語義 vs 視覺」錯位的典型案例，AST linter 容易檢出（Paragraph 節點唯一子節點為 Strong/Emph）。

2.3 為什麼採 siblings_only 而非全域唯一

平行結構（多案例、多模板章節）的複用語義來自上層標題賦予的脈絡。例如：

1## 【案例一】Uber 2022
2### 弱點環節        ← 合法
3### 攻擊路徑
4
5## 【案例二】Okta 2023
6### 弱點環節        ← 合法，因為在不同的父層下
7### 攻擊路徑

重名只有在同層並列時才代表結構錯誤。強制全域唯一會逼作者寫 ### 【案例二】弱點環節，破壞平行結構的視覺一致性，收益並不大。

3. URL 與連結規則

3.1 裸 URL 轉換（mdtools fmt --fix 自動處理）

段落或表格儲存格內的裸 URL 會自動包成 markdown 連結。顯示文字依路徑可識別性分級：

識別碼偵測用 regex 白名單，初始清單專注在高頻識別碼格式（例如 CVE-YYYY-N），其他格式以「遇到再加」原則擴充。清單維護在 scripts/mdtools/internal/rules/identifiers.go。

3.2 反釣魚校驗（mdtools lint 強制檢查）

Markdown 語法允許顯示文字與實際 href 完全不符，這是釣魚攻擊的結構基礎。本規則在 AST 層阻擋此模式。

• R-URL-1（URL 樣顯示文字一致性）：若顯示文字含 .com / .org / .gov / .net / .io / .dev / .tw 等 TLD 字樣，則顯示文字的 domain 必須等於 href 的 domain（含子網域比對）。
• R-URL-2（描述型顯示文字自由）：顯示文字不含 TLD 字樣時，視為人類可讀描述，不做 domain 比對。

違規範例（會被 lint 阻擋）：

1[nvd.nist.gov](https://malicious.example.com/fake)     ← 顯示文字暗示 NVD，href 卻不是
2[cisa.gov/advisory](https://cisa-gov.evil.example)     ← 顯示文字抄 CISA 格式，domain 不符

合法範例：

1[Uber 事件公告](https://www.uber.com/newsroom/security-update/)
2[nvd.nist.gov/CVE-2023-34362](https://nvd.nist.gov/vuln/detail/CVE-2023-34362)

這條規則在紅隊 / 安全相關教材中特別重要：讀者本來就該對來源警戒，排版規則不該削弱這個警戒訊號。縮短顯示文字提升可讀性，反釣魚校驗守住安全底線，兩者互補。

3.3 例外情境

• 程式碼區塊（fenced code block，``` 包圍）內的 URL 不做任何處理（不縮短、不校驗）。代碼範例經常需要展示完整 URL 給讀者複製執行。
• 引用區塊（> 開頭）內的 URL 比照段落處理，會縮短也會做反釣魚校驗。

4. 表格規則

• 統一使用 aligned 風格：每欄內容用空白補齊到該欄的最大寬度，使 | 在 monospace 渲染下垂直對齊。
• 欄位分隔線使用 | --- | 形式，不含對齊冒號 :（分隔線內的 - 數量跟隨該欄寬度自動填足）。
• 寬度計算使用顯示寬度（display width）— CJK 字元佔 2 欄寬、ASCII 佔 1 欄寬，分隔列與資料列按同一套寬度對齊。
• mdtools fmt --fix 自動正規化：插入新行或改動欄寬時會全表重算，作者不需手工維持對齊。

選 aligned 而非 compact 的理由是原始檔可讀性：技術教材的表格常需在 code review 裡對照，aligned 風格讓 reviewer 直接看出哪些欄位對應哪些內容，不用在腦中解析鋸齒狀的 pipes。手工對齊在長表格反覆編輯時確實會失效（新增一行就全表要重對齊），但這正是 mdtools fmt --fix 接手的地方。

5. 基礎格式細節

這節整理容易被忽略、但會影響 parser 正確性或渲染品質的小規則。

5.1 程式碼區塊必須註明語言（MD040）

由 mdtools lint 檢查。未註明語言的 fenced code block 會被報警：

 1```                   ← 違規：缺語言標示
 2func main() {
 3    fmt.Println("hi")
 4}
 5```
 6
 7```go                 ← 合法
 8func main() {
 9    fmt.Println("hi")
10}
11```

純文字輸出（例如 terminal output、log 片段）使用 text 或 plain：

1```text
2Error: permission denied
3```

Shell 範例統一用 bash（即使是 zsh 語法，讓 syntax highlighter 有合理預設）；純設定檔依實際格式（toml、yaml、json、ini）。

5.2 fenced code block 前後需空行（MD031）

由 mdtools fmt --fix 自動處理。缺空行會讓前後段落被 parser 併入 code block 或反之。

5.3 列表前後需空行（MD032）

由 mdtools fmt --fix 自動處理。

 1上一段結束。
 2- 列表項一           ← 違規：列表前無空行，會被部分 parser 當段落延續
 3- 列表項二
 4
 5上一段結束。
 6
 7- 列表項一           ← 合法
 8- 列表項二
 9
10下一段開始。

5.4 有序列表編號一致性（MD029）

由 mdtools fmt --fix 正規化。本專案採 ordered 風格（全部遞增編號）：

11. 第一步
22. 第二步           ← 合法
33. 第三步
4
51. 第一步
61. 第二步           ← 違規：混用風格（fmt --fix 會改成 1./2./3.）
72. 第三步

選擇 ordered 的理由：原始檔可讀性高，作者直接看到步驟數；插入新項目的對齊代價比全部重新渲染低。

5.5 段落間空行

段落之間、標題前後、列表與段落之間都需空行。mdtools fmt --fix 會自動規範化多餘 / 缺失的空行，作者不需手工維護。

5.6 檔案結尾需有換行（MD047）

POSIX 文字檔規範；缺失時 git diff 會出現 \ No newline at end of file。mdtools fmt --fix 自動補。

5.7 Tab 字元（MD010）— 僅限 fenced code block

由 mdtools lint 檢查（warn 等級）。Prose / 列表 / 表格 / 引用等非 code-block 行內若出現 tab 字元，會被標記並建議改成空白；fenced code block 內的 tab 保留（Go 原始碼依 gofmt 慣例用 tab，文章要讓讀者能直接複製貼用）。

Repo 根目錄的 .markdownlint.json 用 "MD010": { "code_blocks": false } 告知 IDE 的 markdownlint extension 採用同一套 policy，讓編輯器跟 CI 的警告保持一致。

5.8 行長度上限（MD013）— 預設關閉

本規則預設關閉。中英混用的技術寫作不適用 80-char 慣例：

• 中文每字元算 1 個寬度時，80-char ≈ 40 個中文字，寫到一半就要斷行，嚴重影響可讀性。
• 中文每字元算 2 個寬度時，80-char 相當於 20-30 個中文字，更離譜。
• Markdown 編輯器普遍支援軟斷行與 IDE word wrap，實體行長度對閱讀體驗影響小。

若未來需要打開（例如發現真的有人寫出 2000-char 單行段落），建議上限 400 字元（軟上限，warn 不阻擋）。設定在 scripts/mdtools/internal/rules/config.go 的 LineLengthLimit 欄位。

5.9 裝飾符號禁用（emoji / 視覺記號）

本節本身豁免：規範要描述「哪些符號禁用」必然要列舉這些符號（use-mention distinction）。本節舉例的 emoji 屬 mention（指稱）、非 use（裝飾使用）、不違反規則。掃描指令會 hit 到本節、判讀時跳過。

content/** 正文不可使用 emoji（如 ✅ ❌ ⚠️ 🚨 🟡 🟢 ⭐ 📌 💡 ⚡ 🎯）與裝飾性 unicode 符號（✓ ✗ ✘）。表格、列表、行內標記都不行。

替換策略（emoji 承載的語意要回到文字結構、不是純粹刪除符號）：

理由：

• Grep-ability：emoji 無法用 plain text grep 命中；視覺結構容易掩蓋語意結構、reviewer 看不出「優 / 缺」是用 emoji 區分還是用標題段區分
• CLI parser 相容性：部分 multi-byte emoji 在 Rust-based CLI 工具（如某些 mdtools / pagefind / lint pipeline）觸發 char-boundary panic
• 跨語境穩定：emoji 在不同字型 / 平台 / 終端機渲染差異大、容易斷行或顯示為框

掃描指令（提交前自己跑一次、有 hit 就替換）：

1rg "✅|❌|⚠️|🚨|🟡|🟢|🔴|🟠|🔵|⭐|📌|💡|⚡|🎯|✨|📝|🔍|🛠|⛔|✓|✗|✘" content/

本規則目前未進 mdtools lint 自動掃描、靠人工 grep。未來會加進 lint pipeline。

5.10 位置引用與數量命名候選掃描（REF1 / REF2、警告層）

mdtools lint 對 content/** 跑兩個警告層掃描、來源是引用紀律卡（#155 引用章節用語意標題、#156 集合命名用角色）：

• REF1-positional-anchor：正文中的位置式引用候選 —「見第 3 點」「詳見第五章」「§4」。位置編號是當下排列的衍生值、目標是活文件時、結構重排會讓引用 silent 指向錯的內容。
• REF2-count-in-name：標題與 front matter title 中內嵌成員數的集合命名 —「六大原則」「遷移五階段流程」。成員增減時名稱先失真、且名稱是被複製最多次的字串。

兩個規則都停在警告層、命中是候選、不是判決 — 回報前要做語意判定：

掃描器內建兩個自動豁免：被 「」 包住的命中視為反例引用、直接跳過；「第」開頭的序數（第三階段）不屬 REF2 的集合命名。既有內容的命中屬歷史基線、依「changed-set scoped lint」原則處理 — 新增與修改的檔案要判讀、存量警告分開回報。

5.11 否定起手候選掃描（POS-negation-lead、警告層）

mdtools lint 對 content/** 跑否定起手掃描、來源是 #166 重點優先陳述是跨語言的資訊結構原則（搭配 #165 register 違規要文體異源）：

• POS-negation-lead：正文中「不是 X、而是 Y」「不是 X — 是 Y」「與其 X、不如 Y」的重點後置候選。核心概念（Y）被擠到「而是 / 不如」之後、讀者要先處理一個被否定的 X 才拿到重點。這是資訊結構效率問題、跨語言成立（英文「not X but Y」、日文「X ではなく Y」）、不是中文特有句型 — 偵測可機械化、判定不可。pattern 涵蓋的連接詞（而是 / 「— 是」/ 不如）枚舉不完、判準是「核心概念在不在句首」而非哪個連接詞 — 漏掉的變體只是讓候選 silent 到有人讀到（規則第一版就漏了「不是 X — 是 Y」、靠人發現才補）。

判定用「重點位置」、命中是候選、不是判決：

掃描器豁免兩類命中：被 「」 包住的引用（反例引用 / 句型佔位符）、以及 backtick 行內程式碼內的 pattern（grep regex / 技術識別碼）。講這個句型的 meta 卡（#165 / #166）與本規範段落會大量自我觸發 — 屬候選人判定豁免、跟 REF1 / REF2 對 #155 / #156 一致。既有內容的命中（全 content/ 約數百個）屬歷史基線、依「changed-set scoped lint」原則處理 — 偵測把候選池曝光、判定漸進進行、存量警告分開回報。

6. Front matter schema（mdtools lint）

Hugo 依賴 YAML front matter 提供 title / date / weight 等欄位給 render pipeline。缺欄位會讓列表頁、排序、SEO 壞掉，但 Hugo 本身不會失敗（靜默接受不完整資料），所以必須由 linter 守住。

6.1 通用層（content/**/*.md）

所有內容文章必須有：

• title：字串，不可空。
• date：YYYY-MM-DD 格式（ISO 8601 date）。

Hugo _index.md section 頁面例外：這類檔案是 Hugo 的 section 列表 landing page，不是內容文章，沒有語意上的「日期」。只要求 title，不強制 date。

6.2 推薦層（警告，不阻擋）

推薦填寫（mdtools lint warn level）：

• description：字串，建議 30–150 字，影響 SEO 與列表頁預覽。
• tags：陣列，至少 1 個標籤。

推薦層是歷史內容的緩衝區，不是新增內容的放行條件。新增文章必須同時填寫 description 與 tags；修改既有文章時，若同一檔案缺少推薦欄位，應在同次變更補齊，避免每次驗證都被舊 warning 淹沒。

驗證時先跑 changed-set scoped lint 判斷本次變更品質，再視需要跑 full lint 觀察整體基線。回報 full lint 結果時，要把歷史 warning、已知 warning 與本次新增問題分開描述。

6.3 卡片嚴格層（content/backend/knowledge-cards/**）

知識卡片額外要求（對應 .codex/briefs/knowledge-cards.md K2）：

• title、date、description 必填。
• weight：整數，決定在 _index.md 主題表格中的排序位置。

6.4 禁止欄位

以下欄位存在時 mdtools lint 警告（避免語義混淆）：

• author：本專案為單作者 blog，統一於 Hugo 設定。
• permalink：使用 Hugo 預設路徑規則，避免手動覆蓋。

若未來需要鬆綁，在 scripts/mdtools/internal/rules/frontmatter.go 的 DisallowedFields 清單調整。

6.5 slug 必填、跟檔名對齊

所有 content 文章 frontmatter 必須有 slug 欄位，值跟檔名（不含 .md）對齊。

1---
2title: "視覺手段對齊錯誤層次"
3slug: "visual-tool-error-layer-alignment"   # 跟檔名對齊
4date: 2026-04-28
5---

為什麼必填：

slug 是 URL 的核心識別、跨多個工具共用（Hugo build、mdtools lint、跨檔 markdown link、search index）。若不顯式定義，slug 散落在三處推導鏈：

三個推導鏈不一致時 = silent broken link（mdtools pass 但 hugo build 後 404、或反過來）。把 slug 升成 frontmatter 顯式 fact、所有工具基於同一 source、消除 derivation 鏈。

詳細論述見 report #93 URL slug 必須顯式定義為 fact。

檔名對齊規則：

• 檔名命名建議：英文小寫、kebab-case 或 snake_case、不含中文（避免 hugo urlize 規則跨版本變動）
• slug 值 == 檔名 stem（不含 .md）
• 修檔名時必須同步修 slug；修 slug 時必須同步 rename 檔案

Hugo _index.md 例外：section 列表頁已有 slug: 欄位指定資料夾路徑、不適用本規則。

7. 卡片雙向完整性（mdtools cards）

作用範圍：content/**/*.md，重點關注 content/backend/knowledge-cards/。

L3（正文首次出現術語必須連結到卡片）暫不納入，待術語字典（.codex/briefs/knowledge-web-expansion.md）啟動後再開。

為什麼要做跨文件檢查

知識卡片是 blog 的核心知識資產。隨著卡片數量增加：

• Orphan 卡片（沒有正文連結進來）會變成知識死角，讀者無法發現。
• 斷掉的相對連結（檔案被改名或移動）肉眼難以發現，只有讀者點擊失敗才暴露。
• K4 合規（首段 + 概念位置段要有鄰卡連結）保證卡片間的知識網不會鬆散。

這些檢查用 regex 做都卡在「段落歸屬怎麼判斷」。AST 天生知道節點的父子結構，做起來自然。

8. 執行時機

Pre-commit hook（.githooks/pre-commit）

1. mdtools fmt --fix — 自動修格式；改動會 git add 回 staged，避免改完又沒進 commit。
2. mdtools lint — 結構檢查；失敗阻擋 commit。
3. mdtools cards — 完整性檢查；失敗阻擋 commit。

Pre-push hook（.githooks/pre-push）

pre-push 的責任是把 CI 同款全量檢查提前到本機。pre-commit 為了速度只處理 staged markdown；pre-push 會跑 make check，也就是 mdtools fmt --check content/、mdtools lint content/、mdtools cards content/，讓整個 content/ 的格式與連結 drift 在推送前被攔下。

啟用 hook：

1git config core.hooksPath .githooks
2# 或：make install-hooks

CI（.github/workflows/md-check.yml）

三個子命令都跑 --check / 嚴格模式，任何違規 fail CI。

9. 寫作者使用指引

• 寫作時優先遵循本規範。pre-commit / pre-push 報錯時讀訊息修正；不可用 git commit --no-verify 或跳過 hook 的方式繞過檢查。
• 新增案例平行章節（例如多個「工具評測」「事件時序」）時不需登記到任何白名單 — siblings_only 自動判讀。
• 新增 URL 時優先採用裸 URL 轉換段的分級形式；若顯示文字含 TLD 字樣，確認 domain 與 href 完全一致。
• 新增卡片時確認首段與「概念位置」段各有至少一個相鄰卡片連結（L4 要求）；確認 front matter 含 title / date / description / weight（卡片嚴格層）。
• 程式碼區塊養成習慣先寫語言標示再填內容；純文字輸出用 text。

10. 規則擴充流程

新規則進入本文的路徑：

1. 先在 scripts/mdtools/internal/rules/ 實作為可開關的 rule（預設關）。
2. 在代表性檔案上測試誤判率。
3. 誤判率 < 1% 且有明確教材品質收益時，預設開啟並更新本文。
4. 預設開啟後同步修正既有違規；若違規數量大，可分批 PR。

11. 為什麼自訂而不是用現成 markdownlint

markdownlint-cli2 的 MD022 / MD024 / MD026 / MD029 / MD031 / MD032 / MD034 / MD036 / MD040 / MD047 / MD060 這些基礎規則都有（MD013 預設關閉、MD025 本規範嚴於原版），為什麼還要自寫？

關鍵差在卡片雙向完整性、反釣魚校驗、Front matter schema 這三類檢查，屬於跨文件 / AST 層 / 業務邏輯層的自訂邏輯，現成 linter 無法表達。這些檢查是 blog 品質的核心訊號，必須跟基礎格式檢查放在同一個工具鏈、同一次 AST parse 內處理，避免多個工具重複解析、重複維護。

另外 goldmark 是 Hugo 內建的 markdown parser。用同一個 parser 做 lint 保證「lint 通過 → Hugo render 一致」，杜絕兩套 parser 解讀不同的長尾 bug。

本文為 blog 專案 Markdown 寫作規範的單一真實來源。repo 根目錄的 AGENTS.md 引用本文作為排版規範權威，規則與 scripts/mdtools 實作保持同步。

這才建立了 5W1H 自覺決策方法論：在建立任何任務之前，必須強制回答六個問題。不是「可以回答」，而是「必須回答」，任何一個缺失都阻止任務建立。

為什麼直覺判斷不夠用

直覺判斷的門檻太低。任何模糊的想法都可能直接變成任務被付諸實作，等發現重複了或架構位置錯了，才知道白花了時間。

5W1H 框架在任務建立的那一刻設置強制思考關卡。只有通過六個問題，任務才能被建立。

六個問題，六個層次的自覺

Who：責任歸屬，防止重複實作

Who 問的不只是「誰來做」，更重要的是「有沒有人已經做過了」。在我們的協作模式中，Who 必須明確標記執行者和分派者兩個角色，格式如：「parsley-flutter-developer（執行者）由 rosemary-project-manager（分派者）分派」。

這個格式強制一個邊界：主線程不應自己寫程式碼，職責是設計任務、分派任務、驗收結果。如果任務標記為主線程執行但類型是程式碼實作，系統直接阻止。

執行 Who 前要先做四步檢查：搜尋現有 Domain 是否有相同功能，確認既有 Service 是否已實作，查看測試覆蓋是否涵蓋，最後才決定是重用還是新建。Domain 中已有相同功能就禁止新建，責任不明就禁止執行。這兩條規則消滅了大部分重複實作。

What：功能定義，單一職責的守門員

What 要求明確說出具體的輸入輸出、業務行為和異常處理。合格的 What 必須能一句話描述完且無法再拆分。

「書籍處理——包含驗證、儲存、查詢等」不合格。「驗證輸入字串是否符合 ISBN-10 或 ISBN-13 格式，輸入 String isbn，輸出 ValidationResult，空字串拋出 ValidationError」才是。

職責不清就禁止執行，與既有功能重疊就整合，包含多個不相關職責就拆分。

When：觸發時機，副作用要完整識別

When 要求明確說出觸發事件，不是「書籍資料需要驗證的時候」，而是「使用者完成 ISBN 條碼掃描，觸發 ISBNScannedEvent，副作用包含觸發書籍資訊查詢和更新 UI 狀態，整合到 ScanTask 聚合根的事件系統」。

副作用未識別是 When 的紅線。連鎖反應沒有提前想清楚，後來就是難以追蹤的 bug。

Where：架構位置，確保層級正確

Where 決定功能在 Clean Architecture 中的位置。不是「在需要的地方執行」，而是「Domain Layer，BookValidator 位於 Book Aggregate，由 AddBookUseCase 呼叫，呼叫路徑是 UI → UseCase → Domain → Validator」。

位置錯誤就重新定位，不能為了方便就地執行。跨層級混亂就重新架構，不妥協。

Why：動機驗證，識別逃避性開發

Why 是六個問題中最重要的，因為它直接對抗最常見的開發陷阱——逃避。

合格的 Why 必須有需求文件編號，能說明具體的使用者價值和場景。「系統需要更多驗證」不合格，它沒有需求依據，而且可能只是為了逃避更難的問題。

遇到這些語言會立即阻止：「先做簡單的」（逃避複雜問題）、「順便加個功能」（缺乏需求）、「優化一下效能」（可能在迴避功能問題）。

How：實作策略，任務類型的強制標記

How 要求明確實作策略，並強制標記任務類型，格式是 [Task Type: XXX]。六種類型：Implementation（程式碼實作，必須由執行代理人執行）、Dispatch（任務分派，主線程執行）、Review（驗收，主線程執行）、Documentation、Analysis、Planning。

這個標記讓 Who 和 How 的合規性可以被自動檢查：How 標記為 Implementation 但執行者是主線程，系統直接阻止；Dispatch 類型的任務執行者是代理人，同樣阻止。

「先建立基本功能之後再加測試」是直接違規，任何臨時解法都禁止。

Who 和 How 的聯動檢查

正確組合：Implementation 搭配執行代理人，Dispatch/Review 搭配主線程。違規組合：Implementation 搭配主線程（主線程不應寫程式碼），Dispatch 搭配代理人，缺少執行者/分派者標記。

這個機制解決了一個真實痛點：主線程在時間壓力下直接修改程式碼，繞過代理人執行的設計。有了 How 的任務類型標記和 Who 的格式要求，這種行為在任務建立階段就被攔截。

逃避語言清單

框架持續更新一份逃避語言清單，分五類：

• 品質妥協：「太複雜」「先將就」「暫時性修正」「症狀緩解」、“workaround”、“hack”、“quick fix”
• 簡化妥協：「更簡單的方法」「簡化處理」——通常意味著在迴避真正的設計問題
• 擱置問題：「架構問題先不管」「技術債務之後處理」——發現了卻不解決，最危險
• 測試妥協：「簡化測試」「基本測試即可」
• 模糊詞彙：沒有具體指標的「優化」「自動」

偵測到任何逃避語言，系統立即阻止並要求修正。

Hook 系統：讓規則有牙齒

框架的執行依賴 Hook 系統。TodoWrite 工具使用前，Hook 檢查 5W1H 完整性；任何一個 W 或 H 缺失，操作立即阻止；發現逃避語言，進入修復模式。

修復機制：阻止操作 → 明確說明缺失哪個項目 → 要求補充 → 再次驗證。

這個框架改變了什麼

最明顯的感受是對話品質變了。以前任務可能只有「實作書籍驗證功能」；現在必須帶著完整的 Who（誰來做、是否已存在）、What（具體輸入輸出）、When（何時觸發、有哪些副作用）、Where（架構層）、Why（需求來源）、How（任務類型和策略）才能被建立。

很多模糊的想法在回答六個問題的過程中就自然消失了——它們根本過不了關。

我們選擇了 Clean Architecture。它不只是架構模式，更是一套「責任分層」語言，讓我們和 AI 代理人都能用同一套詞彙討論誰該負責哪個部分、什麼時候可以動手。

核心原則：依賴只能由外向內

Clean Architecture 最核心的一句話是「依賴只能由外向內」。內層不知道外層的存在，外層依賴內層定義的介面。業務邏輯因此得以獨立，換資料庫、換 UI 框架都不需要動到核心規則。

架構由內到外分為四層：

Entities（核心業務規則） 封裝核心業務概念，例如書籍、訂單、使用者。定義實體屬性和業務不變量的驗證，不依賴任何框架或資料庫。

Use Cases（應用業務邏輯） 協調 Entities 之間的互動，定義系統功能。同時定義 Input Port、Output Port、Repository Port，只依賴 Entities 和這些自己定義的介面。

Interface Adapters（介面轉接層） 橋接業務邏輯和外部技術。Controller 接收外部請求並轉換為 Use Case 輸入，Presenter 格式化 Use Case 輸出，Repository 實作在這一層開始成形。

Frameworks & Drivers（框架與外部系統） 包含所有技術細節——資料庫、UI 框架、第三方服務。可以隨時替換，完全不影響內層。

依賴反轉原則（DIP）讓這一切成立

Use Case 需要存取資料，但不能直接依賴 SQLite。正確做法是：在 Use Cases 層定義 Repository Port（抽象介面），Use Case 只依賴這個介面。真正的資料庫實作在最外層，它去實作這個介面。

依賴方向因此被反轉：資料庫實作依賴 Use Case 定義的介面，而非 Use Case 依賴資料庫。最後在 Composition Root 把具體實作注入進去，這就是依賴注入的本質。

設計從內到外，實作從外到內

這是我們在 AI 協作中最重要的一個認知。

設計階段由內到外

1. 設計 Entities：識別業務實體、定義 Value Objects（ISBN、Title 這類有驗證規則的值物件），在建構子中驗證業務不變量。
2. 設計 Use Cases：定義 Input Port、Output Port、Repository Port。確定業務邏輯需要什麼，但不決定如何實作。
3. 設計 Interface Adapters：Controller 如何轉換外部請求、Presenter 如何格式化輸出。
4. 設計 Frameworks：選擇資料庫方案，實作 Repository。到這步才碰具體技術。

實作階段由外到內

1. 先定義所有 Ports。在寫任何實作之前，確立 Use Case 介面和 Repository 介面，這是系統的骨架。
2. 外層用 Mock 介面開發和測試。Controller 在 Use Case 還沒真正實作前就能測試，因為它依賴的是抽象介面。
3. 補完內層實作：Interactor 實作業務邏輯，Repository 存取真正的資料庫。
4. Composition Root 組裝依賴注入，系統就能真正執行。

設計階段確保業務邏輯不被技術細節污染，實作階段讓每一層都能獨立開發和測試。

驗證架構是否正確

每個 Phase 完成後，我們對照以下幾個方向確認。

依賴方向

• Entities 沒有任何外層的 import
• Use Cases 只 import Entities 和自己定義的介面
• Frameworks 層實作的是 Interface Adapters 定義的介面

介面契約

• Repository Port 定義在 Use Cases 層（不是 Frameworks 層）
• Repository 回傳的是 Entity 而不是資料庫 DTO
• Input/Output Port 沒有洩漏框架的型別（例如 HTTP Request、SQLite Row）

業務邏輯位置

• 業務不變量的驗證在 Entity 建構子
• 應用層邏輯在 Use Case Interactor
• Controller 只負責轉換和呼叫，不包含業務判斷

Interface-Driven Development

• 所有 Ports 在設計階段就定義完成
• 外層真的用 Mock 介面在開發測試
• 組裝注入在 Composition Root 統一處理

為什麼這對 AI 協作特別有價值

傳統開發中，架構邊界的維護依賴工程師的經驗，容易在壓力下妥協。AI 代理人則非常適合執行有明確規則的框架——規則夠清楚，它就能持續一致地遵守。

分層邊界就是這樣的規則。告訴代理人「這個 class 屬於 Use Cases 層，所以不能 import 任何 Framework 層的東西」，代理人就能機械性地驗證和維護這個邊界。

這套語言也讓任務拆分有了清楚的依據。「這個功能需要修改 Entity 和 Use Case，但不涉及 Repository 實作」是一個清楚的任務描述，對應到具體的修改範圍，不會模糊。

從實際經驗來看，引入 Clean Architecture 之後，AI 的實作結果更容易預測，測試覆蓋率更容易維持，架構審查也更有效率。代價是設計階段需要更多前置思考，但這個投資通常值得。

我們在專案中建立了一套設計階段品質閘門：在 Ticket 進入 Phase 2 之前強制執行 C1/C2/C3 三項檢測。 問題在文字階段就抓出來，修正只需幾分鐘；等到程式碼都寫好了，才是幾個小時起跳的代價。

三層檢測標準

C1 God Ticket：超過 10 個檔案、跨越超過 2 個架構層、或預估超過 16 小時，判定過大，必須拆分。

C2 Incomplete Ticket：驗收條件少於 3 個可量化項目、缺少測試規劃、未定義工作日誌名稱、無參考文件連結——任一缺失，Ticket 不完整。

C3 Ambiguous Responsibility：標題缺少層級標示（如 [Layer 5]）、目標含複合職責（出現「和」或「或」）、步驟用「相關檔案」而非具體路徑、驗收條件跨層——任一模糊，需重新定義。

檢測順序的設計邏輯

固定執行順序：C1 → C3 → C2。

C1 最先，因為一旦判定 God Ticket，拆分後產生多個新 Ticket，C2/C3 的分析全部作廢要重來。C3 排第二，職責不清的 Ticket，補充驗收條件也會是模糊的。C2 最後，在範圍合理、職責明確的基礎上，確認必要元素齊全。

執行流程

Step 1：C1 God Ticket 檢測

從 Ticket 的步驟章節提取所有檔案路徑，計算檔案數量。接著使用檔案路徑分析法判斷每個檔案所屬的架構層：

• lib/presentation/widgets/、lib/presentation/pages/ 屬於 Layer 1（UI 層）
• lib/presentation/controllers/、lib/presentation/view_models/ 屬於 Layer 2（行為層）
• lib/application/use_cases/、lib/application/services/ 屬於 Layer 3（UseCase 層）
• lib/domain/repositories/（介面）、lib/domain/events/ 屬於 Layer 4（Domain 介面層）
• lib/domain/entities/、lib/domain/value_objects/、lib/infrastructure/ 屬於 Layer 5（Domain 實作層）

層級跨度 = 最高層 - 最低層。如果有檔案分佈在 Layer 1 到 Layer 5，層級跨度就是 4，遠超過 2 的上限。

預估工時根據步驟數量與複雜度係數評估：步驟數 × 平均每步時間 × 複雜度係數（1.0 到 2.0）。

檢測失敗時，依序嘗試三種拆分策略：

1. 按層級拆分（優先）：將跨層的 Ticket 按架構層拆成多個
2. 按職責拆分（次要）：將工時過長的 Ticket 按職責邊界拆分
3. 按功能模組拆分（最終）：將職責過多的 Ticket 按功能模組拆分

拆分後的每個子 Ticket 都需要重新執行 C1 檢測。

Step 2：C3 Ambiguous Responsibility 檢測

確認四個要素：

• 層級標示：標題包含 [Layer X] 標籤
• 職責描述：目標章節無「和」或「或」的複合描述
• 檔案範圍：步驟列出具體路徑，而非「相關檔案」
• 驗收限定：驗收條件不出現跨層項目

任一不符，依序修正：明確層級 → 重寫職責 → 列出具體檔案 → 限定驗收範圍。

Step 3：C2 Incomplete Ticket 檢測

確認四個必要元素都存在：

• 驗收條件：3 個以上可量化、可驗證的項目（「程式碼品質提升」這種描述不算）
• 測試規劃：明確的測試檔案路徑和對應的測試項目
• 工作日誌：定義好工作日誌的檔案名稱（而非「待填寫」）
• 參考文件：至少 1 個有效的文件連結

缺少哪個就補哪個，沒有例外。

Step 4：提交審查

所有 Ticket 通過 C1/C2/C3 之後，生成品質閘門檢測報告，提交 PM 審查。PM 批准後才能進入 Phase 2。

阻斷機制與執行時機

任何 Ticket 未通過 C1/C2/C3，禁止進入 Phase 2。不是建議，是硬性規定。問題立即修正，所有過程寫入工作日誌。

執行時機有三個：設計完成後立即檢測、PM 分派前確認報告、PM 審查時以報告作依據。三個時機缺一不可——缺了任何一個，閘門就會有漏網之魚。

實際效益

最直接的改變是：開發者接到 Ticket 時就已經有明確範圍、清楚職責、具體驗收標準，不需要反覆確認。

更重要的是，因為修正成本真的很低，團隊才會認真對待每一次品質閘門，而不是當作走形式。一旦修正成本高，就會開始討價還價、局部修正、累積技術債——品質閘門也就形同虛設。

這讓我們認真思考：Ticket 不只是一張便利貼，它是任務的完整生命週期。

四個狀態，一條主線

待執行（Pending）：Ticket 準備好但還沒人開始。進入條件是標題格式正確、五個核心欄位填寫完整、前置依賴都已完成。

進行中（In Progress）：核心紀律是即時記錄，遇到問題就寫進日誌，不要等到最後才回憶。我們設的建議上限是 8 小時——超過通常代表 Ticket 太大，需要拆分。

Review 中（In Review）：第三方驗證。重點聚焦在驗收條件：逐項打勾，要麼通過要麼不通過。建議 1-2 小時內完成，避免卡住流程。

已完成（Completed）：不可逆的終態。進入條件：所有驗收條件打勾、Review 通過、測試 100% 通過、靜態分析 0 錯誤、工作日誌更新。缺一不可。

Ticket 標題：動詞加目標

標準格式是「動詞 + 目標」。動詞選擇反映任務類型：「定義」用於介面或規範，「撰寫」用於測試文件，「實作」用於具體功能，「修復」用於 Bug，「重構」用於改善結構。

對比：「做 Repository」和「實作 SQLiteBookRepository」——後者讓人在領取前就知道工作規模。

五個核心欄位

每張 Ticket 必須有這五個欄位：

背景說明為什麼需要這個任務，讓三個月後的自己也能理解來龍去脈，不用去問當初的人。

目標一句話說清楚要達成什麼，建議不超過 30 字。可驗證的目標：「實作 SQLiteBookRepository，符合 IBookRepository 介面，通過所有單元測試」。不可驗證的：「優化資料儲存」。

步驟列 3-5 個具體動作，每個指明操作對象和預期結果。目的是讓人一領取就知道從哪裡開始。

驗收條件是任務的契約，必須客觀可勾選。不是「程式碼品質良好」，而是「dart analyze 0 錯誤」；不是「測試通過」，而是「覆蓋率 100%，通過率 100%」。

參考文件連結設計文件、需求規格、相關 Ticket，讓執行者有完整上下文。

執行的七個步驟

領取前先確認依賴都完成，工作量合理再標記進行中。

閱讀背景和目標，把參考文件看完再動手。

執行時遇到問題即時記進日誌。

自檢時逐項勾選驗收條件，全過才進下一步。

提交時標記為 Review，附上自我檢查結果。

處理 Review 結果，通過則關閉，未通過根據反饋修正再提交。

記錄經驗——這一步最容易省略，也最有長期價值。Ticket 完成時回答：學到了什麼？有什麼可改進的地方？是否需要建立 error-pattern 防止重複？知識沉澱進系統，才不會只留在某個人腦子裡。

阻塞狀態的積極處理

Blocked 最容易被誤用：標記了就等著。我們的原則是阻塞不超過 24 小時，必須採取行動。

行動方式取決於原因：缺前置條件就派發前置任務；技術問題不清楚就建調查任務；需要決策就建評估任務。把「被動等待」轉成「積極解除」，每個阻塞都變成一個有人負責的子任務。

結語

從「修復那個問題」到「修復書籍搜尋在 ISBN 格式不一致時回傳空結果的問題」，這個距離比看起來近。只需要一點紀律，和對「完成」這件事更認真的態度。

我們的解法是建立一套 Ticket 設計派工方法論。這篇文章記錄實踐方式和核心概念，以及後來加入的積極派發原則。

為什麼需要 Ticket？

工作日誌已經記錄了一切，為什麼還需要 Ticket？

兩者定位不同。工作日誌是「記錄層」，給未來的開發者看，記錄決策脈絡。Ticket 是「執行層」，給正在做事的人看，代表一個可以獨立完成、驗收、追蹤的最小任務單位。

一個 Ticket 有幾個核心特徵：獨立性（可以獨立執行和驗收）、原子性（不可再分割）、可驗證性（有明確的完成標準），以及單一職責（一個動詞加上一個目標）。

單一職責是拆分 Ticket 的唯一標準

方法論早期我們用量化指標判斷是否需要拆分：職責數量、檔案數量、測試案例數、行數。直觀，但實際用起來有問題：一個 100 行的 Ticket 可能職責非常清楚，完全不需要拆；一個 30 行的如果混了兩個不相關的目標，就應該拆。數字不能反映語義。

後來改為四個語義檢查：

語義檢查：能用「動詞加單一目標」描述嗎？描述時出現「並且」或「以及」，通常需要拆。

修改原因檢查：只有一個原因會觸發修改嗎？兩個不同的業務規則各自可能觸發修改，就是兩個 Ticket。

驗收一致性：所有驗收條件都指向同一個目標嗎？

依賴獨立性：拆分後不會產生循環依賴嗎？

這四個問題比任何量化指標都更接近本質。

驗收條件的標準也要說清楚：「功能正常」不夠，「所有單元測試通過且 dart analyze 輸出 0 個問題」才算。

Ticket 與 Clean Architecture 的對應

我們的專案用 Clean Architecture，Ticket 設計也遵循同樣的分層邏輯。

Interface 定義優先於具體實作。每個功能模組先建 Interface 定義的 Ticket，再建具體實作的 Ticket。這樣外層可以依賴 Interface 先行開發，不被內層實作進度卡住。

分層拆分讓每個 Ticket 待在自己的架構層，Domain、Application、Infrastructure、Presentation 層的 Ticket 不互相混合，也更容易並行執行。

即時 Review：在問題發生當下就解決

傳統 code review 在整個版本完成後進行，此時修正成本很高，問題可能已經影響了許多後續實作。

我們改為每個 Ticket 完成時立即觸發 Review。因為範圍只有單一 Ticket 的相關程式碼，Review 者不需要理解整個版本的脈絡，反饋在數小時內完成，修正成本極低。

Review 涵蓋四個面向：功能正確性（功能實現、驗收條件、邊界情況、錯誤處理）、架構合規性（Clean Architecture、依賴方向、Interface-Driven、架構債務）、測試通過率（單元測試、整合測試、覆蓋率、跳過測試）、文件同步性（Ticket 日誌、設計決策、API 文件、README），共 16 項。

三層文件結構：讓 6000 行問題消失

解決臃腫工作日誌的方式是拆層：

• 主版本日誌：500–1000 行，說明版本目標，提供所有 Ticket 的索引
• Ticket 工作日誌：每個 Ticket 一份，100–200 行，記錄執行過程、Review 結果和完成標記
• 設計決策日誌：300–500 行，記錄設計決策演進，包含廢棄決策的原因

原本 6000 行的文件拆分後變成一份 800 行主日誌加上 12 個 Ticket 日誌加上一份 400 行設計決策日誌，總量降到約 2000 行，資訊查找時間減少大約 80%。

積極派發：發現問題就建 Ticket

這是後來加入的原則，也是這套方法論最核心的轉變。

執行一個 Ticket 時，經常會發現超出原本範圍的情況。以前的做法是「繼續在這個 Ticket 裡處理」或「先記著等有空再說」。前者讓 Ticket 失去單一職責，後者讓問題消失在記憶裡。

積極派發的做法：只要發現超出範圍的新情況，立刻評估性質，建立對應的新 Ticket。阻塞了當前 Ticket 就建子 Ticket 標記依賴；獨立於當前 Ticket 就建新 Ticket 讓兩者並行；是未來的改進就建技術債務 Ticket 記錄起來。

好處是：每個決策都有獨立記錄，保持可追溯性；任務粒度更細，更容易估算；學習點不會淹沒在大 Ticket 裡；一次只專注一件事。

要注意的反模式是「為派發而派發」。積極派發不是讓每件事都變成獨立 Ticket，判斷標準始終是單一職責：情況是否真的超出原 Ticket 範圍？

這套方法論從單一大文件演進到精簡主文加引用網絡，量化指標被單一職責取代，是因為語義比數字更能反映 Ticket 是否設計得好。積極派發的加入，是因為 Ticket 可以成為持續改善的工具，不只是任務追蹤。

如果你的工作日誌越來越長、協作衝突越來越多，從三個問題開始：Ticket 能用「動詞加單一目標」描述嗎？驗收條件是客觀可檢查的嗎？跟其他 Ticket 的依賴關係清楚嗎？

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 的規範，在每個關鍵時機自動執行，開發者甚至可以不知道它存在——但規範確實在發生效用。品質基線從依賴個人紀律，變成由系統保證。

結果就是：Review 的時候發現第一個 Ticket 的架構方向有問題，接下來五個都是建在那個錯誤上面。這時候修正成本已經是即時發現的六到十倍，開發者剛花了三天卻要整個打掉，士氣很難不崩。

後來我們設計了「即時 Review 機制」，核心就一句話：Ticket 完成就 Review，不累積。

三個原則

即時觸發。Ticket 完成的當下就觸發，不是等 Wave 結束，不是等今天收工。錯誤的架構決策會在下一個 Ticket 開始前就污染後續設計，等不起。

30 分鐘完成。這個時間限制是設計訊號：如果一個 Ticket 的 Review 超過一小時，代表那個 Ticket 太大，應該在規劃時就拆。

標準清單。16 項固定檢查項，分功能正確性、架構合規性、測試通過率、文件同步性四類。不管誰 Review、什麼時間點，標準都一樣。

怎麼跑

觸發：完成實作、驗收條件全滿足、測試 100% 通過、靜態分析零錯誤，狀態標為「Review 中」。

執行：30 分鐘內跑完 16 項。功能正確性（10 分鐘）、架構合規性（8 分鐘）、測試通過率（5 分鐘）、文件同步性（2 分鐘），最後 5 分鐘記錄結果。

偏差糾正：發現問題就照固定流程走——暫停、記錄根因、建修正 Ticket、執行、再 Review。流程結構化是關鍵，「發現問題不知怎麼辦」是問題被忽略的主因。

問題分三級

P0（阻塞）：功能錯誤、架構偏差、測試失敗。必須在 Review 通過前修正。

P1（重要）：邊界處理缺失、文件不完整。建 Ticket 追蹤，當前 Ticket 可先通過。

P2（建議）：命名改善、程式風格。記錄即可。

分級的目的：Review 保持快速，重要問題不被跳過。

超時是訊號

Ticket 完成後 2 小時內開始 Review，目標 30 分鐘，最長 1 小時。超時代表 Ticket 範圍太大，不是 Reviewer 的問題。這個標準幫助我們持續校正 Ticket 的粒度。

最明顯的變化

導入前，「Review」這件事是模糊的——知道應該做，但時機不固定、標準不一、出了問題也不清楚怎麼處理。

導入後，偏差被控制在單一 Ticket 的範圍內，沒機會擴散。另一個意外收穫是，16 項清單讓我們對「品質」有了共同語言，Review 結果可以比較、可以追蹤，不再靠個人感覺。

即時 Review 的目的是把修正成本壓到最低。問題在最小範圍被抓到，代價才會真的小。

需要一套方法讓主線程始終掌握全局，同時讓各代理人在清楚的規格下專注執行。這就是這套方法論的起點。

三大核心原則

主線程只分派、不寫程式碼。 主線程的價值在於全局視野和決策，一旦它開始親自動手，統籌能力就消失了。

任務符合 Atomic Ticket 原則：一個 Action 加一個 Target。「實作 BookEnrichmentProcessor」是好的任務；「實作資料處理」太模糊。任務夠原子，才能精確評估、精確驗收。

100% 測試通過率，沒有例外。 我們試過接受「暫時跳過」，結果累積的債務比預期高出很多倍。現在的規則是：任何檢查失敗就等於階段未完成。

Agent 角色定義

主線程（rosemary-project-manager）負責分派任務、監控進度，處理代理人回報的升級請求。禁止親自閱讀或修改程式碼，不繞過子代理人直接操作。

TDD 四個階段各有專責代理人：Phase 1 由 lavender-interface-designer 做功能設計，Phase 2 由 sage-test-architect 做測試設計，Phase 3a 由 pepper-test-implementer 制定語言無關的實作策略，Phase 3b 由 parsley-flutter-developer 執行 Flutter 程式碼，Phase 4 由 cinnamon-refactor-owl 做重構評估。

五重文件系統

文件混亂是任務失敗的隱性原因之一。代理人不知道去哪找資訊，或者基於過時文件做了錯誤假設。

每份文件只回答一個問題：CHANGELOG 回答「這個版本做了什麼？」、todolist.yaml 回答「還有哪些問題要處理？」、worklog 回答「這個版本要達成什麼目標？」、ticket 回答「這個任務怎麼執行的？」、error-patterns 回答「之前遇過類似問題嗎？」

細節下沉原則確保 worklog 只記錄大方向，具體細節都沉到 ticket 層級。

任務分派前的準備度檢查

這是從失敗中學到的最重要教訓：分派任務前，先確認代理人有足夠資訊執行。

四個面向：API 規格和設計文件是否具體到類別定義？測試規格是否存在？完成標準是否可測量？潛在風險和依賴關係是否梳理清楚？

任何一個回答為否，就先建立對應文件再分派。我們早期跳過這步驟，代理人執行到一半才發現關鍵資訊缺失，修復成本遠高於事前準備。

階段完成的強制驗證

每個開發階段完成後，必須通過五項強制檢查：

• flutter analyze 零 error
• 無「Target of URI doesn’t exist」，100% package 格式導入
• 測試 100% 通過，覆蓋率不得下降
• 無功能重複的服務實作
• 檔案位置符合 Clean Architecture，依賴方向正確

任何一項失敗就等於階段未完成。不允許「暫時跳過」。

技術債務的責任分工

Phase 4 的 cinnamon-refactor-owl 必須在重構評估中識別所有技術債務，用標準格式記錄到工作日誌，執行 /tech-debt-capture 建立 Ticket，確認 Ticket 成功建立後才能完成 Phase 4。

這個設計解決一個常見問題：技術債務往往被口頭記錄，然後就消失了。現在強制要求轉化為可追蹤的 Ticket。

資訊流動，不是固定計畫

v0.11.0 實戰中最深刻的學習：敏捷開發是持續發現、快速調整的動態過程。

Phase 2 測試設計讓我們提前識別了 80% 的實作問題。sage-test-architect 在設計測試時發現 BookEnrichmentData 放在錯誤的架構層，同時發現 Domain 服務層完全缺失，需要 28 個 TDD 新建測試。

這個發現改變了整個計畫，原估 4-6 天調整為 6-7 天。我們面對兩個選擇：維持原時程但降低測試覆蓋率，或延長時程確保品質。

選了後者，理由是 Domain 層是核心基礎不能妥協。最終結果：71 個測試 100% 通過，時程只多了 1 天。

這個案例確立了一個原則：Phase 間的資訊必須雙向流動。Phase 2 發現的問題不只影響 Phase 3，也必須回饋給 Phase 1 更新設計文件。「Phase 1 完成就凍結」是錯誤模式，每個 Phase 的產出都是基礎版本，隨著後續發現持續更新。

架構衝突的零容忍

發現 BookEnrichmentData 位置錯誤後，主線程立即停止 Phase 3 啟動，指派緊急遷移任務：移動檔案、更新所有 import 引用、執行測試確認無錯誤、提交變更。實際花了 0.4 小時完成。

如果在 Phase 3 已基於錯誤架構實作多個任務後才修正，修復成本至少高出十倍。

動態文件更新的觸發點

三種情況必須立即觸發文件更新：

架構變更時——類別位置調整、介面簽名變更，必須同步更新所有引用該類別的任務和設計文件。

測試設計發現時——識別新測試用例、發現缺失的邊界條件，更新對應實作任務的驗收標準。

實作階段發現時——技術方案調整、新增輔助類別，更新後續相關任務的參考實作。

核心洞察

AI 協作開發的核心挑戰是：如何讓多個 AI 代理人在有限的上下文中，基於共享的知識庫，做出一致且高品質的決策。

五重文件系統、Atomic Ticket、準備度檢查、強制驗證閘門——這些都是為了解決「資訊在 AI 協作中如何可靠流動」這個根本問題。

這套方法論仍在持續演進。每個版本都帶來新的學習，新的 error-pattern，新的流程調整。

認知負擔：一切的出發點

人類工作記憶有限，大約一次只能處理七個項目（Miller’s Law）。看到縮寫要在腦中展開、看到模糊詞要猜測含義、看到長函式要分段記憶——這些都是認知負擔。

自然語言化的目標很簡單：讓程式碼像讀文章一樣自然，把讀者的認知資源留給理解業務邏輯，而不是解碼程式碼本身。

第一原則：命名要能直接讀懂

函式命名

1// 錯誤：不知道在做什麼
2void process(data) {}
3void handle(item) {}
4
5// 正確：一眼看懂
6void calculateBookReadingProgress(Book book) {}
7void validateUserRegistrationData(User user) {}
8void enrichBookMetadataFromExternalSource(Book book) {}

變數命名

1// 錯誤：縮寫和多用途
2var usr = getCurrentUser();
3var data = loadUserData();
4data = processBookData(); // 100行後同一變數換了意思
5
6// 正確：明確且專用
7final authenticatedUser = getCurrentUser();
8final userProfileData = loadUserData();
9final enrichedBookMetadata = processBookData();

類別命名

1// 錯誤：說不清在做什麼
2class Manager {}
3class Handler {}
4class BookDAO {}
5
6// 正確：業務職責一目了然
7class BookMetadataEnrichmentService {}
8class UserRegistrationValidator {}
9class LibraryBookSearchEngine {}

布林命名

布林變數應該能讀成問句，在 if 裡就能自然被理解：

1bool isValid;      // "Is valid?"
2bool hasPermission; // "Has permission?"
3bool canEdit;       // "Can edit?"
4
5// 不好：語意不清
6bool permission;

常見命名反模式

• 匈牙利命名法：strName, intCount — 型別系統自己會提供型別資訊，名稱不用重複
• 無意義前綴：theUser, aBook — 沒帶來任何資訊，直接刪掉
• 過度縮寫：usrMgr — 迫使讀者展開，userManager 更自然
• 數字後綴：user1, user2 — 改成 primaryUser, secondaryUser 才說明關係

第二原則：函式控制在五到十行

超過十行通常表示函式承擔了多重職責。判斷是否需要拆分的最快方法：函式名稱裡有「和」或「或」的話，一定要拆。

 1// 錯誤：15行，三種職責混在一起
 2Book processBook(String isbn) {
 3  if (isbn.length != 13) throw ArgumentError('Invalid ISBN');
 4  if (!isValidISBNChecksum(isbn)) throw ArgumentError('ISBN checksum failed');
 5  final apiResponse = httpClient.get('/books/$isbn');
 6  if (apiResponse.statusCode != 200) throw Exception('API failed');
 7  final bookData = json.decode(apiResponse.body);
 8  return Book.create(
 9    id: BookId(generateUniqueId()),
10    title: BookTitle(bookData['title']),
11    source: BookSource.external(),
12  );
13}
14
15// 正確：拆成三個單一職責函式
16Book createBookFromISBN(String isbn) {
17  validateISBNFormat(isbn);
18  final bookData = fetchBookDataFromExternalAPI(isbn);
19  return buildBookFromExternalData(bookData);
20}
21
22void validateISBNFormat(String isbn) {
23  if (isbn.length != 13) throw ArgumentError('ISBN must be 13 digits');
24  if (!isValidISBNChecksum(isbn)) throw ArgumentError('ISBN checksum validation failed');
25}
26
27Map<String, dynamic> fetchBookDataFromExternalAPI(String isbn) {
28  final apiResponse = httpClient.get('/books/$isbn');
29  if (apiResponse.statusCode != 200) throw Exception('Failed to fetch book data');
30  return json.decode(apiResponse.body);
31}
32
33Book buildBookFromExternalData(Map<String, dynamic> bookData) {
34  return Book.create(
35    id: BookId(generateUniqueId()),
36    title: BookTitle(bookData['title']),
37    source: BookSource.external(),
38  );
39}

第三原則：一個變數只做一件事

同一個變數在不同地方承載不同意義，是我見過最難追蹤的 bug 來源之一。

 1// 錯誤：同一變數三種身分
 2var result = validateUser(userData);
 3if (result.isValid) {
 4  result = processPayment(paymentData);
 5  if (result.success) {
 6    result = updateDatabase(result.data);
 7  }
 8}
 9
10// 正確：每個變數都有自己的名字
11final userValidationResult = validateUser(userData);
12if (userValidationResult.isValid) {
13  final paymentProcessingResult = processPayment(paymentData);
14  if (paymentProcessingResult.success) {
15    final databaseUpdateResult = updateDatabase(paymentProcessingResult.data);
16  }
17}

變數生命週期也要管：

 1// 錯誤：books 在100行間一直換狀態
 2void processLibraryBooks() {
 3  var books = getAllBooks();
 4  books = filterAvailableBooks(books);
 5  books = sortBooksByTitle(books);
 6}
 7
 8// 正確：每個階段的狀態都有名字
 9void processLibraryBooks() {
10  final allLibraryBooks = getAllBooks();
11  final availableBooks = filterAvailableBooks(allLibraryBooks);
12  final sortedAvailableBooks = sortBooksByTitle(availableBooks);
13}

第四原則：用事件驅動表達業務流程

複雜的業務流程往往會寫成一個大函式，裡面塞滿 if/else。問題不在於 if/else 本身，而是把不同職責的邏輯混在一起。

 1// 錯誤：驗證、API呼叫、結果處理全混在一起
 2void submitForm(FormData formData) {
 3  if (formData.name.isEmpty) { showErrorMessage('姓名不能為空'); return; }
 4  if (formData.email.isEmpty) { showErrorMessage('Email不能為空'); return; }
 5  if (!isValidEmail(formData.email)) { showErrorMessage('Email格式不正確'); return; }
 6  final apiResult = submitToAPI(formData);
 7  if (apiResult.success) {
 8    showSuccessMessage('提交成功');
 9    navigateToSuccessPage();
10    clearForm();
11  } else {
12    showErrorMessage('提交失敗：' + apiResult.error);
13    highlightErrorFields(apiResult.errorFields);
14  }
15}
16
17// 正確：每個事件有自己的函式
18void submitUserRegistrationForm(UserRegistrationFormData formData) {
19  final validationResult = validateUserRegistrationData(formData);
20  if (validationResult.isValid) {
21    handleSuccessfulValidation(formData);
22  } else {
23    handleValidationFailure(validationResult.errors);
24  }
25}
26
27ValidationResult validateUserRegistrationData(UserRegistrationFormData formData) {
28  final errors = <ValidationError>[];
29  if (!isValidUserName(formData.name)) errors.add(ValidationError.invalidUserName());
30  if (!isValidUserEmail(formData.email)) errors.add(ValidationError.invalidEmail());
31  return ValidationResult.fromErrors(errors);
32}
33
34void handleSuccessfulValidation(UserRegistrationFormData formData) {
35  submitUserRegistrationToAPI(formData)
36    .then(handleSuccessfulAPIResponse)
37    .catchError(handleAPIFailure);
38}
39
40void handleValidationFailure(List<ValidationError> errors) {
41  displayValidationErrors(errors);
42  highlightInvalidFormFields(errors);
43}

狀態機也是同樣的道理：

 1// 錯誤：一個函式根據狀態做完全不同的事
 2void updateBookStatus(Book book, String newStatus) {
 3  if (newStatus == 'available') {
 4    book.status = BookStatus.available;
 5    book.borrower = null;
 6    updateSearchIndex(book);
 7    notifyWaitingUsers(book);
 8  } else if (newStatus == 'borrowed') {
 9    book.status = BookStatus.borrowed;
10    book.borrowDate = DateTime.now();
11    sendBorrowConfirmation(book);
12  } else if (newStatus == 'maintenance') {
13    book.status = BookStatus.maintenance;
14    removeFromSearchIndex(book);
15    notifyMaintenanceTeam(book);
16  }
17}
18
19// 正確：每個事件獨立
20void handleBookReturnEvent(Book book) {
21  executeBookReturn(book);
22  notifyBookBecameAvailable(book);
23}
24
25void handleBookBorrowEvent(Book book, User borrower) {
26  executeBookBorrow(book, borrower);
27  confirmBorrowingToUser(book, borrower);
28}
29
30void handleBookMaintenanceEvent(Book book) {
31  markBookForMaintenance(book);
32  notifyMaintenanceRequired(book);
33}

第五原則：可讀性優於簡潔性

程式碼的價值排序：正確性 > 可讀性 > 可維護性 > 簡潔性。

行數從來不是指標，清晰才是：

 1// 錯誤：為了少寫幾行犧牲可讀性
 2books.where((b) => b.s == 'a' && b.p > 100).map((b) => b.t).toList();
 3
 4// 正確：每一步都說清楚在做什麼
 5final availableBooksWithMoreThan100Pages = allBooks
 6    .where((book) => book.status == BookStatus.available)
 7    .where((book) => book.pageCount > 100)
 8    .toList();
 9
10final bookTitlesForDisplay = availableBooksWithMoreThan100Pages
11    .map((book) => book.title.value)
12    .toList();

如何驗證程式碼品質

陌生人測試：讓不熟悉這段程式碼的工程師讀。5分鐘內能理解主要邏輯算合格，需要解釋才能理解就要重寫。

自然語言測試：把程式碼翻譯成中文說出來。翻譯流暢自然算合格，說不清楚就改命名。

六個月後測試：假設半年後的自己要修改這段程式碼，能快速找到位置算合格，不敢動怕壞掉就要重新設計。

每一行程式碼都是一句話，每個函式都是一個段落。好的程式碼是對未來維護者的體貼——不只是風格偏好，而是降低維護成本的工程決策。

這讓我們重新思考：註解到底是為了誰而寫的？

註解的本質

程式碼註解不是程式的解釋員。它的存在是為了保護原始設計意圖，提供無法從程式碼本身推斷出來的訊息。

不應該做的：解釋程式在做什麼（好的程式碼應該自己說話）、描述函式使用方法（那是文件的工作）、充當 TODO 清單。

應該做的：作為需求保護器，防止維護時破壞原始需求；記錄設計意圖，保存業務邏輯的考量；提供維護指引，明確標示約束條件；建立程式碼與需求規格的連結。

第一原則：程式碼本身必須自說明

如果程式碼需要靠註解才能被理解，首先應該改善的是程式碼，不是補更多解釋。

process(Book book) 需要一行「檢查書籍狀態並更新進度」的註解，但如果直接命名為 updateReadingProgressWhenStatusChanges(Book book)，解釋性的註解就不需要了。此時真正值得寫下來的，是這個函式背後的業務需求和約束條件：

1void updateReadingProgressWhenStatusChanges(Book book) {
2  // 需求：UC-005 閱讀進度管理
3  // 當使用者標記書籍為「閱讀中」時，自動設定進度為 0%
4  // 當使用者標記為「已完成」時，自動設定進度為 100%
5  // 約束：不可覆蓋使用者手動設定的進度值
6}

變數也一樣：final data = book.getInfo() 毫無意義，final enrichedBookMetadata = book.getMetadataWithEnrichment() 就完全自說明了。

驗證標準：移除所有註解後，如果仍能理解程式邏輯，程式碼達標。需要猜測變數含義就重新命名，無法確定函式目的就拆分函式。

第二原則：註解記錄的是需求脈絡

程式碼自說明，不代表不需要註解——需要的是不同種類的註解。

每個業務邏輯函式都應該追溯到明確的需求來源：

1/// 需求：UC-003.2 書籍分類管理
2/// 使用者可以為書籍設定多個標籤進行分類
3/// 約束：標籤名稱不可重複，最多 10 個標籤
4void addTagToBook(BookId bookId, Tag tag) {
5  // 實作...
6}

這條註解告訴維護者：這個函式的存在依據是 UC-003.2，不可以被打破的規則是標籤不可重複且最多十個。

書籍狀態的轉換順序是業務規則，不是技術細節，也應該記錄：

1/// 需求：BR-001 書籍狀態轉換規則
2/// 書籍狀態變更順序：初始 → 資訊補充中 → 資訊補充完成 → 可用
3/// 約束：不可跳過中間狀態，不可逆向轉換
4/// 例外：管理員可以直接設定為任何狀態
5BookStatus transitionBookStatus(BookStatus current, BookStatus target) {
6  // 實作...
7}

設計決策也要記錄。為什麼選懶載入加分頁？因為有效能需求：

1/// 需求：NFR-002 效能需求
2/// 書庫載入時間不可超過 2 秒
3/// 設計決策：採用懶載入 + 分頁載入策略
4/// 影響：首次載入只載入 20 本書，滾動時動態載入
5List<Book> loadLibraryWithPagination(int page, int pageSize) {
6  // 實作...
7}

一個完整的業務邏輯註解必須包含：需求來源（UC 或 BR 編號）、業務描述、約束條件、以及修改此邏輯會影響哪些功能。

第三原則：維護指引必須明確

好的維護指引讓維護者修改程式碼之前就知道會影響哪裡。不應該隨意修改的邏輯，要主動發出警告：

1/// 需求：UC-001.3 書籍唯一性檢查
2/// 同一書庫內不可有相同 ISBN 的書籍
3/// 警告：此邏輯關聯到資料一致性，修改前必須檢查：
4/// - 書籍匯入流程 (ImportBookService)
5/// - 書籍合併功能 (BookMergeService)
6/// - 資料庫索引設計 (book_isbn_unique_index)
7bool isDuplicateBook(String isbn, LibraryId libraryId) {
8  // 實作...
9}

預期會被擴展的邏輯，要提供擴展指引：

1/// 需求：UC-004 書籍搜尋功能
2/// 支援書名、作者、標籤的模糊搜尋
3/// 擴展指引：新增搜尋條件時必須：
4/// 1. 更新 SearchCriteria 值物件
5/// 2. 修改索引策略以維持效能
6/// 3. 更新搜尋測試案例涵蓋新條件
7List<Book> searchBooks(SearchCriteria criteria) {
8  // 實作...
9}

模組間的耦合關係也需要標示：

 1/// 需求：UC-006 借閱管理
 2/// 計算書籍歸還到期日
 3/// 相依性警告：此邏輯與以下模組緊密耦合
 4/// - LoanReminderService（提醒計算）
 5/// - OverdueBookDetector（逾期偵測）
 6/// - LibraryStatistics（統計計算）
 7/// 修改歸還期限計算會影響上述所有模組
 8DateTime calculateDueDate(DateTime loanDate, int loanPeriodDays) {
 9  // 實作...
10}

第四原則：結構一致的標準格式

把上面的原則整合成一個標準格式：

1/// 需求：[需求編號] [簡短描述]
2/// [詳細業務描述，說明使用者需求]
3/// 約束：[限制條件和邊界規則]
4/// [維護指引：修改須知、相依性警告、擴展要求]
5[函式簽名]

複雜業務邏輯的範例：

 1/// 需求：UC-007.1 閱讀統計分析
 2/// 計算使用者的閱讀速度和預估剩餘時間
 3/// 約束：只統計狀態為「閱讀中」的書籍，頁數必須大於 0
 4/// 計算邏輯：(已讀頁數 / 實際閱讀時間) = 閱讀速度（頁/小時）
 5/// 維護指引：修改計算公式會影響：
 6/// - 閱讀目標設定功能
 7/// - 個人化推薦系統
 8/// - 學習分析報表
 9/// 相依模組：ReadingProgressTracker, BookMetadata, UserPreferences
10ReadingSpeed calculateReadingSpeed(
11  ReadingProgress progress,
12  BookMetadata metadata,
13  Duration actualReadingTime
14) {
15  // 實作...
16}

禁止的註解模式

最常見的錯誤是重述程式碼行為。「設定書籍標題」對應的程式碼是 book.setTitle(newTitle)，完全多餘。「使用 Map 快速查找避免 O(n) 複雜度」也一樣，有經驗的開發者看程式碼就知道。

UI 層特別容易出現這類問題。以 Widget 選取回饋設計為例，錯誤做法是列出技術細節：

 1/// 反例：重複描述程式碼內容
 2/// BookListItem - 書庫列表項目 Widget
 3///
 4/// 視覺設計：
 5/// - 陰影刻痕變化（凸起→凹陷）
 6/// - AnimatedContainer 200ms 過渡動畫
 7///
 8/// 觸覺回饋：
 9/// - 選擇時：HapticFeedback.selectionClick()
10/// - 取消選擇：HapticFeedback.lightImpact()
11class BookListItem extends StatelessWidget {
12  // ...
13}

這些看程式碼就能看到。真正有價值的是背後的決策依據：

 1/// 【需求來源】UC-05: 雙模式書庫展示切換 - 書籍選擇互動
 2/// 【規格文件】docs/ui_design_specification.md#book-selection-feedback
 3/// 【設計決策】採用方案C-1基礎版 - 極簡視覺回饋設計
 4/// 【為什麼選擇陰影刻痕變化】
 5/// - 不影響文字可讀性：避免背景色干擾閱讀體驗
 6/// - 符合無障礙設計：不依賴顏色作為唯一視覺提示
 7/// 【為什麼選擇差異化觸覺回饋】
 8/// - 選中 vs 取消必須有不同的觸覺回饋類型
 9/// - selectionClick 提供明確的「確認」感受
10/// - lightImpact 提供輕微的「狀態變更」提示
11/// 【修改約束】
12/// - 觸覺回饋時機不可調換（與使用者預期一致）
13/// - 陰影變化動畫時長需保持 < 250ms（符合 Material Design 規範）
14/// 【維護警告】
15/// - 此 Widget 被 3 個書庫頁面使用
16/// - 修改視覺回饋會影響整體使用者體驗一致性
17class BookListItem extends StatelessWidget {
18  // ...
19}

模糊描述也不可取——「處理書籍相關邏輯」等於沒有描述。過時的 TODO 必須清除，否則會讓人以為某個功能還沒實作。

第五原則：事件驅動架構的特殊需求

在 UseCase 或 Domain 層，函式名稱包含 handle*、on*、process*、emit*、dispatch*，或回傳類型為 Future<>、Stream<> 的函式，都需要標示其在事件流中的角色：

 1/// 【需求來源】UC-01: Chrome Extension 匯入書籍資料
 2/// 【規格文件】docs/app-requirements-spec.md#chrome-extension-import
 3/// 【設計方案】方案C-1基礎版 (v0.12.7 Phase 1)
 4/// 【工作日誌】docs/work-logs/v0.12.7.md - 方案研究和設計決策
 5/// 【事件類型】BookAdded 事件處理
 6/// 【修改約束】修改時需確保事件流完整性，避免影響上游訂閱者
 7/// 【維護警告】此函式被 3 個 UseCase 依賴，修改前需檢查影響範圍
 8Future<void> handleBookAdded(BookAddedEvent event) async {
 9  // 實作...
10}

以 _ 開頭的私有輔助函式（_isValid*、_format*、_convert*、_validate* 等）不包含業務邏輯，豁免詳細業務註解。

第六原則：Widget 獨立性的明確標示

非私有命名（不以 _ 開頭）、繼承自 StatefulWidget、ConsumerWidget、StreamBuilder 或 FutureBuilder 的 Widget，具備獨立狀態，需要明確記錄需求來源和修改約束：

 1/// 【需求來源】UC-05: 雙模式書庫展示切換
 2/// 【規格文件】docs/ui_design_specification.md#book-list-item
 3/// 【設計方案】方案C-1基礎版 - 陰影刻痕變化 + 觸覺回饋
 4/// 【工作日誌】docs/work-logs/v0.12.7.md - UI 互動設計
 5/// 【Widget 類型】獨立狀態管理 Widget
 6/// 【修改約束】此 Widget 具備獨立狀態，下層刷新不觸發上層重建
 7/// 【維護警告】修改前需確認子 Widget 依賴關係
 8class BookListItem extends StatefulWidget {
 9  // 實作...
10}

私有的 StatelessWidget（如 _BookTitleText、_ProgressBar）和純展示型組件，只展示上層傳遞的資料，豁免詳細業務邏輯註解。

第七原則：工作日誌與規格文件的追溯鏈

設計決策涉及複雜研究或多方案比較時，幾行註解無法承載所有背景，需要建立追溯鏈：

1/// 【工作日誌】docs/work-logs/v0.12.7.md - 方案C-1基礎版設計

維護者能循著這條鏈找到完整的決策記錄。業務邏輯也可以指向規格文件章節：

1/// 【規格文件】docs/app-requirements-spec.md#section-name
2/// 【規格文件】docs/event-driven-architecture-design.md#event-flow

這讓程式碼成為整個需求、設計、實作文件體系的一部分，而不是孤立的存在。

品質驗證：兩個測試

可執行性測試：維護者看到這條註解後，能理解業務需求嗎？修改約束明確嗎？需求來源可以追溯嗎？

必要性測試：移除這條註解後，是否會遺失業務脈絡？如果移除後仍能理解程式邏輯，就要檢查它是否只是在重述程式碼。如果內容過時，直接刪除，不要保留會誤導維護者的假資訊。

結論

好的程式碼是自說明的，但好的業務系統還需要一個跨越時間的溝通機制，讓六個月後接手的人能理解每個設計決策背後的原因，不會在不了解背景的情況下破壞原始設計。

這就是我們對程式碼註解的重新定位——需求的守護者。

這是需求保護機制，不是文書工作。

問題不在架構，在派工

Clean Architecture 告訴你「怎麼組織程式碼」，但沒告訴你「怎麼拆 Ticket」。每次 Code Review 都像翻地層，從 Widget 翻到 Entity，不知道從哪開始看；Domain 沒穩定，UI 那層就沒辦法測，整個流程互相等待。

這個銜接點，需要一套專門處理 Ticket 拆法的方法論。

核心原則：一張 Ticket，一個層級

一個 Ticket 只應該修改單一架構層級的程式碼，變更的原因單一且明確。

SRP 說一個類別只有一個改變的原因，我們把它升一層：一張 Ticket 也只有一個改變的原因。

聽起來嚴苛，但實際跑起來好處很直接：Code Review 只需要理解一層的邏輯、測試不需要拉起整個系統、PR 影響範圍可預測，壞掉的時候更容易定位。

我們怎麼定義「五層」

傳統 Clean Architecture 四層中，Interface Adapters 同時處理「事件邏輯」和「資料轉換」，職責太雜，我們把它細分成五層：

Layer 1 — UI/Presentation：純視覺呈現，Widget 長什麼樣。變更原因只有一個：設計稿改了。

Layer 2 — Application/Behavior：事件處理和 UI 邏輯。按鈕點擊怎麼處理、Loading 狀態怎麼切換、Domain Entity 怎麼轉成 ViewModel。Flutter 對應 Controller 和 ViewModel。

Layer 3 — UseCase：業務流程編排。協調多個 Repository 和 Domain Service，把業務步驟串起來。不管 UI 怎麼顯示，也不管資料庫怎麼存。

Layer 4 — Domain Events/Interfaces：定義契約。Repository 抽象介面、Domain Event 結構、跨層 DTO。只定義，不實作。

Layer 5 — Domain Implementation：核心業務邏輯。Entity、Value Object、Domain Service、業務規則驗證。整個系統最穩定的部分。

Infrastructure 層（資料庫、外部 API、EventBus）不納入層級隔離，它的變更驅動是技術決策，不是業務需求，Ticket 設計上本來就獨立對待。

從外而內，而不是從內而外

許多教材說「先設計 Domain 再往外做」，但實際開發時，我們發現從外而內更能控制風險。

原因很簡單：Layer 1 UI 壞掉只影響視覺，Layer 5 Domain 邏輯壞掉影響整個系統的業務規則。從影響最小的地方開始，需求偏差時調整成本低；一開始就動 Domain，到了 UI 才發現需求理解有誤，代價就大得多。

實作順序是 Layer 1 → Layer 2 → Layer 3 → Layer 4 → Layer 5，每層完成後立即驗證。

有幾個例外：架構遷移要先定義 Layer 4 介面契約（Interface-First），讓外層修改有穩定依據；安全性修復從 Layer 5 往外；Bug Fix 從問題根源那層開始。

Ticket 拆分的量化標準

幾個判斷指標：修改檔案數 1 到 3 個（最多 5 個）、預估開發時間 2 到 8 小時（超過一天就拆）、修改層級嚴格限制 1 層、新增程式碼測試覆蓋率 100%。

數字可以商議，但有標準就不用靠直覺判斷「感覺差不多」。

反面教材：

1Ticket：實作書籍收藏功能
2
3變更範圍：
4- lib/ui/pages/book_detail_page.dart       (Layer 1)
5- lib/application/controllers/book_detail_controller.dart  (Layer 2)
6- lib/usecases/add_book_to_favorite_usecase.dart  (Layer 3)
7- lib/domain/entities/favorite.dart        (Layer 5)

這張 Ticket 跨了四層，PR 送出來沒人知道從哪開始審，測試也很難設計。正確做法是拆成四張各自獨立的 Ticket，按依賴順序執行。

如何判斷一段程式碼屬於哪一層

最常模糊的是 Layer 2 和 Layer 3 之間的邊界。判斷流程：

1. 在渲染 UI 元素？→ Layer 1
2. 在處理 UI 事件、控制 UI 狀態、或把 Domain 資料轉成 UI 格式？→ Layer 2（把 Domain Exception 轉成 ErrorViewModel 也是這層的事）
3. 在協調多個 Domain Service 或 Repository、編排業務步驟？→ Layer 3
4. 在定義介面契約或事件結構？→ Layer 4
5. 在實作業務規則或定義 Entity？→ Layer 5
6. 以上都不是 → Infrastructure 層

這套方法論的定位

這是 Clean Architecture 的「派工指南」。Clean Architecture 告訴你程式碼怎麼組織，層級隔離告訴你 Ticket 怎麼拆、按什麼順序做。

它和 Atomic Ticket 方法論也不衝突：Atomic Ticket 強調職責維度（一個 Action 加一個 Target），層級隔離強調層級維度（一個 Ticket 只動一層），兩個維度同時符合才是最完整的 Ticket 設計。

緊急 Hotfix、原型開發、一次性腳本不需要強行套用。但在正常功能開發和重構中，跑起來之後的感覺是：每次把一個大需求拆成按層排好的 Ticket 序列，就等於把架構邊界重新確認了一遍。

為了提升AI開發前端的穩定性，我想依賴MVVM確實定義前端的狀態跟模型，以及責任分層，這樣可以降低除錯的複雜度

核心概念

ViewModel 定位

ViewModel 是 MVVM 架構的核心層，負責：

1. Domain → UI 轉換：將 Domain 模型轉為 UI 需要的格式
2. UI 狀態管理：管理 Widget 狀態和互動邏輯
3. Provider 定義：定義 Riverpod Provider 供 Widget 使用
4. UI 專用計算邏輯：提供顏色、圖標、格式化文字等 UI 屬性

MVVM 分層原則

 1┌─────────────────────────────────────────┐
 2│ Presentation Layer (UI 層)              │
 3├─────────────────────────────────────────┤
 4│ Widget (Page/Extensions)                │
 5│ - 純 UI 組裝，無業務邏輯                 │
 6│ - 使用 ViewModel Provider 取得資料       │
 7│ - 顯示 ViewModel 提供的 UI 屬性          │
 8├─────────────────────────────────────────┤
 9│ ViewModel                               │
10│ - Domain → UI 轉換                       │
11│ - UI 狀態管理                            │
12│ - UI 專用計算邏輯                        │
13│ - Provider 定義                          │
14├─────────────────────────────────────────┤
15│ Mapper                                  │
16│ - Domain 模型 → ViewModel 轉換邏輯       │
17├─────────────────────────────────────────┤
18│ Domain Layer (領域層)                    │
19│ - 業務邏輯                               │
20│ - Domain 模型                            │
21│ - Domain 服務                            │
22└─────────────────────────────────────────┘

ViewModel 命名規範

命名格式

格式：[Feature]ViewModel

範例：

• EnrichmentProgressViewModel - 補充進度顯示
• ChromeExtensionImportViewModel - Chrome Extension 匯入
• LibraryDisplayViewModel - 書庫展示
• AdvancedSearchViewModel - 進階搜尋

檔案位置

標準路徑：lib/presentation/[feature]/[feature]_viewmodel.dart

範例：

1lib/presentation/
2├── import/
3│   └── chrome_extension_import_viewmodel.dart
4├── library/
5│   ├── library_viewmodel.dart
6│   └── library_display_page.dart
7└── search/
8    └── advanced_search_viewmodel.dart

ViewModel 職責定義

包含的職責

1. Domain → UI 轉換

將 Domain 模型轉換為 UI 需要的格式：

1/// Domain 來源
2final EnrichmentProgress domainProgress;
3
4/// UI 專用欄位（計算屬性）
5String get displayStatus => _mapStatus();
6IconData get statusIcon => _mapIcon();
7Color get progressColor => _mapColor();

2. UI 狀態管理

管理 Widget 需要的狀態：

1class EnrichmentProgressViewModel {
2  // 狀態欄位
3  final EnrichmentProgress domainProgress;
4  final List<Book> failedBooks;
5
6  // UI 控制狀態
7  bool get showFailedBooks => failedBooks.isNotEmpty;
8  bool get canRetry => domainProgress.isComplete && failedBooks.isNotEmpty;
9}

3. Provider 定義

定義 Riverpod Provider 供 Widget 使用：

1final enrichmentProgressViewModelProvider =
2  StreamProvider.family<EnrichmentProgressViewModel, String>(
3    (ref, operationId) {
4      // Provider 邏輯
5    },
6  );

4. UI 專用計算邏輯

提供 UI 需要的格式化資料：

 1/// 格式化的摘要文字
 2String get summaryText =>
 3  '已處理 ${domainProgress.processedBooks}/${domainProgress.totalBooks} 本';
 4
 5/// 進度顏色（根據狀態決定）
 6Color get progressColor {
 7  if (domainProgress.failedEnrichments > 0) return Colors.orange;
 8  if (domainProgress.isComplete) return Colors.green;
 9  return Colors.blue;
10}

不包含的內容

1. Widget 程式碼

 1// 反例：ViewModel 中包含 Widget
 2class EnrichmentProgressViewModel {
 3  Widget buildProgressBar() {  // 違規
 4    return LinearProgressIndicator(...);
 5  }
 6}
 7
 8// 正例：Widget 在 Extension 中
 9extension EnrichmentProgressWidgets on Widget {
10  Widget enrichmentProgressBar(EnrichmentProgressViewModel vm) {
11    return LinearProgressIndicator(
12      value: vm.domainProgress.percentageComplete / 100,
13      color: vm.progressColor,
14    );
15  }
16}

2. 直接依賴 Flutter 框架（除 ChangeNotifier）

 1// 反例：依賴 Flutter Material
 2import 'package:flutter/material.dart';
 3
 4class MyViewModel {
 5  BuildContext? context;  // 違規
 6}
 7
 8// 正例：使用 Dart 原生類型
 9class MyViewModel {
10  Color progressColor;  // 可以使用 Color（來自 dart:ui）
11  IconData statusIcon;  // 可以使用 IconData
12}

3. 業務邏輯

 1// 反例：在 ViewModel 中執行業務邏輯
 2class EnrichmentProgressViewModel {
 3  Future<void> enrichBook(Book book) {
 4    // 呼叫 API、驗證資料、儲存到資料庫
 5    // 這些是 Domain 層的職責
 6  }
 7}
 8
 9// 正例：業務邏輯在 Domain Service
10class IBookInfoEnrichmentService {
11  Future<EnrichedBookInfo> enrichBookInfo(Book book);
12}
13
14// ViewModel 只負責狀態管理
15class EnrichmentProgressViewModel {
16  final EnrichmentProgress domainProgress;
17  // 不包含業務邏輯
18}

ViewModel 結構範本

基本結構

 1/// UI 層專用的 [Feature] 顯示模型
 2///
 3/// 職責：
 4/// - 將 Domain 模型轉換為 UI 需要的格式
 5/// - 提供 UI 專用的計算屬性
 6/// - 管理 UI 狀態
 7///
 8/// 需求：[需求編號]
 9class [Feature]ViewModel {
10  // =============================================================================
11  // Domain 來源（不可變）
12  // =============================================================================
13
14  /// Domain 模型來源
15  final [DomainModel] domainModel;
16
17  /// 額外的 Domain 資料（如失敗清單）
18  final List<[Entity]> additionalData;
19
20  // =============================================================================
21  // UI 專用欄位（計算屬性）
22  // =============================================================================
23
24  /// 狀態顯示文字
25  String get displayStatus => _mapStatus();
26
27  /// 狀態圖標
28  IconData get statusIcon => _mapIcon();
29
30  /// 進度顏色
31  Color get progressColor => _mapColor();
32
33  /// 摘要文字
34  String get summaryText => _formatSummary();
35
36  // =============================================================================
37  // 建構子
38  // =============================================================================
39
40  const [Feature]ViewModel({
41    required this.domainModel,
42    this.additionalData = const [],
43  });
44
45  // =============================================================================
46  // Domain → UI 轉換方法（私有）
47  // =============================================================================
48
49  /// 對應狀態到顯示文字
50  String _mapStatus() {
51    // 轉換邏輯
52  }
53
54  /// 對應狀態到圖標
55  IconData _mapIcon() {
56    // 轉換邏輯
57  }
58
59  /// 對應狀態到顏色
60  Color _mapColor() {
61    // 轉換邏輯
62  }
63
64  /// 格式化摘要文字
65  String _formatSummary() {
66    // 格式化邏輯
67  }
68}

完整範例：EnrichmentProgressViewModel

  1import 'package:flutter/material.dart';
  2import 'package:book_overview_app/domains/import/value_objects/enrichment_progress.dart';
  3import 'package:book_overview_app/domains/library/entities/book.dart';
  4
  5/// UI 層專用的補充進度顯示模型
  6///
  7/// 職責：
  8/// - 將 EnrichmentProgress Domain 模型轉為 UI 格式
  9/// - 提供進度顏色、圖標、文字等 UI 屬性
 10/// - 管理失敗書籍清單的顯示
 11///
 12/// 需求：UC-01.Enrichment.Progress
 13class EnrichmentProgressViewModel {
 14  // =============================================================================
 15  // Domain 來源
 16  // =============================================================================
 17
 18  /// Domain 進度模型
 19  final EnrichmentProgress domainProgress;
 20
 21  /// 失敗補充的書籍清單
 22  final List<Book> failedBooks;
 23
 24  // =============================================================================
 25  // UI 專用欄位（計算屬性）
 26  // =============================================================================
 27
 28  /// 狀態顯示文字
 29  ///
 30  /// 對應規則：
 31  /// - processedBooks == 0 → "準備中"
 32  /// - processedBooks > 0 && !isComplete → "補充中"
 33  /// - isComplete → "已完成"
 34  String get displayStatus {
 35    if (domainProgress.isComplete) return '已完成';
 36    if (domainProgress.processedBooks == 0) return '準備中';
 37    return '補充中';
 38  }
 39
 40  /// 狀態圖標
 41  ///
 42  /// 對應規則：
 43  /// - 準備中 → Icons.pending
 44  /// - 補充中 → Icons.sync
 45  /// - 已完成 → Icons.check_circle
 46  IconData get statusIcon {
 47    if (domainProgress.isComplete) return Icons.check_circle;
 48    if (domainProgress.processedBooks == 0) return Icons.pending;
 49    return Icons.sync;
 50  }
 51
 52  /// 進度顏色
 53  ///
 54  /// 對應規則：
 55  /// - 有失敗 → 橘色警告
 56  /// - 已完成 → 綠色成功
 57  /// - 進行中 → 藍色
 58  Color get progressColor {
 59    if (domainProgress.failedEnrichments > 0) return Colors.orange;
 60    if (domainProgress.isComplete) return Colors.green;
 61    return Colors.blue;
 62  }
 63
 64  /// 摘要文字
 65  ///
 66  /// 格式：「已處理 X/Y 本（成功 A，失敗 B）」
 67  String get summaryText {
 68    final processed = domainProgress.processedBooks;
 69    final total = domainProgress.totalBooks;
 70    final success = domainProgress.successfulEnrichments;
 71    final failed = domainProgress.failedEnrichments;
 72
 73    if (failed > 0) {
 74      return '已處理 $processed/$total 本（成功 $success，失敗 $failed）';
 75    }
 76    return '已處理 $processed/$total 本';
 77  }
 78
 79  /// 失敗書籍摘要清單
 80  ///
 81  /// 提供簡化的書籍資訊供 UI 顯示
 82  List<BookSummary> get failedBooksSummary {
 83    return failedBooks.map((book) => BookSummary.fromBook(book)).toList();
 84  }
 85
 86  /// 進度百分比（直接使用 Domain 計算）
 87  double get progressPercentage => domainProgress.percentageComplete;
 88
 89  /// 當前處理書名（如果有）
 90  String? get currentBookTitle => domainProgress.currentBook?.title.value;
 91
 92  /// 是否顯示失敗清單
 93  bool get showFailedBooks => failedBooks.isNotEmpty;
 94
 95  /// 是否可以重試
 96  bool get canRetry => domainProgress.isComplete && failedBooks.isNotEmpty;
 97
 98  // =============================================================================
 99  // 建構子
100  // =============================================================================
101
102  const EnrichmentProgressViewModel({
103    required this.domainProgress,
104    this.failedBooks = const [],
105  });
106}
107
108/// 書籍摘要（UI 專用簡化資料）
109class BookSummary {
110  final String id;
111  final String title;
112  final String author;
113
114  const BookSummary({
115    required this.id,
116    required this.title,
117    required this.author,
118  });
119
120  factory BookSummary.fromBook(Book book) {
121    return BookSummary(
122      id: book.id.value,
123      title: book.title.value,
124      author: book.author.value,
125    );
126  }
127}