양파개발자 실바의 블로그

레거시 프로젝트에 에이전트 팀 투입하기: 파악 → 테스트 → 재작성 → 검증 4단계 전략

dev ai

이 글은 Claude Code 에이전트 팀 입문의 후속 심화편입니다. 기능 활성화 방법, 서브에이전트와의 차이, 에이전트 패널 조작법 같은 기본 개념은 입문 글을 참고하세요. 여기서는 레거시 코드베이스라는 구체적인 전장에 팀을 어떻게 투입하는지만 다룹니다.

1. 레거시에 팀을 붙이기 전에

1-1. 무작정 던져 넣으면 프로젝트가 파괴된다

세월의 흔적이 묻어난 레거시 프로젝트에 에이전트 팀을 도입하는 건, 비유하자면 배선도조차 없어진 오래된 빌딩의 리모델링을 로봇 건설팀에게 맡기는 것과 같습니다.

“이 레거시 코드 깔끔하게 리팩토링해 줘”라고 팀을 던져 넣으면, 에이전트들은 기존 비즈니스 로직의 숨은 의도와 오래된 예외 처리를 싹 밀어버립니다. 이유는 간단합니다. 그 코드가 왜 그렇게 생겼는지 아무 데도 적혀 있지 않으니, 에이전트 입장에서는 그냥 못 만든 코드로 보입니다.

반대로 전략적으로 판을 깔아두면 레거시는 에이전트 팀이 가장 빛나는 전장이 됩니다. 레거시의 특징을 보면 이유가 드러납니다.

  • 만든 사람이 없거나 인수인계가 부실하다
  • 문서가 없거나 실제 코드와 다르다
  • 아무도 전체를 모른다. 각자 자기가 만진 영역만 안다
  • 테스트가 없어서 고치는 게 무섭다

전체를 아는 사람이 없다면, 여러 조사자가 각 영역을 동시에 파헤쳐 지도를 합치는 것이 가장 빠릅니다. 단일 세션으로 수백 개 파일을 순차 탐색하면 컨텍스트가 차면서 앞부분을 잊어버립니다. 팀원은 각자 독립된 컨텍스트 창을 가지므로 이 문제가 없습니다.

1-2. 단계별 팀 적합도

목표가 “파악 → 테스트 → 리팩토링 → 기능 개발”까지라면, 단계마다 팀의 적합도가 크게 다릅니다. 공식 문서 기준으로 정리하면 이렇습니다.

단계 팀 적합도 이유
① 코드 파악 ★★★ 최적 읽기 전용 + 영역이 자연스럽게 갈림 + 서로 반박하며 가설 검증
② 테스트 작성 ★★ 조건부 모듈별 파일 분리는 쉽지만 공통 fixture·설정에서 충돌
③ 리팩토링 ★★ 관리 필요 파일 충돌 위험. 사람이 소유권을 갈라줘야 함
④ 기능 개발 ★ 대체로 부적합 순차적·의존 관계 많음. 단일 세션이 더 나음

공식 문서는 “에이전트 팀이 처음이면 코드를 쓰지 않는 작업부터 시작하라”고 권하고, 순차적인 작업, 같은 파일을 계속 고치는 작업, 의존 관계가 촘촘한 작업은 단일 세션이나 서브에이전트가 더 효과적이라고 명시합니다.

즉 팀의 진짜 무기는 ①②이고, ③은 뒤에 설명할 전략으로 살릴 수 있고, ④에서는 팀에서 손을 떼는 게 맞습니다.

1-3. 가장 중요한 함정: 팀원은 worktree로 격리되지 않는다

이 한 가지는 반드시 알고 시작해야 합니다.

에이전트 팀은 팀원을 git worktree로 격리해주지 않습니다. 모든 팀원이 같은 작업 디렉터리에서 같은 파일을 편집합니다.

서브에이전트는 isolation: worktree 프론트매터로 각자 별도 checkout을 받을 수 있고, 백그라운드 세션은 자동으로 격리됩니다. 하지만 팀원은 아닙니다. 그래서 공식 문서도 팀에 대해서는 “worktree로 격리하라”가 아니라 “작업을 분할해서 팀원마다 다른 파일을 소유하게 하라” 고 안내합니다.

레거시 리팩토링에서 이 차이는 치명적입니다. 두 팀원이 같은 파일을 고치면 나중에 저장한 쪽이 앞의 변경을 조용히 덮어씁니다. 5장의 Strangler Fig 전략이 이 문제를 구조적으로 해결합니다.

1-4. 전체 지도

0단계  판 깔기 (감옥 구축)
       └─ CLAUDE.md 금기 영역 · 검증 수단 · 권한 사전 허용 · 도메인 힌트
             ↓
1단계  코드 파악          [팀 최적 구간]
       └─ 고고학자 에이전트 (Read-Only) → ARCHITECTURE.md
             ↓
2단계  안전망 구축         [팀 유효 구간]
       └─ 테스터 에이전트 → 현재 동작을 고정하는 특성화 테스트
             ↓
3단계  재작성             [Strangler Fig]
       └─ 이주자 에이전트 (새 폴더만 Write) + 검증관 (결과 Diff 대조)
             ↓
4단계  기능 개발          [팀에서 손 떼는 구간]
       └─ 팀으로 설계 검토 → 단일 세션으로 구현 → 팀으로 리뷰

2. 0단계 — 판 깔기: ‘감옥’부터 만든다

레거시의 핵심 문제는 “코드 고쳤다가 어디가 터질지 모른다” 입니다. 에이전트에게 칼(수정 권한)을 쥐여주기 전에 안전장치를 만드는 것이 1순위입니다.

2-1. CLAUDE.md에 금기 사항 명시

팀원은 각자 프로젝트 루트의 CLAUDE.md를 읽습니다. 리드의 대화 이력은 물려받지 않으므로, 팀 전체 공통 규칙은 여기에 두는 것이 유일한 방법입니다.

레거시에서는 아직 코드를 모르니 완벽하게 쓸 수 없습니다. 지금 아는 것만 적고 1단계 결과로 보강하면 됩니다.

# 실행 명령어
- 개발 서버: `make dev`
- 테스트: `pytest tests/` (현재 통과율 40%, 실패는 대부분 기존 문제)
- 린트: `ruff check .`

# 절대 수정 금지 (건드리면 안 되는 영역)
- `migrations/` 전체
- `legacy/billing_v1/` — 결제 정산에 사용 중, 별도 협의 필요
- `.env*` 파일

# 작업 규칙
- 기존 코드 스타일을 그대로 따를 것. 인접 코드를 "개선"하지 말 것
- 코드를 삭제하지 말 것. 필요 없다고 판단되면 보고만 할 것
- 의도가 불분명한 로직은 임의로 정리하지 말고 질문할 것

마지막 두 줄이 레거시에서 특히 중요합니다. “의도를 모르면 지우지 말고 물어라” 가 사고를 막는 핵심 방어선입니다.

/init 명령으로 초안을 자동 생성한 뒤 다듬는 것이 빠릅니다. 단 길어지면 오히려 무시됩니다. 각 줄에 대해 “이걸 지우면 Claude가 실수할까?”를 물어 아니면 지우세요.

2-2. 사람만 아는 맥락을 미리 주입한다

에이전트가 코드만 읽어서는 절대 알 수 없는 것이 있습니다. “이 코드는 2021년 11월 이벤트 때 임시로 막아둔 로직” 같은 히스토리입니다. 이건 사람만 압니다.

팀을 띄우는 프롬프트나 CLAUDE.md에 이런 힌트를 미리 넣어주세요.

# 도메인 히스토리 (코드만 봐선 알 수 없는 맥락)
- `OrderService.legacy_discount()` — 2021년 11월 프로모션용 임시 코드.
  아직 과거 주문 조회에서 호출되므로 제거 불가
- `user.is_active` 와 `user.status` 가 중복인 이유 — 구 관리자 페이지가
  `is_active` 만 참조. 관리자 페이지 교체 전까지 둘 다 유지
- 결제 재시도 로직의 5초 sleep — PG사 API 레이스 컨디션 회피용. 제거 금지

이 몇 줄이 에이전트가 “중복 필드니까 정리하겠습니다”라며 서비스를 망가뜨리는 사고를 막습니다.

2-3. 검증 수단 확보 — “테스트가 없으면 빌드라도”

Claude는 작업이 끝나 보이면 멈춥니다. 스스로 확인할 수단이 없으면 “문법이 멀쩡하다”가 유일한 완료 신호가 됩니다. 레거시는 바로 이 검증 수단이 없는 게 문제입니다.

없으면 만들어야 합니다. 우선순위는 이렇습니다.

순위 수단 레거시에서 확보하는 방법
1 테스트 스위트 2단계에서 본격 작업. 지금은 “돌아가는 것만” 확인
2 빌드·타입체크 대부분 이미 있음. 없으면 이게 최우선
3 린트 설정 파일 하나로 즉시 도입 가능
4 스모크 스크립트 서버 띄우고 헬스체크 엔드포인트 한 번 때리는 셸 스크립트

최소한 “이 명령을 돌리면 성공/실패가 나온다” 는 게 하나는 있어야 팀을 신뢰할 수 있습니다.

2-4. 권한 사전 허용

팀원의 권한 요청은 전부 리드 세션으로 올라옵니다. 팀원 5명이 각자 pytest를 돌릴 때마다 승인 창이 뜨면 아무 일도 못 합니다. 팀을 띄우기 전에 자주 쓸 명령을 미리 허용하세요.

{
  "permissions": {
    "allow": [
      "Bash(pytest:*)",
      "Bash(ruff:*)",
      "Bash(rg:*)",
      "Bash(git log:*)",
      "Bash(git blame:*)",
      "Bash(git diff:*)"
    ]
  }
}

레거시 탐색에서는 특히 rg(ripgrep), git log, git blame 계열이 핵심입니다. “이 코드가 왜 이렇게 생겼는지”의 답이 대부분 커밋 히스토리에 있기 때문입니다.

2-5. 규모 결정: 3~5명

공식 권장은 팀원 3~5명, 팀원당 태스크 5~6개입니다. 레거시 첫 투입이라면 파악 단계 4명 → 이후 3명이 무리 없습니다. 토큰은 팀원 수에 비례해 늘고, 팀원이 늘수록 조율 비용과 충돌 가능성도 함께 커집니다.

3. 1단계 — 코드 파악: 고고학자 에이전트 (팀 최적 구간)

여기가 에이전트 팀의 진짜 실력이 나오는 구간입니다. 전원 읽기 전용이므로 파일 충돌 위험이 0이고, 영역이 자연스럽게 갈리며, 서로 반박하게 만들 수 있습니다.

3-1. 영역 분할 탐색

핵심은 팀원마다 다른 축으로 코드베이스를 자르는 것입니다. 같은 축을 주면 네 명이 같은 파일을 읽습니다.

이 프로젝트는 인수인계가 없는 레거시입니다. 코드를 수정하지 말고 파악만 하세요.
팀원 4명을 만들어 각각 다른 축으로 조사하게 해 주세요. 전원 읽기 전용입니다.

- 진입점 담당: HTTP 라우팅, CLI, 배치, 크론 등 외부 요청이 들어오는 모든 지점과
  거기서 시작되는 호출 흐름
- 데이터 담당: DB 스키마, 모델, 마이그레이션 히스토리, 실제 사용되는 테이블과
  죽은 테이블 구분
- 외부 연동 담당: 외부 API 호출, 큐, 캐시, 파일 스토리지, 인증 연동
- 빌드/배포 담당: 의존성, 설정 파일, 환경변수, CI/CD 파이프라인, 로컬 실행 절차

각자 조사 결과를 ARCHITECTURE.md 의 자기 섹션에만 이어붙이고,
겹치는 부분은 서로 메시지로 확인하세요.

ARCHITECTURE.md를 섹션별로 소유권을 나눠 쓰게 한 점이 중요합니다. 파일 하나를 네 명이 동시에 고치면 충돌하지만, “너는 3장만”이라고 지정하면 실질적으로 갈립니다. 불안하면 ARCHITECTURE_entrypoints.md 처럼 파일 자체를 나누는 게 더 안전합니다.

3-2. “왜 이렇게 생겼는지”를 캐게 만든다

레거시 파악의 핵심은 구조도가 아니라 숨은 의도입니다. 이건 코드만 읽어서는 안 나오고, git log와 git blame을 봐야 나옵니다.

조사 중에 "왜 이렇게 짜여 있는지 이해가 안 되는 코드"를 발견하면 추측하지 말고,
`git log -p` 와 `git blame` 으로 해당 코드가 들어온 커밋과 메시지를 확인하세요.
그래도 모르면 ARCHITECTURE.md 의 "미해결 질문" 섹션에 기록하세요.

“모르면 미해결 질문으로 남겨라” 가 결정적입니다. 이 지시가 없으면 에이전트는 그럴듯한 추측을 사실처럼 문서에 적어버리고, 그 잘못된 문서가 이후 모든 단계의 전제가 됩니다.

3-3. 가설 경쟁형 위험지점 발굴

구조 파악이 끝나면 “어디를 건드리면 터지는가” 를 찾습니다. 여기서는 팀원들을 서로 반박하게 만드는 것이 무기입니다.

ARCHITECTURE.md 를 바탕으로, 이 코드베이스에서 "리팩토링하면 가장 위험한 지점"을
팀원 3명이 각각 다른 가설로 조사하게 해 주세요.
서로 메시지를 주고받으며 상대의 위험도 평가를 반박하도록 하세요.
근거 없이 "위험해 보인다"고 한 항목은 서로 걸러내세요.
합의된 위험 순위를 RISKS.md 에 정리하세요.

단일 세션은 그럴듯한 위험 하나를 찾고 탐색을 멈춥니다. 서로 반박하는 조사자가 여럿일 때, 살아남은 평가가 실제 위험일 확률이 훨씬 높아집니다.

3-4. 산출물을 자산으로 승격시킨다

1단계가 끝나면 사람이 반드시 할 일이 있습니다. 에이전트가 만든 문서에 틀린 맥락이 없는지 검수하는 것입니다. 여기서 놓친 오류는 이후 모든 단계로 전파됩니다.

검수를 통과한 내용은 CLAUDE.md로 승격시킵니다.

# 아키텍처 (1단계 조사 결과, 2026-08-04 검수 완료)
- 상세 구조: @ARCHITECTURE.md
- 리팩토링 위험 지점: @RISKS.md
- 진입점은 `app/api/` 와 `app/batch/` 두 곳뿐. 그 외는 모두 내부 호출

@경로 문법으로 참조하면 필요할 때 읽어가므로, CLAUDE.md 본문은 짧게 유지됩니다. 이제 이후 모든 세션과 모든 팀원이 이 지도를 공유합니다. 1단계의 진짜 가치는 여기에 있습니다.

4. 2단계 — 안전망 구축: 테스터 에이전트

기존 동작을 보장하는 테스트 그물이 촘촘해질 때까지 에이전트에게 서비스 코드 수정 권한을 주지 않습니다.

4-1. 특성화 테스트란

레거시에 붙이는 테스트는 일반 테스트와 목적이 다릅니다.

  • 일반 테스트: 코드가 올바르게 동작하는지 검증
  • 특성화 테스트(Characterization Test): 코드가 현재 어떻게 동작하는지 고정

레거시에는 버그인지 기능인지 모를 동작이 잔뜩 있습니다. 그걸 판단하려 들면 진도가 안 나갑니다. 그래서 일단 현재 출력값을 그대로 정답으로 박아두고, 리팩토링 후 출력이 달라지면 실패하게 만듭니다. 옳고 그름을 따지는 건 나중 문제입니다.

`app/services/order.py` 의 현재 동작을 고정하는 특성화 테스트를 작성하세요.

- 목적은 "올바른 동작 검증"이 아니라 "현재 동작 고정"입니다.
- 버그처럼 보이는 동작도 고치지 말고 그대로 테스트로 박아두세요.
  단, 발견한 의심 지점은 테스트에 주석으로 남기고 별도 보고하세요.
- 내부 구현이 아니라 입력 → 출력을 검증하세요. 리팩토링해도 깨지지 않아야 합니다.
- 작성 후 `pytest tests/services/test_order.py` 를 실행해 전부 통과할 때만 완료 보고하세요.

“내부 구현이 아니라 입력 → 출력” 이 핵심입니다. 내부 함수 호출 순서를 검증하는 테스트를 만들면, 리팩토링할 때마다 테스트가 깨져서 안전망 역할을 못 합니다.

4-2. 팀원별 모듈 배정과 충돌 회피

테스트 작성은 파일이 자연스럽게 갈리므로 병렬화가 쉽습니다. 문제는 공통 부품입니다.

대상 소유자 이유
tests/services/test_order.py 팀원 A 모듈별로 완전히 분리됨
tests/services/test_user.py 팀원 B 동일
tests/conftest.py (공통 fixture) 리드가 선점 전원이 건드리려 함. 최대 충돌 지점
pytest.ini, tests/factories.py 리드가 선점 동일 
공통 fixture 와 설정 파일(`tests/conftest.py`, `pytest.ini`, `tests/factories.py`)은
리드가 먼저 작성합니다. 팀원은 이 파일들을 읽기만 하고 수정하지 마세요.
공통 fixture 추가가 필요하면 직접 만들지 말고 리드에게 요청하세요.

이 한 문단이 2단계에서 가장 자주 터지는 충돌을 막습니다. 팀원 세 명이 각자 conftest.py에 fixture를 추가하면 서로의 것을 덮어씁니다.

4-3. 훅으로 완료 조건을 강제한다

CLAUDE.md의 지시는 권고입니다. 팀원이 테스트를 안 돌리고 완료 보고하는 일이 실제로 발생합니다. 이걸 결정적으로 막으려면 훅을 씁니다.

{
  "hooks": {
    "TaskCompleted": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "pytest tests/ -q || (echo '테스트 실패. 완료 처리 불가' >&2; exit 2)"
          }
        ]
      }
    ]
  }
}

TaskCompleted 훅이 종료 코드 2로 끝나면 태스크 완료가 차단되고 피드백이 팀원에게 전달됩니다. 즉 테스트가 통과하지 않으면 물리적으로 완료 처리를 할 수 없습니다.

유사하게 TeammateIdle 훅은 팀원이 유휴 상태로 빠지려는 순간에 개입해 계속 일하게 만들 수 있습니다.

4-4. 이 단계의 완료 기준

“테스트를 몇 개 썼는가”는 무의미한 기준입니다. 3단계에서 손댈 영역이 테스트로 덮여 있는가가 유일한 기준입니다.

RISKS.md 의 위험 순위 상위 항목부터, 해당 코드 경로가 특성화 테스트로 덮였는지
커버리지로 확인하세요. `pytest --cov=app/services --cov-report=term-missing` 결과에서
3단계 리팩토링 대상 모듈의 커버리지가 80% 이상일 때 이 단계를 완료로 보고하세요.

5. 3단계 — 재작성: Strangler Fig 패턴

5-1. 핵심 원칙: 레거시를 직접 고치게 하지 않는다

레거시 시스템을 한 번에 뒤엎는 건 불가능합니다. 마틴 파울러의 교살자 무화과(Strangler Fig) 패턴 — 레거시 주변을 새 코드로 조금씩 둘러싸며 대체하는 기법 — 을 팀 구조에 그대로 이식합니다.

[ 레거시 시스템 ]
       │
       ▼ (1) 고고학자 (Read-Only)  ← 1단계에서 완료
       │     숨은 의도·도메인 지식 문서화
       ▼
       │ (2) 테스터                ← 2단계에서 완료
       │     현재 동작을 고정하는 특성화 테스트
       ▼
       │ (3) 이주자 (src/v2/ 만 Write 가능)
       │     레거시를 고치는 게 아니라, 새 폴더에 클린 코드로 재작성
       ▼
       │ (4) 검증관 (Read-Only)
       │     레거시 결과 vs 신규 모듈 결과 교차 대조 (Diff)
       ▼
[ 트래픽 스위칭 ] ← 사람이 판단

이 구조가 1-3절에서 지적한 worktree 미격리 문제를 구조적으로 해결합니다. 이주자는 새 폴더에만 쓰고, 검증관은 아무것도 쓰지 않습니다. 쓰기 권한을 가진 에이전트가 겹치지 않으니 충돌이 발생할 수 없습니다.

5-2. 이주자 에이전트 프롬프트

당신은 `src/v2/order/` 에 신규 주문 모듈을 작성하는 이주자 에이전트입니다.

- 작업 범위: `src/v2/order/` 내부 파일만 생성·수정 가능
- 절대 금지: `app/services/order.py` 등 기존 레거시 코드는 읽기 전용입니다.
  단 한 줄도 수정하지 마세요.
- 참고 자료: @ARCHITECTURE.md, @RISKS.md, 그리고 `tests/services/test_order.py`
  (현재 동작이 여기에 고정되어 있습니다)
- 구현 원칙: 레거시의 동작을 그대로 재현하되 구조만 개선하세요.
  동작을 "개선"하지 마세요. 개선 아이디어는 별도로 보고만 하세요.
- 완료 조건: `src/v2/order/` 에 대해 기존 특성화 테스트와 동일한 입출력이
  나오는지 확인하고, `pytest tests/v2/ -q` 통과 시 보고하세요.

“동작을 개선하지 마세요” 가 이 프롬프트의 가장 중요한 줄입니다. 재작성 단계에서 구조 개선과 동작 변경이 섞이면, 나중에 문제가 터졌을 때 원인을 분리할 수 없습니다.

5-3. 검증관 에이전트: 결과 교차 대조

이주자가 만든 코드가 진짜 같은지 확인하는 전담 팀원을 둡니다. 자기가 쓴 코드를 자기가 채점하지 않게 만드는 것이 요점입니다.

당신은 검증관 에이전트입니다. 전체 프로젝트에 대해 읽기 전용 권한만 가집니다.

- 역할: 레거시 `app/services/order.py` 와 신규 `src/v2/order/` 의 실행 결과가
  동일한지 대조하세요.
- 방법: 같은 입력을 양쪽에 넣어 출력을 비교하는 대조 스크립트를
  `scripts/compare_order.py` 에 작성하세요. 경계값과 예외 입력을 포함하세요.
- 코드를 직접 수정하지 마세요. 불일치를 발견하면 입력값과 양쪽 출력값을 함께
  이주자 에이전트와 리드에게 보고하세요.

여기서 “불일치 발견 시 입력값과 양쪽 출력값을 함께” 라고 요구하는 이유는, 근거 없이 “다른 것 같습니다”라는 보고를 막기 위함입니다. 재현 가능한 입력이 없는 보고는 검증할 수 없습니다.

5-4. PR을 작게 쪼갠다

팀이 3,000줄짜리 Big-PR을 만들어 오면 사람은 리뷰하다 포기합니다. 검토 못 한 코드가 머지되면 안전망을 만든 의미가 없습니다.

작업 단위를 나눌 때 다음을 반드시 지키세요.
- 한 PR은 파일 3개 이하, 변경 200줄 이하
- 하나의 PR은 하나의 관심사만 다룹니다 (구조 변경과 이름 변경을 섞지 마세요)
- 각 PR은 독립적으로 테스트가 통과해야 합니다
- PR 본문에 "무엇을 왜 바꿨는지"와 "레거시와 동작이 같음을 어떻게 확인했는지"를
  적으세요

5-5. 플랜 승인을 필수로 걸어라

3단계는 실제로 코드를 쓰는 첫 단계입니다. 팀원이 곧바로 손대는 게 불안하면 읽기 전용 플랜 모드를 강제합니다.

이주자 팀원을 만들되, 코드를 작성하기 전에 반드시 플랜 승인을 받도록 하세요.
승인 기준: 레거시 파일을 수정하지 않는 계획일 때만 승인하세요.
기존 동작을 변경하는 계획, 특성화 테스트를 수정하는 계획은 반려하세요.

승인 판단은 리드가 자율적으로 하므로, 승인 기준을 프롬프트에 못 박아 두는 것이 중요합니다. 기준을 안 주면 리드는 대체로 승인합니다.

5-6. 팀 대신 /batch·worktree를 써야 하는 경우

모든 대규모 변경에 팀이 정답은 아닙니다. 기계적이고 반복적인 대량 변경은 팀보다 다른 수단이 낫습니다.

작업 성격 적합한 수단 이유
판단이 필요한 재작성 (구조 재설계) 에이전트 팀 팀원 간 논의·상호 검증이 가치 있음
기계적 대량 변경 (import 경로 일괄 변경, API 시그니처 통일) /batch 스킬 변경을 worktree 격리된 서브에이전트 5~30개로 쪼개 각자 PR을 냄
완전히 독립된 여러 작업 동시 진행 worktree + 별도 세션 claude --worktree <이름> 으로 파일이 물리적으로 격리됨
코드베이스 전역 감사·수백 파일 마이그레이션 동적 워크플로우 스크립트가 계획을 쥐고 서브에이전트 결과를 교차 검증

판단 기준은 간단합니다. “팀원끼리 논의할 게 있는가?” 없으면 팀을 쓸 이유가 없고, 격리가 보장되는 수단이 더 안전합니다.

6. 4단계 — 실제 기능 개발: 팀에서 손을 뗄 때

6-1. 여기서 팀의 이점이 줄어드는 이유

목표가 “내가 원하는 기능 구현”까지라면, 이 단계에서는 팀 구성을 바꾸는 것이 정답입니다. 신규 기능 개발은 레거시 파악과 성격이 반대입니다.

특성 코드 파악 신규 기능 개발
작업 순서 병렬 가능 순차적 (모델 → 서비스 → API → 테스트)
파일 접촉 읽기만 같은 파일을 여러 번 수정
의존 관계 없음 촘촘함 (앞 단계 결과가 뒤의 입력)
논의 가치 높음 (다관점) 낮음 (설계가 정해지면 실행)

공식 문서가 “순차적 작업, 같은 파일 편집, 의존 관계 많은 작업은 단일 세션이 낫다”고 명시하는 게 정확히 이 상황입니다. 팀원 3명에게 하나의 기능을 나눠주면, 셋이 같은 서비스 파일을 고치며 서로를 덮어씁니다.

6-2. 권장 전환: 팀 → 단일 세션 → 팀

기능 개발에서는 팀을 앞뒤로만 쓰고 가운데는 단일 세션으로 갑니다.

[설계 검토]  팀 3~4명, 다관점  ← 팀이 강한 구간
     ↓  SPEC.md 산출
[구현]      단일 세션 + 서브에이전트  ← 팀 쓰지 않음
     ↓  코드 + 테스트
[리뷰]      팀 3명, 다관점  ← 팀이 강한 구간

설계 검토 단계에서는 팀이 강력합니다. 레거시에 기능을 얹는 건 선택지가 여러 개고, 각 선택지가 어떤 위험을 안는지 다관점 검토가 필요합니다.

주문에 부분 취소 기능을 추가하려고 합니다. @ARCHITECTURE.md 와 @RISKS.md 를 참고하세요.
팀원 3명을 만들어 각각 다른 접근을 설계하게 해 주세요.
- 1명: 기존 `app/services/order.py` 를 확장하는 방안
- 1명: `src/v2/order/` 신규 모듈에 구현하는 방안
- 1명: 반대 입장 — 두 방안의 위험과 숨은 비용을 지적
서로 반박하게 하고, 합의된 결론을 SPEC.md 에 쓰세요.
파일 목록, 인터페이스, 범위에서 제외할 것, 검증 방법을 반드시 포함하세요.

구현 단계는 새 세션에서 단일 세션으로 진행합니다. 설계 논의로 가득 찬 컨텍스트를 그대로 들고 가면 구현 품질이 떨어집니다. SPEC.md라는 문서로 넘기고 컨텍스트는 깨끗하게 시작하는 것이 낫습니다. 조사가 필요할 때만 서브에이전트를 씁니다.

리뷰 단계에서 다시 팀을 부릅니다. 자기가 쓴 코드를 자기가 리뷰하면 편향되므로, 새 컨텍스트의 리뷰어가 필요합니다.

`git diff main` 의 변경사항을 팀원 3명이 리뷰하게 해 주세요.
- 1명: SPEC.md 요구사항이 모두 구현됐는지, 범위를 벗어난 변경이 없는지
- 1명: 레거시 기존 동작을 깨뜨렸을 가능성 (@RISKS.md 위험 지점 중심)
- 1명: 테스트가 실제로 의미 있는 케이스를 덮는지
스타일 취향이 아니라 정확성과 요구사항에 영향을 주는 것만 지적하게 하세요.

마지막 줄이 중요합니다. 지적하라고 시킨 리뷰어는 문제가 없어도 무언가를 지적합니다. 그걸 다 쫓아가면 불필요한 추상화와 방어 코드가 쌓입니다.

6-3. 사람은 병목이 아니라 지휘자다

팀이 리팩토링과 테스트를 다 끝냈더라도 Git 커밋, PR 머지, 트래픽 스위칭 판단은 사람이 직접 diff와 테스트 결과를 확인해야 합니다. 특히 레거시에서는 사람만 아는 맥락이 계속 등장하므로, 검수 버퍼를 없애면 안 됩니다.

또한 팀을 오래 방치하지 마세요. 중간중간 확인하며 방향을 잡아주는 것이 낭비를 줄입니다.

7. 레거시에서 특히 자주 터지는 문제

7-1. 잘못된 가정이 팀 전체로 전파된다

레거시 특유의, 가장 위험한 실패 모드입니다. 팀원 A가 “이 필드는 안 쓰이는 것 같다”고 잘못 판단하고 메시지로 공유하면, 팀원 B와 C는 그걸 사실로 받아들이고 각자 작업합니다. 단일 세션이라면 오류 하나로 끝나는 일이 팀에서는 세 배로 번집니다.

대응: 1단계 프롬프트에 근거 요구를 명시적으로 넣습니다.

다른 팀원의 조사 결과를 인용할 때는 반드시 근거(파일:라인 또는 커밋 해시)를
함께 확인하세요. 근거 없는 주장은 "미해결 질문"으로 취급하고 사실처럼 쓰지 마세요.
"안 쓰이는 것 같다" 는 판단은 실제로 호출부를 전수 검색한 뒤에만 하세요.

그리고 1단계 산출물은 사람이 반드시 검수해야 합니다. 여기서 통과한 오류는 2~4단계 전체의 전제가 됩니다.

7-2. 리드가 팀원을 기다리지 않고 직접 구현한다

자주 발생합니다. 리드가 조율만 해야 하는데 답답해하며 직접 코드를 씁니다. 그러면 팀원과 같은 파일을 건드려 충돌합니다.

대응:

팀원들이 태스크를 마칠 때까지 기다린 뒤 진행하세요.
직접 코드 파일을 수정하지 말고 조율과 종합만 담당하세요.

7-3. 토큰이 폭발한다

레거시 탐색은 원래 파일을 많이 읽습니다. 거기에 팀원 수를 곱하면 토큰 사용량이 급격히 늘어납니다.

대응:

  • 모델 믹스: 리드는 Opus, 팀원은 Sonnet/Haiku. 팀원은 리드의 /model을 자동으로 물려받지 않으므로 /config의 Default teammate model을 확인하세요
  • 탐색 범위 지정: “코드베이스를 조사해”가 아니라 “app/api/ 아래를 조사해”로 좁힙니다
  • 읽기 전용 단계에서 팀원 수 줄이기: 4명이 필요한지 3명으로 되는지 먼저 판단합니다

7-4. 태스크 상태가 지연되고 후속 작업이 막힌다

팀원이 작업을 끝내고도 완료 처리를 깜빡하면, 의존 관계가 걸린 후속 태스크가 계속 대기합니다.

대응: Ctrl+T로 태스크 리스트를 열어 상태를 확인하고, 멈춘 것 같으면 실제 작업이 끝났는지 보고 수동으로 상태를 고치거나 리드에게 확인시킵니다.

7-5. 세션을 재개하면 팀원이 사라져 있다

/resume과 /rewind는 in-process 팀원을 복원하지 않습니다. 레거시 작업은 며칠에 걸치기 쉬워서 이 문제를 자주 만납니다.

대응: 세션 재개 후 리드가 없는 팀원에게 말을 걸려 하면 새 팀원을 만들라고 지시하세요. 근본적인 대책은 중요한 산출물을 반드시 파일로 남기는 것입니다. ARCHITECTURE.md, RISKS.md, SPEC.md가 있으면 팀이 날아가도 새 팀에 그대로 넘길 수 있습니다.

7-6. 권한 프롬프트가 쏟아진다

팀원의 권한 요청은 모두 리드로 올라옵니다. 승인 창을 열 번 넘게 누르면 사실 검토를 안 하고 클릭만 하게 됩니다.

대응: 2-4절처럼 팀을 띄우기 전에 자주 쓸 명령을 미리 허용하세요.

8. 실행 체크리스트

0단계 — 판 깔기

  • CLAUDE.md에 실행/테스트 명령어 기입
  • CLAUDE.md에 절대 수정 금지 영역 명시
  • 사람만 아는 도메인 히스토리 주입
  • 검증 수단 최소 하나 확보 (테스트 없으면 빌드·린트라도)
  • rg, git log, git blame, 테스트 명령 사전 허용
  • 팀 규모 3~5명으로 결정

1단계 — 코드 파악 (전원 읽기 전용)

  • 팀원마다 다른 축으로 영역 분할 (진입점 / 데이터 / 외부연동 / 빌드배포)
  • 문서 섹션 또는 파일 소유권 분리
  • “모르면 추측하지 말고 미해결 질문으로” 지시
  • 가설 경쟁형 위험지점 발굴 → RISKS.md
  • 사람이 산출물 검수 (여기서 놓친 오류는 전 단계로 전파)
  • 검수 통과분을 CLAUDE.md로 승격

2단계 — 안전망 구축

  • 특성화 테스트 목적 명시 (“현재 동작 고정”, 버그도 그대로)
  • 입력 → 출력 검증 (내부 구현 검증 금지)
  • 공통 fixture·설정 파일은 리드가 선점
  • TaskCompleted 훅으로 테스트 통과 강제
  • 3단계 대상 모듈 커버리지 목표를 완료 조건으로

3단계 — 재작성

  • 레거시 파일은 읽기 전용, 신규 폴더에만 쓰기
  • 이주자와 검증관 분리 (쓴 사람이 채점하지 않게)
  • “동작을 개선하지 마세요” 명시
  • 플랜 승인 필수 + 승인 기준 명시
  • PR 파일 3개·200줄 이하로 제약
  • 기계적 대량 변경이면 팀 대신 /batch·worktree 검토

4단계 — 기능 개발

  • 설계 검토는 팀 다관점 → SPEC.md
  • 구현은 새 세션에서 단일 세션 + 서브에이전트
  • 리뷰는 다시 팀 다관점, “정확성·요구사항만 지적” 명시
  • 커밋·머지·트래픽 스위칭은 사람이 diff 확인 후 판단

핵심요약

  • 레거시에 팀을 그냥 던지면 숨은 의도와 예외 처리를 밀어버립니다. 판을 깔고 들어가야 합니다. 코드만 봐선 알 수 없는 도메인 히스토리를 CLAUDE.md에 먼저 주입하세요.
  • 에이전트 팀은 파악·검증에 강하고 순차적 구현에 약합니다. 1단계 코드 파악이 최적 구간, 4단계 기능 개발은 단일 세션으로 넘기는 게 맞습니다.
  • 팀원은 worktree로 격리되지 않습니다. 그래서 “레거시를 직접 고치지 말고 새 폴더에 재작성”하는 Strangler Fig 구조가 답입니다. 쓰기 권한을 가진 에이전트를 겹치지 않게 만드는 것이 요점입니다.
  • 특성화 테스트로 현재 동작을 고정한 뒤에만 코드를 건드리게 하세요. 버그처럼 보이는 동작도 일단 그대로 박아둡니다.
  • 레거시 특유의 위험은 잘못된 가정의 전파입니다. 근거(파일:라인, 커밋 해시)를 요구하고, 1단계 산출물은 반드시 사람이 검수하세요.