docs-update 是做什麼的？
文件會悄然腐化：沒有錯誤發生，只是文字不再真實。此技能會找出近期變更應觸及的文件，並使其保持一致。
下列命令會完整寫出 ~/.claude/skills/docs-update/scripts/ 的路徑。請完全按照範例執行——保留開頭的 ~，不要展開它。 權限規則會比對文字命令字串，因此 /home/<你>/.claude/...（波浪號展開後）、python3 ~/...、相對路徑或先執行 cd 都會被視為不同的字串，且每個都會重新觸發提示。使用波浪號路徑並非「非正式寫法的絕對路徑」——對權限規則而言，它就是路徑。
文件應與變更一同交付，而非事後補上。 如果你在功能分支上，請將文件提交到該分支，以便合併時一併攜帶。事後的文件跟進 PR，往往永遠不會有人寫。
1. 選擇範圍
依優先順序：
使用者已指定。 「全面掃描」、「從 v2.1 開始」、「僅此分支」——直接使用。--full 參數代表全面掃描，會讀取所有內容，適合長時間未更新或首次在此儲存庫採用此技能時使用。
文件記錄自身的上次更新點：
~/.claude/skills/docs-update/scripts/docscheck.py markers
如果文件帶有 Last updated: <日期|SHA>，則從該點開始對該文件進行範圍設定（使用 --since）。不一致的文件會各自擁有自己的範圍，沒有單一答案。
否則，從 Git 推導範圍：
~/.claude/skills/docs-update/scripts/docscheck.py scope
它會優先選擇最後合併的分支（一整個分支的工作量才是人們通常所指的單位），若無則回退到最後一次提交。可使用 --since <參考> 覆蓋。
當前工作階段完成的工作是腳本無法察覺的情況。如果本次工作階段已做出變更，你已經知道哪些檔案被修改，請將工作階段前的參考傳遞為 --since，或直接根據你的編輯清單處理。
scope 會將結果分為 kind=code（程式碼變更）和 kind=doc-already-touched（已觸及的文件）。第二類文件很重要：它們是隨著變更一併更新的文件，因此應該檢查其正確性，而非檢查是否有缺失。
2. 找出變更實際影響的文件
~/.claude/skills/docs-update/scripts/docscheck.py impacted
針對每個變更的程式碼檔案，此命令會回報在文件中明確提及該路徑的文件。引用你變更過檔案的文件，最有可能描述已不再真實的內容，這遠比重新閱讀所有文件更有效。
它僅比對完整路徑。同時比對父目錄聽起來更全面，但實際用途不大：在一個 monorepo 中，apps/web-nuxt/ 出現在 62 份文件中的 55 份，因此所有變更都會影響所有文件。
result=none 是正常情況，並不代表「無需處理」——只是沒有文件提及這些路徑，因此應根據主題進行判斷，即步驟 3。
3. 根據主題判斷，使用儲存庫自身的文件分類
impacted 能找到提及路徑的文件，但無法找出描述你變更的行為卻未提及檔案的文件。因此，請閱讀變更內容並思考其意義。
首先了解此儲存庫如何組織文件——例如 brain/、docs/、CONTEXT.md、ADR 目錄——並遵循該結構，而非自行創建。如果專案技能涵蓋文件（.claude/skills/*），則以其為準。
常見對應關係：
| 變更類型 | 應更新的文件 |
|---|---|
| 新的使用者可見功能 | 功能文件 + 其索引/目錄行；README 功能列表 |
| 變更既有行為 | 該功能的文件 |
| 結構、認證、建置、儲存、即時通訊、提供者 | 相關架構文件 |
| 非顯而易見的決策，或在審查中浮現的決策 | 決策/ADR 日誌，包含其理由 |
| 新術語 | 詞彙表 |
| 新增或變更的環境變數、命令、腳本 | README 及任何設定/操作文件 |
| 新增依賴 | 任何堆疊/技術列表文件（這些通常手動維護且常被遺忘——請比對清單檔案） |
| 使用者可見的變更 | CHANGELOG 的 [Unreleased] 區段 |
兩個陷阱：
- 嵌入在文章中的衍生事實。 文件若寫著「目前版本為 2.16.2」或列出技術棧，這些資訊是從其他地方複製而來且已變更。請比對真實來源（如清單檔案、版本檔案），而非相信文章。
- 本應是歷史性或目標性的文件。 CHANGELOG 條目、TODO 和 ROADMAP 中提及的檔案可能已被刪除或從未撰寫。請勿「修正」它們。
4. 檢查引用是否仍有效
~/.claude/skills/docs-update/scripts/docscheck.py links
兩種型別：
kind=link- 相對 Markdown 連結，目標已不存在。這始終是真正的問題。kind=source- 內聯程式碼路徑，已不復存在，通常是因為檔案移動或重新命名。敘述性文件會被排除，而大括號展開、<佔位符>、Glob 模式和 .gitignore 忽略的建置輸出會被過濾，因此剩下的內容值得檢查。
僅修正範圍內的內容。儲存庫其他位置的發現值得報告，但不要無聲地將工作擴大成全面掃描。
5. 撰寫
為你撰寫的所有內容套用 Unslop
對你新增或修改的每一行套用 unslop 技能。 文件是 slop 造成最大傷害的地方：它由試圖學習的人閱讀，是新接觸者首先遇到的內容，且不像聊天訊息那樣短暫。
文件中最常見的 slop 跡象：
- 開場廢話。 「本文提供了一個關於……的概述」、「在本節中，我們將探討……」。刪除它們，直接從事實開始。
- 用文章重複程式碼。 「
getUser函式取得一個使用者。」如果句子只是將識別碼擴展成英文，就毫無價值。請寫下程式碼無法表達的部分：約束、原因、注意事項。 - 空洞的加強詞：全面、穩健、無縫、強大、靈活、簡單、輕易、僅僅。「只要簡單地執行 X」在 X 不簡單時就是錯誤的。
- 在答案明確時使用模糊用語：「通常」、「一般來說」、「應該正常來說」。要嘛就是如此，要嘛取決於某個可命名的條件——請明確寫出。
- 注意-填充：「值得注意的是」、「請注意」、「請記住」。其後的句子才是內容，直接寫出它。
- 總結當頁內容的摘要章節。 如果文件需要回顧，就代表它太長了。
- 重複名稱的說明欄位。 表格行
| --verbose | 啟用詳細輸出 |浪費一行且沒有傳達任何資訊。 - 三法則填充——第三個例子只是為了節奏而加入，而非因為它與前兩個不同。
配合檔案風格，而非 slop
配合檔案既有的語氣：時態、密度、條目是一行還是段落。如果文件某個段落突然風格不同，比整份文件都簡潔更糟糕。
這兩個規則只有在既有文件本身草率時才會衝突。此時：配合其結構和密度，而非填充詞，且不要重寫你未觸及的其他章節。 一份文件更新若同時調整整份文件的風格，會產生難以審查的差異，並且掩蓋了真正重要的變更。如果某份文件需要全面的文章潤飾，請提出此事，並將其視為一個獨立的工作。
其他
- 連結原始碼路徑，而非重述程式碼，這樣下一次變更時，連結會中斷而非默默地與文章內容矛盾。
- 描述目前為真的狀態，使用現在式。文件不是變更日誌：「我們用 Y 取代了 X」屬於 CHANGELOG，「系統使用 Y」屬於文件。
- 如果文件有上次更新標記，請更新它。
6. 報告
- 使用的範圍及其原因
- 更新的文件及各文件中的變更
- 檢查過但刻意保留不變的文件
- 超出範圍但發現的損壞連結或引用（列出但不修正）
- 任何無法自行判斷而需要使用者協助的事項