Claude Code 工具集稽核：一份報告，兩項決策，清理 192 個項目

我之前寫的一個技能呼叫了一個已不存在的腳本。某個規則和某個技能用不同的措辭表達了相同的內容。CLAUDE.md 檔案中列出了一個我已刪除的指令。

如果放任不管，一個 Claude Code 工具集（包含技能、規則、代理、掛鉤和 CLAUDE.md 檔案）就會像這樣變得過時。這些項目在撰寫時都是正確的。

我將這個工具集視為代理展現其擁有者思維的地方，因此我認為一個雜亂的工具集，也代表著思緒的混亂。這篇文章記錄了 harness-stocktake 的發布，這是一個能一次性執行清理工作的工具。這並非新概念，過去六個月左右，我逐一完善了稽核的各個部分，隨後發現它們可以合併。

第一個部分是 skill-stocktake，一個用於技能的稽核工具。我在 2026 年 2 月開發了它，並撰寫了相關文章，隨後向社群技能集合 ECC (Everything Claude Code) 提交了一個 Pull Request，並成功合併。

之後，用於從技能中提煉規則的 rules-distill 也被合併到 ECC 中。我在本地持續新增，直到有了七個部分：skill-stocktake 用於技能，rules-stocktake 用於規則，rules-distill 用於尋找規則候選，agent-stocktake 用於代理，hook-stocktake 用於掛鉤，context-sync 用於使 CLAUDE.md 和 README 等描述與實際內容保持一致，以及 repo-asset-stocktake 用於儲存庫設定和腳本。每個部分都變得更好，但整個工具集並未因此變得整潔。

這些部分是獨立運行的，每個都要求我一次決策一個項目。我在 2026 年 10 月 31 日寫道：「skill-stocktake 要求我逐一決定每個項目，因此很難批量核准。」

逐項決策是一種設計選擇，它防止我在未查看內容的情況下進行批量核准。我將這種設計複製到了所有七個部分中，因此決策的數量隨著部分和項目數量的增加而增長。

各部分負責判斷，核准和應用則在一個地方完成。這次合併改變了工作分配方式。七個部分負責處理所有直到判斷的環節。判斷結果包括：保留 (Keep)、改善 (Improve，使內容更好)、更新 (Update，使過時的參考與現有內容保持一致)、合併 (Merge) 或淘汰 (Retire)。

核准和應用則交由 harness-stocktake 中的單一程序處理。這七個部分平行判斷，結果會彙整成一份報告。每個項目佔一行，包含判斷結果、目標檔案、原因以及具體的變更。我會閱讀報告，只修改我想變更的行，然後一次性核准。

核准的變更會應用到一個工作分支，並產生一份完成報告。我會查看完成報告，然後合併到主分支。

逐項決策的目的是為了防止未經閱讀就核准。現在採用單一核准，防止這種情況的不是數量，而是報告的撰寫方式。每一行都包含足夠的理由，讓使用者無需打開檔案即可做出決策，且影響最大的項目（淘汰）會優先顯示。

以下是一份報告中的一行範例，經過縮短。它來自外掛程式儲存庫中的範例工具集，任何人都可以打開查看：判斷：淘汰 (替代方案：改善) 目標：.claude/hooks/check-secrets.sh 原因：settings.json 的 PostToolUse 在每次 Bash 呼叫時都會呼叫此腳本，但該檔案不在儲存庫中。每次呼叫都會導致掛鉤錯誤，且沒有實際執行任何秘密檢查。

將所有內容彙整到一份報告中，也讓各部分之間的衝突變得可見，例如淘汰一個技能可能會破壞某些規則的引用。同一天，我對自己的工具集進行了第一次執行。這七個部分產生了 192 個項目，其中 74 個是非保留項目。

我做了兩項決策：核准報告，以及閱讀完成報告後進行合併。當我在這篇文章中提到「清理」時，指的是核准的變更已應用並合併到主分支的狀態。我只執行過這一次。

我對 20 個公開工具集進行了測試。如果只測試自己的工具集，我可能只會看到自己製造混亂的習慣。因此，我在本地複製了 20 個公開工具集，並以唯讀模式 (--dry-run) 執行。

選擇方式是：一次 GitHub 程式碼搜尋 (filename:SKILL.md path:.claude/skills) 返回了 662 個儲存庫；我使用固定種子將它們打亂，並選取了前 20 個非分支、在 90 天內更新過且至少有五個技能的儲存庫。我沒有聯繫這些擁有者，也不會公開儲存庫名稱。

在三個領域中，20 個儲存庫中有 19 個至少獲得一個非保留的判斷：文件 (CLAUDE.md、README 和 ADRs，即設計決策記錄)、技能，以及儲存庫設定和腳本。對於規則，則是 20 個中的 2 個。非保留判斷不僅包括淘汰和合併，還包括改善和更新的建議。判斷者也是 Claude 模型，而非擁有者。

因此，這些數字代表的是潛在的修復候選，而非確認需要修復的缺陷。這 20 個儲存庫來自單一搜尋，不代表整個 Claude Code 工具集生態。此外，我執行的是預發布版本。

在執行 /doctor 之後再執行 harness-stocktake。Claude Code 內建了 /doctor 指令，它會列出未使用的外掛程式、未使用的技能和緩慢的掛鉤；/doctor prompt-audit 則列出過時或矛盾的指令；而 /skill-doctor 則測量每個技能的常駐成本。

harness-stocktake 則著重於跨檔案的內容檢查：例如與技能矛盾的規則、腳本已消失的掛鉤、與程式碼不符的 ADR，以及執行相同工作的兩個代理。當我在自己的工具集上同時執行兩者並進行比較時，它們各自發現了對方未發現的問題，也存在一些意見不合之處。

例如，對於一個我 10 天未使用的技能，/doctor 建議將其關閉，而 harness-stocktake 則在閱讀其內容後判斷為保留。查看使用頻率和查看內容本身會得出不同的答案。因此，我發布這個工具並非為了取代 /doctor，而是作為在 /doctor 之後執行的工具。

試用看看。你可以透過 claude plugin install harness-stocktake --marketplace shimo4228/harness-stocktake 安裝它。

打開 Claude Code 並輸入 /harness-stocktake:harness-stocktake --dry-run。它會讀取 ~/.claude 並寫入一份 Markdown 報告，不會更改任何檔案。若要查看儲存庫的 .claude/ 目錄，請新增 --project <儲存庫路徑>。此外，還有一個 GitHub Action 可用於每月在儲存庫上執行此工具。

我的決策與未決事項。我將這七個部分打包成一個外掛程式，並發布了一個 GitHub Action，用於在儲存庫上持續運行。我在本地運行了公開的工具集，沒有聯繫擁有者，只發布了彙總數據。目前沒有傳送使用數據（遙測）的機制。

我將代理知識增長的程序分為六個階段，稱之為 AKC (Agent Knowledge Cycle)。harness-stocktake 執行其中一個階段：整理 (Curate)，該階段負責查找重複、過時和從未觸發的項目。有些事情我尚未確定。我只在自己的工具集上與 /doctor 進行了比較，而沒有在 20 個公開工具集上進行。

檢查判斷結果是否與儲存庫中的實際內容相符，也是由 Claude 系列模型完成，而非擁有者。作為外掛程式分發的工具集不在這 20 個之列。而且，我尚未測量代理在修復後是否表現得更好。

我認為保持工具集整潔，就像保持思緒清晰一樣。我所改變的是整理的方式：從每個項目一個決策，變為一份報告和兩項決策。

相關連結：harness-stocktake (GitHub)，外掛程式本身，包含範例工具集及其產生的報告。harness-stocktake-action (GitHub Marketplace)，一個用於每月在儲存庫上執行此工具的 GitHub Action。

將 AI 的弱點轉移到 Shell 腳本，設計、建構和發布技能稽核指令，記錄了第一個部分 skill-stocktake。我找到了將我的 Claude Code 技能發布給 57,000 名開發人員的最短路徑，記錄了向 ECC 提交 Pull Request 的過程。

代理知識週期 (DOI)，六個階段，包括整理。本文的 Markdown 原始碼 (GitHub)，每篇文章的 Markdown 和索引 (docs/PUBLICATIONS.md) 都位於同一個儲存庫中。作者的 GitHub，包含 DOI 的研究儲存庫。

本文撰寫方式：Claude (Claude Code) 撰寫了散文並將其翻譯成英文。它根據我的工具集稽核記錄、在 20 個公開工具集上本地運行的彙總數據、我之前的文章以及與我的對話進行了工作。

我決定將工具集視為思維的出口，將我所完善的各部分合併的故事線，並將文本中的數字限制為 192 個項目和兩項決策。我在發布前閱讀了完整的日文原文，並對兩個版本的內容負責。