Agent-Skills.md

Agent Skills: Refactor Cleaner

리팩토링, 데드 코드, 사용하지 않는 코드, 코드 정리, 클린업 - Identifies and removes dead code, unused imports, and redundant code. Systematic cleanup while maintaining functionality.

UncategorizedID: aimskr/aims-toolkit/refactor-cleaner

Repository

aimskr/aims-toolkit
aimskr

Install this agent skill to your local

pnpm dlx add-skill https://github.com/aimskr/aims-claude-toolkit/tree/HEAD/skills/refactor-cleaner

Skill Files

Browse the full folder contents for refactor-cleaner.

Download Skill

Loading file tree…

skills/refactor-cleaner/SKILL.md

Skill Metadata

Name
refactor-cleaner
Description
"리팩토링, 데드 코드, 사용하지 않는 코드, 코드 정리, 클린업 - Identifies and removes dead code, unused imports, and redundant code. Systematic cleanup while maintaining functionality."

Refactor Cleaner

데드 코드를 식별하고 안전하게 제거합니다.

🔄 워크플로우 (필수)

IMPORTANT: 리팩토링 전 반드시 코드 분석부터 수행합니다.

Phase 0: 코드 탐색 (code-explorer 활용)
    ↓
Phase 1: 스캔 (데드 코드 식별)
    ↓
Phase 2: 검증 (사용처 확인)
    ↓
Phase 3: 분류 (삭제 가능 여부)
    ↓
Phase 4: 정리 (안전한 삭제)
    ↓
Phase 5: 문서화 (리팩토링 기록)

Phase 0: 코드 탐색 (REQUIRED)

리팩토링 대상 분석을 위해 code-explorer 서브에이전트를 먼저 실행합니다.

1. code-explorer 에이전트 실행:
   - 실행 흐름 추적
   - 의존성 맵핑
   - 아키텍처 레이어 파악

2. 탐색 결과 확인:
   - 핵심 컴포넌트 식별
   - 진입점(Entry Points) 파악
   - 외부 의존성 확인

3. 리팩토링 범위 결정:
   - 안전하게 수정 가능한 영역
   - 주의가 필요한 영역
   - 건드리면 안 되는 영역

서브에이전트 프롬프트 예시:

Task: code-explorer로 [target_path] 분석
Focus:
- 실행 흐름과 의존성 추적
- 외부에서 호출되는 public API 식별
- 내부에서만 사용되는 private 함수 식별
Return: 핵심 파일 목록과 의존성 맵

핵심 원칙

  1. 안전 우선: 삭제 전 사용처 완전 확인
  2. 점진적 정리: 한 번에 하나씩 제거
  3. 테스트 유지: 삭제 후 테스트 통과 확인
  4. 문서화: 삭제 이유 기록

정리 대상

1. 사용하지 않는 임포트

# Before
import os
import sys  # 사용 안 함
from typing import List, Dict, Optional  # Dict 사용 안 함

# After
import os
from typing import List, Optional

2. 사용하지 않는 변수

# Before
def process(data):
    unused_var = "never used"  # 삭제 대상
    result = transform(data)
    return result

# After
def process(data):
    result = transform(data)
    return result

3. 호출되지 않는 함수

# 삭제 전 확인:
# 1. 전체 코드베이스에서 호출 검색
# 2. 테스트에서 호출 검색
# 3. 동적 호출 가능성 확인 (getattr, __import__)
# 4. API 엔드포인트로 노출 여부 확인

4. 도달 불가능 코드

# Before
def example():
    return "result"
    print("이 코드는 실행되지 않음")  # 삭제 대상

# After
def example():
    return "result"

5. 중복 코드

# DRY 원칙 적용
# 3번 이상 반복되는 코드 → 함수로 추출

분석 프로세스

Phase 1: 스캔

1. 사용하지 않는 임포트 식별
2. 사용하지 않는 변수 식별
3. 호출되지 않는 함수/클래스 식별
4. 도달 불가능 코드 식별

Phase 2: 검증

각 항목에 대해:
1. 전체 코드베이스 검색
2. 테스트 코드 검색
3. 설정 파일 검색
4. 동적 참조 가능성 확인

Phase 3: 분류

🔴 확실히 삭제 가능
🟡 추가 확인 필요
🟢 유지 (문서화된 이유)

Phase 4: 정리

1. 안전한 항목부터 삭제
2. 각 삭제 후 테스트 실행
3. 커밋 (작은 단위)

도구별 명령어

Python

# 사용하지 않는 임포트 확인
autoflake --check --remove-all-unused-imports -r .

# 사용하지 않는 변수 확인
pylint --disable=all --enable=unused-variable .

# 데드 코드 분석
vulture . --min-confidence 80

JavaScript/TypeScript

# ESLint로 미사용 변수 확인
eslint --rule 'no-unused-vars: error' .

# 미사용 exports 확인
npx ts-prune

# 미사용 의존성 확인
npx depcheck

Java

# 미사용 임포트 확인
mvn spotless:check

# 데드 코드 분석
mvn pmd:check

자동 정리 스크립트

Python

# 미사용 임포트 자동 제거
autoflake --in-place --remove-all-unused-imports -r src/

# isort로 임포트 정리
isort src/

JavaScript/TypeScript

# ESLint 자동 수정
eslint --fix .

# 미사용 import 제거
npx eslint --fix --rule 'unused-imports/no-unused-imports: error' .

안전 체크리스트

삭제 전 확인

  • [ ] grep으로 전체 검색 완료
  • [ ] 테스트 코드에서 검색 완료
  • [ ] 설정 파일에서 검색 완료
  • [ ] 동적 참조 가능성 확인
  • [ ] 외부 API 노출 여부 확인
  • [ ] 문서에서 참조 여부 확인

삭제 후 확인

  • [ ] 모든 테스트 통과
  • [ ] 빌드 성공
  • [ ] 린트 통과
  • [ ] 애플리케이션 정상 동작

삭제하면 안 되는 경우

1. 의도적 미사용

# 의도적으로 미사용 (인터페이스 준수)
def callback(event, context):  # context는 AWS Lambda 규약
    return handle(event)

2. 미래 사용 예정

# TODO: v2.0에서 사용 예정
# def new_feature():
#     pass

3. 동적 로딩

# 동적으로 로딩되는 플러그인
# 직접 import는 없지만 __import__로 로딩됨

4. 테스트 전용

# 테스트에서만 사용되는 헬퍼
def _test_helper():
    pass

사용 방법

전체 리팩토링 (권장)

/refactor-cleaner src/services/

또는

src/services/ 디렉토리 리팩토링해줘

자동으로 실행되는 플로우:

  1. code-explorer로 코드 분석
  2. 데드 코드 스캔
  3. 사용처 검증
  4. 삭제 대상 분류
  5. 정리 실행
  6. 문서 작성 (docs/refactoring/YYYY-MM-DD-<target>-refactor.md)

분석만 (삭제 안 함)

이 프로젝트의 데드 코드를 분석만 해줘 (삭제는 하지 마)

자동 정리 (미사용 import만)

미사용 임포트만 자동으로 제거해줘

Phase 5: 문서화 (REQUIRED)

IMPORTANT: 리팩토링 완료 후 반드시 문서를 작성합니다.

문서 저장 위치

{project}/docs/refactoring/YYYY-MM-DD-<target>-refactor.md

문서 템플릿

# Refactoring Report: <Target Name>

## Overview
- **Date**: YYYY-MM-DD
- **Target**: <리팩토링 대상 경로>
- **Executor**: Claude

## Summary
| 항목 | 수치 |
|------|------|
| 분석된 파일 | N개 |
| 발견된 이슈 | N개 |
| 삭제된 코드 | N개 |
| 검토 필요 | N개 |

## Code Explorer 분석 결과
<Phase 0에서 파악한 내용 요약>
- 핵심 컴포넌트:
- 의존성 구조:
- 주의 영역:

## 삭제된 항목 🔴
| 파일 | 라인 | 타입 | 코드 |
|------|------|------|------|
| utils.py | 45 | unused import | `import re` |
| models.py | 120 | unused function | `def old_helper()` |

## 검토 필요 항목 🟡
| 파일 | 라인 | 타입 | 이유 |
|------|------|------|--------|
| api.py | 200 | possibly unused | 동적 로딩 가능성 |

## 유지된 항목 🟢
| 파일 | 라인 | 타입 | 유지 이유 |
|------|------|------|------------|
| handler.py | 50 | unused param | AWS Lambda 규약 |

## 테스트 결과
- [ ] 모든 테스트 통과
- [ ] 빌드 성공
- [ ] 린트 통과

## 후속 작업
1. <권장 사항 1>
2. <권장 사항 2>

## 변경된 파일 목록
- `path/to/file1.py`
- `path/to/file2.py`

문서 작성 규칙

  1. docs/refactoring/ 디렉토리가 없으면 생성
  2. 파일명: YYYY-MM-DD-<target>-refactor.md
  3. 대상명은 디렉토리/모듈명 사용 (e.g., services, auth-module)
  4. 모든 삭제 항목은 구체적으로 기록

예시

# 생성되는 파일
docs/refactoring/2026-01-27-services-refactor.md
docs/refactoring/2026-01-27-auth-module-refactor.md