/cleanup - 코드 및 프로젝트 정리

트리거

• 코드 유지보수 및 기술 부채 감소 요청
• 데드 코드 제거 및 import 최적화 필요
• 불필요한 주석 및 주석 처리된 코드 정리 필요
• 프로젝트 구조 개선 및 정리 요구
• 코드베이스 위생 및 품질 개선 작업

사용법

/cleanup [대상] [--type code|imports|files|comments|all] [--safe|--aggressive] [--interactive]

파라미터

• 대상: 정리할 디렉토리 또는 파일 경로 (기본값: 현재 디렉토리)
• --type: 정리 유형 - code (데드 코드), imports (미사용 import), files (미사용 파일), comments (불필요한 주석), all (기본값: all)
• --safe: 최대 안전성 검증으로 보수적 정리
• --aggressive: 엣지 케이스 포함 철저한 정리 (기본값)
• --interactive: 복잡한 결정에 대해 확인 요청 (기본값)

--safe vs --aggressive 동작 차이

항목	--safe	--aggressive (기본값)
미사용 import	제거	제거
미사용 지역 변수	제거	제거
주석 처리된 코드	제거	제거
완료된 TODO/FIXME	제거	제거
의미 없는 주석	제거	제거
미사용 export 함수	건너뜀 (검증 필요 표시)	제거 (확인 후)
고아 파일	건너뜀 (검증 필요 표시)	제거 (확인 후)
진행 중 TODO	보존	보존
JSDoc/문서화 주석	보존	보존

핵심 차이: --aggressive는 "검증 필요" 항목도 --interactive 확인 후 제거

동작 흐름

1. 분석 (Analyze)

• 대상 범위에서 정리 기회 스캔
• 데드 코드, 미사용 import, 고아 파일, 불필요한 주석 식별
• 안전성 고려사항 및 의존성 평가

2. 계획 (Plan)

• 발견 항목을 유형 및 위험 수준별로 분류
• 안전한 제거를 위험한 것보다 우선순위화
• 백업 생성:

  # git 저장소인 경우
  git stash push -m "cleanup-backup-$(date +%Y%m%d-%H%M%S)"
  
  # git이 아닌 경우
  cp -r [대상] [대상].cleanup-backup
  

• 백업 완료 확인 후 다음 단계 진행

3. 실행 (Execute)

• 우선순위 순서로 체계적 정리 적용
• 점진적 검증 (파일당 또는 변경 그룹당):

  # 구문 검증 (JS/TS)
  node -c [파일] 또는 npx tsc --noEmit [파일]
  
  # 린트 검증
  npx eslint [파일] --quiet
  

• 검증 실패 시 해당 변경 롤백 후 다음 항목 진행
• 복잡한 다중 파일 작업의 진행 상황 추적 (TodoWrite)

4. 검증 (Validate)

• 테스트 실행:

  # 프로젝트 테스트 명령 자동 탐지 후 실행
  npm test 또는 yarn test 또는 pnpm test
  

• 빌드 검증:

  npm run build 또는 npx tsc --noEmit
  

• import 참조 검증:

  # 깨진 import 탐지
  npx madge --circular --extensions ts,tsx [대상]
  

• 검증 실패 시: 백업에서 롤백 → 실패 원인 보고

5. 보고 (Report)

• 제거된 코드/파일 통계 요약
• 건너뛴 항목과 이유 나열
• 지속적인 유지보수를 위한 권장사항 제공

정리 패턴

데드 코드 탐지

분석 단계:
1. 정적 분석으로 미사용 함수/변수 찾기
2. 동적 사용 패턴 확인 (리플렉션, 문자열 기반 호출)
3. 외부 참조 없음 검증
4. 의존성 검증과 함께 제거

Import 최적화

분석 단계:
1. 모든 import 문 파싱
2. 파일 스코프에서 실제 사용 추적
3. 미사용 import 식별
4. 제거 및 남은 import 재정렬

파일 구조 정리

분석 단계:
1. 고아 파일 식별 (import/참조 없음)
2. 중복 또는 유사 중복 파일 찾기
3. 재구성 또는 제거 제안

불필요한 주석 정리

분석 단계:
1. 주석 처리된 코드 블록 탐지
2. 오래된/완료된 TODO/FIXME 식별
3. 코드와 불일치하는 주석 탐지
4. 의미 없는 주석 식별 (예: // 변수 선언)

안전성 검증

정리 전:
- 영향받는 파일의 백업/스냅샷 생성
- 현재 테스트 상태 문서화

정리 중:
- 각 변경 후 점진적 검증
- 예상치 못한 실패 시 중단

정리 후:
- 전체 테스트 스위트 실행
- 빌드 검증
- 고위험 변경에 대한 수동 검토

도구 사용

분석 단계

• Grep: 사용 분석을 위한 패턴 탐지
• Glob: 파일 탐색 및 구조 매핑
• Read: 의존성 추적을 위한 내용 검사

실행 단계

• Edit: 안전한 코드 수정
• Write: 구조 변경 시 파일 업데이트
• Bash: 테스트, 린터, 빌드 명령 실행

추적 단계

• TodoWrite: 다중 파일 작업의 진행 상황 추적

예시

안전한 코드 정리

/cleanup src/ --type code --safe

보수적 정리:

• 명확히 죽은 코드만 제거
• 동적 사용 가능성 있는 것은 보존
• 기존 테스트로 검증

Import 최적화

/cleanup src/ --type imports

Import 정리:

• 미사용 import 제거
• 규칙에 따라 남은 import 정렬
• 프레임워크별 import 패턴 처리

주석 정리

/cleanup src/ --type comments

주석 정리:

• 주석 처리된 코드 블록 제거
• 완료된 TODO/FIXME 제거
• 의미 없는 주석 제거

종합 프로젝트 정리

/cleanup

기본값으로 전체 정리 (--type all --aggressive --interactive):

• 코드, import, 파일, 주석 전체 분석
• 각 카테고리에 대해 확인 요청
• 상세 보고서 생성

보수적 정리

/cleanup src/ --safe

안전 우선 정리:

• 명확히 불필요한 항목만 제거
• 의심스러운 항목은 건너뜀
• 테스트 커버리지 낮은 프로젝트에 권장

안전성 가이드라인

항상 안전하게 제거 가능

• 주석 처리된 코드 블록
• 완료된 TODO/FIXME 주석
• 의미 없는 주석 (예: // 변수 선언, // 생성자)
• 미사용 지역 변수
• 참조가 없는 import
• export가 없는 빈 파일

검증 필요

• 미사용 export 함수 (외부 소비자가 있을 수 있음)
• 직접 import되지 않는 파일 (진입점일 수 있음)
• 피처 플래그 뒤의 코드
• 진행 중인 TODO/FIXME 주석
• JSDoc/문서화 주석

자동 제거 금지

• 설정 파일
• 테스트 픽스처 및 목
• 문서 파일
• 제외용 .gitignore 패턴과 일치하는 파일
• 라이선스/저작권 주석
• eslint-disable, @ts-ignore 등 의도적 주석

출력 형식

## 정리 요약

### 제거됨
- 8개 파일에서 15개 미사용 import
- 3개 데드 함수 (245줄)
- 2개 고아 유틸리티 파일
- 12개 주석 처리된 코드 블록
- 5개 완료된 TODO 주석

### 건너뜀 (검토 필요)
- `utils/legacy.ts` - export되었으나 내부 사용 없음
- `helpers/format.ts:formatDate` - 동적 호출 가능성

### 검증
- 테스트: 142개 통과, 0개 실패
- 빌드: 성공
- 린트: 새 경고 없음

### 권장사항
- 외부 사용 없음 확인 후 `utils/legacy.ts` 제거 고려
- `src/api/client.ts`의 주석 코드 검토

경계

수행:

• 체계적으로 코드 정리, 데드 코드 제거, 프로젝트 구조 최적화
• 백업 및 롤백 기능으로 포괄적인 안전성 검증 제공
• 패턴 인식으로 지능적인 정리 알고리즘 적용
• 프로젝트별 규칙 및 제외 패턴 존중

수행 안 함:

• 철저한 안전성 분석 및 검증 없이 코드 제거
• 프로젝트별 정리 제외 또는 아키텍처 제약 무시
• 기능을 손상시키거나 버그를 도입하는 정리 작업 적용
• 설정, 문서, 테스트 픽스처 파일 자동 삭제