team-dev

name	team-dev
description	팀 에이전트 병렬 개발 오케스트레이터. SubTask 목록을 의존성 분석 후 병렬 가능 그룹으로 분류하고, 팀원 에이전트가 git worktree 격리 환경에서 동시 구현한다. '/team-dev', '팀 개발', '병렬 구현', '팀으로 개발' 등 언급 시 호출
argument-hint	[Task 목록 또는 기능명] [--auto] [--dry-run]

Team Dev — 팀 에이전트 병렬 개발 오케스트레이터

$ARGUMENTS 에 대해 SubTask를 의존성 분석하고, 병렬 가능 그룹으로 분류한 후, 팀원 에이전트가 worktree 격리 환경에서 동시 구현한다.

ANALYZE → [ DISPATCH → BUILD → VERIFY → INTEGRATE ] × 그룹 → COMPLETE

---

전제 조건

• Git 저장소 필수 — worktree 격리를 위해 git init이 완료된 상태여야 한다
• SubTask 목록 필수 — SubTask 목록을 입력으로 받는다 ($ARGUMENTS에 있거나, 자연어 기능 설명에서 분리 가능해야 한다). 없으면 AskUserQuestion으로 요청한다
• 프로젝트 규칙 문서(선택) — CLAUDE.md 등 프로젝트 규칙 파일이 있으면 팀원 프롬프트의 컨텍스트로 주입한다
• 검증 스크립트(선택) — verify.sh·npm test·npm run build 등 프로젝트 검증 수단이 있으면 각 SubTask 완료 후 및 통합 시 실행한다 (없으면 정적 검증 단계를 생략한다)

---

Phase 0: PARSE — 인자 파싱

$ARGUMENTS에서 아래를 추출한다:

항목	추출 대상	기본값
SubTask 목록	TaskList 도구의 기존 목록 또는 자연어 기능 설명	(필수 — 없으면 AskUserQuestion)
--auto	그룹 간 자동 진행 여부	OFF (그룹 완료마다 확인)
--dry-run	의존성 분석 + 그룹 분류만 수행	OFF
--tdd	TDD RED 게이트 발동 (test-first 구현)	OFF
--no-tdd	TDD 제안·태그 모두 끔 (escape hatch)	OFF

TDD 의미론: 인터랙티브(--auto 없음)에서는 적격 SubTask에 [TDD]를 붙여 Phase 1-6 승인게이트에 제안 노출한다. --auto 단독이면 자동태그 OFF(전부 test-after), --auto --tdd면 적격 SubTask에 자동 부착(제안 생략), --no-tdd면 판단·제안 모두 끈다. 적격 기준과 절대제외는 아래 Phase 1-1-1 참조. team-dev는 git 필수라 RED 게이트의 실패테스트 선커밋 안전망이 항상 가용하다.

실행 모드 분기

모드	플래그	실행 방식
서브에이전트 모드 (기본)	없음	Agent 도구로 worktree 격리 병렬 spawn
에이전트 팀 모드 (experimental)	(Agent Teams 활성 시)	팀 리더가 팀원 인스턴스 생성, Task 할당, 코드 리뷰, 통합 검증

에이전트 팀 모드는 Claude Code의 experimental Agent Teams 기능이 활성화된 환경에서만 동작한다. 활성화돼 있지 않으면 기본 서브에이전트 모드로 진행한다. 상세는 phase-dispatch.md [B] 참조.

---

Phase 1: ANALYZE — 의존성 분석 및 그룹 분류

SubTask 수집 → 컨텍스트 수집 → UI/UX 설계 → 의존성 분석 → 그룹 구성 → 사용자 승인. 상세 절차는 phase-analyze.md 참조.

---

Phase 2: DISPATCH — 팀원 배포

그룹 내 각 SubTask를 팀원 에이전트에게 배포한다. 서브에이전트 모드(기본)와 에이전트 팀 모드(experimental) 두 가지 분기. 상세 절차 및 프롬프트 템플릿은 phase-dispatch.md 참조.

---

Phase 3: BUILD — 빌드 대기

run_in_background: true로 실행했으므로, 각 에이전트 완료 시 자동 알림을 받는다.

각 에이전트의 반환값을 수집한다:

• 성공: worktree 경로 + 브랜치명 + 수정 파일 목록
• 실패: 실패 사유 + 현재 상태

실패 처리:

상황	대응
1개 실패, 나머지 성공	실패한 SubTask만 팀 리더가 직접 수정
과반 실패	사용자에게 보고, 계획 재검토 제안
전체 실패	사용자에게 보고, 순차 구현 모드로 전환 제안

---

Phase 4: VERIFY — 통합 검증

worktree 코드 통합 → 통합 검증 → 그룹 완료 보고. 상세 절차(merge 충돌 해결, 2단계 검증)는 phase-verify.md 참조.

---

Phase 5: NEXT — 다음 그룹 진행

auto 모드 OFF 일 때:

사용자에게 진행 여부를 묻는다:

사용자 입력	동작
승인 / next	다음 그룹 Phase 2로 진행
--auto	auto 모드 ON — 남은 그룹 전부 자동 진행
수정 지시	수정 적용 후 Phase 4 재검증
stop	중단

auto 모드 ON 일 때:

• 즉시 다음 그룹 Phase 2로 진행
• Phase 4 FAIL 시 → auto 모드 자동 해제, 사용자에게 보고 후 대기

다음 그룹의 프롬프트에 이전 그룹의 완료된 코드(타입 정의, export 경로 등)를 컨텍스트로 반영한다.

---

Phase 6: COMPLETE — 최종 보고

모든 그룹 완료 시:

🎉 팀 개발 완료
══════════════════════════════════
Task:        {기능명}
총 SubTask:  {N}개 완료
병렬 그룹:   {M}개
══════════════════════════════════
→ 이후 커밋·PR·배포 워크플로우로 연결

응답 마지막에 ---DONE--- 블록을 포함한다.

---

순차 구현과의 역할 구분

병렬 개발이 항상 유리한 것은 아니다. SubTask 간 의존성이 높거나 규모가 작으면 순차 구현이 더 빠르고 안전하다.

항목	순차 구현	/team-dev (병렬)
실행 방식	SubTask 순차 구현	SubTask 병렬 구현
적합한 상황	SubTask 간 의존성 높음, 소규모	독립 SubTask 다수, 대규모
검증	SubTask마다 즉시 검증	개별 검증 + 통합 검증 2단계
권장 SubTask 수	2~5개	4개 이상 (병렬 이점)

SubTask 3개 이하 → 순차 구현 (더 빠르고 안전)
SubTask 4개 이상 + 독립성 높음 → /team-dev (병렬 이점)
SubTask 4개 이상 + 의존성 높음 → 순차 구현 (더 안전)

---

특수 인자

인자	설명
--auto	그룹 간 자동 진행 (FAIL 시 자동 해제)
--dry-run	의존성 분석 + 그룹 분류만 수행, 실제 구현 안 함
--tdd / --no-tdd	TDD RED 게이트 발동 / 완전 끔 (Phase 0 참조)

---

주의사항

• 팀원 에이전트는 할당된 SubTask의 파일만 수정한다.
• merge 충돌 자동 해결이 불확실하면 반드시 사용자에게 확인한다.
• 병렬 에이전트 수는 최대 5개로 제한한다.
• 이 스킬은 코드 구현 전용이다. 리서치·계획은 다른 워크플로우에서 수행한다. team-research가 함께 설치돼 있으면 사전 리서치에 활용할 수 있다.

---

Known Pitfalls

본 skill 실행 중 반복 발생한 실패 패턴. 신규 패턴 발견 시 entry를 추가한다.

(현재 누적 entry 없음.)

작성 형식

• [패턴명] — YYYY-MM-DD
  • 상황: 어떤 단계(SubTask 분리/병렬 실행/merge)·조건에서 발생
  • 원인: 무엇 때문에 실패 (worktree 충돌 / 의존성 misjudge / merge 충돌 등)
  • 회피: 다음 실행 시 적용할 가이드