潔癖.skill は何をしますか？
阻止 AI Agent 在你的倉庫中亂丟
plan.md、todo.md、summary.md和一次性產物。 別讓 AI Agent 把你的專案根目錄變成 Markdown 垃圾場。
這不是一個 Markdown 刪除器。 這個 Skill 管理的是 Agent 工作的本地環境：倉庫產物、工作區快取、WSL2/Docker 儲存、套件管理員快取、模型快取，以及 Agent/IDE 狀態。
一個檔案或快取並不只是因為它很大就是垃圾。當它沒有意圖、沒有所有者、沒有讀者、沒有生命週期、沒有復原路徑時，它才成為衛生風險。目標不是激進地刪除，而是要確保每個產物、快取和本地環境足跡都有其目的、位置和安全的下一步動作。
1. 衛生模型
使用三層模型：
| 層級 | 範圍 | 範例 | 預設動作 |
|---|---|---|---|
| 倉庫 | Agent 建立的產物 | plan.md、todo.md、.agent_tmp/、.agent_reports/ | 分類、報告、乾執行清理 |
| 工作區 | 跨專案的開發快取 | node_modules、.venv、target、建置快取 | 審計、評分、建議 |
| 本地機器 | 工具鏈與虛擬化環境 | WSL2、Docker Desktop、套件快取、模型快取、Agent/IDE 狀態 | 唯讀對映、風險分類、手動指引 |
報告應區分：
發現— 本地觀察到的事實。安全建議— 低風險的下一步，例如執行乾執行或將未來的報告移至.agent_reports/。手動 / 高風險操作— 遷移、VHDX 壓縮、Docker 資料搬遷、模型快取搬遷或組態編輯。絕不自動執行這些操作。
2. 何時使用此 Skill
當使用者詢問以下內容時，請呼叫此 Skill：
| 觸發條件 | 範例 |
|---|---|
| 整理 / 組織 | "整理專案目錄"、"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. 何時不用此 Skill（絕不執行）
請停下來詢問使用者，或嚴格避免以下請求：
- 刪除正式專案文件
- 修改使用者筆記
- 清理原始碼 (
src/、lib/、app/) - 觸碰工具狀態目錄 (
.codex/、.claude/、.cursor/、.vscode/、*.sqlite、state.json、session.json、workspaceStorage、globalStorage、auth-token) - 未經確認的大量 Markdown 刪除
- 強制刪除 Git 追蹤的檔案
- 清理個人/使用者資料夾中未知的 Markdown
- 修改系統設定或登錄檔
- 註冊排程任務
- 上傳日誌、報告、憑證或環境資料
- 未經使用者明確指定根範圍而掃描整台電腦
- 讀取認證 token、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 — 自我慶賀 | 總結、最終報告、工作總結、經驗教訓、變更總結 | 不要建立 | 不適用 | 不適用 |
| E — 工具狀態（超出範圍） | .codex/、.claude/、.cursor/、*.sqlite、狀態檔案 | 工具目錄 | 不適用 | 從不 |
關鍵規則：
- 類別 A → 從不自動刪除，從不自動重寫
- 類別 B → 特定檔案名稱
<task>_<date>.md，絕不在專案根目錄 - 類別 C → 僅限
.agent_tmp/，絕不提交，任務結束時清理 - 類別 D → 不要建立。聊天視窗就是總結。
- 類別 E → 完全忽略，從不標記為可疑
5. 產生意圖檢查（強制執行）
在建立任何新檔案之前，請填寫此檢查清單。如果你無法回答每個欄位，請不要建立檔案。
產生意圖檢查
─────────────────────
1. 使用者要求建立檔案？ 是 / 否
2. 目的：
3. 讀者：
4. 預期生命週期： 工作階段 / 天 / 持續 / 正式文件
5. 目標路徑：
6. 為什麼聊天回應不夠：
7. 類別： 暫存 / 持續 / 正式文件
8. 是否應加入 .gitignore？ 是 / 否
決定規則：
| 情境 | 動作 |
|---|---|
| #1 = 否，類別 ≠ A | 不要建立。 在聊天中回答。 |
| 目的 = 計劃/待辦事項/總結/進度，讀者 = 這位使用者 | 僅限聊天。 不建立檔案。 |
| 必須建立，類別 = C | .agent_tmp/<specific-name>.md |
| 必須建立，類別 = B | .agent_reports/<task>_<YYYY-MM-DD>.md |
| 類別 = 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/** 在沒有策略的情況下被識別為有意的類別 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 追蹤檔案、類別 A 文件
tidy_repair.py 是診斷→下一步的伴侶工具。預設僅提供計劃。--apply 建立 .agent_tmp/ + .agent_reports/ 並附帶 .gitkeep。根目錄流程移動需要同時加上 --apply 和 --move-root，並且仍然拒絕 Git 追蹤/受保護的名稱。
hygiene_snapshot.py save 預設寫入 .agent_reports/hygiene-history/ 下（類別 B 交付物歷史，不是根目錄垃圾）。gate 和診斷在衛生/策略失敗時退出碼為 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編輯和模型快取搬遷視為手動 / 高風險操作。 - 絕不讀取 token、session 檔案、SQLite 資料庫、登錄機碼、私人日誌或憑證儲存。
有關 WSL2 和 Docker 的詳細資訊，請閱讀 references/wsl2-docker-hygiene.md。
13. 清理規則
允許的自動清理：
.agent_tmp/— 超過 7 天的檔案.agent_reports/— 超過 30 天的檔案- 使用者指定的 Agent 暫存目錄
- 指定的、已過期的、Agent 建立的流程檔案
禁止的自動清理：
- 受保護的文件（類別 A）
- 原始碼
- 工具狀態（類別 E）
- 使用者資料夾中未知的 Markdown
- Git 追蹤的檔案
- 根層級可疑檔案 → 僅報告，詢問使用者
14. 審計規則
- 唯讀 — 從不修改檔案
- 有深度限制，跳過
.git/、node_modules/、dist/、build/、target/、.venv/、venv/ - 列出：
.agent_tmp/、.agent_reports/、根層級可疑檔案、受保護文件 - 建議動作，但不執行任何動作
- 不進行上傳或網路呼叫
15. 任務結束檢查清單
在報告「完成」之前：
- 我建立了任何檔案嗎？每個檔案是否都有產生意圖檢查的理由？
- 是否
…
[截斷以利翻譯]