소규모 팀을 위한 멀티 에이전트 코딩 워크플로: Worktree, 역할, 리뷰 게이트

여러 coding agent를 동시에 쓰는 것은 다음 변경이 독립된 범위로 나뉘고, 계약이 안정적이며, 각 agent의 workspace가 분리되고, 팀이 여러 diff를 실제로 review할 수 있을 때만 의미가 있습니다. 두 agent가 같은 파일을 수정해야 하거나 인터페이스가 아직 움직이거나 reviewer가 diff를 따라가지 못한다면 한 agent로 순차 진행하는 편이 더 빠릅니다.

소규모 팀의 안전한 기본형은 자율 swarm이 아닙니다. human lead, 격리된 implementer agent, verifier agent로 시작합니다. 모든 task에는 owner, worktree 또는 branch, allowed files, forbidden files, handoff, 검증 명령, merge gate가 있어야 합니다.

먼저 경로 보드, task brief, worktree 격리, handoff, 검증 gate, merge 순서, review-hour 지표를 통과시키세요. agent 수는 그 다음에 늘립니다.

agent 수보다 경로를 먼저 정한다

멀티 에이전트 코딩이 효과가 있는 이유는 실행자가 많아서가 아니라 소유권을 분리할 수 있기 때문입니다. frontend agent와 backend agent를 동시에 돌려도 API를 함께 발명하는 단계라면 안전한 분담이 아닙니다. bug fix와 test 작성도 test agent가 fix 내용을 추측해야 한다면 독립 검증이 아닙니다.

소규모 팀은 네 가지 경로만 봐도 충분합니다. 단일 agent는 hot file, migration, 보안, 큰 refactor에 맞습니다. 2단계 pipeline은 implementer와 verifier를 나눕니다. 3분할은 API나 type contract가 고정된 뒤에만 작동합니다. agent team은 강한 CI, merge queue, review 여력이 있는 경우에만 시도합니다.

경로는 일주일 안에서도 바꿀 수 있습니다. 먼저 2단계 pipeline을 돌려 review하기 쉬운 diff가 나오는지 확인하세요. ownership이 보이지 않는 상태에서 agent를 늘리면 산출보다 coordination cost가 먼저 커집니다.

여러 coding agent가 실제로 도움이 되는 조건

잘 맞는 작업은 경계가 보이는 breadth-first 작업입니다. 한 agent가 UI state를 구현하고 다른 agent가 integration tests를 작성합니다. 한 agent가 failing path를 조사하고 다른 agent가 regression coverage를 확인합니다. shared type이나 API contract가 고정된 뒤 서로 다른 module을 고칩니다. 핵심은 agent가 다른 agent의 미완성 코드를 기다리지 않고 끝낼 수 있다는 점입니다.

다섯 조건을 동시에 확인하세요. scope가 한두 개의 fileset으로 설명된다. shared contract가 전달 가능한 수준으로 안정적이다. 각 agent가 branch 또는 worktree를 가진다. 사람이 chat transcript가 아니라 diff와 proof를 본다. CI와 reviewer가 sequential merge를 감당한다.

마지막 조건이 작은 팀의 함정입니다. 두 agent는 한 reviewer보다 빠르게 코드를 만듭니다. lead가 conflict resolver가 되면 workflow가 빨라진 것이 아니라 bottleneck이 review로 옮겨진 것입니다.

단일 agent가 더 나은 경우

강하게 결합된 작업은 단일 agent가 좋습니다. database migration, auth middleware, billing flow, public API, weak tests, dependency update, repo-wide rename, security-sensitive edit는 하나의 통제선에 둡니다. 여기서는 병렬화보다 판단의 일관성이 중요합니다.

실용적인 stop rule은 간단합니다. 한 agent가 다른 agent의 unfinished code를 기다려야 다음 행동을 알 수 있다면 병렬로 돌리지 않습니다. lead가 contract를 쓰고, 한 agent가 첫 diff를 만들고, verifier나 사람이 확인한 뒤 다음 agent가 최신 main에서 시작합니다.

소규모 팀에서는 이 순서가 더 빠른 경우가 많습니다. 후속 단계에는 실제 base가 있고 guessed interface가 남지 않습니다. review 범위가 좁고 rollback도 쉽습니다.

첫날부터 돌리는 workflow

첫 주에 전체 개발 프로세스를 바꾸지 마세요. 낮은 위험 issue 하나를 고릅니다. human lead가 issue brief를 쓰고 경로를 선택합니다. implementer agent는 별도 branch 또는 worktree에서 작업합니다. verifier는 brief, changed files, handoff만 읽습니다. human reviewer는 semantic diff와 merge risk를 확인합니다. main에는 한 번에 하나의 branch만 들어갑니다. 남은 worktree는 계속하기 전에 main을 반영합니다.

모든 backlog를 모든 agent에게 주지 마세요. agent에게는 끝낼 수 있고 설명할 수 있고 넘길 수 있는 task만 줍니다. 산출물은 branch와 written artifact여야 하며, 출처를 알 수 없는 수정 묶음이어서는 안 됩니다.

첫 운영표에는 왜 separable한지, 누가 shared contract를 owns하는지, 금지 파일이 무엇인지, 검증 명령이 무엇인지, 실패하면 누구에게 돌아가는지, merge 순서가 어떻게 되는지를 적습니다. 이 질문에 답하지 못하면 아직 병렬화할 준비가 안 된 것입니다.

overlap을 막는 task brief

task brief는 workflow의 핵심 객체입니다. 두 agent가 서로 다른 문제를 조용히 풀지 못하게 하고, reviewer가 대화 기록을 뒤지지 않고 contract를 볼 수 있게 합니다.

md
Agent Task Brief

owner: agent-a
workspace: ../agent-a
branch: agent/a-checkout-state
goal: 주문 요약 컴포넌트에 checkout state를 추가한다.
non_goals:
- payment provider code를 바꾸지 않는다.
- database schema를 바꾸지 않는다.
allowed_files:
- src/features/checkout/**
- tests/checkout/**
forbidden_files:
- src/lib/payments/**
- db/migrations/**
- package-lock.json
interface_contract:
- 기존 OrderStatus 값을 사용한다.
- 새 status가 필요하면 멈추고 human lead에게 묻는다.
shared_state:
- local database migration 없음.
- test fixtures만 사용.
required_checks:
- pnpm lint
- pnpm test tests/checkout
handoff_required:
- changed files
- commands run
- proof or failing output
- known risks
- review focus
done_means:
- verifier가 checks를 재현하고 diff를 설명할 수 있다.

forbidden files는 형식이 아닙니다. schema, route map, lock file, env, public API, shared configuration을 지키는 boundary입니다. 금지 범위를 쓰지 못하는 task는 병렬화하기에는 너무 큽니다.

worktree 또는 branch로 격리한다

Git worktree는 같은 repository에 여러 working tree를 둡니다. 한 agent가 테스트를 실행하고 파일을 고쳐도 다른 agent의 checkout을 더럽히지 않습니다. 공식 문서는 메커니즘을 설명하지만, 팀에서 중요한 것은 어떤 directory, 어떤 branch, 어떤 command, 어떤 merge plan인지입니다.

bash
git switch main
git pull --ff-only
git worktree add ../agent-a -b agent/a-checkout-state
git worktree add ../agent-b -b agent/b-profile-copy
git worktree add ../verify -b verify/checkout-state
git worktree list

worktree는 source files를 격리하지만 모든 상태를 격리하지는 않습니다. database, ports, local services, secrets, package lock, CI runners, feature flags, public contracts에는 single owner가 필요합니다.

worktree를 쓸 수 없다면 clean checkout이나 branch도 됩니다. 진짜 요구사항은 workspace boundary와 merge plan입니다.

handoff는 채팅 밖에 남긴다

chat summary는 handoff가 아닙니다. verifier와 reviewer에게는 pull request, issue comment, branch 안의 짧은 handoff.md처럼 남는 artifact가 필요합니다. changed files, commands, proof, risks, review focus를 적습니다.

md
Agent Handoff

task: checkout state in order summary
owner: agent-a
branch: agent/a-checkout-state
changed_files:
- src/features/checkout/OrderSummary.tsx
- tests/checkout/order-summary.test.ts
commands_run:
- pnpm lint
- pnpm test tests/checkout
proof:
- checkout tests pass locally
known_risks:
- empty order state still uses existing fallback copy
review_focus:
- confirm OrderStatus mapping is complete
next_owner:
- verifier

verifier는 기본적으로 구현을 이어받지 않습니다. 먼저 brief 준수 여부를 확인합니다. allowed files, tests, interface contract, proof, risks가 핵심입니다. verifier가 같은 feature files를 다시 써야 한다면 첫 task brief가 너무 느슨했다는 signal입니다.

역할은 부담을 줄일 때만 추가한다

소규모 팀에는 큰 role taxonomy가 필요 없습니다. human lead, implementer, verifier, human reviewer로 시작하세요. specialist는 docs, tests, migration, investigation처럼 독립 흐름이 있을 때만 추가합니다.

lead가 모든 코드를 쓸 필요는 없지만 contract를 owns해야 합니다. 사람이 contract를 owns하지 않으면 agent가 각자 contract를 만들고, 그 차이가 나중에 conflict가 됩니다.

검증 gate와 merge queue

parallel work는 merge queue에 들어갈 때 product work가 됩니다. branch는 순서대로 merge하고, checks를 다시 실행하고, 남은 worktree는 매 merge 뒤 업데이트합니다.

bash
git switch main
git pull --ff-only
git merge --no-ff agent/a-checkout-state
pnpm lint
pnpm test
git push

cd ../agent-b
git fetch origin
git rebase origin/main

verification gate는 다섯 가지를 봅니다. diff가 allowed files만 바꾸는지, required checks가 기록됐는지, interface contract가 유지됐는지, handoff가 risks와 review focus를 쓰는지, 사람이 semantic change를 이해하는지입니다. AI review는 보조 pass입니다. semantics, security, data handling, merge responsibility는 사람에게 남습니다.

Codex, Claude Code, Cursor, framework의 위치

workflow shape를 먼저 정하고 tool을 고릅니다. Codex는 reviewable diffs, CLI, IDE, cloud tasks, PR-oriented flow에 맞습니다. Claude Code는 supervised local sessions, 복잡한 context, 세밀한 permission rules에 맞습니다. Cursor background agents, worktree wrappers, orchestration frameworks는 같은 process를 구현하는 surface입니다.

Codex와 Claude Code 선택 자체가 문제라면 별도 Claude Code vs Codex를 봅니다. Codex usage나 quota가 막는다면 OpenAI Codex usage limits를 봅니다. 이 workflow의 주인은 brand가 아니라 brief, workspace isolation, handoff, diff, verification, human merge입니다.

좋은 tool은 brief를 보존하고, workspace를 분리하고, diff를 보여주고, proof를 기록하고, reviewer가 merge를 멈출 수 있게 합니다. 이것이 안 되면 강한 모델도 작은 팀의 병렬화를 위험하게 만듭니다.

agent 수보다 review hour로 측정한다

agent 수는 약한 지표입니다. commit 수도 약합니다. 큰 diff를 만들 수 있어도 reviewer가 믿고 merge하지 못하면 효과가 없습니다. 소규모 팀에서는 accepted diff per review hour를 봐야 합니다.

표준화 전 두세 개 issue로 시험하세요. 좋은 single-agent baseline과 비교합니다. 2단계 pipeline이 cleaner tests, faster review, more accepted work per lead hour를 만들면 유지하세요. coordination cost가 더 크면 split을 줄입니다.

일주일 도입 계획

Day 1에는 낮은 위험 issue를 고르고 task brief와 하나의 implementer branch를 만듭니다. Day 2에는 verifier를 추가하되 구현 edit는 금지합니다. Day 3에는 sequential merge를 하고 review minutes를 기록합니다. Day 4에는 contract가 안정적일 때만 두 번째 implementer를 시도합니다. Day 5에는 accepted work, rework, conflicts, CI, review time을 비교합니다.

목표는 agent team이 멋지다는 것을 증명하는 것이 아닙니다. 소규모 팀이 더 짧은 lead time과 더 적은 rework로 reviewable code를 ship할 수 있는 최소 process를 찾는 것입니다.

자주 묻는 질문

가장 작은 안전한 workflow는 무엇인가요?

human lead, one implementer agent, one verifier agent입니다. implementer는 isolated workspace에서 scoped diff를 만들고 verifier는 brief, tests, allowed files, risks를 확인하며 human reviewer가 merge합니다.

두 명 팀도 여러 agent를 써야 하나요?

separable work라면 가능합니다. 다만 큰 agent team이 아니라 two-agent pipeline부터 시작하세요. lead가 diff와 handoff를 읽을 시간이 있어야 합니다.

Git worktree가 필수인가요?

필수는 아닙니다. worktree는 강한 default이지만 clean checkout이나 separate branch도 가능합니다. 진짜 요구사항은 workspace isolation과 merge plan입니다.

어떤 파일을 single-owner로 둬야 하나요?

schemas, migrations, package locks, env files, auth middleware, feature flags, public API contracts, shared route maps입니다. 예외는 human lead가 contract를 명시적으로 바꿀 때뿐입니다.

AI review가 human review를 대체할 수 있나요?

아니요. AI review는 syntax, tests, style, consistency를 돕습니다. semantics, product risk, security, data handling, merge responsibility는 사람이 책임집니다.

언제 여러 agent를 멈춰야 하나요?

같은 files가 필요하거나, interface가 움직이거나, reviewers가 따라가지 못하거나, CI가 같은 이유로 반복 실패하거나, accepted diff per review hour가 single-agent baseline보다 낮아질 때입니다.

Codex와 Claude Code는 어디에 쓰나요?

Codex, Claude Code, Cursor, worktree wrappers, orchestration frameworks는 같은 workflow의 implementation surface입니다. brief, workspace, diff, proof, review gate를 보존하는 것을 선택하세요.

소규모 팀은 동시에 몇 agent를 돌려야 하나요?

대부분은 one implementer plus one verifier를 먼저 증명해야 합니다. 세 agent는 scopes가 independent일 때만 가능합니다. 큰 agent team은 ownership, CI, merge queue, review capacity가 필요합니다.