潔癖.skill
Stop AI agents from littering your repo with
plan.md,todo.md,summary.md, and throwaway artifacts. 別讓 AI Agent 把你的專案根目錄變成 Markdown 垃圾場。
這不是一個 Markdown 刪除器。 此技能管理 Agent 工作的本地環境：儲存庫產物、工作區快取、WSL2/Docker 儲存、套件管理器快取、模型快取以及 Agent/IDE 狀態。
一個檔案或快取並非因為體積龐大就是垃圾。當它沒有意圖、沒有擁有者、沒有讀者、沒有生命週期、沒有復原路徑時，就成為衛生風險。目標不是激進地刪除，而是確保每個產物、快取和本地環境足跡都有其目的、位置和安全的下一個動作。
1. 衛生模型
使用三層模型：
| 層級 | 範圍 | 範例 | 預設動作 |
|---|---|---|---|
| Repository | Agent 建立的產物 | plan.md, todo.md, .agent_tmp/, .agent_reports/ | 分類、回報、乾執行清理 |
| Workspace | 跨專案的開發快取 | node_modules, .venv, target, 建置快取 | 審計、評分、建議 |
| Local machine | 工具鏈與虛擬化環境 | WSL2, Docker Desktop, 套件快取, 模型快取, Agent/IDE 狀態 | 唯讀映射、風險分級、手動引導 |
報告應區分：
Findings— 本地觀察到的事實。Safe Suggestions— 低風險後續步驟，例如執行乾執行或將未來報告移至.agent_reports/。Manual / Risky Operations— 遷移、VHDX 壓縮、Docker 數據搬遷、模型快取搬遷或配置編輯。絕不自動執行這些操作。
2. 何時使用此技能
當使用者詢問以下問題時，請調用此技能：
| 觸發情境 | 範例 |
|---|---|
| 整理 / 組織 | "整理專案目錄", "clean up this repo", "organize my project" |
| 生成產物 | "寫計畫", "生成報告", "create a plan/todo/summary/report/audit" |
| 審計 | "審計專案檔案", "scan for agent artifacts", "列出可疑檔案" |
| 清理 | "清理 Agent 檔案", "clean agent temp files", "刪除暫存檔案" |
| 決定 | "這個檔案該不該生成？", "should I create this file or keep it in chat?" |
| 評分 | "給我的倉庫打潔癖分", "repo hygiene score", "how clean is my repo?" |
| 工作區審計 | "掃描工作區", "audit my workspace", "找出多個儲存庫的 Agent 產物" |
| 本地環境審計 | "審計我的本地環境", "inspect local agent environment", "where are my dev caches" |
| 建立規則 | "建立 AGENTS.md / CLAUDE.md / Cursor Rules" |
| 任務完成 | 結束前的衛生檢查 |
| 污染 | "多個 Agent 亂寫檔案", "project root is a mess of markdown" |
| 抱怨 | "不要生成垃圾文件", "清理 plan.md / todo.md" |
| 環境檢查 | "inspect my coding environment", "where is node/python/go installed?" |
| 磁碟增長 | "why is my C drive growing?", "find package/model caches" |
| WSL2 / Docker | "WSL2 佔用太大", "Docker Desktop disk is huge", "where is ext4.vhdx" |
| 模型快取 | "Ollama/Hugging Face models on C drive", "AI model cache audit" |
| Agent 狀態 | "Claude/Codex/Cursor state locations", "agent config/cache footprint" |
3. 何時不使用此技能（絕對禁止）
停下來詢問使用者或嚴格避免，若請求涉及：
- 刪除正式專案文件
- 修改使用者編寫的筆記
- 清理原始碼（
src/,lib/,app/） - 觸碰工具狀態目錄（
.codex/,.claude/,.cursor/,.vscode/,*.sqlite,state.json,session.json,workspaceStorage,globalStorage,auth-token） - 未經確認的大規模 Markdown 刪除
- 強制刪除 Git 追蹤的檔案
- 在個人/使用者資料夾中清理未知的 Markdown
- 修改系統設定或登錄檔
- 註冊排程工作
- 上傳日誌、報告、憑證或環境數據
- 未經使用者明確指定根範圍就掃描整台電腦
- 讀取身份驗證令牌、session 檔案、sqlite 資料庫或私人日誌
- 僅僅因為體積龐大就刪除工具或模型快取
- 在沒有單獨明確的遷移請求下移動工具或重寫環境變數
- 壓縮 WSL/Docker VHDX 檔案
- 匯出/匯入 WSL 發行版
- 編輯
.wslconfig、Docker 設定、shell profile 或套件管理器配置
4. 產物分類
Agent 建立的每個檔案都屬於五個類別之一。類別——而非副檔名——決定處理方式。
| 類別 | 範例 | 存放位置 | 生命週期 | 自動刪除？ |
|---|---|---|---|---|
| A — 正式文件 | README.md, CHANGELOG.md, LICENSE, docs/**, CONTRIBUTING.md, 使用者筆記 | docs/, 專案根目錄 | 永久 | 永不 |
| B — 使用者要求的交付物 | 審計報告、遷移計畫、研究報告（使用者明確要求） | .agent_reports/ | 30 天 | 保留期限後 |
| C — 暫時性工作產物 | 計畫、待辦事項、筆記、草稿、進度、任務清單 | .agent_tmp/ | 7 天 | 保留期限後 |
| D — 自我表揚型 | 摘要、最終報告、工作摘要、經驗教訓、變更摘要 | 不要建立 | N/A | N/A |
| E — 工具狀態（超出範圍） | .codex/, .claude/, .cursor/, *.sqlite, 狀態檔案 | 工具目錄 | N/A | 永不 |
關鍵規則：
- Class A → 絕不自動刪除，絕不自動重寫
- Class B → 特定檔案名稱
<task>_<date>.md，絕不在專案根目錄 - Class C → 僅限
.agent_tmp/，絕不提交，任務結束時清理 - Class D → 不要建立。對話本身就是摘要。
- Class E → 完全忽略，絕不標記為可疑
5. 產物意圖檢查（強制）
在建立任何新檔案之前，請填寫此檢查表。如果您無法回答每個欄位，請不要建立該檔案。
產物意圖檢查
─────────────────────
1. 使用者要求建立檔案？ yes / no
2. 目的：
3. 讀者：
4. 預期生命週期： session / days / persistent / formal-doc
5. 目標路徑：
6. 為什麼僅用對話回覆不夠：
7. 類別： temporary / persistent / formal-documentation
8. 是否應加入 .gitignore？ yes / no
決策規則：
| 情境 | 動作 |
|---|---|
| #1 = no, class ≠ A | 不要建立。 在對話中回答。 |
| 目的 = 計畫/待辦事項/摘要/進度, 讀者 = 此使用者 | 僅限對話。 不建立檔案。 |
| 必須建立, class = C | .agent_tmp/<specific-name>.md |
| 必須建立, class = B | .agent_reports/<task>_<YYYY-MM-DD>.md |
| Class = A (正式文件) | docs/ 路徑，使用者明確要求 |
| 檔案只是重複此對話內容 | 不要建立 |
| 無明確讀者 | 不要建立 |
| 無明確生命週期 | 不要建立 |
| 無後續使用 | 不要建立 |
6. 檔案生成的硬性規則
- 預設：不要寫入檔案。
- 計畫、待辦事項、摘要、進度 → 在對話中回答。
- 禁止在專案根目錄放置通用流程 Markdown，除非使用者明確指定檔案名稱。
- 禁止在專案根目錄（除非使用者明確要求該確切檔案）：
todo.md, plan.md, notes.md, lessons.md, summary.md, report.md, final_report.md, implementation_plan.md, migration_plan.md, audit_report.md, cleanup_report.md, task_list.md, progress.md, work_summary.md, changes_summary.md, *_summary.md, *_report.md, *_plan.md - 暫存檔案 →
.agent_tmp/ - 持久性報告 →
.agent_reports/ - 正式文件 →
docs/（僅在明確要求時） - 不要為了「看起來專業」而生成報告。
- 不要自動建立任務結束摘要檔案。
- 不要將對話內容複製到檔案中。
- 使用具體檔案名稱：
<task>_<context>_<date>.md - 如果使用者要求檔案，先提議路徑 + 檔案名稱。
- 如果使用者說「告訴我」/「總結」/「規劃一下」→ 在對話中回答。
7. 允許與禁止的位置
允許
| 內容 | 允許的位置 |
|---|---|
| 暫存工作檔案 | .agent_tmp/ |
| 使用者要求的報告 | .agent_reports/ |
| 正式文件 | docs/（需明確要求） |
| 使用者指定的路徑 | 使用者明確命名的任何路徑 |
禁止
| 位置 | 原因 |
|---|---|
| 專案根目錄（通用流程 Markdown） | 保留給正式儲存庫檔案 |
src/, lib/, app/ | 原始碼目錄 |
.codex/, .claude/, .cursor/, .vscode/ | 工具狀態 — 不要觸碰 |
8. 受保護的檔案（永不自動刪除）
README.md, README.*.md
CHANGELOG.md
LICENSE, LICENSE.*
CONTRIBUTING.md
CODE_OF_CONDUCT.md
SECURITY.md
Everything under docs/
任何在 .agent_tmp/ 或 .agent_reports/ 之外的 Git 追蹤檔案
使用者手寫筆記
9. 生命週期
| 位置 | 預設保留期限 | 清理方式 |
|---|---|---|
.agent_tmp/ | 7 天 | Agent 應在任務結束時自行清理 |
.agent_reports/ | 30 天 | 若需長期保留則移至 docs/ |
docs/ | 永久 | 無自動生命週期 |
10. 儲存庫衛生分數
當被問及儲存庫衛生分數時，若 Python 可用，優先使用 ${CLAUDE_SKILL_DIR}/scripts/score_repo_hygiene.py。在僅有 Windows 的環境中，使用 ${CLAUDE_SKILL_DIR}/scripts/score-repo-hygiene.ps1。
| 分數 | 評級 (en) | 評級 (zh) |
|---|---|---|
| 90–100 | Clean | 很乾淨 |
| 70–89 | Mostly clean | 基本乾淨 |
| 50–69 | Needs tidy-up | 需要整理 |
| 0–49 | Artifact landfill | Agent 產物垃圾場 |
評分維度： 根目錄清潔度、產物放置、保護文件清晰度、Git 衛生、Agent 狀態隔離、清理就緒度。可選權重因子：--weights references/score-weights.example.json。
可選專案政策：在儲存庫根目錄放置 .tidy-skill.json（或 tidy-skill.policy.json），或傳遞 --policy。結構範例：references/tidy-skill.policy.example.json。政策可以擴展禁止/保護的根目錄模式、設定 min_score、要求 .agent_tmp/ + .agent_reports/，並透過 planning_root_globs 選擇有意圖的規劃佈局根目錄名稱（有關規劃與檔案共存，請參閱 references/tidy-skill.policy.pwf.example.json）。無需政策時，.planning/** 被視為有意的 Class C 工作記憶。
醫生、修復、分類、快照
| 需求 | 腳本 |
|---|---|
| 一次性安裝 + 衛生醫生 / CI 關卡 | ${CLAUDE_SKILL_DIR}/scripts/tidy_doctor.py |
| 乾執行優先的安全修復（佈局目錄；可選根目錄移動） | ${CLAUDE_SKILL_DIR}/scripts/tidy_repair.py |
| 乾執行主機鉤子配置發射器 | ${CLAUDE_SKILL_DIR}/scripts/tidy-install-hooks.py |
寫入前分類路徑（類別 A–E）；透過 --stdin --json 批次處理 | ${CLAUDE_SKILL_DIR}/scripts/classify_artifact.py |
儲存/比較分數歷史；基於 min_score 閘控 | ${CLAUDE_SKILL_DIR}/scripts/hygiene_snapshot.py |
安全動詞（始終具有相同意義）：
- dryrun — 僅預覽（修復、清理、安裝鉤子的預設值）
- careful — 僅修改 Agent 工作檔案（
tidy_repair.py --apply --move-root） - guard — 堅決拒絕主機配置、VHDX、Docker 數據、Git 追蹤檔案、Class A 文件
tidy_repair.py 是診斷→下一步的醫生夥伴。預設僅產出計畫。--apply 創建帶有 .gitkeep 的 .agent_tmp/ + .agent_reports/。根目錄流程移動需要同時使用 --apply 和 --move-root，並且仍然拒絕 Git 追蹤 / 受保護的名稱。
hygiene_snapshot.py save 預設寫入 .agent_reports/hygiene-history/ 下（Class B 交付物歷史，而非根目錄垃圾）。gate 和 doctor 在衛生/政策失敗時返回退出碼 2。
11. 工作區衛生審計
當被要求掃描多個儲存庫時，優先使用 ${CLAUDE_SKILL_DIR}/scripts/audit_workspace_hygiene.py 以獲得可移植的基準線。在僅有 Windows 的工作流程中，${CLAUDE_SKILL_DIR}/scripts/audit-workspace-hygiene.ps1 也可以。使用者必須明確指定根目錄。切勿預設掃描整個磁碟機。
對於單一儲存庫的 Agent 產物審計，若 Python 可用，優先使用 ${CLAUDE_SKILL_DIR}/scripts/audit_agent_artifacts.py。若停留在 PowerShell 工作流程中，則使用 ${CLAUDE_SKILL_DIR}/scripts/audit-agent-artifacts.ps1。審計和評分都接受可選的 --policy。
可選的任務結束唯讀檢查：${CLAUDE_SKILL_DIR}/hooks/stop-hygiene-check.py（僅回報；永不刪除）。觸發短語位於 commands/TRIGGERS.md。
12. 本地機器衛生審計
當被問及 C 槽增長、WSL2、Docker Desktop、模型快取、套件快取、Agent 狀態或本地開發環境膨脹時，使用 ${CLAUDE_SKILL_DIR}/scripts/audit-dev-environment.ps1。
對於非 Windows 環境的可攜式套件/模型快取映射，使用 ${CLAUDE_SKILL_DIR}/scripts/audit_dev_environment.py。對於 Windows 特定的 WSL2/Docker VHDX 檢查，使用 PowerShell 腳本。
規則：
- 當需要掃描專案/工作區時，要求明確的掃描根目錄。
- 僅在使用者希望包含預設使用者設定檔快取位置時才使用
-IncludeUserProfile。 - 僅在使用者明確要求磁碟機層級提示時才使用
-IncludeDrives。 - 將 WSL/Docker 遷移、VHDX 壓縮、Docker 數據搬遷、
.wslconfig編輯和模型快取搬遷視為「手動 / 高風險操作」。 - 永不讀取令牌、session 檔案、SQLite 資料庫、登錄檔金鑰、私人日誌或憑證儲存。
有關 WSL2 和 Docker 的詳細資訊，請閱讀 references/wsl2-docker-hygiene.md。
13. 清理規則
允許的自動清理：
.agent_tmp/— 超過 7 天的檔案.agent_reports/— 超過 30 天的檔案- 使用者指定的 Agent 暫存目錄
- 已命名、已過期、Agent 建立的流程檔案
禁止的自動清理：
- 受保護的文件（Class A）
- 原始碼
- 工具狀態（Class E）
- 使用者資料夾中的未知 Markdown
- Git 追蹤的檔案
- 根目錄可疑檔案 → 僅回報，詢問使用者
14. 審計規則
- 唯讀 — 永不修改檔案
- 有限深度，跳過
.git/,node_modules/,dist/,build/,target/,.venv/,venv/ - 列出：
.agent_tmp/,.agent_reports/, 根目錄可疑檔案, 受保護文件 - 建議動作，不執行任何動作
- 無上傳或網路呼叫
15. 任務結束檢查清單
在報告「完成」之前：
- 我是否建立了任何檔案？每個檔案是否都通過了產物意圖檢查？
- 是否
…
[因篇幅限制截斷]