Molayo

© 2026 Molayo

Qiita헤드라인2026. 06. 19. 17:43

Claude Code로 대규모 리팩터링을 안전하게 진행하는 절차｜영향 범위 조사 → 계획 → 작게 분할 → 테스트 검증 → 단계적 적용

요약

Claude Code의 Plan mode와 서브 에이전트 기능을 활용하여 대규모 리팩터링을 안전하게 수행하는 절차를 안내합니다. 영향 범위 조사, 단계적 계획 수립, 테스트 검증을 통해 코드의 안정성을 확보하는 방법을 다룹니다.

핵심 포인트

  • Plan mode를 활용해 코드 변경 전 영향 범위를 먼저 조사합니다.
  • 서브 에이전트를 사용하여 메인 컨텍스트를 유지하며 탐색합니다.
  • 리팩터링 계획을 작은 커밋 단위로 분할하여 실행합니다.
  • CLAUDE.md를 통해 프로젝트의 코딩 컨벤션을 유지합니다.

대규모 리팩터링 (Refactoring)을 AI에게 맡길 때, 가장 해서는 안 될 일은 "전부 알아서 잘 고쳐줘"라고 통째로 맡겨서 일괄 치환하게 하는 것입니다. 차이(diff)가 거대해져서 어디서 망가졌는지 추적할 수 없게 되고, 결국 스스로 전부 다시 읽어야 하는 상황에 처하게 됩니다.

이 기사에서는 Claude Code의 실제 기능(Plan mode, 서브 에이전트, CLAUDE.md, /clear, Hooks)을 사용하여, 대규모 리팩터링을 "망가뜨리지 않고·추적 가능한 형태로" 진행하는 절차를 정리합니다. 독자는 Claude Code를 일상적으로 사용하는 개발자를 상정하고 있습니다.

리팩터링을 AI에게 맡길 때의 안전성은 거의 다음 3가지 점에서 결정됩니다.

영향 범위를 먼저 파악하기 (읽기만 하고 쓰지 않기)
계획을 세우고 리뷰한 뒤에 쓰기 (승인 게이트를 거치기)
1단계 = 작은 차이로 만들고, 매번 테스트로 검증하기

이는 인간이 하는 리팩터링의 정석과 완전히 동일합니다. Claude Code에는 이 정석을 그대로 적용할 수 있는 기능들이 갖춰져 있습니다.

갑자기 코드를 건드리게 하기 전에, 먼저 "어디에 영향을 미치는지"를 조사하게 합니다. 여기서 중요한 것은 쓰기를 동반하지 않는 조사에 철저히 집중하는 것입니다.

Claude Code에는 Plan mode가 있으며, Shift+Tab을 2번 누르거나 /plan 명령어로 진입할 수 있습니다. Plan mode에서는 Claude가 코드베이스를 읽고 분석 및 계획은 하지만, 당신이 승인할 때까지 파일을 변경하지 않습니다 (Plan Mode - ClaudeLog). 조사 단계에서 그대로 사용할 수 있습니다.

조사 예시:

（Plan mode에서）
UserService의 getUser 메서드의 반환 타입(return type)을 변경하고 싶다.
변경하기 전에, 먼저 다음을 조사해서 보고해줘:
...

조사와 같은 읽기 중심의 작업은 서브 에이전트 (sub-agent)에게 맡기면 메인 대화의 컨텍스트 (context)를 더럽히지 않고 끝낼 수 있습니다. Claude Code에는 읽기 전용으로 코드베이스를 탐색하는 Explore 서브 에이전트(기본적으로 빠르고 저비용인 모델로 동작)나, Plan mode에서 사용되는 Plan 서브 에이전트가 내장되어 있습니다 (Create custom subagents - Claude Code Docs).

조사 결과가 나오면, 자신의 눈으로 영향 범위를 확인합니다. Claude가 놓친 호출 지점이 있다면 여기서 지적하여 추적하게 합니다. 이 단계에서의 확인이 이후의 사고를 가장 많이 줄여줍니다 (효과는 대상 코드베이스나 지시의 정밀도에 따라 달라집니다).

영향 범위가 보이면, 다음은 실행 계획을 세우게 합니다. Plan mode는 바로 이를 위해 존재하며, Claude가 제시한 계획을 읽은 뒤 Shift+Tab으로 모드를 전환하여 실행으로 옮길 수 있습니다.

계획에는 "순서"와 "분할"을 명시하게 하는 것이 요령입니다.

조사 결과에 기반하여, 리팩터링 절차를 작은 단계로 분할해줘.
각 단계는:
- 1 커밋 (commit)에 담길 수 있는 작은 크기로 할 것
...

여기서 나온 계획을 읽고, 순서가 이상하거나 1단계가 너무 크다고 느껴지면 다시 분할하게 합니다. 계획 단계에서의 되돌림 (rework)은 비용이 작으므로, 납득할 때까지 다듬습니다.

리팩터링에서 은근히 효과적인 것이 "기존의 코드 작성 방식에 맞추게 하는 것"입니다. 내버려 두면 AI는 자신만의 스타일로 작성하여 코드베이스의 일관성이 깨집니다.

프로젝트 루트에 CLAUDE.md를 두면, 그 내용은 세션 시작 시 자동으로 컨텍스트에 읽혀집니다. 명명 규칙 (naming convention), 사용하는 라이브러리, 테스트 작성법, 피해야 할 패턴 등을 적어두면 매번 동일한 전제하에 작업을 수행하게 할 수 있습니다.

# CLAUDE.md
## 코딩 규약
- 에러 핸들링 (error handling)은 Result 타입을 사용한다 (예외를 throw 하지 않는다)
...

참고로, 조사용인 Explore / Plan 서브 에이전트는 속도와 비용을 위해 CLAUDE.md를 건너뛰는 반면, 그 외의 내장/커스텀 서브 에이전트는 CLAUDE.md를 읽어들입니다 (Create custom subagents - Claude Code Docs). 실제로 코드를 다시 쓰는 단계에서는 규약이 적용된다고 이해해 두면 좋습니다.

리팩터링의 정의는 "외부에서 보이는 동작을 바꾸지 않고 내부를 정돈하는 것"입니다. 즉, 동작을 고정하는 테스트가 있다면 그것이 그대로 가드 (guard)가 됩니다.

다시 쓰기 전에, 대상 범위의 테스트 현황을 확인하게 합니다.

리팩터링 대상인 UserService에 대한 기존 테스트를 실행해서,
현재 모두 green인지 확인해줘.
커버되지 않은 동작이 있다면, 리팩터링 전에
...

테스트가 빈약한 영역에서는, 먼저 동작을 고정하는 테스트 (characterization test)를 추가한 뒤에 본체를 수정하게 합니다. 이를 통해 "바꿀 의도가 없었는데 망가진 경우"를 감지할 수 있습니다.

이 부분이 가장 중요합니다. 계획의 1단계만 실행하게 하고, 테스트를 통과시킨 뒤, 커밋하고 다음으로 넘어갑니다.

계획의 스텝 1만 실행해줘. 그 외에는 건드리지 마.
변경하면 테스트를 실행하고 결과를 보여줘.
green이라면, 이 스텝만 커밋해줘 (메시지는 refactor: 로 시작할 것).

포인트는 다음과 같습니다.

  • 차이(diff)를 작게 유지하기: 1단계 = 1개의 관심사. 무관한 변경을 섞지 않습니다. 리뷰하기 쉬워지고, 문제가 생겼을 때 원인 파악이 용이합니다.
  • 각 커밋을 "빌드와 테스트가 통과하는 상태"로 유지하기: 문제가 발생한 커밋만 git revert로 되돌릴 수 있습니다 (Git Commit Best Practices).
  • 리팩터링과 기능 변경·버그 수정을 섞지 않기: 섞으면 변경 사항의 의도를 파악하기 어려워집니다 (My git Workflow for Refactoring - Kyle Shevlin).

각 단계가 끝나면 차이를 확인합니다.

git diff --stat
git diff

의도하지 않은 파일이 변경되지 않았는지, 예상치 못한 동작 변경이 섞여 있지 않은지를 여기서 걸러냅니다.

Claude Code의 Hooks 기능을 사용하면, 도구 실행 전후에 임의의 명령어를 자동으로 실행할 수 있습니다. 예를 들어 파일 편집 후에 자동으로 포매터(formatter)나 테스트를 실행하는 등의 가드(guard)를 설정할 수 있습니다. 사람이 리뷰하기 전에 기계로 체크할 수 있는 부분은 Hooks에 맡기면 놓치는 부분을 줄일 수 있습니다.

단계를 몇 번 진행했다면, 덩어리 단위로 리뷰합니다. 차이가 작기 때문에 사람의 리뷰나 AI에게 요청하는 자기 리뷰(self-review) 모두 수행하기 쉬워집니다.

지금까지의 스텝 1~3의 차이를 리뷰해줘.
동작이 변하지 않았는지, 규칙을 따르고 있는지,
놓친 호출 지점이 없는지 체크해서 보고해줘.

긴 작업이 계속되면 컨텍스트(context)가 커져서 정밀도가 떨어지기 쉽습니다. 하나의 논리적인 단위가 끝나면 /clear로 컨텍스트를 끊어주는 것이 유효합니다. 다음 단위는 CLAUDE.md와 현재 코드(=커밋된 상태)로부터 다시 시작할 수 있으므로, 대화 이력을 끌고 가지 않아도 됩니다.

Claude Code로 대규모 리팩터링을 안전하게 진행하는 흐름은 다음과 같습니다.

  • 조사: Plan mode + Explore로 영향 범위를 파악 (직접 쓰게 하지 않음)
  • 계획: 작은 단계로 분할하게 하고, 리뷰 후 승인
  • 규칙: CLAUDE.md를 통해 기존 패턴에 맞추게 함
  • 가드: 테스트를 먼저 확보 (필요하다면 특성화 테스트(characterization test)를 추가)
  • 적용: 1단계씩 실행 → 테스트 → 작게 커밋
  • 리뷰: 덩어리 단위로 확인하고, /clear로 구분

AI는 한꺼번에 대량으로 작성할 수 있는 만큼, 인간보다 더 "작게 나누어 매번 검증하는" 규율이 효과적입니다. 승인 게이트(approval gate), 테스트, 그리고 작은 차이(diff)라는 이 세 가지를 놓치지 않는다면, 리팩터링은 관리 가능한 범위 내에 머물 것입니다 (실제 효과는 코드베이스의 규모나 테스트 정비 상태에 따라 다릅니다).

Claude Code를 바로 시도해 볼 수 있는 무료 스킬 4가지를 GitHub에 공개해 두었습니다: claude-code-skills-starter. Claude Code 실전 팁은 X @k___n___t_1125 에서 발신하고 있습니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0