Claude Code 실전 — 멀티파일 리팩토링과 디버깅 마스터
"테스트 코드가 다 깨졌어요. 3시간째 잡고 있는데 어디서 꼬였는지 모르겠습니다." 이런 상황에서 우리는 보통 커피를 리필하고 밤샐 준비를 한다. 하지만 Claude Code 유저라면 터미널에
/loop라고 치고 커피를 마시며 쉬면 된다.
4편에서 셋업한 Claude Code를 실전에 투입할 차례다. Claude Code가 다른 도구들을 압도하는 영역인 '정교한 리팩토링'과 '집요한 디버깅'에 대해 집중적으로 알아본다.
1. /loop : 에러가 잡힐 때까지 멈추지 않는다
코딩을 하다 보면 "이론상으론 맞는데 왜 안 되지?" 싶은 버그를 만난다. 로그를 찍어보고, 한 줄 고치고 다시 테스트를 돌리는 지루한 과정. 이 작업을 에이전트에게 통째로 넘겨버리는 기능이 바로 /loop다.
자율 디버깅 워크플로우
단일 프롬프트가 아니라, 세션 스코프의 백그라운드 워커로 Claude를 활용하는 방식이다.
> /loop "npm run test:e2e 명령을 실행해.
실패하는 테스트가 있다면 원인을 찾아 코드를 수정하고 다시 실행해.
모든 테스트가 패스할 때까지 이 과정을 반복해."
이 명령을 내리면 Claude Code는 내장된 ReAct 루프를 극대화하여 작동한다.
1. npm run test:e2e 실행
2. 실패한 에러 로그 (예: Expected 200 but got 500) 읽기
3. 관련 소스코드 파일 열어서 원인 분석
4. 코드 수정 및 저장
5. 다시 npm run test:e2e 실행... (성공할 때까지 반복)
단순한 무한 루프가 아니다. 같은 에러가 두세 번 반복되면, "이 접근 방식이 틀렸다"고 판단하고 다른 가설을 세워 접근하는 고도의 추론 능력을 보여준다.
2. 멀티파일 리팩토링: 아키텍처를 뒤집다
AI에게 "A 함수를 B로 바꿔줘"라고 하는 건 쉽다. 하지만 "현재 monolithic 구조로 된 src/services/ 폴더의 비즈니스 로직들을 도메인 주도 설계(DDD) 패턴에 맞춰 src/domains/ 폴더 구조로 완전히 분리해 줘"라고 하면 이야기가 다르다.
이런 대규모 변경 시 Claude Code가 빛을 발한다.
성공적인 리팩토링을 위한 2단계 전략
대규모 리팩토링 시 바로 코드를 고치게 놔두면 엉킬 위험이 있다. 앞서 배운 모드 전환을 활용해야 한다.
1단계: Plan 모드로 청사진 그리기 Shift + Tab으로 Plan 모드로 진입한 뒤 지시한다.
> src/services 폴더의 유저 결제 로직을 분리하려고 해.
> 어떻게 파일들을 쪼개고 인터페이스를 나눌지 상세한 계획을 세워줘.
Claude가 코드를 건드리지 않고, 어떤 파일을 지우고 새로 만들지 plan.md 같은 형태로 보고서를 작성한다. 사람이 이를 읽고 피드백을 주며 설계를 확정한다.
2단계: Auto-Accept 모드로 기계적 실행 설계가 확정되었다면 Auto-Accept 모드로 전환한다.
> 방금 합의한 계획대로 모든 파일 이동, 생성, 코드 수정을 실행해.
수십 개의 파일이 순식간에 재배치되고 임포트 경로가 자동으로 수정되는 마법을 볼 수 있다. 설계는 사람이, 단순 노동은 AI가 하는 이상적인 협업이다.
3. Agent Teams: 혼자 안 되면 팀을 꾸려라
2026년에 접어들며 터미널 에이전트 생태계의 가장 뜨거운 화두는 멀티 에이전트 협업이다. (블로그의 이전 글인 멀티 에이전트 아키텍처 완전 정복을 참고하자.)
Claude Code 역시 환경 변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 켜면, 리드(Lead) 에이전트가 여러 팀원(Teammate) 에이전트를 소환해 병렬로 작업하는 Agent Teams 기능을 사용할 수 있다.
실전 투입: 역할 분담 리뷰
거대한 Pull Request를 올리기 전, 내 코드를 스스로 리뷰하고 싶을 때 팀을 활용해 보자.
> 내가 방금 커밋한 내용들에 대해 전체적인 리뷰를 진행해줘.
> 한 명은 '보안 취약점' 관점에서만 코드를 파고들고,
> 다른 한 명은 '성능 최적화와 메모리 누수' 관점에서만 코드를 검토해.
> 너(리드)는 둘의 의견을 종합해서 최종 리포트를 작성해.
이렇게 하면 한 에이전트가 너무 많은 컨텍스트를 들고 있다가 집중력을 잃는(Context Rot) 현상을 막을 수 있다. 각 에이전트는 좁고 뾰족한 시야로 자신의 임무만 수행하며, 백그라운드 메일박스를 통해 서로 소통한다.
📝 정리
- [x] /loop 디버깅: 테스트나 빌드 에러를 만났을 때, 원인 파악부터 코드 수정, 재검증까지 에이전트가 통째로 백그라운드에서 해결하도록 위임한다.
- [x] 2단계 리팩토링: 복잡한 구조 변경은 Plan 모드로 설계를 먼저 검토받은 후, Auto-Accept 모드로 기계적으로 실행시켜야 꼬이지 않는다.
- [x] Agent Teams: 단일 에이전트의 컨텍스트 한계를 넘어, 보안, 성능, 테스트 등 전문 분야별로 서브 에이전트를 소환해 병렬 검토를 수행한다.
Claude Code가 인간과 협업하는 "최고의 페어 프로그래머"라면, 다음 6편에서 다룰 Codex CLI는 인간의 개입을 최소화하는 "진정한 의미의 자율 주행 자동차"에 가깝다. 본격적인 자동화의 세계로 넘어가 보자.
