Tidy · 프로젝트 정리 규칙은(는) 무엇을 하나요?

저장소의 모든 파일은 다음 세 질문에 답할 수 있어야 합니다:

왜 존재하는가? (필요성) — 삭제하면 무엇이 망가집니까?
왜 여기 있는가? (소속) — 이 프로젝트의 디렉토리 규칙에 따르면 어떤 디렉토리에 속합니까?
다른 사람이 이해할 수 있는가? (가독성) — 파일 이름과 README만 봐도 새 개발자가 이 파일이 무엇을 하는지 알 수 있습니까?

사용자가 /tidy를 입력하면 바로 아래 "패턴 2: 기존 프로젝트 정리"를 실행합니다.

세 단계 메커니즘

단계	역할	실행 주체
디렉토리 규칙 `.claude/tidy.json`	각 최상위 디렉토리에 무엇을 넣을지 선언하여, "어디에 넣을지"를 판단이 아닌 조회로 변경	프로젝트 정리 시 생성하고 이후 유지보수
Hooks (플러그인 설치 시 함께 설치)	세션 시작 시 규칙과 디렉토리 규칙 주입; 규칙에 맞지 않는 새 파일 차단; 각 턴 종료 시 새 파일 검사	자동, 아래 "Hook 프롬프트 수신 시" 참조
본 스킬	코드 작성 시 판단 기준, 기존 프로젝트 정리 워크플로우	사용자

Hooks는 새로 추가된 파일만 검사하며, 기존 프로젝트의 문제는 "패턴 2"로 정리합니다.

세 가지 검사 수준

시점	수행 작업
새 파일 생성 시	아래 4가지 질문 검토 (Hooks가 있으면 자동 차단)
단계 완료 / 작업 종료 시	`audit.py <루트> --changed` (git 프로젝트, HEAD 기준 변경사항만) 또는 `--since 2h` (수정 시간 기준, git 프로젝트가 아니어도 사용 가능). Hooks가 없는 도구(Codex, Cursor)는 매 작업 완료 전에 한 번씩 실행합니다.
사용자가 프로젝트 정리 요청 시	전체 `audit.py <루트>`, "패턴 2" 수행

확인 후 처리할 필요가 없는 경고(의도된 배포본, 서드파티 파일명)는 audit.py <루트> --review <규칙> <경로> --reason <결론>으로 기록하여 이후 보고하지 않습니다. 파일 내용이 변경되면 다시 나타나 재검토를 알립니다.

패턴 1: 코드 작성 시 (매번 적용)

새 파일 생성 전 4가지 질문

질문	통과하지 못할 경우
필요한가? 기존 파일에 포함할 수 있는가? 일회성인가?	기존 파일에 병합; 일회성 내용은 응답에만 작성하고 파일로 저장하지 않음
어디에 넣을까? `.claude/tidy.json`의 layout과 일치하는가?	이미 선언된 디렉토리에 배치; 새 최상위 디렉토리가 정말 필요하다면 layout과 README "디렉토리 구조"에 먼저 등록
이름은 무엇으로? 이름이 용도를 설명하고 같은 디렉토리의 스타일과 일관된가?	references/naming.md 규칙에 따라 이름 지정
커밋해야 하는가? 생성물, 의존성, 비밀키, 대용량 파일인가?	`.gitignore`에 추가하여 버전 관리에서 제외

AI의 가장 흔한 나쁜 습관 (금지)

❌ 나쁜 습관	✅ 올바른 방법
루트 디렉토리에 `test.py`, `debug.js`, `check_xxx.py` 임시 스크립트 작성	`.scratch/` (반드시 `.gitignore`에 등록) 또는 시스템 임시 디렉토리에 작성하고 작업 종료 후 삭제
`foo_v2.ts`, `foo_new.ts`, `foo.backup.ts`, `foo_old/` 복사본 생성	원본 파일을 직접 수정하고, 이력은 git에 맡김
작업 완료 시마다 `IMPLEMENTATION_SUMMARY.md`, `FIX_REPORT.md` 생성	요약은 응답과 커밋 메시지에 작성; 장기 지식은 README 또는 `docs/` 기존 문서에 병합
`build/`, `out/`, `dist/`, 렌더링된 비디오/오디오, 로그 파일 커밋	`.gitignore`에 추가; README에 생성 방법 명시
`node_modules/`, `.venv/` 커밋 또는 여기저기 흩어짐	무시; 다중 언어 도구체인은 각각 제자리에 (structure.md "혼합 프로젝트" 참조)
한글, 공백, 괄호 파일명: `프롬프트 공유.md`, `final (1).mp4`	파일명은 영문 kebab-case 사용, 한글은 파일 제목에만 사용
스캐폴딩 샘플 정리하지 않음, 대량 주석 처리된 오래된 코드, 사용하지 않는 의존성	참조 없음 확인 후 삭제
동일한 설정을 두 곳에 작성 (`.prettierrc` + `package.json#prettier`)	한 곳에만 유지
"나중에 쓸 수도 있으니까" 미리 빈 디렉토리, 빈 파일 생성	필요할 때 생성

Hook 프롬프트 수신 시

새 파일 생성이 차단된 경우: 프롬프트에 따라 방법 변경 — 기존 파일에 병합, 디렉토리 변경, 이름 변경, 또는 아예 파일로 저장하지 않음. 차단을 우회하기 위해 Bash로 파일을 작성하지 마십시오 (Stop 검사에서 발견됩니다).
종료 전 검사에서 문제가 나열된 경우: 하나씩 처리 (임시 파일 삭제, 복사본 병합, 이동, .gitignore 보충) 후 종료.
사용자가 명시적으로 요청한 경우 (예: 한글 파일명을 원하는 경우): 규칙에 따라 경로를 .claude/tidy.json의 allow에 추가 (예: {"non-portable-name": ["docs/강의/**"]}) 하고 응답에 설명. 예외 범위는 최소화하고, disable로 전체 규칙을 끄지 말며, 임의로 예외를 추가하지 마십시오.
로컬에는 남기되 git에 넣지 않아야 할 파일 (완성본, 검수 완료된 더빙, 모델 가중치 등): keepLocal에 등록하고 이유를 명시한 후 .gitignore에 추가. 삭제하지 마십시오.
새 최상위 디렉토리가 필요한 경우: 먼저 적절한 기존 디렉토리가 없는지 확인한 후, layout과 README "디렉토리 구조"에 등록.

패턴 2: 기존 프로젝트 정리

스크립트는 본 스킬의 scripts/ 디렉토리에 있으며, Python 3.9+ 표준 라이브러리만 필요합니다.

1단계: 스캔

python3 <skill>/scripts/audit.py <프로젝트 루트>            # 텍스트 보고서
python3 <skill>/scripts/audit.py <프로젝트 루트> --format json

2단계: 프로젝트 이해 및 참조 확인

스크립트는 휴리스틱 방식이므로 각 경고를 확인한 후 처리해야 합니다. 텍스트 보고서는 개수가 많은 동일 유형 문제를 접지만, 개별 확인이 필요하면 --all을 추가하세요. 결론을 내리기 전에:

README, package.json / pyproject.toml의 scripts와 진입점을 읽으십시오.
삭제하거나 이동하려는 각 파일의 참조를 확인하십시오:
```
python3 <skill>/scripts/refs.py <프로젝트 루트> <파일> [<파일> ...]
```
결과는 네 가지: in-use (명확한 참조), convention (프레임워크가 규칙에 따라 로드), maybe (약한 일치만 있음), unreferenced (찾을 수 없음). unreferenced의 경우에도 동적 경로와 외부 호출을 고려해야 하며, 판단 기준은 references/file-necessity.md를 참조하십시오.

3단계: 정리 계획 제시 및 확인 대기

경로	작업	대상 위치	이유
`프롬프트 공유.md`	이동+이름 변경	`docs/prompts.md`	루트에 문서 흩어짐; ASCII가 아닌 파일명
`out/`	무시	—	렌더링 산출물, `npm run render`로 재생성 가능
`src/Root_old.tsx`	삭제	—	refs.py: unreferenced; Root.tsx와 내용 동일

작업은 일곱 가지뿐입니다: 보존 / 이동 / 이름 변경 / 삭제 / 보관 / 무시 / 로컬 보존 (무시하되 삭제하지 않고, keepLocal에 등록). 확실하지 않으면 "확인 대기"로 표시합니다. 경고가 예상되는 경우(배포본, 연속 프레임 캡처)라면 작업은 규칙에 따라 allow를 추가하는 것이지 파일을 삭제하는 것이 아닙니다.

삭제와 대량 이동은 반드시 사용자 확인을 받아야 합니다. 계획이 확인되기 전에 파일을 변경하지 마십시오.

4단계: 실행

작업 공간이 깨끗한지 확인; git 저장소가 아니면 git init을 제안하고 초기 커밋을 스냅샷으로 수행.
python3 <skill>/scripts/audit.py <루트> --fix-gitignore: 무시되지 않은 의존성, 생성물, 쓰레기 파일, 비밀키를 .gitignore에 자동으로 추가 (추가만 하고 삭제는 하지 않음). 이미 git이 추적 중인 파일은 나열되며 git rm --cached가 필요합니다.
이동 / 이름 변경은 git mv 사용; 이후 이전 경로에 대해 refs.py 또는 grep을 실행하여 모든 참조(import, staticFile(), 설정, 스크립트, 문서 링크)를 수정.
빌드 / 테스트 / lint를 실행하여 손상된 부분이 없는지 확인.
구조 조정과 코드 수정은 별도의 커밋으로 분리.

5단계: 디렉토리 규칙 확정 (건너뛰지 마십시오)

정리가 완료되면 디렉토리 규칙을 생성하여 이후 모든 세션이 자동으로 따르도록 합니다:

python3 <skill>/scripts/audit.py <루트> --init     # 현재 최상위 디렉토리를 기반으로 .claude/tidy.json 초안 생성

그런 다음 각 디렉토리의 설명을 완성 (TODO 대체)하되, 배치 결정을 안내할 수 있도록 작성하십시오. 예를 들어 "public/": "staticFile()이 읽는素材: 이미지, 폰트, 더빙"처럼 써야지, 그냥 "정적 리소스"라고만 쓰지 마십시오. README "디렉토리 구조"도 동시에 업데이트하십시오. 설정 형식은 references/config.md를 참조하십시오.

안전 기준

재생성 불가능한 파일 (사용자 소스, 녹음, 수제 프롬프트, 데이터)은 확인 없이 절대 삭제하지 않음 — 적절한 디렉토리로 이동하거나 보관.
.env 등 비밀키 내용을 읽거나 출력하지 않음; 비밀키가 이미 git에 추적되고 있음을 발견하면 사용자에게 키 교체와 이력 정리를 알리고, 단순히 파일만 삭제하지는 않음.
파일이 사용 중인지 확실하지 않으면 "확인 대기"로 표시하고 추측하지 않음.

삭제 vs 보관?

'git에 넣을지'와 '삭제할지'는 별도로 판단합니다.

이 파일...
├─ 저렴하게 재생성할 수 있습니까? (빌드 산출물, 캐시, 로그, 의존성, 임시 프레임)
│    └─ 예 → 삭제 + .gitignore에 추가
├─ 재생성 가능하지만 비용이 높습니까? (완성본, 검수 완료 더빙, 렌더링된 강의 패키지, 훈련된 모델 — 시간, 비용 또는 재검수 필요)
│    └─ 예 → 로컬 보존 + .gitignore에 추가 + tidy.json의 keepLocal에 등록 (이유 명시), README에 생성 방법 명시
├─ git이 이미 추적 중인 오래된 코드입니까?
│    └─ 예 → 바로 삭제 (git 이력이 보관 역할)
├─ 재생성 불가능하지만 참고 가치가 있습니까? (조사 노트, 예전 프롬프트, 디자인 시안, 의사 결정 기록)
│    └─ 예 → docs/archive/로 이동, 파일명에 날짜 접두사 추가, docs/archive/README.md에 이유 한 줄 기록
├─ 대용량 소스입니까? (오디오/비디오, 데이터세트, 모델)
│    └─ 예 → git에 넣지 않음 (또는 Git LFS 사용), README에 획득 방법 명시
└─ 재생성 불가능하고 가치도 없음 → 목록 작성 후 사용자 확인 후 삭제

보관 세부 규칙은 references/docs.md를 참조하십시오.

참조 파일

파일	내용	언제 읽을까
references/structure.md	최상위 디렉토리 화이트리스트, 다양한 프로젝트 유형의 표준 디렉토리 레이아웃 (Node/TS, Remotion, Python, 혼합 프로젝트)	파일 위치 결정, layout 설계 시
references/file-necessity.md	파일 필요성 판단, 일반적인 삭제 가능 샘플	삭제 가능 여부 판단 시
references/naming.md	각 언어의 명명 규칙, 금지된 명명 패턴	새 파일 생성 또는 이름 변경 시
references/docs.md	README 최소 요구사항, docs/ 레이아웃, 보관 규칙	문서 작성, 보관 시
references/config.md	`.claude/tidy.json` 필드 설명과 예시	디렉토리 규칙 생성 또는 수정 시
assets/README.template.md	README 템플릿	프로젝트에 README가 없을 때
assets/gitignore/	`.gitignore` 조각: 일반, Node, Python, 미디어	무시 규칙 보충 시
assets/agents-rules.md	AGENTS.md에 붙여넣을 수 있는 규칙 (Hooks를 지원하지 않는 다른 AI 도구용)	프로젝트가 Cursor / Codex 등도 사용할 때

Tidy · 프로젝트 정리 규칙