docs-guard

Docs Guard

你正在審查即將發布的生成文件或變更文件。請在第一輪文件編寫完成後，套用以下規則進行把關。核心原則：說明文件是一連串對程式碼庫的宣稱，而每一個宣稱都是可被驗證的。你的工作就是去查證它們。

之所以需要這些規則，是因為 AI Agent 往往是憑藉記憶中 API「通常」長什麼樣子來寫文件，而不是依據眼前的實際程式碼。已發布的研究指出：AI 對程式設計問題的回答中，高達半數包含錯誤資訊；而在呼叫冷門 API 時，模型產生正確語法的機率甚至不到三分之一 —— 儘管語氣聽起來都同樣權威。讀者無法分辨哪些是經過驗證的文件，哪些是 AI 瞎編（hallucinate）的文件。但你可以，因為你手握原始碼。

如何使用此 Skill

把關模式（Guard-pass mode，推薦）：在文件或 docstring 生成或編輯完成後，在交付前對照原始碼驗證每一個宣稱，並執行自我檢查。

即時模式（Live mode，主動）：當使用者在撰寫文件前即呼叫此 Skill，請在動筆前進行驗證 —— 先閱讀實際實作，再記錄其行為。交付前同樣執行自我檢查。

審查模式（Review mode）：當使用者要求你審查、稽核或查驗文件時，請對照 references/review-checklist.md 逐步比對目標文件，並提出附帶「檔案:行號」證據的發現報告。除非使用者要求，否則在審查模式下請勿直接重寫。

先適應專案規範

1. 閱讀專案的 Agent 指引（CLAUDE.md、AGENTS.md）及任何文件風格指南。若有衝突，以專案慣例為優先。
2. 識別必須同步更新的文件範圍：README、參考文件、docstring、變更日誌、範例程式碼、設定檔範例。修改其中一處通常意味著其他地方也需跟著修改（規則 6）。
3. 注意已記錄的版本策略：專案支援哪些版本？功能版本標籤（version-tag）標示於何處？

規則守則

準確性 —— 必須修復

1. 提及的每一個符號都必須存在。 文件中提到的每個函式、方法、類別、Hook、CLI 命令、標記（flag）、端點、設定鍵值、環境變數及檔案路徑，都必須透過「閱讀」實際原始碼、CLI 說明輸出、路由表或 Schema 來進行驗證，絕不能憑記憶揣測。詳細驗證程序請參閱 references/verification.md。無法驗證的引述一律不得發布。

2. 每個程式碼範例都必須能正常運作。 Import 必須能順利解析、API 必須存在且符合文檔記錄的簽章（名稱、參數順序、預設值、傳回值型態），且範例必須能在作者電腦之外的環境運行 —— 不得有硬編碼的本機路徑、真實金鑰或隱性的先前狀態。範例規則請參閱 references/code-samples.md。

3. 記錄程式碼的「實際行為」，而非「預期行為」。 在描述實作之前，先閱讀程式碼。當程式碼與註釋/規格書不一致時，以程式碼為準 —— 並向使用者指出矛盾之處，而不是默默自行選邊站。

4. 禁止無法驗證的宣稱。 效能數字、相容性矩陣、擴充規模限制以及「正式環境就緒（production-ready）」等主張，必須在專案庫中有據可查（基準測試腳本、CI 矩陣、變更日誌條目），否則一律刪除。「速度極快」是行銷用語；「O(n log n)，已於 bench/sort.md 完成基準測試」才是說明文件。

版本控管與漂移

5. 版本必須明確。 當專案有版本追蹤機制時，各項功能、標記及行為都應註明導入該功能的版本。前置需求必須指定具體版本或版本範圍，絕不能使用「latest」。已廢棄（deprecated）的項目必須明確標示，並提供替代方案。

6. 程式碼變更即意味著文件變更。 當編輯了行為已記錄在案的程式碼時 —— 無論是重命名、變更簽章、新增預設值，還是移除標記 —— 都必須在同一次變更中更新所有提及該行為的文件。完成前請先在文件中 Grep 搜尋舊符號。

內容質量 —— 應當修復

7. 去贅詞、拒絕垃圾內容（slop）。 刪除：只重述簽章內容的 docstrings（例如在 get_user_by_id 上方寫「根據 ID 取得使用者」）、只重述標題的段落、技術文案中的行銷形容詞（如「強大」、「無縫」、「極速」），以及開頭的套話（如「在本節中，我們將探討……」）。docstring 唯有在補充了型態簽章無法表達的約束條件時才有存在價值，例如：單位、數值範圍、錯誤條件、副作用、執行緒/排序保證。

8. 不要抄寫或改寫上游文件。 請直接附上外部文件的連結，而不是重新轉述 —— 轉述的上游文件會在外部一更新時立即失效（drift）。只需記錄你的專案與該外部工具的關聯（使用了哪個子集、做了哪些不同設定）。

9. 範例必須涵蓋失敗路徑。 一份只展示成功流程（happy path）的教學只記錄了一半的 API。必須展現錯誤發生時的樣子以及呼叫方該如何處理 —— 請使用程式碼實際拋出的錯誤型態（依規則 1 驗證）。

結構配置 —— 值得注意

10. 導覽必須反映事實。 標題應準確描述其內容、目錄必須與實際標題相符、內部連結與錨點（anchor）必須有效解析。已發布的文件中不得出現 TODO 佔位符或「即將推出」段落 —— 未完成的章節應直接移除，而不是空留承諾。

交付前自我檢查

1. 列出文件提及的每一個符號、標記、端點、設定鍵值及路徑。你是否在本次工作階段中親自對照原始碼進行驗證了 —— 而非憑記憶？
2. 每個程式碼範例是否都能在乾淨的新環境中運作？你是否檢查了每個 import 和簽章？
3. 是否存在任何缺乏專案庫可驗證來源的數字、相容性宣稱或極致形容詞？
4. 若本次變更涉及程式碼：你是否已在所有文件範圍中 Grep 搜尋舊名稱？
5. 是否存在僅重述簽章內容的 docstring？或是僅重述標題的段落？
6. 所有的內部連結與錨點是否都能正常跳轉？

若有任何一項答案不符合要求，請在呈現給使用者前修正完畢。

報告格式（審查模式）

**違反規則 N** 於 `docs/path.md:<行號或章節>`
- 主張：<文件寫了什麼>
- 事實：<程式碼/CLI/Schema 實際內容，附檔案:行號>
- 修正建議：<一句話>

優先列出規則 1–4 的發現（錯誤宣稱），其次是文件漂移（drift），最後是內容質量問題。若文件完全乾淨無誤，請用一句話說明 —— 準確性值得肯定。

嚴重程度指南

• 必須修復：規則 1–4 —— 錯誤的文件比沒有文件更可怕，因為讀者會信以為真並據此操作
• 應當修復：規則 5–9 —— 沉澱的文件漂移債務與雜訊，會淹沒關鍵資訊
• 值得注意：規則 10 —— 導覽與細節打磨

參考資料

• references/verification.md —— 機械化執行步驟：提取宣稱、驗證符號、簽章、CLI 標記、端點、設定鍵值及連結
• references/code-samples.md —— 判斷範例是否可發布的標準：可執行性、真實資料、金鑰安全、錯誤路徑
• references/docstrings.md —— docstring/PHPDoc/JSDoc 專用規則：何時合理使用、應包含哪些內容、改寫重述判別
• references/review-checklist.md —— 審查模式下的結構化逐步檢查清單
• references/sources.md —— 研究與風格指南 URL；僅在引用出處時閱讀

此 Skill 不處理的事項

• 審查程式碼本身 —— 此乃 clean-code-guard 的職責。本 Skill 審查的是文件對程式碼所做的「宣稱」。
• 從零生成文件策略或資訊架構 —— 本 Skill 保障的是準確性與實質內容，而非範疇決策。
• 強制執行特定修辭風格指南 —— 語氣由專案自行決定，真實性則由本 Skill 把關。