동작하는 코드
여러 파일에 걸친 변경을 요청해봅시다:
> 프로젝트에서 console.log를 모두 찾아서 적절한 로깅 라이브러리(winston)로 교체해줘.
> 로거 설정 파일도 만들어줘.
Claude가 여러 파일을 동시에 수정합니다. 각 파일의 diff를 하나씩 보여주고 승인을 요청합니다.
더 복잡한 리팩토링도 가능합니다:
> src/api/ 디렉토리의 모든 라우트 핸들러에 에러 처리 미들웨어를 적용해줘.
> 현재 try-catch가 없는 핸들러를 찾아서 asyncHandler로 감싸줘.
직접 수정하기
@ 기호로 특정 파일을 컨텍스트에 포함시킬 수 있습니다:
> @src/types/user.ts 의 User 타입을 기반으로
> @src/api/users.ts 의 모든 함수에 타입을 추가해줘
이렇게 하면 Claude가 해당 파일들을 우선적으로 참조합니다.
대규모 변경 전에는 반드시 안전 장치를 마련하세요:
> 변경 시작하기 전에 현재 상태를 git stash로 저장해줘
또는 브랜치를 만들어두세요:
> refactor/logging이라는 브랜치를 만들고 거기서 작업해줘
"왜?" — 프로젝트 규모의 작업이 Claude Code의 진가
단일 파일 편집은 어떤 도구로든 할 수 있습니다. Claude Code가 특별한 건 프로젝트 전체의 맥락을 이해하고 여러 파일을 일관성 있게 변경할 수 있다는 점입니다.
멀티파일 작업 시 체크리스트
- 변경 전: Git 브랜치 생성 또는 stash 저장
- 요청 시: 변경 범위와 규칙을 명확히 전달
- 리뷰 시: 각 파일의 diff를 꼼꼼히 확인
- 변경 후: 테스트 실행으로 회귀 확인
@ 멘션으로 파일 지정
| 사용법 | 의미 |
| ---------------- | --------------------------- |
| @src/config.ts | 특정 파일을 컨텍스트에 포함 |
| @src/utils/ | 디렉토리 전체를 참조 |
| @package.json | 설정 파일을 참조 |
대규모 리팩토링 프롬프트 예시
> 이 프로젝트의 모든 API 응답 형식을 통일해줘.
> 현재: 각 엔드포인트가 제각각의 형식으로 응답
> 목표: { success: boolean, data: T, error?: string } 형태로 통일
> @src/types/response.ts 에 공통 타입을 정의하고,
> @src/api/ 의 모든 핸들러를 수정해줘.
심화 학습
변경이 너무 많아서 리뷰하기 어려워요
대규모 변경은 단계적으로 나눠서 진행하세요:
- "먼저 타입 정의만 만들어줘"
- "이제 users API만 수정해줘"
- "나머지 API도 같은 패턴으로 수정해줘"
한 번에 20개 파일을 바꾸면 리뷰가 어렵습니다. 5개씩 나눠서 검증하세요.
- 프로젝트에서 여러 파일에 걸친 간단한 변경을 요청해보세요 (예: 모든 파일의 들여쓰기를 2칸에서 4칸으로).
@멘션으로 두 개의 파일을 지정하고, 둘 사이의 관계를 설명해달라고 요청해보세요.- 브랜치를 만들고 대규모 변경을 시도한 뒤, 문제가 있으면 브랜치를 삭제하세요.
Q1. 대규모 리팩토링 전에 가장 먼저 해야 할 일은?
- A) 바로 리팩토링을 시작한다
- B) Git 브랜치를 만들거나 stash로 현재 상태를 저장한다
- C) 프로젝트를 삭제하고 새로 만든다
- D) Claude에게 "알아서 해줘"라고 말한다