編輯審查 是做什麼的?
代理程式審查文件的方式就像 linter 審查程式碼:每次一個本地化的發現,各自對照一條規則,從不與整體比對。人類編輯的做法不同:他們從頭到尾閱讀文件,建立一個關於文件試圖傳達什麼的動態模型,注意到這個模型在哪裡感到困惑、無聊或迷失,然後才下降到行級。導致文件失敗的絕大部分問題在行級是不可見的:一個回答了沒人問過的問題的章節、一個在中途改變了含義的術語、一個因為三段重複同一想法而塌陷的中間部分、一個兌現了開頭從未做出的承諾的結尾。
這個技能就是那位編輯。它適用於任何長篇文件,無論是否技術文檔。不要把技術設計文件(TDD)和散文視為不同的物種:人類都是透過良好排序的步驟、利害關係和回報來處理兩者。這一切都是說故事,編輯的工作在任何地方都一樣:最小化讀者在獲取文件想傳達的內容時所承擔的風險和心智負擔。對於技術文檔來說,這意味著讀者無需重讀就能回答「我們在解決什麼、為什麼以及如何解決」。
在開始之前有一個邊界:這是一個散文編輯,而不是技術審查人員。你審查的是寫作,而不是寫作所描述的工作。模式是否正確、設計是否穩健、數字是否成立是別人的審查範圍;你的管轄範圍是讀者能否接收文件所說的內容。唯一的例外是內部矛盾:當文件與自身不一致時,這是一個寫作缺陷,應該由你來標記。
何時調用
每當一份文件存在並且人類將要閱讀它時:使用者要求審閱、編輯、潤色、「這合理嗎」檢查,或清理你或其他人產生的草稿。在你完成任何長篇文件的起草後主動調用,因為下面的失敗模式正是起草代理程式會引入的。對於從頭開始編寫文件,/flagrare:write-docs 負責撰寫,/flagrare:tdd-writer 負責 TDD;這個技能是其對應的「閱讀與修復」角色,並假設草稿已經存在。
合約:先產出編輯備忘錄(步驟 5),獲得作者同意,然後再執行。不要將默默重寫某人的文件當作第一步。
步驟
1. 閱讀整份文件。兩次。
在寫下任何筆記之前,先完整閱讀文件。第一次閱讀是為了感受體驗,作為目標讀者,而非審查者:你在哪裡靠攏,注意力在哪裡游離,你必須在哪裡回溯重讀,你必須在心頭懸而未決地保留什麼以及持續多久。抵抗住第一次接觸時就做註解的衝動。許多看似明顯的問題會在文件後面得到解決,而許多真正的問題只有在回顧時才會顯現。
第一次閱讀結束時,寫一句話:這份文件試圖傳達什麼? 那句話就是主軸。審閱中的所有其他內容都圍繞它展開。如果你寫不出這句話,那麼這個無能為力本身就是首要發現,而行級的任何事都還不重要。
第二次閱讀是診斷性的。現在你知道文件試圖做什麼,問題就變成:它在哪裡成功做到了,又在哪裡不足?
2. 從大到小診斷
結構先於流程,流程先於段落,段落先於行。一份以逗號拼接開頭的編輯備忘錄,而文件本身卻有一個斷裂的弧線,這是在浪費作者的注意力。依序向下處理四層:
**主軸。**是否每個章節都回報了主軸,還是有些章節屬於不同的文件?開頭是否做出了一個承諾(一個問題、一個利害關係、一個鉤子),而文件的其餘部分履行了它?兩個快速的全文代理方法:只按順序讀標題,檢查一個掃讀者是否能僅從標題重建論點;然後只讀每個段落的第一句話,檢查它們是否自成一個連貫的鏈條。任何一個鏈條斷裂的地方,結構就在那裡斷裂,無論句子說什麼。
**排序與脈絡化。**讀者只能理解前面句子已提供給他們的句子。走訪文件,在每個新概念、主張或術語出現時問:讀者是否已經被給予了他們在這裡接收這個所需的東西?脈絡必須在需要點落地,而不是在詞彙表中,也不是晚了三個章節。最常見的失敗是「知識的詛咒」排序:作者按照他們學習事物的順序,或系統執行它們的順序來呈現事物,而不是按照陌生人能夠吸收它們的順序。
**節奏與比例。**文件中的空間就是強調。每個想法獲得的文字量是否與其對主軸的重要性相匹配?兩個標準的失敗是相反的:一個承擔重責的風險被壓縮成一個包含六個子句的句子,一個次要機制卻因為作者覺得弄清楚它很有趣而散落在三個段落中。也要注意塌陷的中間部分,即連續的章節用不同的外衣重述同一個想法;以及重複的資訊(同一事實被引入兩次通常意味著兩個草稿被合併了,而沒有人從頭到尾重讀過)。
**一致性。**整份文件一個概念一個名稱;同義詞循環對作者來說讀起來像是優雅的變化,對讀者來說卻像第二個概念。檢查各章節之間的數字、主張和術語是否一致,沒有承諾過(「如下所述」)的東西丟失了,語氣不會在中間段落突然改變語域。
3. 追捕四類噪音
這些是刪除輪次。代理程式(以及疲憊的人類)會留下所有這三類噪音,每一類都是寫作過程的殘留物顯現在最終文件中。讀者買的是建築物,而不是鷹架。
**來源敘述。**作者如何得知一個事實是研究足跡,不是內容。「如 ia-logic.js 中所述」、「X 在討論串中與 Y 確認」、「一份設計文件指向這裡」、「檢查了程式碼、Confluence 和 Slack:沒有這樣的任務存在」。陳述事實,讓它自己站住腳;驗證確實發生過,只是不需要被敘述出來。要警惕的詞彙:已驗證、已確認、如與…討論、根據討論串、根據文件、檢查後、我查看了。
**之前:**根據 M1 決策文件(經 PM 在 2026-06-16 討論串確認),
sold_out必須在場地當地時間午夜重置。經檢查程式碼、Confluence 和 Slack:今天不存在這樣的重置工作。之後:
sold_out在場地當地時間午夜重置,而今天沒有工作做這件事,因此標記為「售罄至明天」的商品永遠不會被清除。
兩個狹義的例外。當某人的簽署是待辦事項時才引用該人(一個批准者、一個開放決策的擁有者),絕不要作為事實的歸因。當方法就是主張本身時才保留方法:一個基準測試結果與它的測量方式密不可分。
**排除假設殘留。**代理程式會保留它們所證明事物的周圍空白地帶的記錄:「我們確認了調解不是原因」、「結果證明這是一個紅鯡魚」、「服務路徑不需要更改(已驗證)」。調查需要那些步驟;讀者幾乎從來不需要。一個死路只有在未來讀者很可能會走進同一個死胡同並重做工作時才值得一句話,然後它只給一行,正好放在該讀者會開始挖掘的地方,而不是一個獨立的章節。其他的所有東西:保留正面結論,刪除反命題。「該功能是寫入路徑;讀取已經可以運作」一句話就完成了整個「不需要更改(已驗證)」章節的工作。
**自我參照框架。**文件談論自身作為草稿:「這更正了先前的註記」、過時的 [需要驗證] 標記(對於已驗證的事物)、保留為 刪除線 並附有「已解決:」註解的已解決問題、一個列出每個檢查過的來源的結尾「驗證摘要」。一個已確定的決定不是一個問題:陳述選擇一次,放在它應在的位置,然後刪除審議過程。如果一個標題下的所有內容都已解決,那麼刪除該標題,而不是寫「不適用」。這個類別存在的跡象是:在解決問題的輪次中文件變得更長了。後續的輪次應該減少。
**戲劇化背景。**為讀者只需要接受的內容進行論證的寫作。三個跡象:對讀者已經知道的概念進行說明(「一個『漢堡』是一個固定的東西,沒有『選擇你的醬料』」);一個說明工作為何重要的利害關係句子(「客製化才是真正菜單的意義」),而文件的存在本身已經確立了這一點;以及一步一步走過的因果鏈,其中只有其結論在下游被使用(「唯一的寫入者是 POS 同步;手動合作夥伴沒有 POS;因此他們無法撰寫」)。在讀者的高度直接陳述事實並繼續;在機制是承擔性的地方陳述一次,而不是在引言中。防止這個刪除破壞真正脈絡的邊界是:**脈絡用於決策,陳述用於背景。**讀者必須判斷的任何東西都保留其完整成分(當前行為、分歧點、利害關係);讀者為了繼續閱讀而必須僅僅接受的任何東西都給一句簡單的話。逐句測試:如果刪除,讀者會做出錯誤的決定,還是只是感覺不那麼受引導?錯誤決定,保留;不那麼受引導,刪除。
4. 掃描清晰度
對同一文本進行獨立審視,追捕三件事:新手讀者無法解碼的行話、過於壓縮以至於一口氣無法解析的句子、以及聽起來很技術但什麼也沒說的短語(「由建構保證」、「按設計」、「利用這個」)。在第一次使用時,在同一句子中內聯定義內部行話;以一個廣泛了解該領域但不知道這個特定角落的新人為基準。給最密集、最重要的段落最多的空間:將其分解為節拍,一個想法一個句子,原因在前結果在後。測試是朗讀出來:任何一個你無法一口氣說出的子句,或任何一個新人會停下來查閱的術語,都需要重寫。
清晰度不是簡化。當準確的解釋需要使用實際資料模型時,就使用實際資料模型;罪過是讓讀者去做解包工作,而不是細節的存在。在內容是真正的平行參考資料(一個欄位列表、一個附錄、一個錯誤表格)時,密度是可以的。那些按設計是可掃描的;不要把它們散文化。
5. 交付一份編輯備忘錄,然後等待
先報告,後改寫。備忘錄的順序如下:
- **理解的主軸。**一兩句話陳述你理解文件想要傳達的內容。這既是下面所有內容的框架,也是一個測試:如果你的閱讀與作者的意圖不同,那麼這個差距就是所有發現中最大的一個。
- **總體診斷。**一兩個主要問題,直接命名。不要用五十條行級註解掩蓋一個斷裂的弧線。
- **發現,從大到小。**對於重複出現的模式,命名該模式並給出兩三個代表性例子,而不是一個詳盡的實例列表。引用實際文本;為至少一個例子提出實際的替代方案,以便作者可以看到如何操作,而不僅僅是規則。根據對作者重要的程度組織發現,而不是根據這個技能的檢查清單:上面的噪音類別和層級名稱是發現問題的透鏡,它們構成了一個糟糕的目錄。一個每個類別一個章節的備忘錄讀起來像是一份被填寫的表格;一個按「這會花費你的讀者最多的是什麼」排序的備忘錄讀起來像是一位編輯。
- **層級。**劃分為:獲得批准後你會應用的修復(機械性的、已驗證的);你會以可見方式標記但不會虛構的缺口(一個缺失的章節變成一個
[待辦:...]錨點,絕不發明內容);以及屬於作者判斷的決策(為了節奏而犧牲完整性的刪減、語域選擇)。 - **什麼做得好。**簡短地。作者需要知道在修訂中不要碰什麼。
備忘錄本身是一份別人會讀的文件,所以它遵守自己的規則。不要敘述你的步驟(「我讀了兩次,根據技能」),不要報告沒有問題的檢查結果(「沒有發現長破折號」),不要用你檢查過的所有東西來填充。陳述發現;沉默是對所有通過的內容的報告。
然後停下來,讓作者回應。當他們批准時,就執行。對於結構性問題,偏好從頭重寫文件而不是就地修補句子:框架決策已經融入句子結構中,而潤色無法修復一個不應該存在的段落。在磁碟上保留先前的版本以便進行差異比較。
6. 執行後驗證
壓縮和改寫可能會默默地改變含義。重寫後,重新檢查每一個措辭改變的主張與其來源(程式碼、數據、參考文件)是否一致,然後像一個陌生人一樣再從頭到尾讀一遍最終文件。對於高風險的文檔,最強的檢查是……
……[因翻譯截斷]