洁癖.skill은(는) 무엇을 하나요?
AI Agent가 저장소를
plan.md,todo.md,summary.md및 임시 파일로 어지럽히는 것을 막습니다. AI Agent가 프로젝트 루트를 마크다운 쓰레기장으로 만들지 않도록 합니다.
이것은 단순한 마크다운 삭제 도구가 아닙니다. 이 Skill은 Agent가 작업하는 로컬 환경(저장소 아티팩트, 작업 공간 캐시, WSL2/Docker 저장 공간, 패키지 관리자 캐시, 모델 캐시, Agent/IDE 상태)을 규율합니다.
파일이나 캐시가 단지 크다고 해서 쓰레기인 것은 아닙니다. 의도, 소유자, 독자, 생명주기, 복구 경로가 없을 때 위생 문제가 됩니다. 목표는 무조건 삭제하는 것이 아니라, 모든 아티팩트, 캐시, 로컬 환경 사용 흔적이 목적, 위치, 안전한 다음 작업을 가질 수 있도록 보장하는 것입니다.
1. 위생 모델(Hygiene Model)
3계층 모델을 사용합니다:
| 계층 | 범위 | 예시 | 기본 동작 |
|---|---|---|---|
| 저장소(Repository) | Agent가 생성한 아티팩트 | plan.md, todo.md, .agent_tmp/, .agent_reports/ | 분류, 보고, DryRun 정리 |
| 작업 공간(Workspace) | 프로젝트 간 개발 캐시 | node_modules, .venv, target, 빌드 캐시 | 감사, 점수 산정, 권장 |
| 로컬 머신(Local Machine) | 도구 체인 및 가상 환경 | WSL2, Docker Desktop, 패키지 캐시, 모델 캐시, Agent/IDE 상태 | 읽기 전용 맵, 위험 버킷, 수동 안내 |
보고서는 다음을 분리해야 합니다:
발견 사항(Findings)— 로컬에서 관찰된 사실안전한 제안(Safe Suggestions)— DryRun 실행이나 향후 보고서를.agent_reports/로 이동하는 것과 같은 저위험 다음 단계수동/위험 작업(Manual/Risky Operations)— 마이그레이션, VHDX 압축, Docker 데이터 재배치, 모델 캐시 재배치, 설정 편집. 절대 자동으로 수행하지 마십시오.
2. 이 Skill을 사용해야 하는 경우
사용자가 다음에 대해 물을 때 이 Skill을 호출하십시오:
| 트리거 | 예시 |
|---|---|
| 정리 / 조직화 | "프로젝트 디렉터리 정리", "이 저장소 정리", "내 프로젝트 구성" |
| 아티팩트 생성 | "계획 작성", "보고서 생성", "계획/할 일/요약/보고서/감사 생성" |
| 감사(Audit) | "프로젝트 파일 감사", "Agent 아티팩트 스캔", "의심스러운 파일 나열" |
| 정리(Clean up) | "Agent 파일 정리", "임시 파일 삭제" |
| 결정(Decide) | "이 파일을 생성해야 하나?", "이 파일을 생성할까 아니면 채팅에 남길까?" |
| 점수 산정(Score) | "내 저장소 위생 점수", "저장소가 얼마나 깨끗한가?" |
| 작업 공간 감사 | "작업 공간 스캔", "여러 저장소의 Agent 산출물 찾기" |
| 로컬 환경 감사 | "내 로컬 환경 감사", "로컬 Agent 환경 점검", "개발 캐시 위치" |
| 규칙 생성 | "AGENTS.md / CLAUDE.md / Cursor Rules 생성" |
| 작업 완료 | 종료 전 마무리 위생 점검 |
| 오염(Pollution) | "여러 Agent가 파일을 마구 생성함", "프로젝트 루트가 마크다운으로 난잡함" |
| 불만(Complaint) | "쓰레기 문서 생성 금지", "plan.md / todo.md 정리" |
| 환경 점검(Env Inspect) | "내 코딩 환경 점검", "node/python/go 설치 위치는?" |
| 드라이브 증가(Drive Growth) | "C 드라이브가 왜 커지고 있나?", "패키지/모델 캐시 찾기" |
| WSL2 / Docker | "WSL2 용량 너무 큼", "Docker Desktop 디스크 큼", "ext4.vhdx 위치는?" |
| 모델 캐시(Model caches) | "Ollama/Hugging Face 모델이 C 드라이브에", "AI 모델 캐시 감사" |
| Agent 상태(Agent state) | "Claude/Codex/Cursor 상태 위치", "Agent 설정/캐시 사용 공간" |
3. 이 Skill을 사용하지 말아야 하는 경우 (절대 금지)
사용자에게 질문을 중단하고 물어보거나 요청이 다음을 포함하는 경우 엄격히 회피하십시오:
- 공식 프로젝트 문서 삭제
- 사용자가 작성한 노트 수정
- 소스 코드(
src/,lib/,app/) 정리 - 도구 상태 디렉터리 수정 (
.codex/,.claude/,.cursor/,.vscode/,*.sqlite,state.json,session.json,workspaceStorage,globalStorage,auth-token) - 확인되지 않은 대량 마크다운 삭제
- Git 추적 파일 강제 삭제
- 개인/사용자 폴더의 알 수 없는 마크다운 정리
- 시스템 설정 또는 레지스트리 수정
- 예약 작업 등록
- 로그, 보고서, 자격 증명, 환경 데이터 업로드
- 사용자가 명시적으로 루트 범위를 지정하지 않은 전체 컴퓨터 스캔
- 인증 토큰, 세션 파일, SQLite 데이터베이스, 개인 로그 읽기
- 단지 크다는 이유로 도구 또는 모델 캐시 삭제
- 별도의 명시적 마이그레이션 요청 없이 도구 이동 또는 환경 변수 재작성
- WSL/Docker VHDX 파일 압축
- WSL 배포판 내보내기/가져오기
.wslconfig, Docker 설정, 셸 프로필, 패키지 관리자 설정 편집
4. 아티팩트 분류(Artifact Classification)
Agent가 생성하는 모든 파일은 5개의 클래스 중 하나에 속합니다. 클래스(Class) — 확장자가 아님 — 가 처리 방식을 결정합니다.
| 클래스 | 예시 | 위치 | 생명주기 | 자동 삭제? |
|---|---|---|---|---|
| A — 공식 문서(Formal Documentation) | README.md, CHANGELOG.md, LICENSE, docs/**, CONTRIBUTING.md, 사용자 노트 | docs/, 프로젝트 루트 | 영구적 | 절대 안 함 |
| B — 사용자 요청 산출물(User-requested Deliverables) | 감사 보고서, 마이그레이션 계획, 연구 보고서 (사용자가 명시적으로 요청) | .agent_reports/ | 30일 | 보존 기간 후 |
| C — 임시 작업 아티팩트(Temporary Working Artifacts) | 계획, 할 일, 노트, 스크래치, 진행 상황, 작업 목록 | .agent_tmp/ | 7일 | 보존 기간 후 |
| D — 자기 칭찬(Self-congratulatory) | 요약, 최종 보고서, 작업 요약, 교훈, 변경 사항 요약 | 생성 금지 | 해당 없음 | 해당 없음 |
| E — 도구 상태(범위 외) | .codex/, .claude/, .cursor/, *.sqlite, 상태 파일 | 도구 디렉터리 | 해당 없음 | 절대 안 함 |
핵심 규칙:
- 클래스 A → 절대 자동 삭제 금지, 절대 자동 재작성 금지
- 클래스 B → 특정 파일 이름
<작업>_<날짜>.md, 프로젝트 루트에 절대 생성 금지 - 클래스 C →
.agent_tmp/에만, 절대 커밋 금지, 작업 종료 시 정리 - 클래스 D → 생성 금지. 채팅이 요약입니다.
- 클래스 E → 완전히 무시, 절대 의심스러운 것으로 표시 금지
5. 아티팩트 의도 확인(Artifact Intent Check) (필수)
새 파일을 생성하기 전에 반드시 이 확인 항목을 작성하십시오. 모든 항목에 답할 수 없다면 파일을 생성하지 마십시오.
아티팩트 의도 확인
─────────────────────
1. 사용자가 파일을 요청했습니까? 예 / 아니오
2. 목적:
3. 독자:
4. 예상 생명주기: 세션 / 일 / 영구 / 공식 문서
5. 대상 경로:
6. 채팅 응답으로 충분하지 않은 이유:
7. 클래스: 임시 / 영구 / 공식 문서
8. .gitignore에 포함되어야 합니까? 예 / 아니오
결정 규칙:
| 시나리오 | 동작 |
|---|---|
| #1 = 아니오, 클래스 ≠ A | 생성 금지. 채팅으로 답변. |
| 목적 = 계획/할 일/요약/진행, 독자 = 이 사용자 | 채팅만. 파일 생성 금지. |
| 생성 필수, 클래스 = C | .agent_tmp/<특정-이름>.md |
| 생성 필수, 클래스 = B | .agent_reports/<작업>_<YYYY-MM-DD>.md |
| 클래스 = A (공식 문서) | docs/ 경로, 사용자가 명시적으로 요청 |
| 파일이 이 채팅을 다시 기술함 | 생성 금지 |
| 명확한 독자 없음 | 생성 금지 |
| 명확한 생명주기 없음 | 생성 금지 |
| 후속 사용 없음 | 생성 금지 |
6. 파일 생성에 대한 엄격한 규칙
- 기본값: 파일을 작성하지 마십시오.
- 계획, 할 일, 요약, 진행 상황 → 채팅으로 답변.
- 프로젝트 루트는 일반 프로세스 마크다운에 대해 금지됩니다. 사용자가 명시적으로 파일 이름을 지정하지 않는 한.
- 프로젝트 루트 금지 (사용자가 정확히 해당 파일을 요청하지 않는 한):
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/(명시적으로 요청된 경우에만) - "전문적으로 보이기 위해" 보고서를 생성하지 마십시오.
- 작업 종료 시 요약 파일을 자동으로 생성하지 마십시오.
- 채팅 내용을 파일로 복제하지 마십시오.
- 특정 파일 이름 사용:
<작업>_<컨텍스트>_<날짜>.md - 사용자가 파일을 요청하면 경로 + 파일 이름을 먼저 제안하십시오.
- 사용자가 "말해 줘" / "요약해 줘" / "계획해 줘"라고 말하면 → 채팅으로 답변.
7. 허용 및 금지 위치
허용
| 내용 | 허용 위치 |
|---|---|
| 임시 작업 파일 | .agent_tmp/ |
| 사용자 요청 보고서 | .agent_reports/ |
| 공식 문서 | docs/ (명시적 요청 필요) |
| 사용자 지정 경로 | 사용자가 명시적으로 지정한 모든 경로 |
금지
| 위치 | 이유 |
|---|---|
| 프로젝트 루트 (일반 프로세스 마크다운) | 공식 저장소 파일용으로 예약됨 |
src/, lib/, app/ | 소스 디렉터리 |
.codex/, .claude/, .cursor/, .vscode/ | 도구 상태 — 건드리지 마십시오 |
8. 보호된 파일 (절대 자동 삭제 금지)
README.md, README.*.md
CHANGELOG.md
LICENSE, LICENSE.*
CONTRIBUTING.md
CODE_OF_CONDUCT.md
SECURITY.md
docs/ 아래 모든 항목
.agent_tmp/ 또는 .agent_reports/ 외부의 Git 추적 파일
사용자가 직접 작성한 노트
9. 생명주기(Lifecycle)
| 위치 | 기본 보존 기간 | 정리 |
|---|---|---|
.agent_tmp/ | 7일 | Agent는 작업 종료 시 스스로 정리해야 함 |
.agent_reports/ | 30일 | 장기 보관을 위해 docs/로 이동 |
docs/ | 영구적 | 자동 생명주기 없음 |
10. 저장소 위생 점수(Repo Hygiene Score)
저장소 위생 점수를 요청받으면, Python을 사용할 수 있을 때 ${CLAUDE_SKILL_DIR}/scripts/score_repo_hygiene.py를 선호하십시오. Windows 전용 환경에서는 ${CLAUDE_SKILL_DIR}/scripts/score-repo-hygiene.ps1을 사용하십시오.
| 점수 | 등급 |
|---|---|
| 90–100 | 깨끗함(Clean) |
| 70–89 | 대체로 깨끗함(Mostly clean) |
| 50–69 | 정리 필요(Needs tidy-up) |
| 0–49 | 아티팩트 쓰레기장(Artifact landfill) |
차원: 루트 청결도, 아티팩트 배치, 보호 문서 명확성, 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 작업 메모리로 인식됩니다.
Doctor, repair, classify, snapshots
| 필요 | 스크립트 |
|---|---|
| 일회성 설치 + 위생 doctor / CI 게이트 | ${CLAUDE_SKILL_DIR}/scripts/tidy_doctor.py |
| DryRun 우선 안전 수리 (레이아웃 디렉터리, 선택적 루트 이동) | ${CLAUDE_SKILL_DIR}/scripts/tidy_repair.py |
| DryRun 호스트 후크 설정 생성기 | ${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 — 미리보기만 (수리, 정리, install-hooks의 기본값)
- careful — Agent 작업 파일만 변경 (
tidy_repair.py --apply --move-root) - guard — 호스트 설정, VHDX, Docker 데이터, Git 추적 파일, Class A 문서를 엄격히 거부
tidy_repair.py는 doctor의 진단 → 다음 단계 도우미입니다. 기본값은 계획만 제공합니다. --apply는 .gitkeep과 함께 .agent_tmp/ + .agent_reports/를 생성합니다. 루트 프로세스 이동은 --apply와 --move-root가 모두 필요하며, 여전히 Git 추적/보호 이름을 거부합니다.
hygiene_snapshot.py save는 기본적으로 .agent_reports/hygiene-history/ 아래에 기록합니다 (Class B 산출물 기록, 루트 쓰레기 아님). gate와 doctor는 위생/정책 실패 시 exit 코드 2를 반환합니다.
11. 작업 공간 위생 감사(Workspace Hygiene Audit)
여러 저장소를 스캔하라는 요청을 받으면, 이식 가능한 기준선을 위해 ${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. 로컬 머신 위생 감사(Local Machine Hygiene Audit)
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편집, 모델 캐시 재배치는수동/위험 작업(Manual/Risky Operations)으로 취급하십시오. - 토큰, 세션 파일, SQLite 데이터베이스, 레지스트리 키, 개인 로그, 자격 증명 저장소를 절대 읽지 마십시오.
WSL2 및 Docker 세부 정보는 references/wsl2-docker-hygiene.md를 참조하십시오.
13. 정리 규칙(Cleanup Rules)
허용되는 자동 정리:
.agent_tmp/— 7일보다 오래된 파일.agent_reports/— 30일보다 오래된 파일- 사용자가 지정한 Agent 임시 디렉터리
- 명명되고, 만료되었으며, Agent가 생성한 프로세스 파일
금지되는 자동 정리:
- 보호된 문서 (Class A)
- 소스 코드
- 도구 상태 (Class E)
- 사용자 폴더의 알 수 없는 마크다운
- Git 추적 파일
- 루트 수준 의심 파일 → 보고만, 사용자에게 문의
14. 감사 규칙(Audit Rules)
- 읽기 전용 — 파일을 절대 수정하지 않음
- 제한된 깊이,
.git/,node_modules/,dist/,build/,target/,.venv/,venv/건너뜀 - 목록:
.agent_tmp/,.agent_reports/, 루트 수준 의심 파일, 보호 문서 - 조치를 제안하지만, 수행하지 않음
- 업로드나 네트워크 호출 없음
15. 작업 종료 체크리스트(End-of-Task Checklist)
"완료"를 보고하기 전에:
- 파일을 생성했습니까? 각각이 아티팩트 의도 확인(Artifact Intent Check)에 의해 정당화되었습니까?
- .agent_tmp/에 임시 파일이 남아 있습니까? 작업 종료 시 정리해야 합니다.
- 예상치 못한 위치에 파일을 생성했습니까? (예: 프로젝트 루트)
- 사용자가 명시적으로 보고서를 요청했습니까? 그렇다면 .agent_reports/에 올바르게 배치되었습니까?
- 사용자에게 저장소 위생 상태를 요약했습니까?
- 추가 정리 또는 구성을 위한 제안 사항이 있습니까?