>> 10만 줄 이상을 혼자? Claude Code 4.8 동적 워크플로와 병렬 서브에이전트 실전
소개
전담 태스크포스 없이 10만 줄 이상 레거시 코드베이스를 한 명이 리팩터링할 수 있을까요? 2026년 5월 Anthropic은 Claude Opus 4.8과 Claude Code의 동적 워크플로(Dynamic Workflows)를 출시했습니다. 연구 미리보기 패턴으로, 에이전트가 작업을 계획하고, 병렬 서브에이전트를 전개하며, 결과를 검증한 뒤 보고합니다(Claude Opus 4.8 발표).
Claude Code 동적 워크플로는 언어·프레임워크 간 마이그레이션에서 풀스택 팀이 겪는 고통——한 채팅에 담기지 않는 파일 수, 순차 에이전트 루프로는 감당 못 하는 의존성——을 정확히 겨냥합니다. 실행 트리 동작, 단일 스레드 Claude Code보다 나은 경우, 실제 테스트 스위트가 있는 저장소에서 돌릴 7단계 런북을 설명합니다.
에이전트 기본기(평가, 컨텍스트 한계)를 아직 다지는 중이라면 2026 개발자 AI 스킬을 먼저 읽으세요. 동적 워크플로는 좋은 습관을 증폭할 뿐 대체하지 않습니다.
Opus 4.8과 동적 워크플로의 변화
Anthropic이 마이그레이션에 중요하다고 설명하는 세 가지 메커니즘:
| 메커니즘 | 역할 | 마이그레이션 의미 |
|---|---|---|
| 계획 단계 | Claude가 저장소를 작업 단위로 분해 | 「한 파일만 고치다 컨텍스트 소진」 방지 |
| 병렬 서브에이전트 | 한 세션에서 수백 개 | 파일·패키지 수준 병렬 |
| 검증 게이트 | 최종 보고 전 출력 확인 | 10만 줄 규모의 조용한 파손 감소 |
Opus 4.8은 불확실성 하에서의 정직함도 강조합니다. 초기 테스터는 Opus 4.7 대비 미표시 결함이 적다고 보고합니다. 마이그레이션에서는 테스트 없이 「완료」라고 하는 경우가 줄어듭니다.
가용성(최신 문서 확인): 동적 워크플로는 Claude Code 연구 미리보기로 Enterprise, Team, Max 플랜에 제공. API 모델 ID: claude-opus-4-8. 어려운 장기 작업에는 xhigh effort.
아키텍처: 멀티에이전트 실행 트리
동적 워크플로를 얕은 오케스트레이션 트리로 보세요. 무제한 스웜이 아닙니다.
구성 요소
| 노드 | 책임 | 전형 산출물 |
|---|---|---|
| 리드 세션 | 범위, 계획, 병합 전략 | MIGRATION.md 체크리스트 |
| 플래너 | 저장소 분할(패키지·레이어·기능 슬라이스) | 작업 단위 manifest JSON |
| 워커 서브에이전트 | 슬라이스별 변환 적용·로컬 수정 | 브랜치 커밋 또는 패치 시리즈 |
| 검증기 | 테스트/린터, diff 검토, 충돌 스캔 | CI 로그 요약 |
| 사람 병합 | PR 승인, 정책 충돌 해결 | 서명된 병합 커밋 |
데이터 흐름
- 마이그레이션 계약 정의: 대상 프레임워크, 금지 API, 완료 기준 = CI 그린.
- 리드 에이전트가 저장소를 조사해 N개 병렬 가능 단위 출력(10만 LOC 모놀리스에서 50–200+ 흔함).
- 서브에이전트는 공유 정책 문서 읽기 전용, 각 슬라이스 내부만 쓰기.
- 검증기가 실패 집계; 리드는 실패 단위 재생성 또는 파일 경로와 함께 에스컬레이션.
- 테스트 스위트 기준을 만족할 때 병합——모델의 「완료」가 아님.
Anthropic 사례와 일치: 킥오프부터 병합까지 수십만 줄 코드베이스 마이그레이션, 기존 자동화 테스트 스위트를 통과 기준으로.
의사결정 매트릭스: 동적 워크플로가 이기는 경우
| 상황 | 동적 워크플로? | 권장 대안 |
|---|---|---|
| 10만+ LOC, 기계적 변환(import 경로, API rename) | 예 | — |
| <5k LOC 스파이크 | 아니오 | 단일 세션 Claude Code |
| 자동 테스트 없는 마이그레이션 | 테스트 추가 전 아니오 | 특성화 테스트 먼저 |
| 보안 민감 auth/암호화 재작성 | 부분 — 계획만; 슬라이스별 사람 검토 | 수동 레인 + 에이전트 보조 |
| 법적 감사 가능 diff 필요 | 예, 플래너 manifest 고정 | manifest를 git에 저장 |
변경 모듈 테스트 커버리지가 30% 미만이면 동적 워크플로를 시작하지 마세요. 2주를 골든 패스 테스트에 투자하세요. 그렇지 않으면 병렬 에이전트는 올바른 동작이 아니라 그럴듯한 diff를 최적화합니다.
시작 전 전제 조건
- 클린 체크아웃에서 CI 45분 이내——또는 슬라이스별 CI + 머지 큐.
- CI에서 포매터 + 린터 강제(자동 수정 루프 수렴 가속).
docs/migration/의 마이그레이션 플레이북(금지 패턴, 목표 관용구).- 브랜치 전략: 하나의 통합 브랜치; 워커는 topic 브랜치 또는 스택 PR.
- 토큰 예산: 장기 작업은 Opus 4.8
xhigh; Opus 4.7 기본보다 사용량 증가 예상.
IDE/에이전트 위생(허용 목록, 시크릿)은 Cursor 및 대체 스택도 참고——Claude Code 셸에도 동일 원칙.
7단계 마이그레이션 런북
1단계 — 기준선 및 범위 동결
git checkout -b migration/opus-48-baseline
git rev-parse HEAD > .migration/baseline.sha
CI=1 npm test 2>&1 | tee .migration/baseline-test.log
통과: 기준선 테스트 그린 또는 실패가 KNOWN_FAILURES.md에 문서화.
2단계 — 마이그레이션 계약 작성
Create MIGRATION.md with:
- 대상 스택 버전(예: React 19, Spring Boot 3.4)
- 범위 내 디렉터리
- 범위 외(생성 코드, 벤더 라이브러리)
- 완료 =
npm test && npm run lint그린
3단계 — Claude Code에서 동적 워크플로 시작
- Opus 4.8(
claude-opus-4-8) 선택. - 수시간 마이그레이션은 effort를
xhigh로. - 아래 프롬프트 패턴 사용,
MIGRATION.md와 기준 SHA 첨부.
동적 워크플로는 자격 Claude Code 플랜에서 연구 미리보기입니다.
MIGRATION.md에 따라 코드베이스 마이그레이션을 계획하세요.\n병렬 작업 단위를 각 ≤2k LOC로 분할하세요.\n서브에이전트로 변환을 적용하세요.\n완료 보고 전 기존 테스트 스위트로 검증하세요.
4단계 — 플래너 manifest 검토
| 확인 | 실패 조치 |
|---|---|
| 5k LOC 초과 단위? | 분할 요청 |
| 10개 이상 단위가 동일 전역 상태? | 해당 모듈 직렬화 |
| 단위별 테스트 매핑 누락? | 테스트 대상 추가 |
manifest를 git .migration/units.json에 저장.
5단계 — 워커 실행 및 fan-out 모니터링
- VCS 충돌 급증 시 디렉터리당 동시 편집 제한.
- 배치 병합마다 포매터 재실행.
- 마이그레이션 범위 밖 임의 리팩터링 거부.
대형 저장소에서는 수십~수백 서브에이전트 예상.
6단계 — 검증 게이트와 CI
git fetch --all
npm test 2>&1 | tee .migration/final-test.log
diff .migration/baseline-test.log .migration/final-test.log > .migration/test-delta.txt
통과: 문서화된 알려진 목록 외 신규 실패 없음.
7단계 — 사람 병합 및 사후 분석
- 생성/실패/재시도 단위 수
- 경과 시간 vs 추정
- 토큰 소비(Anthropic 사용량 대시보드)
- 7일 내 스테이징에서 발견된 결함
필요 시 feature flag 뒤 main에 병합.
10만 LOC를 견디는 병렬 서브에이전트 전술
| 전술 | 세부 |
|---|---|
| 의존성 레이어로 슬라이스 | Utils → 도메인 → UI로 순환 병합 고통 감소 |
| 기계적 변환 우선 | 의미적 리팩터 전 정규식 안전 rename |
| 단위당 하나의 관심사 | 「HTTP 클라이언트 마이그레이션」과 「상태 관리」 분리 |
| 멱등 스크립트 | 워커는 codemod CLI; LLM은 fallout만 수정 |
| 검증기가 flake 탐지 | 실패 테스트 1회 재시도; 두 번째는 에스컬레이션 |
Anthropic은 Opus 4.8에서 서브에이전트가 더 오래 실행 가능하다고 합니다——그래도 명시적 경과 시간 상한(예: 단위당 20분)을 두어 한 워커 hang이 트리 전체를 막지 않게 하세요.
문제 해결
오류 A — 「마이그레이션 완료」인데 CI 빨강
패턴: 리드 요약은 성공; 로컬 npm test 실패.
Fix:
.migration/final-test.log첨부 후 세션 재개.- 프롬프트:
units.json 작업 단위별 실패 테스트 나열. 실패 단위만 재생성. - 병합 전 검증기가 통과한 CI 실행 URL 또는 로그 해시를 참조해야 함.
오류 B — 병합 충돌 폭풍
패턴: 30% 이상 단위가 동일 5파일(예: 중앙 index.ts) 수정.
수정: 공유 파일용 직렬 레인으로 재계획——한 서브에이전트가 barrel export; 나머지는 패치 순차 적용.
git diff --name-only migration/opus-48-baseline...HEAD | sort | uniq -c | sort -nr | head
횟수 >3 파일은 병합 핫스팟.
오류 C — 속도 제한/토큰 고갈
패턴: 서브에이전트가 트리 중간 정지; 브랜치에 부분 커밋 산재.
수정: fan-out 일시 중지; 완료 단위 병합; 더 작은 배치(예: 25단위)로 재개. 남은 어려운 슬라이스만 xhigh——저장소 전체 재시작 금지.
팀 규모별 권장 경로
| 당신이… | 권장 |
|---|---|
| 솔로 풀스택 | 10만 줄 3파(utils → services → UI); Big Bang 병합 금지 |
| 2–5인 스타트업 | 한 사람이 manifest + 병합; 에이전트가 슬라이스 |
| 플랫폼 팀 | codemod + CI 제공; 동적 워크플로는 의미적 공백만 |
주말만 있다면: 테스트 완비 2만 LOC로 범위 축소; 모놀리스에 베팅하기 전 워크플로 입증.
FAQ
Claude Code 동적 워크플로란?
Claude Code가 대규모 작업을 계획하고, 한 세션에서 많은 병렬 서브에이전트를 실행하며, 끝나기 전 출력을 검증하는 연구 미리보기 오케스트레이션 모드입니다——마이그레이션 같은 저장소 규모 작업용(출처).
Claude Opus 4.8이 꼭 필요한가요?
Anthropic은 Dynamic Workflows를 Opus 4.8 세대에 묶어 더 길고 안정적인 에이전트 실행을 지원합니다. 모델 ID claude-opus-4-8을 쓰고 플랜에 Claude Code 연구 기능이 포함되는지 확인하세요.
한 사람이 정말 10만 줄 이상을 리팩터링할 수 있나요?
CI가 강하고 변환이 대체로 기계적이면 한 사람이 오케스트레이션할 수 있습니다. 의미적 재작성은 여전히 사람 검토 레인이 필요합니다——동적 워크플로는 달력 시간을 줄일 뿐 책임은 줄이지 않습니다.
병렬 서브에이전트는 몇 개까지?
Anthropic은 대규모 마이그레이션에서 한 세션에 수백 개를 언급합니다. 실제 수는 이론적 최대가 아니라 병합 충돌 데이터로 제한해야 합니다.
「완료」 기준은?
기존 자동화 테스트 스위트——모델 자기 보고가 아닙니다. 검증기 출력은 병합 전 체크리스트로 쓰고 CI 대체로 삼지 마세요.
OpenClaw/Dify형 에이전트를 대체하나요?
아니요. Claude Code 동적 워크플로는 IDE 중심 저장소 리팩터입니다. 오케스트레이션 플랫폼(OpenClaw + Dify)은 다른 문제——Ops 자동화·다중 시스템 워크플로——를 다루며, 규율 있는 migration runbook을 대체하지 않습니다.