Ephasme/refine-document

精煉文件

取一份文件，產出一個版本，讓對專案沒有歷史背景的讀者能據以行動：無歷史包袱、基於事實、簡潔、組織良好，並針對宣告的讀者量身打造。

四個階段，固定順序，最後加上驗證關卡。所有移除的內容都會寫入記錄檔，因此錯誤的決定是可復原的。

呼叫方式

refine-document <路徑> [--target=agent|human] [--no-record]

標誌	預設值	效果
--target	agent	最後一個階段針對哪個讀者最佳化。會改變文件，不只是語氣——請參閱階段 4。
--no-record	關閉	跳過記錄檔。移除的內容將無法復原，除非透過版本控制。

在觸碰檔案之前：

1. 確認要求指定了此文件。 這會直接改寫使用者的檔案。
2. 確認檔案已被版本控制追蹤且是乾淨的。 如果不是，請告知並取得明確同意——使用 --no-record 時，這是唯一的復原路徑。
3. 在你的第一則訊息中說明你正在使用的目標，包含使用預設值的情況。預設值若無聲無息，會導致文件針對錯誤的讀者打造。
4. 多份文件： 對每份文件執行此程序一次，每個子代理（若可用）各處理一份，並傳遞相同的目標和標誌給所有子代理。一個子代理負責剛好一個檔案。

輸出

輸出	路徑	內容
精煉後的文件	原始路徑，直接覆寫	僅包含當前狀態，針對目標讀者打造
記錄檔	{名稱}.changelog.md，相同目錄	所有移除的內容，逐字記錄，附帶原始位置——可跨執行附加
報告	你的回覆	請參閱報告

階段順序

依此順序執行階段，每個階段對文件進行一次獨立的讀取。每個階段都會縮小下一個階段的輸入，順序錯亂會導致彼此抵消——在階段 1 要刪除的散文上壓縮是白費功夫，而在壓縮之前組織則是在組織填充內容。

1. 清除遺留資訊——移除所有僅作為過去參考才有意義的內容。
2. 基於事實——每個存留的宣稱都經過驗證、引用或標記。
3. 簡潔——一個事實，一個位置，保持事實的最短形式。
4. 組織——關鍵優先，然後針對目標讀者的形狀。

階段 1 — 清除遺留資訊

必要子技能： 使用 strip-legacy-content 來執行此階段。它擁有遺留資訊的分類法、移除而非改寫的規則，以及此技能也會寫入的 {name}.changelog.md 格式。將 --no-record 對應到它的 --no-changelog。

若該技能不可用，請移除：歷史與演進敘述、決策記錄與 ADR、棄用通知、遷移與升級指南、內嵌的變更日誌與發行說明、回溯相容章節、被否決的替代方案、過時評論、已被取代的章節。移除這些片段；不要改寫存留的散文——階段 2-4 會處理。

已棄用功能規則。標記為已棄用的功能不自動等於遺留資訊。套用此測試，並記錄你選擇了哪個分支：

此功能是否有「支援舊系統」以外的用途？

• 否——它僅存在於回溯相容。移除該功能及其通知。
• 是——它是當前行為。保留它，移除移除時間線和「從 v1 開始」的框架，並在記錄中標記它。

階段 2 — 基於事實

文件中的每個陳述都是一個宣稱，包括從舊文件繼承來的。將每個宣稱分類並採取對應行動。沒有第五種選項。

類別	訊號	行動
可查證，可取得成品	行為、標誌、預設值、路徑、命令、配置鍵，且你可以讀取程式碼、配置或 --help	查證它。為真：保留。為假：修正它。
可查證，無法取得成品	相同類型的宣稱，但沒有儲存庫、沒有二進位檔、沒有文件可供查證	完全按照來源所述保留宣稱，不加標記，並在報告中將其列為未查證。
可從外部取得來源	標準、協定行為、第三方產品行為、版本支援	內聯引用主要來源，並附上日期或版本。沒有可接受的來源：刪除該宣稱。
比較性或宣傳性	「快 10 倍」、「同類最佳」、「超快」、「優雅」、「大多數工程師同意」，以及任何比較對象不屬於當前系統的比較（「比 Kafka 更輕量」）	刪除它，除非存在可引用的測量數據——則陳述測量數據及其來源。保留存留的事實：「使用 Redis Streams 排隊任務」。
無法驗證且有風險	一個未查證的宣稱，讀者若據以行動可能造成不可復原的後果：資料遺失、花費、憑證、破壞性命令、安全性邊界	保留它，在文件中標記為 [unverified]，並在報告中列出。

標記是針對風險，而非出處。 一份關於你無法取得的成品的文件，大部分是未查證的宣稱，如果每個都標記，會讓讀者忽略標記。未查證的出處應屬於報告和記錄；文件中的 [unverified] 僅保留給那些一旦失敗，讀者無法挽回的宣稱。如果文件中有超過少數幾個標記，代表你將出處誤分類為風險——請重新分類。

絕對不要發明來源文件中沒有的資訊。 不是配置位置、不是預設值、不是檔案格式、不是先決條件——即使是幾乎確定為真的也不行。一個被直接陳述的推斷事實，與一個經過驗證的事實無法區分，而此階段是防止讀者得到看似正確但實則錯誤答案的唯一屏障。如果來源保持沉默，精煉後的文件也應保持沉默。

絕對不要將未註明來源的宣稱弱化為更模糊的用語。「大約快 10 倍」改寫成「非常快」是同樣的意見，但失去了精確度。引用它或刪除它。

絕對不要因為缺乏來源就刪除操作指令。 標記勝過刪除：標記的指令可以由知情者查證，刪除的指令則永遠消失。

對於宣稱大多來自外部的文件，在繼續之前，請執行 cite-or-refuse 來取得來源，並執行 fact-check-document 來進行完整的宣稱審計。

階段 3 — 簡潔

一個事實，一個位置。 對於每個事實，選擇讀者查找它時會首先到達的單一章節。在那裡完整陳述它。在其他所有地方，要麼刪除該重複陳述，要麼用一個精確命名該章節的指標取代它。

直接刪除：

• 填充開場白：「值得注意的是」、「簡單來說」、「基本上」、「如你所見」。
• 指示讀者正在做的事的指令：「要安裝，請執行安裝命令」。
• 作為第一句話重複的章節標題。
• 不改變任何行動的防禦性備註。
• 與前面範例演示相同內容的範例。

壓縮：

• 超過三個項目且跨兩個以上屬性進行比較 → 使用表格。
• 列出平行事物的段落 → 使用列表。
• 主詞是名詞化的句子 → 使用動詞（例如「做出決定」→「決定」）。

壓縮下限。當移除下一個字會移除一個事實時停止。一份更短但遺失事實的文件是退步，而非進步。字數是工作的症狀，絕不是目標。

唯一有條件允許的重複是針對代理目標的頭尾重複關鍵區塊，且需超過階段 4 設定的長度閾值。低於該閾值，它就像任何其他重複一樣，需要刪除。

階段 4 — 針對宣告讀者組織

共同點：排序法則

根據什麼會阻礙讀者來排序，而不是根據主題的歷史：

1. 這是什麼——一句話，無前言。
2. 阻礙所有其他事情的先決條件——沒有它什麼都無法啟動的環境變數、憑證、必要版本。
3. 破壞性且不可逆的操作——任何會刪除、覆寫、花費金錢或無法復原的事項。這是根據後果而非主題來放置：即使命令不常見，它也會放在靠近頂部，並且會被標記，而不只是提及。
4. 主要路徑——大多數讀者前來執行的事情，從頭到尾。
5. 其他所有事項，最常用的排前面。
6. 邊緣案例、問題排除和參考表格最後。

當文件大約超過五個章節時，摘要區塊應放在頂部；它列出讀者在能執行任何操作之前需要知道的事實，而不是散文的摘要。

--target=agent

讀者是一個模型，它將文件作為上下文載入，通常是在搜尋一個詞彙後只讀取匹配的片段。產出具有以下形狀的文件：

1. 始終先放關鍵區塊；僅在超過約 100 行時，才在最後逐字重複相同區塊。 先決條件、破壞性操作和硬性限制無論長度都應放在最前面。中間遺失退化（Liu 等人，TACL 2024）是在數千到數萬 token 範圍的多文件上下文中測量的——一份短到可以一次讀完的文件在這種意義上沒有「中間」，而尾部複製純屬重複，沒有任何檢索效益。僅在文件超過與內容列表（下方第 9 點）相同的約 100 行閾值時才進行複製，此時搜尋並讀取片段的讀者可能會落在文件中間而錯過該區塊。低於閾值時，只陳述一次，放在頂部，然後停止——那裡的第二份複製是階段 3 應該抓到的回歸，而不是此目標的功能。當複製合理時：將第一份標題設為 ## 關鍵限制，最後一份設為 ## 關鍵限制（重複）——兩個獨特的錨點，一個相同的內文，這是文件中唯一允許的近似重複標題。
2. 正向表述。 陳述要採取的行動。在確實需要禁止的情況下，在同一個句子中給出正向的替代方案：「寫入 state/，而不是 /tmp」。模型處理否定陳述的能力明顯低於肯定陳述。
3. 一個標題，一個可檢索的單元。 每個標題在文件中都是獨一無二的、字面意義的，並由代理會搜尋的詞彙組成——除上述關鍵區塊對之外。其章節應能獨立存在：沒有「如上所述」，沒有指代另一個章節的代名詞。
4. 在使用點使用字面識別碼。 完整路徑、確切命令列、確切環境變數名稱、確切檔案名稱——每次都如此，而不是一次之後用參考代替。
5. 可查證的陳述勝於敘述。 一個命令、一個路徑、一個值、一個退出條件。如果一個句子無法被查證，它很可能是理由——僅在它改變代理行為時才保留。
6. 僅使用 Markdown 結構——標題、列表、圍欄式程式碼、小型表格。不要在 Markdown 文件中添加 XML 標記方案；僅將 JSON 或 YAML 區塊保留給真正是機器讀取資料的內容。
7. 保持每個事實的最短形式。 輸入長度本身就會降低檢索能力，而主題相鄰但無法回答任何問題的內容會作為干擾項——近似但不精確的散文比完全沒有更糟。
8. 沒有矛盾。 兩個不一致的陳述比完全沒有更糟糕。在寫入之前解決它們。
9. 僅在超過約 100 行時才提供內容列表，因為代理可能只讀取整個檔案的片段，否則無法看到範圍。

驗收標準： 一個代理搜尋一個標題並只讀取該章節，其行為是正確的。

--target=human

讀者在閱讀之前會掃描，並只閱讀少數的文字。當格式沒有提供線索時，這種掃描會退化為沿著左邊緣的 F 型掃視——結構是防止這種情況發生的方法，而不是模仿它的方法。產出具有以下形狀的文件：

1. 將重點放在文件以及每個章節的第一句話。 最重要的內容放在前兩個段落；在那裡停止的讀者已經得到他們需要的資訊。
2. 前置載入的行。 每個標題、項目符號和段落都以其承載資訊的詞彙開頭——一行的前兩個詞會被閱讀，其餘則被掃視。
3. 描述性標題：「配置狀態目錄」，絕不要用「概述」、「注意事項」、「詳細資料」或「第三節」。
4. 一個段落一個概念，最多大約四個句子。
5. 客觀語言。 中性措辭在可用性方面明顯優於宣傳性措辭；這是理解度研究的結果，而非風格偏好。
6. 表格用於比較，散文用於推理。 超過三個項目且跨兩個以上屬性 → 表格。相互關聯、因果關係或細微差的解釋則保留散文——將論點碎片化為項目符號會失去連結。
7. 保留領域詞彙。 在第一次使用時，以內聯方式定義一個術語一次。不要簡化技術精確性，也不要為了達到可讀性公式分數而改寫——這些分數看不到組織結構，並會懲罰正確的術語。
8. 當內容超過約兩個螢幕或五個章節時，提供內容列表。

驗收標準： 讀者僅使用文件就能完成文件所述的工作。

不同目標之間必須差異之處

決定項目	--target=human	--target=agent
關鍵限制	一次，在第一個畫面，標記	在約 100 行以下時只在頂部一次；超過時則在頂部和最後逐字重複
章節獨立性	章節可以建立在前一章節的基礎上	每個章節自包含
交叉參考	「見上」是可以接受的	命名確切的標題
標題	描述性且可讀	獨一無二、字面意義、搜尋型
禁止事項	「不要做 X」是可以接受的	「做 Y」承載禁止的含義
識別碼	引入一次，然後縮短	每次都是完整且字面意義
推理	散文保留因果連結	僅在它改變行動時保留
內容列表	超過約 2 個螢幕	超過約 100 行
長度	約原始字數的一半	保持每個事實的最短形式

分歧檢查——必要。在寫入檔案之前，請至少命名此執行因宣告目標而做出的三項不同決定，並將它們放入報告中。