← 플랜 파이프라인 개요
소비자 스킬

/parallel-plan

PLAN.md의 상호 의존이 없는 태스크를 에이전트 팀(팀원)으로 worktree에서 구현·커밋하고, 검증을 통과한 브랜치를 순차 ff-merge해 main에 직접 반영한다. 단, 병렬 이득이 작으면(독립·substantial 태스크 부족) 팀을 띄우지 않고 솔로로 폴백한다.

BashReadEditWriteGlobGrepAgentSendMessageTaskCreateTaskListTaskGetTaskOutputTaskStopTaskUpdate

PLAN.md(또는 PLAN_*.md, 여러 개면 최근 수정본)의 미완료 태스크 중 상호 의존이 없는 것들을 named 백그라운드 팀원(Agent + name + run_in_background: true)에게 배분해 각자 worktree 에서 구현·검증·커밋시키고, 성공한 브랜치를 base(보통 main)에 순차 fast-forward 머지한다. PR 은 만들지 않고, 태스크 사이에 사용자 확인도 묻지 않는다. PLAN 이 없으면 /make-a-plan 을 안내하고 중단한다. 팀 도구가 없으면(전제: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 + teammateMode) 서브에이전트 fire-and-collect 로 폴백한다.

독립 집합 추출 시 PLAN 에 실제 쓰인 태스크 ID 체계를 그대로 쓴다. 의존 판단: 표준 필드 의존: 이 있으면 그 값만 쓴다(의존: 없음 이면 의존 없음 확정). 표준 필드가 없는 구식 플랜에서는 본문의 의존 표기(Depends on:, 선행: 등)를 쓰되, 명시가 없어도 절차상 직전 태스크 산출물을 명백히 전제로 하는 경우만 의존으로 간주한다(/sub-follow-plan 과 동일 규칙). dependencies 가 비었거나 모두 DONE 인 미완료 태스크가 이번 라운드 대상이다.

병렬 적합성 게이트

병렬은 공짜가 아니다. 실측(이 머신 전사 분석): 팀원은 리드 대화를 상속받지 못해 컨텍스트를 cold 로 재구성하고, 3\~5명을 띄워도 실효 동시성은 약 1.8x(최악 0.73x, 직렬보다 느림), 토큰은 단일 에이전트 대비 3\~10배다. 따라서:

·substantial 독립 태스크 ≥ 2개(팀원 cold-start 를 상쇄할 만큼 큰 것 — 다파일·신규 구현·리팩터급)일 때만 팀을 띄운다. 사소한 태스크(단일 파일·기계적 수정)는 팀원에 끼우지 말고 리드가 인라인 처리한다.
·아니면 솔로 폴백(직접 순차 처리 또는 /sub-follow-plan). 폴백 이유를 한 줄 보고하고 진행한다.
·위 수치는 opus/sonnet 팀원 실측이라 보수적이다. 팀원이 상위 모델(Fable 등)로 돌 때는 cold-start 페널티가 낮으므로 문턱을 한 단계 낮춰 병렬을 더 적극 채택해도 된다.

디스패치

1태스크=1팀원 기본, 팀 규모는 min(태스크 수, 5) — 많으면 팀원당 여러 태스크를 순차(각각 별도 worktree·브랜치)로 처리시킨다. 같은 파일을 건드릴 가능성이 큰 태스크들은 같은 팀원에게 묶어 직렬화한다. 분해는 항상 컨텍스트 경계 기준 — 한 태스크의 구현/테스트/리뷰를 여러 팀원에 나누면 핸드오프마다 컨텍스트가 유실되므로 한 팀원이 완결한다. 디스패치 전 TaskCreate 로 태스크보드에 등록한다.

팀원 모델: 호출 시 지정이 없으면 model: "opus" 를 기본으로 명시한다(가벼운 태스크는 sonnet) — 리드가 상위 모델(Fable 등)로 돌아도 팀원에게 상속시키지 않기 위함(2026-07-05 사용자 지시). 특별히 무거운 태스크만 리드 재량으로 그 태스크에 한해 올린다.

팀원 프롬프트에는 MAIN_PATH·BASE_BRANCH·TASK_ID·PLAN 발췌·경로안전 TASK_SLUG(영문/숫자/하이픈/언더스코어 외 _ 치환)를 넣고 다음을 지시한다:

·worktree 생성: git -C {MAIN_PATH} worktree add -b task/{TASK_SLUG}_{slug} {MAIN_PATH}/../{REPO_NAME}__{TASK_SLUG} {BASE_BRANCH}, 이후 모든 git 은 git -C <worktree> 로.
·정의·참조·테스트를 먼저 읽고 구현. 한국어 커밋 [{TASK_ID}] 요약. PLAN.md/AGENTS.md/README.md 수정 금지 — 메타 파일은 리드가 머지 단계에서 일괄 처리한다(충돌 방지).
·스택에 맞는 검증(typecheck/lint/build/test)을 모두 통과시킨다. --no-verify 등 안전 우회 금지.
·RESULT 블록(task/status(success|failed)/branch/worktree/commit/checks/failure_context)을 SendMessage 로 리드에게 보고. checks 에는 이번 세션에서 실제 실행한 명령과 결과만 적고, 못 돌린 검증은 그렇다고 명시한다 — 안 돌린 검증을 통과로 적지 말 것.
·사용자에게 묻지 말고(막히면 리드에게), worktree·브랜치를 직접 정리하지 말고, 실패해도 부분 커밋을 그대로 두고, PR 생성 금지.

failed 보고는 1\~2회 SendMessage 로 진단·재시도를 코칭하고, 그래도 실패하면 블록 처리한다. 무응답 팀원은 TaskGet/TaskOutput 확인 후 필요시 TaskStop.

머지 · 보고

팀원 자기보고를 그대로 믿지 않는다: 브랜치·커밋 SHA 가 실제 존재하는지 확인하고, 위험이 큰 태스크는 머지 전에 fresh-context 검증자 서브에이전트를 띄울 수 있다(선택). 검증자는 블랙박스로 — worktree 경로·diff·PLAN 에서 뽑은 체크 가능한 성공 기준·검증 실행법만 주고, 팀원의 구현 서사·failure_context 는 넘기지 않는다. 전체 검증 스위트를 실제 실행한 결과만 판정 근거로 인정하고, 가능하면 negative 확인(기준을 위반하는 입력이 실제로 실패하는지) 1개 이상.

success 브랜치만 태스크 순으로 한 건씩: base ff-pull → merge-base --is-ancestor 로 ff 가능성 확인, 불가면 worktree 에서 rebase. 충돌이 PLAN.md 뿐이면 append-only 로 해소(양쪽 진행 로그 시간순 보존, 같은 태스크 상태 라인은 완료>진행>TODO 로 통합), 그 외 파일 충돌은 rebase --abort 후 블록 처리하고 다음으로. 머지는 cwd 가 base 브랜치 디렉터리인지 확인 후 merge --ff-only → push origin {BASE_BRANCH} → push github {BASE_BRANCH} 2>/dev/null || true → worktree remove + 브랜치 삭제. 머지마다 메인의 PLAN.md 에 완료·머지 SHA 를 기록하고 즉시 커밋·푸시한다(다음 rebase 충돌 면적 축소).

실패·블록 태스크는 머지하지 않고, worktree·브랜치를 사용자 진단용으로 남기며, PLAN.md 진행 로그에 자동 실행 실패: <한 줄> 을 append 한다(상태는 TODO 유지).

최종 보고: 성공/실패/블록 수, 머지된 태스크(ID·제목·SHA), 실패 태스크와 진단, 이번 머지로 의존이 풀린 다음 라운드 후보. 후보가 있으면 "다시 /parallel-plan 을 실행하면 처리됩니다" 로 안내한다(자동 재실행 금지).