規則文件膨脹之後，每次都要讀的內容與偶爾才查的細節混在一起，讀者做一個判斷之前要先跳過條件、例外與範例。Progressive Disclosure 把每次都要讀的內容留在常駐文件、偶爾才查的細節移到按需讀取的參考文件；範圍是一份文件內部的分層，案例是一個以 AI 代理人協作開發的專案在 2026 年 3 月初精簡它的流程規則文件。判斷一份文件要不要先拆成幾份、沿哪種職責切，在依職責拆分文字文件。

文件膨脹的形態

這個專案的流程規則文件從 2026 年 1 月起反覆迭代，每次迭代都在處理一個實際發生過的疏漏：補充遺漏的邊界情況、新增流程步驟、記錄決策理由。精簡之前的行數：

1parallel-dispatch.md     444 行  ← 原本是「什麼時候可以並行」的判斷指南
2task-splitting.md        325 行  ← 原本是「怎麼拆任務」的清單
3ticket-lifecycle.md      286 行  ← 原本是「Ticket 狀態怎麼轉」的流程
4incident-response.md     257 行  ← 原本是「出錯了怎麼辦」的流程
5version-progression.md   231 行  ← 原本是「什麼時候推進版本」的判斷
6plan-to-ticket-flow.md   153 行  ← 原本是「計畫怎麼變成 Ticket」的流程
7query-vs-research.md     151 行  ← 原本是「查資料要不要派人」的二選一
8decision-tree.md         452 行  ← 核心決策樹，每次都在「補一個分支」（不計入〈七份規則文件的精簡前後〉的七份合計）

這些規則文件是常駐文件：專案的代理人工具在每一次對話開始時把它們整份讀進來，讀進來的內容留在對話的脈絡裡，之後每一回合都隨著一起處理。常駐文件的長度因此是一個直接的成本，每多一行，每一回合都多帶一行。一個代理人要讀 parallel-dispatch.md 決定能不能並行派發任務，它用得到的是：

• 觸發條件與並行安全檢查
• 決策流程、數量原則（一次最多派幾個）與不適用並行的情形
• 派發方式判斷（各自派發，還是組成 Agent Teams——多個代理人組隊並行的派發方式）
• 派發之後的驗證

精簡前的 444 行裡，其餘內容是派發任務用的 5W1H 格式範例（要求寫出 who、what、when、where、why、how 的任務說明）、只在派發分析任務時才適用的並行規則與安全檢查、Agent Teams 的詳細規則與場景表，以及進度追蹤模板。

parallel-dispatch.md 的膨脹過程

parallel-dispatch.md 留在版本紀錄裡的成長軌跡（版本是這份文件自己的版號，v2.0.0 之前的版本沒有留在版本紀錄裡）：

每一次新增都在處理一個實際發生過的疏漏，沒有人刻意讓文件變長，而一個月之內，一份「能不能並行」的判斷指南長到 444 行。程式碼裡的巨型函式也是這樣累積出來的：每次加一點都合理，而沒有人在加的那一刻問這個函式該不該拆。

這次精簡只做了分層，沒有先依修改紀錄判斷這份文件承擔了幾種職責。成長軌跡裡的 Agent Teams 派發方式是新功能，依依職責拆分文字文件的判斷，Agent Teams 的規則也可以獨立成一份文件；這次的做法把它的細節歸進參考細節，派發方式的判斷留在常駐文件。

Progressive Disclosure 的四層

程式碼重構有 Extract Method，把函式內部的細節提取到獨立函式。文件對應的手法是 Progressive Disclosure（漸進式揭露）：依讀者做決策時需要的深度把內容分層，常駐文件放做決策用得到的那幾層，其餘放到參考文件裡按需讀取。這次精簡把內容分成四層（四層是內容的分類，下文的常駐與按需是載入的層級）：

• 快查表：一眼就能找到答案的表格，例如觸發條件表。
• 強制規則：必須遵守的約束，例如並行前的安全檢查清單、數量原則、不適用的情形、派發後的驗證。
• 決策流程：判斷邏輯，例如決策流程圖、派發方式判斷。
• 參考細節：範例、模板、場景表、只在特定情況才用到的規則。

快查表與決策流程合稱決策依據：讀者靠它們做出判斷。常駐文件放決策依據與強制規則，參考細節放到參考文件。處置上只有參考細節與其餘三層之分；前三層的區分用在常駐文件內的排列，精簡後的 parallel-dispatch.md 先放觸發條件表，接著是安全檢查與決策流程。

函式也有同樣的四層，main() 呼叫 sort()，排序的完整實作留在 sort() 裡：

 1# 快查表：函式簽名（一眼就知道做什麼）
 2def can_dispatch_parallel(tasks: list[Task]) -> bool:
 3    # 強制規則：guard clauses
 4    if len(tasks) < 2:
 5        return False
 6    if has_dependency(tasks):
 7        return False
 8
 9    # 決策流程：核心的判斷邏輯
10    return not has_file_overlap(tasks)
11
12# 參考細節：實作留在被呼叫的函式裡
13def has_file_overlap(tasks):
14    ...  # 50 行的具體實作

常駐與按需的分界由載入機制決定。 代理人工具自動讀進哪些檔案，那些檔案就是常駐文件；參考文件要放在這個機制不會自動讀取的位置，代理人只在常駐文件的入口指向它時才打開。有些工具在兩者之間還有一層條件式載入：讀寫某一類路徑的檔案時才自動載入某份規則。觸發情境能用檔案路徑表達的規則放進這一層，觸發由工具判斷，比放在參考文件、靠代理人讀入口可靠；「派發分析任務」這類沒有對應檔案的情境放不進去。規則文字在這類代理人工具裡是給代理人的脈絡，不是強制的設定；一定要擋下的動作，規則文字仍然留在常駐文件，另外交給工具的 hook 在執行前檢查。這個專案的常駐規則放在 .claude/rules/ 底下，參考文件放在 .claude/references/。參考文件放進會被自動讀取的目錄（例如規則目錄底下的子目錄）時，常駐文件的行數變少，每次讀進來的內容卻沒有變；所以移出之後，查一次自己的工具實際載入了哪些檔案，確認參考文件不在裡面。工具會讀取專案裡所有位置、找不到不被自動讀取的地方時，分層只改善常駐文件內的排列，不減少讀進來的量，要減量只剩刪除或改寫內容。

人類讀者沒有載入機制，對他而言常駐指的是不點任何連結、打開這份文件就讀得到的內容。程序文件裡每次執行都要走的步驟屬於常駐，只在出錯或特殊情況才走的分支屬於參考細節。

這個專案後來把載入再分成幾層：每回合都載入的核心規則只留行為禁令與路由，流程類的規則改成相關時才讀，分配方式整理在知識載體責任分配方法論。本篇記的是 2026 年 3 月那一次只有常駐與按需兩層的精簡。

精簡時用的原則，與程式碼重構的原則對應：

DRY 那一列處理的是文件之間的重複。這個專案的 Wave 獨立性原則（不同波次（Wave）的任務在執行時必須完全獨立）若在幾份規則文件裡各寫一次，修改時就要改好幾處。Wave 獨立性原則是強制規則，所以定義在最常用到它的那一份常駐文件，其他文件連到那一段；共用的範例與模板才放到參考文件。

每一份規則文件負責一種判斷，參考細節依附在那個判斷底下：

parallel-dispatch.md 的精簡做法

parallel-dispatch.md 各段落所屬的層

每一段依序問三件事。第一，它是不是每一次派發都要遵守的強制規則；是的話留在常駐文件，不論它是否直接屬於「能不能並行」這個判斷（派發後的驗證就是這一種）。第二，其餘的段落，問每一次派發的判斷都用得到它，還是只有某一類任務才用得到，或者做這個判斷根本用不到；每一次都用得到的是決策依據，常駐（派發方式判斷屬於這一種，每次都要決定用哪一種方式派發），只有某一類任務才用得到的移到參考文件，常駐文件留一個寫明何時要讀的入口，用不到的是參考細節。一般的並行安全檢查每一次派發都要做，留在常駐；只在派發分析任務時才做的安全檢查屬於「某一類任務才用得到」。第三，移出去的規則若違反時代價高，而讀者可能認不出它的觸發情境（例如處理個資、對外傳輸），把它的觸發條件與一句話的規則本體留在常駐文件，這一句歸在強制規則，只把細節移出；整份都是這種違反代價高、觸發情境不易認出的規則的文件（例如資安政策），常駐文件裡留的就是每一條規則的觸發條件與一句話的本體。

分層之後的結構：

1# 精簡前
2.claude/rules/guides/parallel-dispatch.md  (444 行，所有內容混在一起)
3
4# 精簡後
5.claude/rules/guides/parallel-dispatch.md  (98 行，決策依據 + 強制規則)
6.claude/references/parallel-dispatch-details.md  (參考細節，按需查閱)

在常駐文件留下入口

移出去的細節，要在常駐文件裡留一個入口。下面先列原檔的寫法，它的最後一行入口缺開啟條件，接著是改寫。入口所在的那一段本身要能做出決策：強制規則寫出怎樣算通過，入口寫出什麼時候要打開參考文件。這個專案常駐文件裡的派發後驗證：

1## 並行派發後驗證（強制）
2
3所有並行代理人回報完成後，**必須**執行 `git diff --stat` 驗證實際變更。
4
5- [ ] `git diff --stat` 已執行
6- [ ] 代理人報告 vs 實際變更已比對
7- [ ] 無缺失檔案（或已補派）
8
9> 詳細驗證步驟和常見原因：.claude/references/parallel-dispatch-details.md

讀到這一段的代理人在常駐文件裡就判斷得出驗證有沒有通過：三個核取項都成立才算通過。任何一項不成立、要查常見原因時，才打開參考文件。這一段的規則與核取清單寫得完整，最後那一行入口卻只寫了參考文件裡有什麼、沒寫什麼時候要讀，代理人沒有打開它的判斷依據。照這篇的做法，入口寫成帶著開啟條件的形式：

1> 任何一項核取項不成立、要查常見原因時讀：.claude/references/parallel-dispatch-details.md

incident-response.md 的段落結構前後

另一份文件 incident-response.md 的精簡，示範了段落的合併：

 1# 精簡前 (257 行)
 2
 3## 流程總覽
 4## 多視角並行分析選項        ← 參考細節
 5## 強制觸發條件
 6## 執行步驟
 7## 派發對應表
 8## 安全問題嚴重等級          ← 參考細節
 9## Incident Report 格式      ← 參考細節（底下還有報告資訊、錯誤摘要、錯誤分類、根本原因分析、安全風險評估、派發建議等小段）
10## 禁止行為
11## 相關文件

1# 精簡後 (64 行)
2
3## 強制流程
4## 強制觸發條件
5## 派發對應表
6## 禁止行為
7## 相關文件
8> 要做多視角分析、判定安全等級或寫 Incident Report 時讀：.claude/references/incident-response-details.md

參考細節（多視角分析、安全等級、報告格式）整段移到參考文件，入口那一行改寫成帶開啟條件的形式（原檔寫的是「詳細規則：…」）；精簡後的〈強制流程〉一節取代了原本的〈流程總覽〉與〈執行步驟〉兩節。常駐文件只剩下做決策需要的資訊。

七份規則文件的精簡前後

合計不含核心決策樹 decision-tree.md（這套決策樹早期的版本記在二元決策樹系統）。決策樹另外從 452 行精簡到 286 行（-37%），縮減幅度較小，因為決策樹本身就是決策流程，大部分內容都是必要的分支判斷。

前後的行數可以用一條指令量：

1# 統計規則文件目錄下每份文件的行數與合計
2wc -l .claude/rules/flows/*.md .claude/rules/guides/*.md

範例的兩個目錄是這個專案存放流程規則的位置，路徑換成自己存放常駐規則的目錄；量的檔案集合要等於代理人工具實際載入的那些檔案。行數是常駐內容少了多少的間接指標：同一份文件精簡前後各量一次，差值就是每次決策少讀的行數。

精簡的隔天，plan-to-ticket-flow.md 因為新增「執行中額外發現」流程，從 43 行長回 87 行；decision-tree.md 因為新增一層 commit 之後評估與交接的判斷（Commit-Evaluate-Handoff），以及 TDD 各階段完成後的路由，從 286 行長回 434 行。新增的內容都是必要的新功能，所以 43→87 與 286→434 這兩組數字顯示的是常駐文件會持續長回去。分層要在每一次新增段落時重新做：用〈parallel-dispatch.md 各段落所屬的層〉那三個問題判斷新段落屬於哪一層，屬於參考細節的就寫進參考文件，常駐文件只加入口。

精簡時的失誤：過度精簡、只按章節切開、移出後未留入口

過度精簡

把所有細節都移走，常駐文件只剩下標題和連結。讀者每做一個決策都要打開參考文件，跳轉次數太多反而增加認知負擔；程式碼重構裡過度拆分造成的跳轉，在文件精簡裡就是這個形態。

1# 過度精簡的常駐文件
2## 並行派發
3> 詳見：references/parallel-dispatch-details.md
4
5## 任務拆分
6> 詳見：references/task-splitting-details.md

這等於一個函式裡全是 call_other_function()，讀者在常駐文件裡做不了任何判斷。判斷有沒有過度精簡，看的是精簡後的常駐文件裡還做不做得出決策：決策依據與強制規則都要留在常駐文件。驗證的方法是只讓代理人載入常駐文件，參考文件留在它找得到、但不會自動讀到的位置，拿幾個最常見的決策，加上幾個罕見而違反代價高的決策，讓它判斷；看它判不判得出來、該打開參考文件的時候有沒有打開。

只按章節切開

把一份文件按目錄章節切成幾個小檔，每個小檔仍然同時有決策依據與參考細節，讀者在每一份裡都要再找一次核心內容。這裡有兩件事：章節與職責對不上時，切出來的每一份仍然混著幾種職責；章節剛好對應職責時，依章節切就是依職責切，切完之後每一份仍然要分層。

分層與依職責拆處理的是不同的事。依職責拆決定有幾份文件，一份文件只剩一種職責之後，Progressive Disclosure 依資訊層級決定哪些內容常駐、哪些移到參考文件。只按章節切，兩件事都沒有做到。

移出後未留入口

移出參考細節之後沒有在常駐文件留下入口，讀者需要細節時找不到它，跟重構後忘了更新 import 是同一類錯誤。

文件精簡的觸發訊號

常駐內容的長度在這裡是有效的訊號，因為常駐文件每次都整份被讀進來；它決定的是一份文件內部要不要分層；判斷一份文件是否要拆成幾份，依據是修改紀錄。代理人不會像人類讀者那樣回報「找不到」，它的訊號是行為：規則寫在常駐文件裡而代理人沒有照做。

思考題：專案規則檔的分層、決策樹的縮減幅度、精簡後的完整性

1. 一份每次都會被整份讀進來的專案規則檔（例如給代理人工具的專案說明），用 Progressive Disclosure 分層時，哪些內容會留在常駐、哪些會移到參考？
2. 為什麼 decision-tree.md 的縮減幅度（-37%）比其他文件（-70% 到 -78%）小？這說明了什麼？
3. 文件精簡有一個程式碼重構沒有的風險：過度精簡導致讀者找不到需要的資訊。要怎麼驗證精簡後的文件仍然足夠完整？

實作練習：健康度評估、分層與量化

評估一份常駐規則文件的健康度

找一份每次都會被整份讀進來的規則文件，逐項檢查：

• 這份文件被幾種主題修改過？
• 讀者要做最常見的那個決策時，在常駐文件裡找不找得到需要的段落？
• 有沒有段落只在特定情境下才需要閱讀？

執行 Progressive Disclosure

對那份文件做三件事：標出每一段屬於快查表、強制規則、決策流程還是參考細節，把參考細節提取到工具不會自動讀取的參考文件，在原文件中留下寫明何時要讀的入口。

量化驗證

計算精簡前後的行數和縮減率。縮減率本身沒有好壞的門檻，要檢查的是精簡後的常駐文件裡還做不做得出決策（見〈過度精簡〉）。