AI 코딩의 역할 분리 — Advisor/Worker 운용기
Claude Code 하나로 개발하다가, 모델의 역할을 “판단”과 “실행”으로 나눈 뒤 생긴 변화에 대한 기록.
문제: 만능 비서의 한계
AI 코딩 도구를 쓰다 보면 공통적으로 겪는 패턴이 있다.
- 요구사항을 던진다.
- AI가 탐색하고, 설계하고, 코드를 쓰고, 테스트하고, 보고까지 혼자 다 한다.
- 컨텍스트가 길어질수록 초반에 세운 설계 의도가 흐려진다.
- “다 됐습니다”라는 보고를 믿었지만 나중에 문제가 발견된다.
핵심 문제는 하나의 컨텍스트가 판단과 노동을 동시에 감당한다는 것이다. 설계 판단에 써야 할 컨텍스트가 파일 읽기, 코드 diff, 테스트 로그 같은 구현 노이즈로 가득 차 버린다. 사람 조직으로 치면 아키텍트가 직접 키보드를 잡고 모든 코드를 치면서 동시에 코드 리뷰까지 셀프로 하는 셈이다.
그래서 역할을 쪼갰다.
구조: Advisor와 Worker
사용자 (나)
│ 요구사항
▼
Advisor (메인 세션)
│ ├─ 요구사항 분석 · 작업 분해 · 설계 결정
│ ├─ 작업 브리프 작성
│ └─ 결과 검증 (diff 확인, 테스트 직접 실행)
│
│ 브리프 위임 (독립 작업은 병렬로)
▼
Worker (서브에이전트) × N
└─ 코드 작성, 테스트 작성, 리팩터링 — 구현 노동 전부- Advisor = 메인 세션. 나와 대화하는 창구이자 테크리드. 코드를 직접 짜지 않는다.
- Worker = 서브에이전트. 이미 분해된 브리프를 받아 구현만 한다. 판단하지 않는다.
사람 조직의 시니어/주니어 분업과 비슷하다. Worker를 여러 명 병렬로 실행할 수 있다는 점이 다르다.
설정: 파일 두 개면 끝난다
Claude Code 기준으로 필요한 건 프로젝트의 CLAUDE.md(메인 세션 지침)와 .claude/agents/worker.md(서브에이전트 정의) 두 개다.
1. CLAUDE.md — Advisor의 역할 정의하기
## 모델 역할 분담: Advisor / Worker
너는 Advisor다. 판단에 집중하고, 구현 노동은 Worker에게 위임하라.
Advisor(너, 메인 세션)가 직접 하는 일:
- 요구사항 분석, 작업 분해, 설계 결정
- Worker에게 줄 작업 브리프 작성
- 결과 검증: diff 직접 확인, 테스트 직접 실행
- 최종 커밋 승인, 사용자 보고
Worker(서브에이전트)에게 위임하는 일:
- 코드 작성과 수정, 테스트 작성 등 구현 작업 전부
- 모델 티어를 작업 난이도에 맞춰 지정한다: 설계 여지가 있는 구현은 상위 모델,
브리프대로 옮기면 되는 기계적 작업은 기본 모델
- 파일이 겹치지 않는 독립 작업은 병렬로 위임한다. 겹치면 순차 또는 worktree 격리
브리프 템플릿 (이 형식을 그대로 쓴다):
- **작업**: 한 줄 요약
- **컨텍스트**: 네가 이미 파악한 구조·패턴. Worker가 재탐색하지 않게
- **할 일**: 변경할 파일 경로와 구체적 변경 내용
- **함정**: 주의해야 할 사항. 없으면 "없음"이라고 쓴다
- **완료 기준**: 통과해야 할 명령을 실행 가능한 형태로 그대로 적는다
경계:
- Worker의 완료 보고를 그대로 믿지 마라. diff와 완료 기준 재실행으로 확인 후 승인하라
- 검증 실패는 수정 브리프로 재위임하라. 2회 재위임에도 실패하면
브리프(분해·설계) 쪽 결함으로 보고 접근을 재설계하라
- 직접 수정은 사소한 마무리에만. 위임 오버헤드가 더 큰 작업은 직접 처리해도 된다
- Worker의 "발견 사항"은 버리지 마라. 즉시 처리하지 않을 것은 잔여 목록에 기록하라
- 커밋 전 최종 게이트는 Advisor가 한 번만 돌린다. Worker에게 중복으로 돌리게 하지 마라2. .claude/agents/worker.md — Worker의 행동 강령
---
name: worker
description: Advisor가 위임하는 구현 작업 전담 Worker.
이미 분해된 작업 브리프를 받아 실행하는 용도로 사용한다.
model: sonnet
---
너는 Worker다. Advisor(메인 세션)가 분해한 작업 브리프를 받아 구현을 실행한다.
## 역할
- 브리프에 명시된 범위만 구현한다. 브리프에 없는 리팩터링, 추상화, 클린업은 하지 않는다.
- 브리프의 컨텍스트·경로·함정 정보는 재탐색 없이 그대로 쓴다.
브리프에 빠진 정보만 코드베이스를 탐색해 채운다.
## 품질 게이트 — CI에서 error로 걸린다. 작성 시점부터 준수하라
- 함수 complexity ≤ 12, 함수 길이 ≤ 80라인. 넘을 것 같으면 처음부터 나눠 작성한다.
- 중복(jscpd)과 미사용 export(knip)도 게이트다. 복붙 대신 공통부를 재사용한다.
## 검증
- 완료 기준에 명시된 명령만 직접 실행해 통과를 확인한다.
전체 스위트·빌드는 돌리지 않는다 — 최종 게이트는 Advisor 담당이다.
- 실행하지 않은 검증을 통과했다고 주장하지 않는다.
통과하지 못했으면 시도 내역과 함께 "미완료"로 보고한다.
## 보고 형식
1. **변경**: 파일별로 무엇을 바꿨는지 한 줄씩
2. **검증**: 실행한 명령과 결과(통과/실패 원문 요지)
3. **발견 사항**: 범위 밖 이슈. 임의로 수정하지 않고 보고만 한다. 없으면 생략포인트는 두 지침이 서로를 향해 설계되어 있다는 것. Advisor의 “브리프 기준”과 Worker의 “브리프에 포함된 정보는 그대로 따른다”가 맞물리고, Advisor의 “완료 보고를 믿지 마라”와 Worker의 “실행하지 않고 통과를 주장하지 않는다”가 이중 안전망을 만든다.
운용 사이클
실제로 한 기능 요청이 처리되는 흐름은 이렇다.
① 분석 — Advisor가 먼저 코드를 읽는다
Advisor는 위임 전에 관련 파일, 기존 패턴, 함정을 직접 파악한다. 이걸 생략하면 브리프가 부실해지고, 부실한 브리프는 Worker의 재탐색 비용으로 그대로 돌아온다.
② 브리프 — 재탐색이 필요 없는 작업 지시서
브리프에 반드시 들어가는 네 가지:
| 항목 | 내용 |
|---|---|
| 컨텍스트 | Advisor가 이미 파악한 구조·패턴. Worker가 다시 뒤지지 않게 |
| 파일 경로 | 건드릴 파일, 참고할 파일을 명시 |
| 알려진 함정 | ”이 훅은 SSR에서 오류가 발생한다” 같은 주의 사항 |
| 완료 기준 | 통과해야 할 테스트·타입체크 명령을 구체적으로 |
브리프 예시:
## 작업: 사진 업로드 큐에 재시도 로직 추가
### 컨텍스트
- 업로드 큐는 hooks/usePhotoUploadQueue.ts 에 있고, 실패 시 그냥 큐에서 빠진다.
- 이 프로젝트의 비동기 에러 처리는 lib/unwrap.ts 의 unwrap() 패턴으로 통일되어 있다. 따를 것.
### 할 일
- 실패 항목을 최대 3회 지수 백오프로 재시도. 3회 실패 시 상태를 'failed'로 두고 큐에 남긴다.
### 함정
- 큐 상태는 로컬 상태가 아니라 zustand 스토어다. setState 직접 호출 금지.
### 완료 기준
- npm run test -- usePhotoUploadQueue 통과
- npm run typecheck 통과③ 병렬 위임 — 독립 작업은 동시에
서로 파일이 겹치지 않는 작업들은 Worker를 여러 명 동시에 띄운다. 예를 들어 “복잡도 게이트 위반 9건 분해” 같은 작업은 파일 단위로 독립적이라 병렬 위임의 전형적인 케이스다. 사람 팀이라면 조율 회의가 필요할 일이 브리프 몇 장으로 끝난다.
④ 검증 — 보고는 참고자료, 증거가 결론
Worker가 “완료했고 테스트도 통과했다”고 보고해도, Advisor는:
git diff로 변경분을 직접 읽는다 — 브리프 범위를 벗어난 수정이 없는지, 컨벤션을 지켰는지.- 완료 기준 테스트를 직접 다시 실행한다.
검증에 실패하면 고쳐 쓰지 않고 수정 브리프로 재위임한다. “여기가 이렇게 틀렸다, 이 방향으로 고쳐라”까지가 Advisor의 일이다. 직접 손대는 건 오타 수준의 마무리뿐.
⑤ 승인 — 커밋과 보고
검증을 통과한 것만 커밋되고, 사용자에게는 Advisor가 정리된 결과만 보고한다.
왜 이게 잘 동작하나
1. 컨텍스트 분리가 곧 품질이다. Advisor의 컨텍스트에는 설계 의도와 검증 결과만 쌓인다. 파일을 읽은 기록이나 시행착오가 담긴 diff 같은 구현 과정은 Worker의 개별 컨텍스트에 머문다. 긴 세션에서도 Advisor는 “이 프로젝트가 어디로 가고 있는지”를 잃지 않는다.
2. 브리프 작성이 강제 설계 리뷰가 된다. 작업을 위임하려면 먼저 할 일을 정의해야 한다. 브리프에 완료 기준을 쓰기 어렵다면 아직 요구사항이 충분히 정리되지 않았다는 신호다. 이 과정은 설계가 정리되기 전에 구현부터 시작하는 문제를 줄여준다.
3. 검증이 프로세스에 내장된다. AI 결과물을 검증하겠다는 원칙은 구체적인 절차가 있어야 지켜진다. Advisor 지침에 완료 보고를 직접 확인하도록 명시하면 검증이 선택이 아니라 파이프라인의 한 단계가 된다. Worker 쪽에도 실행하지 않은 테스트를 통과했다고 보고하지 않도록 정해 양방향 안전장치를 둔다.
4. 범위 이탈이 구조적으로 막힌다. AI가 요청 범위 밖의 리팩터링까지 진행하는 경우가 있다. Worker 지침의 “브리프에 없는 클린업은 하지 않는다 + 발견 이슈는 보고만 한다” 조합이 이를 막고, 발견 사항은 Advisor가 다음 작업으로 편성할지 판단한다. 이슈를 놓치지 않으면서도 임의 수정을 방지할 수 있다.
실전에서 배운 것들
- 위임 오버헤드 손익분기를 정해둬라. 한두 줄 수정까지 브리프를 쓰는 건 배보다 배꼽이다. “사소한 건 Advisor가 직접”이라는 예외 조항이 지침에 명시되어 있어야 규칙이 오래 간다.
- CI 게이트를 Worker 지침에 명시하라. 이 프로젝트는 함수 복잡도·길이·중복·미사용 export가 CI에서 오류로 처리된다. 이를 Worker 지침에 넣지 않으면 게이트 위반 코드가 검증에서 발견되어 다시 위임하는 과정이 반복된다. 간단한 지침만으로 불필요한 재작업을 줄일 수 있다.
- 검증 분담을 명시하라. Worker는 브리프의 완료 기준만, Advisor는 커밋 전 최종 게이트를 한 번만 실행한다. 이 경계가 없으면 같은 테스트 스위트가 중복 실행되어 시간과 토큰이 낭비된다.
- 함정 항목이 브리프의 가성비 1위다. 컨벤션이나 경로는 Worker도 찾을 수 있지만, “이 스토어는 직접 setState 하면 안 된다” 같은 암묵지는 못 찾는다. 함정 한 줄이 재작업 한 사이클을 아낀다.
- 모델 티어를 역할에 맞춰라. 판단·검증을 맡는 Advisor에 상위 모델을, 브리프대로 실행하는 Worker에 실행력 좋은 모델을 배치하면 비용 대비 품질이 좋아진다. 브리프가 좋을수록 Worker 모델 요구 수준은 내려간다.
- 필요하면 다시 위임하라. 검증 실패 시 Advisor가 “직접 고치는 게 빠르겠다”며 수정하기 시작하면 역할 분리가 무너진다. 수정 브리프는 다음 브리프의 품질을 높이는 피드백이기도 하다.
정리
| Before (단일 세션) | After (Advisor/Worker) | |
|---|---|---|
| 컨텍스트 | 설계와 노동이 한 컨텍스트에서 뒤섞임 | 판단은 메인에, 노동은 일회용 컨텍스트에 |
| 검증 | AI의 자가 보고에 의존 | diff·테스트 직접 확인이 프로세스에 내장 |
| 병렬성 | 순차 처리 | 독립 작업 동시 위임 |
| 범위 관리 | 임의 리팩터링 발생 | 브리프 범위 강제 + 발견 사항 보고 체계 |
결국 이 구조가 하는 일은 단순하다. 사람 조직이 오랫동안 활용해 온 분업 — 설계와 구현의 분리, 코드 리뷰, 작업 지시서 — 을 AI 운용에 적용한 것이다. AI의 역량이 발전하더라도 작업을 효과적으로 나누고 검증하는 방법은 사람 조직의 운영 방식에서 참고할 부분이 많다.
설정 파일 두 개로 시작할 수 있다. CLAUDE.md에 Advisor 규칙을, .claude/agents/worker.md에 Worker 규칙을 넣고, 첫 브리프를 써보면 된다.