知識寫入框架前，依「受眾 x 形態」二軸決定載體。載體錯置有兩種代價：寫進自動載入層 → token 污染（attention 稀釋 + 45k 預算耗盡）；困在專案 memory → 跨專案失傳。本方法論是頂層地圖；各載體的細部規範（如有）路由至 Reference 所列文件。

Scope：本地圖涵蓋 LLM context 載體（人與 AI 閱讀的知識）；專案產物層（docs/ / src/）不屬本地圖，劃分見 framework-asset-separation.md；機器讀取層（config/*.yaml、hook 引用的凍結錨點）另計。memory 行由受眾軸「僅本專案」唯一決定，不需形態軸。

代理人定義 vs skill 的歸屬判準：一段知識可能落在代理人定義或 skill、不易區分時，以「該知識是否隨執行者改變」為判準，不憑直覺擇一。

• 屬代理人定義的知識回答「你是誰、你能做什麼、你偏好怎麼做」——身份定位、授權邊界、設計偏好。識別測試：換一個代理人來執行，這段內容就應該不同。本質是人格與授權。
• 屬 skill 的知識回答「這件事怎麼做」——可重複執行的流程步驟。識別測試：任何角色觸發都應得到同一份流程，與執行者是誰無關。本質是可重複流程。

兩者衝突時，對該知識套用識別測試「換一個代理人，內容會不會變」：會變則歸代理人定義；不會變、任何角色執行都應一致則歸 skill。

載體地圖（受眾 x 載入時機 x 形態）

執行步驟

1. 受眾是誰？（所有角色 / 僅 PM / 全體代理人 / 單一代理人 / 動作觸發者 / 僅本專案）→ 縮小候選載體。「動作觸發者」統括地圖表受眾欄的按需情境詞（觸發者 / 主動查閱者 / 執行特定動作者 / 任務前查詢者）
2. 形態是什麼？（行為禁令 / 調度流程 / 身份偏好 / 工作流方法 / 理念清單 / 技術參考 / 失敗案例 / 專案設定）→ 確定載體
3. 候選屬自動載入層（CLAUDE.md / rules/ / MEMORY.md）？→ 過預算閘門；規範類知識的閘門是必要性否決（「這是否每回合都需要？」否則外移按需層）+ 形態降為「禁令 + 路由」，專案設定 / 指令等事實類的閘門是體積與專案特定性約束（精簡陳述、不含框架通用知識），不適用必要性否決
4. skill / methodology / rule 三選一拿不準 → framework-meta-methodology.md 決策樹
5. 寫完 grep 概念詞，盤點與既有規範的指令方向矛盾，並對齊執法強度（PC-V1-006）

代理人定義內容規範

檢查清單

• 受眾 x 形態二軸定位完成，不是「順手寫在開啟中的檔案」？
• 自動載入層寫入已過預算閘門；規範類形態已降為禁令 + 路由（事實類過閘門即可）？
• 代理人定義新增內容屬「偏好 / 邊界」而非「流程 / 方法」？
• 重複內容用路由取代複製（單一來源）？
• 概念詞 grep 矛盾盤點 + 執法強度對齊完成（PC-V1-006）？

Reference

• .claude/methodologies/framework-meta-methodology.md — skill / methodology / rule 三分決策樹 + 30 秒標準（形態軸的細分）
• .claude/references/framework-asset-separation.md — 框架資產 vs 專案產物、專案設定 vs 代理人知識、Skill Hook 雙層
• .claude/references/auto-load-stub-conventions.md — 自動載入層 stub 構成 + 外移 SOP + 預算驗證
• .claude/rules/core/agent-definition-standard.md — 代理人三區塊結構標準
• .claude/rules/README.md — 自動載入預算原則（每回合必要性自問）
• .claude/pm-rules/pm-quality-baseline.md 規則 7 — memory 升級四問 + 升級目的地預算閘門 + 升級即搬家
• .claude/README.md「同步機制」章 — 寫作類 skill（compositional-writing / multi-round-review）內容 SSOT 在 blog repo，框架端為回流副本；依地圖判定「寫作方法 → skills/」後，內容修改應到上游 repo 執行
• .claude/skills/skill-design-guide/SKILL.md — skills 載體的細部規範（官方規格、frontmatter、漸進揭露結構）

Last Updated: 2026-06-15 Version: 1.8.0 — 「代理人定義 vs skill 歸屬判準」改寫：去除「一句話判定」總結框架，改為含明確識別測試（換一個執行者內容是否改變）的判準段落。方法論作為框架核心規則供 AI 開發時判斷，內容須明確而可套用，不採壓縮式總結（避免單句總結遮蔽判準細節導致 AI 判斷失準） Version: 1.7.0 — root 錯置檔重分配（1.0.0-W8-023.2，第 2/4 批）：4 檔（agent-collaboration.md 794 / decision-workflows.md 116 / quick-ref-agent-dispatch-recovery.md 202 / thinking-process.md 271）逐檔讀內容後全數 flag superseded/obsolete（campaign 規則 3，零搬移零連結手術）：agent-collaboration 與 analyses/archived/ 同名 794 行副本 near-identical 且內容已被 methodologies/tdd-collaboration-flow.md + agent 定義覆蓋；decision-workflows 五情境已被 pm-rules/skip-gate+incident-response+decision-tree 覆蓋；quick-ref-agent-dispatch-recovery 所述 agent_dispatch_recovery.py hook 已不存在；thinking-process 為 2025-12-01 一次性 session 快照非知識載體。本批 0 檔搬移，故不加 map 行，留 PM follow-up 清理（inbound 連結多在 .3/.4 批檔群） Version: 1.6.0 — root 錯置檔重分配（1.0.0-W8-023.1，第 1/4 批）：hook-system-reference.md（Hook 事件索引 / 技術參考）、code-smell-checklist.md（Code Smell 檢測清單 / 技術參考）依二軸（受眾＝動作觸發者、形態＝技術參考）歸入既有 references/ 載體列（line 22），故不另加 map 行；superseded 副本 code-quality-examples.md（已遷 docs/，DOC-010 W10-102）與 document-responsibilities.md（DEPRECATED，已被 five-document-system-methodology.md + doc-flow/references/document-responsibilities.md 取代）flag 不併入，留 PM follow-up Version: 1.5.0 — 載體地圖補列 4 個 legit root 資產各一行歸屬（README 框架導覽 / CHANGELOG 變更記錄 / README-subtree-sync 同步機制 / terminology-dictionary 用語規範表，後者經 language-constraints @ 引用實質載入）（1.0.0-W8-022） Version: 1.4.0 — multi-round-review Round 4（實例分配演練）修正：步驟 1 補受眾詞彙映射橋（六選項 vs 地圖表受眾欄斷層）、步驟 3 事實類閘門判準明文化（體積與專案特定性約束，非必要性否決）。8 條盲跑 6 條乾淨落點，停止訊號達成收斂 Version: 1.3.0 — multi-round-review Round 3 修正：Scope 句（LLM context 載體限定 + 機器讀取層另計 + memory 受眾軸唯一決定）、rules/core 列量測集合精確化（MEMORY.md 不在 guardian 集合）、規範表補「多方案技術知識庫」劃界列（與 framework-asset-separation「框架寫法」段對齊）、地圖補 templates / root 遺留行、Reference 補 skill-design-guide Version: 1.2.0 — multi-round-review Round 2 修正：檢查清單與步驟 3/5 的 R1 劃界同步（清單漂移）、步驟 5 拆動作解歧義、地圖欄名補形態軸、定位句「（如有）」、Reference 補寫作 skill SSOT 例外路由 Version: 1.1.0 — multi-round-review Round 1 修正：步驟 3 形態約束劃界（規範類 vs 事實類）、步驟 5 補執法強度對齊、章名對齊 methodology 標準結構、rules/core 列預算範圍精確化、agents 列改路由至專節 Version: 1.0.0 — 初始建立：框架知識載體的頂層責任地圖（受眾 x 形態二軸），整合 W7 token 收斂三層防護與既有分離原則；代理人定義內容規範首次權威化（人格與授權 vs 可重複流程）

生命週期總覽

 1需求/問題產生
 2    |
 3    v
 4建立 Ticket (/ticket create)
 5    |
 6    v
 7Ticket 狀態: pending
 8    |
 9    v
10認領 Ticket (/ticket track claim)
11    |
12    v
13Ticket 狀態: in_progress
14    |
15    +-- 正常完成 --> /ticket track complete --> 狀態: completed
16    |
17    +-- 無法繼續 --> /ticket track release --> 狀態: blocked
18    |                                              |
19    |                                              v
20    |                                         升級到 PM 處理
21    |
22    v
23完成

這套系統的核心目標是將任務需求有邏輯地拆分拆細。任務進來後先分析，拆分成平行的子任務；子任務若仍太大，可繼續往下切分。執行時從最底層開始，完成後檢查平行任務，再往上驗收父任務，直到整個任務鏈完成。

任務拆小的好處：降低執行時的認知負擔，也讓驗收檢查更容易發現疏失。

Ticket 狀態定義

階段-標準流程對照表

每個生命週期階段都有對應的標準流程和提示，防止關鍵步驟被遺漏。

建立階段

認領階段

執行階段

完成階段

驗收後階段

任務鏈後續步驟建議

當 Ticket 完成時，系統會自動分析任務鏈狀態並建議下一步。

分析優先級

輸出範例

 1============================================================
 2[任務鏈後續步驟建議]
 3============================================================
 4
 5已完成: 0.31.0-W4-007.1
 6        [實作 track P0 功能]
 7
 8任務鏈進度: 1/3 completed
 9   Root: 0.31.0-W4-007
10
11建議下一步:
12   1. 0.31.0-W4-007.2
13      [實作 track P1 功能]
14      原因: 阻塞已解除（blockedBy 0.31.0-W4-007.1 已完成）
15      狀態: pending → 可認領

任務鏈 ID 格式

10.31.0-W3-002              # ticket-handoff 功能（根）
2├── 0.31.0-W3-002.1        # chain_analyzer 模組
3│   ├── 0.31.0-W3-002.1.1  # 問題修復
4│   └── 0.31.0-W3-002.1.2  # 測試補充
5├── 0.31.0-W3-002.2        # handoff_executor 模組
6└── 0.31.0-W3-002.3        # 文件更新

chain 欄位

根任務 0.31.0-W3-002 的 chain：

1chain:
2  root: "0.31.0-W3-002"
3  parent: null
4  depth: 0
5  sequence: [2]

子任務 0.31.0-W3-002.1.1 的 chain：

1chain:
2  root: "0.31.0-W3-002"
3  parent: "0.31.0-W3-002.1"
4  depth: 2
5  sequence: [2, 1, 1]

ID 正則表達式：^(\d+\.\d+\.\d+)-W(\d+)-(\d+(?:\.\d+)*)$

Ticket 建立流程

任務層級判斷

 1任務層級判斷
 2    |
 3    v
 4這個任務是否因為執行現有 Ticket 而產生？
 5    |
 6    +-- 是 → 來源 Ticket 是什麼？
 7    |       |
 8    |       └── 確定來源 Ticket ID → 建立該 Ticket 的子任務
 9    |           ├── 來源: 010.4 → 子任務 ID: 010.4.x
10    |           ├── 來源: 010.4.1 → 子任務 ID: 010.4.1.x
11    |           └── 來源: 010 → 子任務 ID: 010.x
12    |
13    └-- 否 → 建立新任務鏈（新的 Wx-00n）

核心判斷問題：「這個任務是在執行哪個 Ticket 時產生的？」若有明確來源，建立子任務；若無關聯，建立新任務鏈。

建立格式

 1---
 2id: {版本}-W{波次}-{序號}
 3title: {動詞} {目標}
 4type: IMP/RES/ANA/INV/DOC
 5status: pending
 6priority: P0/P1/P2
 7assignee: pending
 8created: {日期}
 9---
10
11# {Ticket ID}: {標題}
12
13## 目標
14
15{目標描述}
16
17## 驗收條件
18
19- [ ] {條件1}
20- [ ] {條件2}

Atomic Ticket 檢查

驗收條件格式要求

驗收條件必須符合 4V 原則：可驗證、可量化、可追溯、可記錄。

標準格式（表格式）：

1## Acceptance Criteria
2
3| #   | 項目       | 來源       | 確認方法   | 狀態 |
4| --- | ---------- | ---------- | ---------- | ---- |
5| 1   | {項目描述} | {來源引用} | {確認方法} | [ ]  |
6| 2   | {項目描述} | {來源引用} | {確認方法} | [ ]  |

Ticket 有效性驗證

有效 Ticket 定義

有效的 Ticket 必須滿足以下條件：

驗證時機

無效 Ticket 處理

無效 Ticket（缺少決策樹欄位）：

• 無法用於 Task 派發（被 Hook 阻止）
• 需要補充決策樹欄位才能使用
• 建議使用 /ticket create 重新建立

補充決策樹欄位

如果 Ticket 缺少決策樹欄位，可手動補充：

1. YAML 格式（在 frontmatter 中）：

   1decision_tree_path:
   2  entry_point: "第X層"
   3  decision_nodes:
   4    - layer: "X"
   5      question: "決策問題"
   6      answer: "答案"
   7      next_action: "下一步"
   8  final_decision: "最終決策"
   9  rationale: "決策理由"

2. Markdown 格式（在內容中）：

   1## 決策樹路徑
   2
   3### 進入點
   4
   5- **層級**: 第X層
   6- **觸發條件**: ...

Ticket 認領流程

認領規則

Ticket 執行流程

 1認領 Ticket
 2    |
 3    v
 4執行對應階段工作
 5    |
 6    v
 7更新工作日誌
 8    |
 9    v
10驗證驗收條件
11    |
12    +-- 全部通過 --> 完成 Ticket
13    +-- 部分通過 --> 繼續處理或升級
14    +-- 無法完成 --> 釋放 Ticket

完成檢查

Ticket 釋放流程

釋放時機

Ticket 類型說明

版本歷史

• v2.8.0 (2026-02-01): 取消驗收豁免機制，改為契約式驗收
• v2.7.0 (2026-02-01): 強化驗收代理人派發要求
• v2.6.0 (2026-01-31): 新增任務層級判斷規則
• v2.5.0 (2026-01-30): 新增階段-標準流程對照表和任務鏈後續步驟建議
• v2.4.0 (2026-01-30): 新增建議追蹤流程整合章節
• v2.3.0 (2026-01-30): 新增驗收條件格式要求章節
• v2.2.0 (2026-01-29): 新增任務鏈 ID 格式章節
• v2.1.0 (2026-01-27): 新增 Ticket 有效性驗證章節
• v2.0.0 (2026-01-23): 重構為 TDD 含 SA 前置審查流程版本

除錯不是試錯過程，是品質提升的系統性工程。隨機修復會產生隨機品質。系統化除錯產生一致的架構改善。

當AI協作處理複雜程式問題時，系統化除錯方法論成為唯一的執行準則。模糊的修復策略會產生模糊的結果。明確的除錯方法論產生一致的品質改善。

系統化除錯的本質

系統化除錯不是什麼

系統化除錯不是：

• 症狀修復：不掩蓋警告，只找根本原因
• 批量處理：不自動修復，只精確分析
• 簡單先行：不從容易修的開始，只按風險優先級
• 表面清理：不只消除警告，只完成未完成的設計

系統化除錯是什麼

系統化除錯是：

• 根因分析：明確區分未完成實作vs過度設計
• 風險導向：按業務風險和架構影響排序修復
• 主從分工：主線程管控進度，代理人執行修復
• 品質提升：每次修復都強化程式設計完整性

除錯的第一原則：根因分析優先

問題本質分類

每個unused警告都屬於以下三類之一：

未完成實作

• 識別：功能設計完整但驗證邏輯缺失
• 處理：補完實作而非移除程式碼
• 範例：測試中建立了secondImport變數但未驗證重複匯入行為

過度設計

• 識別：功能已完成但包含不必要的複雜性
• 處理：移除多餘程式碼保持精簡設計
• 範例：建立獨立服務實例但架構採用單例模式

程式碼風格問題

• 識別：邏輯正確但命名或結構不一致
• 處理：重構改善可讀性和一致性
• 範例：使用File物件但混用path字串操作

分析判斷標準

• 變數有明確的業務意圖 → 未完成實作
• 變數創建後立即被丟棄 → 過度設計
• 變數使用方式不一致 → 程式碼風格問題

不存在「可能是」的情況。如果無法明確分類，則需要更深入的程式碼分析。

範例：完整的根因分析

情境：test檔案中unused變數 ‘initialMemory’

錯誤分析

「這個變數沒用到，直接刪掉。」

正確分析過程

1. 變數意圖：記憶體效率測試的基線測量
2. 使用模式：建立但未在驗證邏輯中引用
3. 分類判斷：未完成實作（測試設計完整但驗證缺失）
4. 修復策略：補完基線比較邏輯而非移除變數

除錯的第二原則：風險導向排序

檔案風險等級

檔案修復必須按風險等級執行：

高風險檔案（立即修復）

• 核心業務邏輯：Domain層實作檔案
• 基礎設施元件：Database、Service、Repository
• 關鍵測試：端到端測試、整合測試

中風險檔案（計畫修復）

• 輔助功能：Utility、Helper類別
• 測試工具：Mock、TestData產生器
• 配置檔案：Configuration、Environment設定

低風險檔案（可延後修復）

• 單元測試變數：純測試輔助變數
• 範例程式碼：Demo、Sample實作
• 文件產生器：Documentation工具

風險評估標準

• 影響核心功能 → 高風險
• 影響開發效率 → 中風險
• 純粹警告清理 → 低風險

每個檔案只能歸類到一個風險等級。無法分類表示需要進一步的架構分析。

修復優先序執行規則

• 高風險檔案：立即修復，不考慮複雜度
• 中風險檔案：當前Sprint完成
• 低風險檔案：下個版本或維護期處理

除錯的第三原則：主從分工模式

角色定義

系統化除錯採用明確的角色分工：

主線程職責

• 進度管控：追蹤修復狀態和整體進展
• 策略決策：確定修復優先序和資源配置
• 品質檢查：驗證修復結果符合品質要求
• 工作記錄：更新工作日誌避免遺漏

代理人職責

• 詳細分析：深入檢查程式碼設計意圖
• 修復執行：實際編寫和修改程式碼
• 測試驗證：確保修復後功能正常
• 技術回報：提供修復細節和影響評估

協作執行規則

• 主線程永不直接修復程式碼
• 代理人永不決定修復優先序
• 每修復一個檔案都必須更新工作日誌
• 所有修復決策都必須通過主線程確認

範例：完整的協作流程

情境：發現5個檔案有unused警告

主線程執行

1. 風險評估：將5個檔案按業務風險分類
2. 優先排序：確定高風險檔案的修復順序
3. 委託分析：要求代理人分析第一個檔案
4. 進度追蹤：更新TodoList標記當前處理檔案

代理人執行

1. 根因分析：判斷unused變數屬於未完成實作vs過度設計
2. 修復實施：根據分析結果執行對應的修復策略
3. 結果驗證：執行靜態分析工具確認警告消除
4. 影響報告：回報修復內容和對整體架構的影響

主線程確認

1. 驗證結果：檢查靜態分析工具輸出確認修復成功
2. 更新記錄：在工作日誌中記錄修復成果
3. 繼續協作：標記完成並委託下一個檔案分析

品質標準

修復完成的判斷標準

每個檔案修復完成必須滿足：

• 警告消除：靜態分析工具不再顯示該檔案的unused警告
• 功能完整：所有測試通過，不引入新的錯誤
• 架構一致：修復符合Clean Architecture分層原則
• 文件更新：工作日誌記錄修復內容和影響

整體品質提升指標

• 警告減少率：unused警告數量持續下降
• 功能完整性：修復過程中完成更多未完成的實作
• 架構一致性：程式碼風格和設計模式更加統一
• 可維護性：程式碼可讀性和邏輯清晰度提升

品質驗證機制

• 每個檔案修復後立即執行靜態分析工具驗證
• 定期檢查整體警告數量變化趨勢
• 記錄修復過程中發現的架構改善機會
• 確認每次修復都強化而非弱化程式品質

執行流程

標準修復流程

1. 問題評估 執行靜態分析工具識別所有unused警告

2. 風險分析 將含有警告的檔案按風險等級分類

3. 優先排序 確定高風險檔案的修復順序

4. 逐檔修復 按優先序對每個檔案執行：

   • 委託代理人詳細分析
   • 根因判斷(未完成實作vs過度設計vs程式碼風格)
   • 執行對應修復策略
   • 驗證修復結果
   • 更新工作記錄

5. 整體驗證 確認警告總數下降且無新錯誤引入

修復策略對應表

例外處理原則

• 分析器誤報：確認變數確實被使用後保持現狀
• 架構衝突：優先解決架構問題後再處理警告
• 測試失敗：立即修復測試問題，暫停警告修復
• 複雜邊界：分解為更小的問題單位處理

成果評估

量化指標

• 警告消除數量：已修復的unused警告總數
• 警告減少率：相對於初始狀態的改善百分比
• 檔案修復數量：完成修復的檔案總數
• 架構改善項目：修復過程中完成的設計改善

質化評估

• 根因解決率：真正解決問題vs僅消除警告的比例
• 架構一致性：程式碼風格和設計模式統一程度
• 功能完整性：修復過程中完成的未完成實作數量
• 可維護性提升：程式碼清晰度和邏輯簡潔性改善

實戰案例：v0.8.19成果

量化成果：

• 初始警告：49個
• 最終警告：25個
• 改善率：49.0%
• 修復檔案：7個高風險檔案

質化成果：

• 補完3個未完成的功能實作
• 移除4處過度設計的複雜程式碼
• 統一5個檔案的程式碼風格
• 解決2個架構不一致問題

持續改進

方法論優化

系統化除錯方法論必須持續優化：

• 記錄邊界案例：遇到的特殊情況和處理方式
• 更新風險分類：基於實戰經驗調整風險評估標準
• 改進協作模式：優化主線程和代理人的分工效率
• 補充修復策略：新增針對特定問題類型的處理方法

知識累積

每次系統化除錯的經驗都必須沉澱為方法論改進：

• 成功的修復策略納入標準流程
• 失效的方法從規範中移除
• 新發現的問題模式補充到分類標準
• 協作過程中的效率改善點持續優化

結論

系統化除錯方法論是品質提升的執行標準。它的價值在精確，它的目的是完成設計。

每個修復都是一次架構改善。每個分析都是一次設計檢視。每個協作都是一次品質提升。

執行系統化除錯就是執行品質標準。遵循這個方法論，我們能持續強化程式架構完整性和設計一致性。

這是工程規範，確保每次除錯都提升而非妥協專案品質。

延伸：套用到 Linux 系統除錯

這套方法論是語言與領域無關的通則。把它落到 Linux 系統除錯這個具體領域——「讀權威狀態而非肉眼猜表象」的紀律、症狀到情境的分流、逐層定位——見 Linux 除錯與診斷：診斷心法。那裡用實機案例（把鎖屏誤判兩次的教訓）展示同一套系統化紀律在 Linux 現場長什麼樣。