웹, iOS, Android 작업을 세 에이전트에 동시에 넘기기 전에 Claude에게 공통 계약 파일부터 읽혀야 합니다. 플랫폼 화면은 나뉘어도 상태 타입과 JSON 픽스처가 겹치면 세 작업은 독립적이지 않습니다. 이 글의 예시 세션은 읽기 전용 서브에이전트로 의존성을 찾고, 선행 결정을 끝낸 뒤 Worktree 편집을 여는 순서로 진행합니다.

핵심 결과만 합치면 되는 조사·테스트·독립 모듈은 병렬화하고, 같은 상태를 바꾸거나 앞 단계의 결정을 기다려야 하는 일은 순차 처리합니다. 코드를 동시에 수정한다면 파일 소유권이나 Git 워크트리로 작업 공간을 분리해야 합니다.

나눌 수 있는 일과 나누면 안 되는 일. 여러 공식 문서 조사, 서로 다른 테스트 묶음, 파일이 겹치지 않는 플랫폼 작업은 병렬 처리하기 좋습니다. 반면 하나의 데이터 모델을 먼저 확정해야 하는 API와 화면, 같은 설정 파일을 고치는 여러 작업은 선행 결정을 마친 뒤 나누는 편이 낫습니다.

작업 설명에 담당 범위만 적지 말고 수정 금지 영역과 결과 형식을 함께 줍니다. 조사 작업은 근거와 불확실성을, 구현 작업은 변경 파일과 테스트 결과를 반환하도록 합니다.

서브에이전트와 독립 작업 공간의 차이. 서브에이전트는 메인 작업의 일부를 조사하거나 분석한 뒤 결과를 돌려주는 데 적합합니다. 같은 작업 트리를 공유한다면 여러 에이전트가 동시에 수정하지 않도록 해야 합니다.

독립 구현이 필요하면 별도 Git 워크트리와 브랜치를 사용합니다. 각 작업은 기준 커밋, 소유 파일과 통합 순서를 가져야 합니다. 작업이 끝난 뒤에는 개별 테스트뿐 아니라 통합된 상태에서 전체 회귀 검증을 다시 실행합니다.

병렬화가 실패하는 전형적인 이유. 요구사항이 확정되지 않은 채 여러 구현을 시작하거나, 모든 에이전트가 공통 파일을 고치거나, 결과를 합칠 담당자가 없는 경우가 많습니다. 겉으로는 동시에 진행되지만 마지막에 충돌과 중복을 정리하느라 더 오래 걸립니다.

과도한 병렬화는 컨텍스트와 비용도 늘립니다. 한 사람이 명확히 리뷰할 수 있는 작업 수와 통합 빈도를 기준으로 동시 작업 수를 제한합니다.

안전한 병렬 작업 계약. 각 작업에 목표, 기준 커밋, 읽을 자료, 수정 가능 파일, 금지 파일, 테스트와 반환 형식을 적습니다. 진행 중 발견한 공통 문제는 임의로 다른 영역까지 고치지 말고 통합 담당자에게 알립니다.

통합 단계에서는 커밋 차이, 중복 구현, API 계약과 테스트 격리를 확인합니다. 병렬 결과가 모두 통과해도 전체 사용자 흐름이 깨질 수 있으므로 최종 E2E와 운영 검증은 하나의 책임 아래 수행합니다.

먼저 읽기 전용 조사 세 개로 경계를 찾습니다. 예시 세션은 웹, iOS, Android가 있는 모노레포의 상태값 추가 작업입니다. 메인 세션은 Plan Mode에서 공통 지침과 계약 파일을 읽고, 플랫폼별 조사만 서브에이전트에 병렬 위임합니다.

병렬 구현 전에 복사할 첫 프롬프트
claude --permission-mode plan

루트 CLAUDE.md와 packages/contracts/status.ts를 먼저 읽으세요.
그다음 읽기 전용 서브에이전트 세 개로 apps/web, apps/ios, apps/android에서
delivery status가 표시되는 위치와 테스트 명령을 조사하세요.
수정하지 말고 각 결과를 다음 형식으로 합치세요.
- 읽은 파일
- 공통 계약 의존성
- 플랫폼 소유 파일
- 겹치는 파일
- 예상 검증 명령
공통 계약이 확정되기 전 구현은 금지합니다.

가상의 세 앱 작업은 공통 패키지에서 충돌할 수 있습니다. 웹, iOS, Android가 있는 모노레포에서 새 `delivery_status` 값을 표시하는 작업을 세 에이전트에 하나씩 맡겼습니다. 세 앱의 화면 파일은 겹치지 않았지만 모두 `packages/contracts/status.ts`에 같은 타입을 서로 다른 이름으로 추가했습니다. 개별 브랜치는 통과했으나 합칠 때 열거형과 직렬화 값이 충돌했습니다.

첫 분할은 플랫폼만 보고 의존성을 놓쳤습니다. 계약 타입을 먼저 한 명이 확정하고, 세 플랫폼은 그 커밋을 기준으로 시작해야 했습니다. 공통 계약을 선행 작업으로 옮기고 플랫폼 구현을 그 뒤에 병렬로 배치하자 충돌 범위가 사라졌습니다.

의존성 표가 에이전트 수를 결정합니다. 이 가상 프로젝트는 공통 계약을 먼저 확정하고 플랫폼 작업을 리뷰 가능한 수만큼 병렬로 엽니다. 리뷰어 한 명이 한 번에 명확히 확인할 수 있는 변경량도 동시 작업 수를 제한했습니다.

선행 결정과 파일 소유권을 드러낸 작업표
A 계약 확정 [먼저]
- 소유: packages/contracts/status.ts
- 산출물: 상태 값, JSON 예제, 계약 테스트

B 웹 표시 [A 뒤 병렬]
- 소유: apps/web/orders/**
- 금지: packages/contracts/**

C iOS 표시 [A 뒤 병렬]
- 소유: apps/ios/Orders/**
- 금지: packages/contracts/**

D Android 표시 [리뷰 용량상 C 뒤]
- 소유: apps/android/orders/**

통합 담당: 잠금 파일, 공통 계약, 전체 회귀

조사는 서브에이전트, 수정은 Worktree로 나눴습니다. 각 플랫폼에서 상태값이 쓰이는 위치를 찾는 조사는 읽기 전용 서브에이전트가 플랫폼별로 맡습니다. 긴 검색 결과는 각 컨텍스트에 남고 메인에는 파일 경로와 위험만 돌아왔습니다. 공식 문서상 서브에이전트는 별도 컨텍스트와 도구 제한을 가지며 결과를 부모 대화에 반환합니다.

가상 실행에서는 수정 작업을 별도 Worktree로 나눕니다. Claude Code의 현재 `--worktree` 기능은 격리된 체크아웃을 만들고, 서브에이전트에도 `isolation: worktree`를 설정할 수 있습니다. 다만 Worktree는 파일 편집만 나눕니다. 세 앱의 개발 서버 포트와 테스트 계정은 작업 계약에서 별도로 분리했습니다.

개별 통과 뒤 통합 실패를 예상해야 합니다. 예시 세션의 예상 결과는 플랫폼별 테스트가 통과해도 공통 JSON 픽스처에서 새 상태값 누락이 발견되는 장면입니다. 통합 담당자는 한 Worktree씩 변경을 가져오고 계약 테스트를 먼저 실행합니다. 실패하면 플랫폼 코드를 더 고치기 전에 공통 픽스처와 계약을 맞춥니다.

사람이 작업표를 승인한 뒤에는 “A의 계약 변경을 기준으로 B와 C를 별도 Worktree에서 구현하세요. 소유 파일 밖은 수정하지 말고 각자 테스트와 `git diff --check`를 실행하세요”라고 요청합니다. 통합 시에는 `git diff --stat`, `git diff -- packages/contracts apps`와 전체 회귀 명령을 확인합니다. 공통 계약이 작업 중 바뀌면 모든 구현을 중단하고 새 기준 커밋으로 다시 시작합니다.

병렬화를 중단해야 할 조건. 두 작업이 같은 파일을 수정하거나, 한 작업의 API 결정이 다른 작업의 입력이거나, 테스트가 하나의 변경 가능한 DB를 초기화한다면 그대로 병렬 실행하지 않습니다. 파일 소유권을 다시 나눌 수 없으면 순차 처리합니다. 에이전트 팀은 현재 실험 기능이며 Worktree 격리를 자동으로 보장하지 않으므로 팀원별 파일 경계가 특히 필요합니다.

2026년 7월 29일 공식 문서 기준으로 서브에이전트는 다른 서브에이전트를 생성하지 못하고, 병렬 세션 수만큼 사용량도 늘어납니다. 이 사례의 산출물은 네 작업 계약, 기준 커밋, 플랫폼별 테스트 결과와 통합 실패 기록입니다. 이 네 가지가 없으면 “동시에 끝났다”는 사실만으로 완료 판정을 내리지 않습니다.