클로드코드 Agents Team으로 2만 줄 코드베이스를 반으로 줄이는 리팩토링 - 5시간만에 끝내기

한줄 요약

Electron 앱의 21,265줄 코드베이스를 Claude Code로 5시간 만에 9,500줄로 줄였습니다. 최근 업데이트된 Agents Team 기능으로 AI 에이전트 팀을 꾸려서 병렬 작업까지 시켜봤는데, 이게 진짜 게임체인저였습니다.

이런 분들께 도움돼요

• Claude Code의 최신 기능인 Agents Team이 실전에서 어떻게 쓰이는지 궁금하신 분

• AI 코딩 도구로 대규모 리팩토링이 진짜 가능한지 확인하고 싶은 개발자

• 기술 부채가 쌓인 프로젝트를 체계적으로 정리할 방법을 찾고 계신 분

Claude Code Agents Team, 뭐가 달라졌나?

본론에 들어가기 전에, 이번에 제가 적극 활용한 Agents Team 기능을 먼저 소개하겠습니다.

Claude Code가 최근 업데이트되면서 여러 AI 에이전트를 팀으로 구성해서 동시에 일을 시킬 수 있는 기능이 추가됐습니다. 이전까지는 Claude Code에게 작업을 하나씩 순서대로 시켜야 했어요. A 끝나면 B, B 끝나면 C — 이런 식으로요.

그런데 Agents Team을 쓰면:

• 팀 리더가 태스크를 나누고 의존성을 설정합니다

• 전문 에이전트들이 독립적인 작업을 동시에 진행합니다

• 각 에이전트가 색깔로 구분되어 진행 상황이 직관적으로 보입니다

• 병렬 작업이 끝나면 리더가 자동으로 통합 검증에 들어갑니다

파란색 - worker-engineer / 녹색 - client-engineer

쉽게 말해, 혼자 일하던 AI가 팀으로 일하게 된 겁니다. 실제로 써보니까 "아, 이게 AI 코딩의 다음 단계구나" 싶었어요.

문제 상황 (Before)

사이드 프로젝트로 만든 Electron 앱(Linear Capture)이 있습니다. macOS에서 스크린샷을 캡처하면 AI가 분석해서 Linear 이슈를 자동으로 만들어주는 앱인데요, 한 달간 기능을 빠르게 쌓다 보니 코드가 난장판이 되었어요.

어땠냐면요:

• index.html 한 파일이 3,247줄 (CSS + JS가 전부 인라인)

• settings.html도 2,483줄

• IPC 핸들러가 894줄짜리 단일 파일

• 4개 동기화 어댑터에 같은 코드가 복붙되어 있고

• AI 분석기 2개가 95% 동일한 코드

• 에러 처리율 고작 22%

기능 하나 추가하려면 수천 줄짜리 파일을 스크롤하면서 "여기가 맞나?" 하고 찾아야 했습니다. Claude Code한테 작업을 시켜도 컨텍스트가 너무 크고 지저분하니까 정확도가 떨어지는 게 체감됐고요.

그런데 결정적 계기가 있었습니다. 아침에 CTO 워크샵에 참여했는데, 경호님이 지피터스 게시판을 리팩토링하는 과정을 컨텍스트 엔지니어링 관점에서 보여주셨어요.

계획 문서를 먼저 만들고, 그걸 AI에게 컨텍스트로 넘겨서 체계적으로 진행하는 방식이 인상적이었습니다.

"이거 내 프로젝트에도 바로 적용해봐야겠다." - 바로 시작했습니다.

사용한 도구

• Claude Code (CLI) — Opus 4.6 모델

• Claude Code Agents Team — 에이전트를 팀으로 구성해서 병렬 작업시키는 최신 기능

• 컨텍스트 문서: REFACTORING.md (6단계 리팩토링 계획서)

컨텍스트 엔지니어링 — 리팩토링 계획서 만들기

아침에 워크샵에서 본 걸 바로 적용했습니다. 무작정 "리팩토링해줘"가 아니라, 먼저 전체 코드를 분석해서 REFACTORING.md 계획서를 만들었어요.

프롬프트 : 
리팩토링 전문 에이전트와 skillS들을 무엇을 추가할지 상세하게 CTO팀 구성해서 '리니어 캡처'의 코드베이스를 완벽하게 파악하여 어떻게 리팩토링 팀을 구성할지 상세하게 /pdca plan으로 계획을 작성해줄래?

6단계로 나눈 계획:

• Phase 1: 레거시 제거 (더 이상 안 쓰는 sql.js 스택)

• Phase 2: 중복 제거 (복붙된 코드 18건)

• Phase 3: 파일 분할 (수천 줄 모놀리스 → 모듈)

• Phase 4: 타입 강화

• Phase 5: 로깅/에러 처리

• Phase 6: 보안 + 테스트

ALT

맥 os x os x os x os x os x os

이 문서가 Claude에게 주는 컨텍스트가 되니까, 각 Phase를 실행할 때 "Phase 2 실행해줘"만 하면 뭘 해야 하는지, 어떤 파일을 건드려야 하는지 정확하게 알고 진행했습니다.

프로젝트 안에 기존 작업 문서들이 여기저기 흩어져 있었는데, 이것도 PDCA(Plan-Do-Check-Act) 관점에서 기능 단위로 깔끔하게 정리해줬어요. 덕분에 이후 작업할 때 필요한 문서를 바로 찾을 수 있게 됐습니다.

5시간 동안 Phase 1~6.1 연속 실행

Phase를 순서대로 실행했습니다.

REFACTORING.md의 Phase 1부터 6까지 순서대로 전부 실행해줘. 각 Phase 끝날 때마다 빌드 + 테스트로 회귀 없는지 확인하고.

레거시 제거, 중복 코드 제거, 파일 분할, 타입 강화, 로깅/에러 처리, 보안 강화까지... 매우 큰 여정이었어요.

결과 (After)

Before vs After

체감 효과

Claude Code한테 작업을 시킬 때 컨텍스트가 깔끔해져서 더 정확하게 작업할 것 같습니다. 수천 줄짜리 파일을 통째로 읽히는 것과, 모듈별로 나뉜 파일을 읽히는 건 결과물 품질이 다르거든요.

Agents Team, 언제 쓰면 좋을까?

이번에 직접 써보고 느낀 Agents Team의 실전 사용법을 정리했습니다.

이럴 때 쓰세요

이럴 때 쓰면 안 돼요

• 같은 파일을 여러 에이전트가 수정: 충돌납니다

• 순서가 있는 의존적 작업: A의 결과물이 B의 입력이면 직렬로 해야 해요

• 간단한 단일 작업: 팀 구성 오버헤드가 더 큽니다

효과적인 프롬프트 패턴

제가 써본 결과, 역할과 대상 파일을 명확히 분리해주는 게 핵심이었습니다:

CTO팀 구성해서 에이전트들에게 시켜줘.

작업 1 (IPC 엔지니어): src/main/ipc-handlers/ 6개 파일의 에러 처리 보완
작업 2 (테스트 엔지니어): tests/ 3개 파일의 실패 테스트 수정

서로 독립적인 작업이니 병렬 진행하고,
둘 다 끝나면 빌드 + 테스트로 통합 검증해줘.

이렇게 하면 team-lead가 태스크를 정확하게 나누고, 각 에이전트가 자기 담당 파일만 건드립니다.

이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. 컨텍스트 엔지니어링이 핵심입니다: "리팩토링해줘"가 아니라 REFACTORING.md 계획서를 먼저 만들고, 그걸 컨텍스트로 줬더니 Claude가 정확하게 따라갔어요. 아침 워크샵에서 본 걸 바로 적용한 건데, 효과가 확실했습니다.

2. Agents Team은 마무리 단계에서 빛납니다: 큰 틀의 구조 변경(Phase 1~5)은 순서대로 해야 하지만, 마무리 단계의 독립적인 보완 작업들은 병렬로 동시에 끝낼 수 있어요. 핵심은 "이 작업들이 서로 독립적인가?"를 판단하는 겁니다.

3. 팀 리더에게 검증까지 맡기세요: "둘 다 끝나면 빌드 + 테스트로 통합 검증해줘"라고 지시하면, team-lead가 병렬 작업 완료 후 자동으로 전체 빌드/테스트를 돌립니다. 사람이 일일이 확인할 필요가 없어요.

4. PDCA 관점의 문서 정리: 기능별로 문서를 깔끔하게 정리해두면 AI가 참고할 컨텍스트 품질이 올라갑니다. 지저분한 폴더에 문서가 섞여있으면 AI도 헷갈리거든요.

다른 업무에 적용한다면?

• 레거시 코드 정리: 어떤 프로젝트든 REFACTORING.md 같은 계획서를 먼저 만들고, Phase별로 AI에게 실행시키는 패턴은 동일하게 적용할 수 있습니다.

• 대규모 마이그레이션: 프레임워크 버전 업그레이드, API 스펙 변경 등 파일 단위로 독립 작업이 가능한 건 Agents Team으로 병렬화할 수 있어요. 100개 파일의 import 경로를 바꿔야 한다면, 디렉토리별로 에이전트를 나눠서 동시에 돌리는 겁니다.

• 코드 리뷰 + 테스트 보강: 에이전트 하나는 코드 리뷰, 하나는 테스트 작성 — 이런 식으로 역할을 분리하면 효율적입니다.

• 풀스택 기능 개발: 프론트엔드 에이전트는 UI 컴포넌트, 백엔드 에이전트는 API — 동시에 작업하고 team-lead가 통합 검증하는 패턴도 가능합니다