문서 목차
이 페이지에서목차

/cc-dev:go — 말만 하면 머지까지, 원스톱 파이프라인

원스톱 파이프라인 — 자연어 요청 하나로 브레인스토밍→이슈 계층 생성(Initiative/Project/Epic/Story)→계획 승인(단일 게이트)→구현→PR 머지까지 자동 진행

항목내용
실행 명령/cc-dev:go
분류워크플로우
난이도●●● 높음
MCP 서버zenhub, sequential

한마디로#

"이런 거 만들어줘" 한 마디를 던지면, 아이디어 정리 → ZenHub 일감 생성 → 작업 계획 → 개발 → 테스트 → PR → 머지까지 전부 자동으로 이어서 진행하는 최상위 명령입니다. 중간에 사람에게 확인받는 지점은 딱 한 번 — "이 계획대로 끝까지 진행할까요?" — 뿐입니다. 승인하면 그 뒤로는 머지와 이슈 종료까지 손댈 일이 없습니다. 예외는 하나입니다 — 같은 원인으로 두 번 연달아 막히면 남은 일감을 계속 태우지 않고 멈춰서, 공통 원인 한 줄과 다시 시작하는 방법을 알려드립니다.

누가·언제 쓰나요#

  • 요구사항 한 줄(또는 기획 문서, 화면 캡처)만 있고, 이슈 만들기부터 머지까지 전 과정을 자동으로 돌리고 싶을 때
  • /cc-dev:zenhub:breakdown → /cc-dev:batch → /cc-dev:run 을 매번 손으로 이어 붙이는 게 번거로울 때
  • 규모를 미리 모를 때 — 작은 버그면 이슈 하나로, 큰 개편이면 Initiative/Project/Epic 계층으로 알아서 스케일을 맞춰 진행합니다

새 풀스택 제품을 빈 저장소에서 시작한다면 먼저 cc-product-auto:product-autopilot의 PRD→CoUI Figma→cob generate→구현→배포 계약으로 라우팅한다. 이 경로는 CoUI Web/Jaspr 제품 사이트, CoUI Flutter 앱·콘솔, Serverpod 백엔드와 Widgetbook의 실제 생성·빌드 증거를 요구한다. /cc-dev:go의 이슈→PR 루프만으로 초기 스캐폴드나 사이트 배포를 성공으로 간주하지 않는다. 제품의 기본 저장소·셸이 생성된 이후 기능 추가부터 이 명령의 이슈/머지 루프를 사용한다.

무엇을 해주나요#

  • 아이디어 정리(브레인스토밍) — 요청이 크거나 모호하면 구조화된 브레인스토밍으로 목표·범위·후보 Epic을 먼저 정리합니다 (작은 요청이면 건너뜀)
  • 이슈 계층 자동 생성 — /cc-dev:zenhub:breakdown 의 규모 추론을 그대로 사용해 Initiative → Project → Epic → Feature/Bug/Task → Sub-task 중 알맞은 범위만 만듭니다. Epic 타임라인은 팀의 최근 실측 스프린트 속도로 산출하고, 여러 Epic을 함께 만들 때는 서로 의존이 없는 것끼리 병렬로, 의존이 있으면 순차로 배치합니다(/cc-dev:zenhub:breakdown Step 2.5 그대로 재사용 — 여기서 새로 만들지 않습니다)
  • 단일 계획 승인 게이트 — 만들 일감 목록, 우선순위, 실행 순서, "이후 머지까지 자동" 정책을 한 화면으로 보여주고 한 번만 확인받습니다
  • 자동 실행 루프 — Epic 은 /cc-dev:batch, 단독 이슈는 /cc-dev:run 으로 우선순위 순서대로 처리하고, PR 머지·이슈 Close·상위 계층 재귀 종료까지 자동으로 마칩니다
  • 디자인 판단도 멈추지 않고 결정 — 색·간격·상태 동작·피드백 방식·문구·입력 포맷처럼 기획서에 안 적힌 디자인 판단은 cc-designer 의 의사결정 프로토콜(design-decision)로 근거를 찾아 확정하고, 왜 그렇게 정했는지를 결정 기록(DDR)으로 남깁니다. 되묻지 않습니다
  • 리뷰 자료까지 — PR 을 만들기 전에 작업내역을 HTML 문서로 커밋해 PR 본문에 연결하고, CI 는 끝까지 기다려 통과를 확인합니다. 검사 결과는 PR 화면의 체크가 보여 주므로 문서에 옮겨 적지 않습니다 (run.md Step 9·10.5).
  • 품질 게이트는 그대로 — 테스트 실패·lint·리뷰 Critical 은 여전히 하드 게이트입니다. 자동화되는 것은 "사람의 승인 클릭"이지 "품질 기준"이 아닙니다
  • 같은 원인으로 두 번 연달아 실패하면 멈춥니다 — GitHub 인증 만료, 오래된 서브모듈처럼 모든 일감이 똑같이 걸릴 원인은 한 건마다 다시 지불할 이유가 없습니다. 연속 2건이 사실상 같은 원인이면 큐를 세우고 공통 원인 + 재개 명령을 보고합니다. 원인이 서로 다른 실패 2건은 예전처럼 다음 일감으로 넘어갑니다
  • 다른 세션이 잡고 있는 일감은 건너뜁니다 — 여러 창에서 동시에 돌려도 같은 일감을 두 번 하지 않습니다. 건너뛴 항목은 "누가 잡고 있는지"와 함께 따로 보고되며, 실패 목록에 섞이지 않습니다 — 고칠 것이 없고 상대가 끝나면 다시 돌리면 되는 항목이기 때문입니다
  • 막힌 일감에 기댄 후속 작업은 건너뜁니다 — "우선순위가 뒤"인 것과 "앞 결과가 있어야 하는" 것은 다른 얘기입니다. 앞 Epic 이 미완이면 그 결과를 쓰는 후속 작업은 없는 기반 위에서 억지로 돌리지 않고 건너뜀(SKIPPED-BLOCKED) 으로 표시해 보고합니다
  • 머지되면 작업 공간도 치웁니다 — 그 일에 연 워크트리는 머지 확인 직후 자동으로 정리·삭제합니다. 아직 안 합쳐진 작업과 막힌 작업은 지우지 않습니다. 이 세션이 돌고 있는 워크트리는 최종 보고를 남긴 뒤에만 지웁니다

어떻게 쓰나요#

# 가장 기본 — 한 줄 요청으로 끝까지
/cc-dev:go "저자 팔로우 기능 추가"

# 화면 캡처와 함께 (breakdown 이미지 분석 경로 사용)
/cc-dev:go "커뮤니티 게시판" --images "list.png,detail.png,form.png"

# 이슈 생성까지만 하고 실행은 보류
/cc-dev:go --plan-only "결제 환불 플로우 개편"

# 머지 전마다 승인받는 보수 모드 (기존 /cc-dev:run Step 12 게이트 유지)
/cc-dev:go --gated "정산 로직 리팩터링"

# 승인 클릭 없이 진행 (CI/무인 환경용 — 병렬 착수는 승인 없이 늘리지 않고 순차로 내려감)
/cc-dev:go --auto "로그인 버튼 오타 수정"
옵션기본값설명
--plan-only off Phase C(계획 승인)에서 멈추고 이슈만 남김. 나중에 /cc-dev:batch / /cc-dev:run 으로 이어감 — 긴 기획 설명(상세 기획 HTML)은 그동안 로컬에만 있다가 그때 작업 브랜치에 커밋되고 이슈에 링크가 붙습니다
--gated off 머지 사전승인 없이 진행 — PR 머지마다 기존 승인 게이트가 다시 살아남 (디자인 판단은 이 모드에서도 되묻지 않습니다 — 머지 게이트와 별개)
--auto off 승인 클릭만 생략(계획 게이트 + 머지 승인). "답할 사람이 없다"는 선언( --unattended )이 하위로 전파되므로, 작업 공간을 늘리는 스폰 승인이 필요한 자리는 승인 없이 늘리지 않고 순차로 내려감 ( --no-parallel ). MAJOR-DRIFT 등 방향 이탈 경고는 그대로 남음 (상세: D-3 ⑥)
--no-brainstormoffPhase A 브레인스토밍 강제 생략 (규모와 무관)
--wrapoff전체 완료 후 /cc-dev:session:wrap 자동 실행
--keep-worktrees off 머지된 Orca 워크트리를 지우지 않고 남긴다. /cc-dev:batch 로 전달되며, 세션 워크트리 회수(E-5)도 건너뛴다
(그 외) — --images / --sprint / --labels 등 breakdown 옵션, --skip-* 등 run 옵션은 각 하위 단계로 그대로 전달

안에서 무슨 일이 벌어지나요#

  1. 규모 감지 & 아이디어 정리 (Phase A) — 요청을 읽고 규모·모호함을 판단합니다. 크거나 모호하면 브레인스토밍(SCAMPER 등)으로 목표/범위/후보 Epic을 정리하고, 작으면 PM 정제(pm-spec-agent)만 거칩니다. 화면 작업이면 완료 기준을 막는 디자인 판단을 여기서 미리 확정합니다(cc-designer 의사결정 프로토콜).
  2. 이슈 계층 생성 (Phase B) — /cc-dev:zenhub:breakdown 프로토콜로 규모에 맞는 계층을 만들고, 생성된 이슈 번호 지도를 확보합니다.
  3. 계획 승인 (Phase C — 유일한 게이트) — 계층/우선순위/실행 순서/머지 정책을 요약해 보여주고 "끝까지 진행할까요?"를 묻습니다. 미리 확정한 디자인 결정도 여기서 한 번에 보여드립니다 — 새 질문이 아니라, 이미 내린 결정의 열람입니다.
  4. 자동 실행 (Phase D) — Epic 우선순위 순서대로 /cc-dev:batch, 단독 이슈는 /cc-dev:run에 위임합니다. 구현 중 디자인 판단은 Step 7.1이 기록하고, 작업내역은 PR 생성 시 HTML 로 커밋해 본문에 연결하며, Step 10.5 는 CI 를 기다려 판정합니다. 품질 게이트 통과 후 사전승인된 머지·Close를 수행하고, 머지된 자식 워크트리는 그 자리에서 회수합니다.
  5. 최종 보고 (Phase E) — 머지된 PR, 닫힌 이슈, 원인별로 묶은 미완·건너뜀 항목, 내려진 디자인 결정(재검토 표시 포함), PR별 작업내역 문서 경로를 한눈에 보고하고, 요청 시 세션을 마무리합니다. 보고를 PR·이슈에 적은 뒤, 이 세션의 워크트리를 회수합니다. 진행 상황은 보고 시점에 처음 적히는 게 아니라 일감이 끝날 때마다 PR·이슈에 남으므로, 워크트리를 지워도 어디까지 됐는지는 사라지지 않습니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Design Principle#

이 커맨드는 새 로직을 거의 갖지 않는 오케스트레이터다. 각 Phase 는 기존 커맨드/에이전트의 프로토콜을 그대로 재사용하며, /cc-dev:go 가 새로 추가하는 것은 다음 세 가지뿐이다:

  1. 체이닝 — breakdown 출력(이슈 번호 지도)을 batch/run 입력으로 넘기는 접착제, 그리고 각 PR 이 Step 9 에서 본문에 남긴 작업내역 경로를 Phase E 로 모으는 집계
  2. 게이트 통합 — 하위 단계에 흩어진 사람-승인 게이트를 Phase C 한 곳으로 모으고, 이후 단계에는 merge pre-authorization 을 전파
  3. 실행 순서 — P0 → P1 → P2, Epic → 단독 이슈 순의 결정적 실행 큐

절대 하지 말 것: breakdown 의 스케일 추론이나 run/batch 의 13단계 사이클을 여기 복제하는 것. 항상 해당 문서를 참조·재사용한다. 디자인 의사결정 역시 판정 로직을 여기 복제하지 않는다 — SoT 는 cc-designer 의 design-decision 스킬이고, /cc-dev:go 는 어느 Phase 에서 그것을 부르는지와 결과를 어디에 실어 보내는지만 정한다.

Non-Interactivity Invariant (디자인 판단은 게이트를 늘리지 않는다)#

이 커맨드의 사람-게이트는 Phase C 하나다. 디자인 판단이 그 수를 늘리지 않는다:

무엇어디서 결정사람에게 묻는가
스펙·AC 를 막는 디자인 판단Phase A-5 (design-decision)❌ — DDR 로 확정, Phase C 요약에 열람용으로 실림
구현 중 발생하는 디자인 판단Phase D → run.md Step 7.1❌ — DDR 로 확정, PR body 에 기록
브랜드 정체성 / 법·정책 / 비가역 / R0 충돌발생 지점✅ — 권고안 1개 + 근거 제시 후 확인 (design-decision 에스컬레이션 4종)

--gated 는 머지 게이트만 되살린다. --auto 라도 위 4종 예외는 그대로 확인을 받는다 (MAJOR-DRIFT 취급과 동일 원칙).

--auto 가 생략하는 것은 승인 클릭이며 스폰 승인 권한이 아니다 — 병렬 스폰 계획 승인은 머지 승인과 다른 대상이므로 사전 승인도 --auto 도 덮지 못한다(D-3 ⑥). 무인 환경에서 답할 사람이 없으면 그 자리는 승인 없이 스폰하지 않고 순차로 강등된다. 즉 --auto 는 게이트 수를 0으로 만드는 플래그가 아니라, 사람이 없을 때의 선언된 강등 경로를 켜는 플래그다.

Phase A: Scale Detection & Ideation#

A-0. 그린필드 풀스택 요청(빈 제품 저장소, 사이트+앱+Serverpod 생성)이면
     cc-product-auto:product-autopilot의 다섯 단계로 라우팅한다. 그 스킬의
     사이트 포함 4-surface/백엔드 검증이 완료되기 전에는 go의 Phase B/D를
     성공으로 보고하지 않는다. 기존 제품에 기능을 추가하는 경우만 아래로 계속한다.
A-1. 요청 파싱 — 자연어 요청 + 전달 옵션 분리. Figma URL/이미지는 breakdown 으로 전달할 목록에 보관.
A-2. 규모 사전 판단 (LLM-SEMANTIC) — breakdown Step 1.5 "Hierarchy Scale Inference" 와 같은 신호를
     가볍게 선판정: {no-epic | epic | project | initiative} + ambiguity {low | high}
     - 규모는 먼저 반사 판정(`cc-dev:jev-reflex` 세트 `scale`)에 묻는다: reflex 면 그 규모를 쓰고, deliberate 면
       Claude 가 규모를 정하면서 **ambiguity=high** 로 둔다(신뢰도가 낮다는 것 자체가 요청이 모호하다는 신호다).
       ⚠️ reflex 라고 ambiguity 를 low 로 두지 않는다 — 모호성 판단은 여전히 Claude 의 것이다(규모가 분명해도 목표가
       모호할 수 있다). unavailable(0·4 가 아닌 종료 코드)이면 이 판정 없이 예전처럼 판단한다.
A-3. 브레인스토밍 (조건부):
     - 조건: 규모 ≥ project 또는 ambiguity=high, 그리고 --no-brainstorm 미지정
     - 방법: cc-product:creative-intelligence 스킬 프레임(SCAMPER/역발상 중 택1)을 **비대화형**으로 적용
       → 산출: 목표 1문장, In/Out 범위, 후보 Epic 목록(이름+한 줄), 리스크 3개 이하
     - 결과는 Phase B 의 breakdown 입력(요구사항 텍스트)으로 합쳐진다. 파일로는 남기지 않는다
       (breakdown 이 .claude/docs/{feature}/ 문서화를 담당).
A-4. 소규모 경로: 규모 ≤ epic 이고 ambiguity=low 면 브레인스토밍 없이 pm-spec-agent 정제만 거친다
     (agents/dev/pm-spec-agent.md — 비대화형, 가정은 기록하고 진행).
A-5. 디자인 판단 선확정 (screen 계열 요청일 때만):
     - 조건: 요청이 화면·UI 를 포함하고(A-2 의 같은 요청에서 `involves_ui` 가 reflex true 거나, 애매하면
       Claude 판단), AC 를 쓰려면 결정이 필요한 디자인 질문이 남아 있을 때
       (빈 상태·에러 처리 방식·입력 포맷·상태 동작·문구 등 — 시안/스펙에 답이 없는 것)
     - 방법: cc-designer `design-decision` 프로토콜을 각 질문에 적용 (근거 사다리 R0→R5).
       R2(코드 선례 전수 조사)를 반드시 수행한다 — 저장소에 이미 답이 있는 질문을 새로 결정하지 않기 위함.
     - 산출: DDR 목록. **AC 에 흡수시킨다** — "가정(Assumption)" 이 아니라 근거가 붙은 결정으로 이슈 본문에 들어간다.
       (pm-spec-agent 의 assumptions 는 디자인 외 영역에만 남는다)
     - 에스컬레이션 4종에 해당하는 질문만 권고안 1개 + 근거와 함께 확인을 받는다.
     - 결정 0건도 정상 — 시안이 이미 답했다면(R1) DDR 을 만들지 않는다.

브레인스토밍도 pm 정제도 AskUserQuestion 금지 (pm-spec-agent 의 Non-Interactivity Rule 준용). A-5 의 디자인 결정도 동일하다 — 에스컬레이션 4종을 제외하면 되묻지 않는다. 사람이 개입하는 곳은 Phase C 하나다.

Phase B: Issue Hierarchy Creation (breakdown 재사용)#

B-1. /cc-dev:zenhub:breakdown 프로토콜 실행:
     - 입력: Phase A 산출(정리된 요구사항 텍스트 + A-5 DDR 목록) + 전달 옵션(--images, --sprint, --labels 등)
       DDR 은 해당 Epic/Story 본문의 AC 로 내려간다 — 구현 단계가 같은 판단을 다시 하지 않게 한다
     - breakdown Step 1.5(스케일 추론) + Step 1.6(우선순위 표)의 "사용자 확인"은 /cc-dev:go 안에서는
       즉시 확정하지 않고 **Phase C 통합 게이트로 이월**한다 — 같은 내용을 두 번 묻지 않기 위함.
       (--auto 모드에서는 추론 결과를 그대로 채택)
B-2. 생성 결과 캡처 — issueMap:
     { initiative?: #, project?: #, epics: [{number, title, priority, children: [#…]}], standalone: [#…] }
     breakdown 출력 로그의 이슈 번호를 파싱하지 말고, 생성 시점에 반환된 id/number 를 직접 축적한다.
B-3. 상세 기획 HTML 은 **로컬 대기 파일**로 남는다 — breakdown 이 `.claude/docs/{scope}/issue-{n}.html` 을
     쓰지만 커밋할 브랜치가 아직 없다. Phase D 의 batch/run 이 각 이슈의 작업 브랜치를 만들 때 첫
     커밋으로 넣고 이슈 본문에 링크를 붙인다(`rules/artifact-publishing.md` §6). 그래서 Phase D 는
     Phase B 와 **같은 체크아웃**에서 시작한다 — 병렬 워크트리로는 batch 가 파일을 옮겨 준다.

Phase C: Unified Plan Gate (유일한 사람-게이트)#

C-1. 요약 출력: 계층 트리(이슈 번호·타입·포인트) + 우선순위 근거 표 + 실행 큐(순서) + 머지 정책
     + A-5 디자인 결정 요약 (DDR id · 결정문 · R번호 · 신뢰도). `신뢰도: low` 는 ⚠️ 로 표시한다.
     ⚠️ 이것은 승인 요청이 아니라 **열람**이다 — 결정별로 확인을 받지 않는다.
     (사용자가 이 요약을 보고 특정 결정을 뒤집고 싶으면 [게이트 유지하며 진행] 을 고르거나
      해당 이슈에서 별도로 지시하면 된다 — 새 질문을 만들지 않는 것이 이 Phase 의 계약이다)
C-2. AskUserQuestion (단일 질문):
     "이 계획대로 PR 머지까지 자동 진행할까요?"
     - [원스톱 진행] — 이후 모든 머지 pre-authorized (기본 권장)
     - [이슈만 남기고 중단] — --plan-only 와 동일하게 종료, 재개 방법 안내
     - [게이트 유지하며 진행] — --gated 와 동일: 실행은 하되 PR 머지마다 승인
C-3. --auto: 이 게이트를 생략하고 [원스톱 진행] 으로 간주. --plan-only: C-2 를 [이슈만 남기고 중단] 으로 강제.

Phase D: Execution Loop (merge pre-authorization 전파)#

D-1. 실행 큐 구성: epics를 priority(P0→P1→P2) → 생성 순으로 정렬, 그 뒤에 standalone 이슈(P0→P2).
     이 정렬은 **실행 순서**만 정한다 — 우선순위는 의존성이 아니다(D-2.5). 기질은 그대로
     **순차 큐**다(`rules/orchestration-graph.md` §4: 머지는 항상 직렬 · "순차/변경 없음" 이 기본값).
     여기서 팬아웃을 새로 만들지 않는다 — 병렬은 batch 안쪽에서만, 승인과 width cap 아래서 일어난다.
D-2. for epic of queue.epics:
       /cc-dev:batch {epic.number} --merge=pre-authorized
       - batch Phase 3(Epic PR 최종 승인)도 pre-authorized 로 자동 머지
       - Story BLOCKED('unstuck_exhausted') 발생 시: Epic 은 batch 의 Stall Budget 계약대로 계속 진행,
         Phase 3 완료성 Hard Gate 가 OPEN child 를 감지하면 그 Epic 은 [INCOMPLETE] 로 기록하고
         **다음 Epic 으로 계속** (전체 파이프라인 중단 금지 — 예외는 D-2.5 의존 후속과
         D-2.7 회로 차단 둘뿐이며, 그 둘도 "품질 게이트를 낮추는" 예외가 아니다)
     for issue of queue.standalone:
       /cc-dev:run {issue} --merge=pre-authorized
D-2.5. Dependency Invariant — **우선순위는 의존성이 아니다**:
     - [INCOMPLETE] 인 Epic 의 산출물에 의존하는 후속 Epic/이슈는 착수하지 않고
       `[SKIPPED-BLOCKED: blockedBy #N]` 으로 기록한다. 의존 축은 새로 정의하지 않는다 — breakdown
       Step 2.5(`rules/zenhub-conventions.md` → "Epic Dependency & Parallel Scheduling")가 생성
       시점에 `createBlockage` 로 남긴 실제 엣지가 있으면 그것을 우선 조회하고, 그 Epic 이 이 방식
       으로 만들어지지 않아 엣지가 없으면 우선순위 스코어링의 "Dependency (blocker)" 축을 대신 쓴다.
       그 축의 판단은 `cc-dev:jev-reflex` 세트 `depends-on`(`a` = [INCOMPLETE] 인 Epic, `b` = 착수 후보)에
       먼저 묻는다 — reflex true 면 의존, reflex false 면 의존 없음, deliberate·unavailable 이면 예전처럼
       Claude 가 판단하고 그래도 판정할 수 없으면 아래 규칙대로 판정 불가다.
     - 이유: 없는 base(머지되지 않은 상위 브랜치·생성되지 않은 Entity/API) 위에서 착수하면
       빈 diff PR · 잘못된 base · **거짓 완료**가 만들어지고, 그 뒤 게이트가 그걸 통과시킨다.
     - 의존 여부를 판정할 수 없으면 통과가 아니다 — 순차/안전 쪽으로 기울여 [SKIPPED-BLOCKED] 로
       남긴다(`rules/orchestration-graph.md` §3: undetermined 의 기본값은 fail).
     - 의존이 없는 형제는 영향받지 않는다 — 그대로 다음 항목으로 계속한다.
     - [SKIPPED-BLOCKED] 는 실패가 아니라 **미착수**다: 재개 명령은 blocker 를 해결한 뒤의
       `/cc-dev:batch {n}` / `/cc-dev:run {n}` 이며, D-2.7 의 연속 실패 카운트에 포함하지 않는다.
D-2.6. Occupancy Invariant — **미착수와 실패를 섞지 않는다**:
     - 하위 호출이 `[INCOMPLETE: issue_occupied]` 로 돌아오면(그 이슈를 다른 세션이 잡고 있다는
       뜻 — `commands/run.md` Step 0.4 · `rules/zenhub-conventions.md` → Work Claim Contract),
       그 항목을 `[SKIPPED-OCCUPIED: heldBy {owner}]` 로 확정하고 **다음 항목으로 계속**한다.
     - **[SKIPPED-BLOCKED] 와 구분한다** — 앞은 "선행 결과가 없다", 이쪽은 "지금 남이 하고 있다".
       사용자 행동이 다르다: 전자는 blocker 를 해결해야 하고, 후자는 **상대 세션이 끝나기를 기다리면
       된다**(또는 상대가 죽었으면 TTL 경과 후 자동 인수된다). 한 통에 담으면 고칠 것이 없는 항목을
       고치라고 보고하게 된다.
     - 보드도 대장도 **건드리지 않는다** — 남의 점유다. 우리 쪽 기록은 큐 상태와 Phase E 보고뿐이다.
     - D-2.7 의 연속 실패 카운트에 **포함하지 않는다**([SKIPPED-BLOCKED] 와 동일 — 실패가 아니라 미착수).
       ⛔ 이것을 실패로 세면, 큰 병렬 세션 하나가 도는 것만으로 회로 차단이 걸려 남은 큐가 통째로 멈춘다.
D-2.7. Circuit Breaker (contract:go.phaseD-execution-queue — 값은 아래 "Loop Contract" 에 있다):
     - causeKey: 하위 호출이 보고한 `[INCOMPLETE: <reason>]` 슬러그를 그대로 쓴다
       (`commands/batch.md` → "Unattended & Approval Contract": `issue_not_found` ·
       `children_blocked` · `merge_approval_unavailable` 등). ⛔ `issue_occupied` 는 예외다 —
       실패가 아니라 미착수이므로 causeKey 로 세지 않는다(D-2.6). 슬러그가 없는 실패는
       도구/환경 층위로 정규화한다(예: `gh_unauthenticated` · `stale_submodule` · `base_missing`).
       정규화는 반사 판정(`cc-dev:jev-reflex` 세트 `failure-cause`, 실패 출력 꼬리를 `failure` 로)에 먼저 묻는다:
       - **환경·도구 키**(`gh_unauthenticated` · `stale_submodule` · `base_missing` · `network` · `rate_limited`)는
         큐의 모든 항목이 똑같이 걸리는 원인이라 reflex 답을 그대로 causeKey 로 쓴다.
       - **증상 키**(`tests_failed` · `lint_failed` · `build_failed` · `dependency_resolution` · `merge_conflict`)는
         원인이 아니라 증상이다 — 서로 무관한 테스트 실패 두 건이 연달아 나도 같은 키가 된다. 그래서 직전 실패와
         `same-failure` 가 **reflex true** 일 때만 같은 causeKey 로 세고, 그 밖에는 항목별 고유 키(`tests_failed#{n}`)로 둔다.
       - deliberate 면 Claude 가 의미로 정한다 · `other` 이거나 그래도 정할 수 없으면 `unknown`(아래 규칙대로 다른
         unknown 과 묶지 않는다) · unavailable 이면 예전처럼 Claude 가 정한다.
     - 같은 causeKey 가 **연속 2건**(K=2) 나오면 남은 큐를 정지한다 — 큐 전체를 원인 하나에 대해
       재지불하지 않는다. 원인이 서로 다른 실패 2건은 breaker 를 켜지 않는다(D-2 규칙 유효).
     - 판정 불가는 `unknown` 이며 **다른 unknown 과 같은 원인으로 묶지 않는다** — 판정 불가를
       일치로 읽으면 breaker 가 무관한 실패 2건에 오작동한다.
     - 정지 시 출력(콘솔 + D-4.7 내구 표면): 공통 원인 1줄 · 그 원인으로 실패한 이슈 목록 ·
       아직 착수하지 않은 남은 항목 목록 · **재개 명령**(원인 해결 후 남은 항목의
       `/cc-dev:batch {n}` / `/cc-dev:run {n}` — 멱등이므로 `/cc-dev:go` 재실행이 아니다).
     - breaker 는 품질 게이트가 아니다 — 이미 통과한 머지를 되돌리지 않는다.
D-3. merge pre-authorization 의 의미 (run.md Step 12 / batch.md Phase 3 에서 해석):
     - AskUserQuestion 머지 승인 스킵 → 즉시 squash merge + Step 12.5 Close 검증 수행
     - 단, 다음은 pre-authorization 이 **덮지 못한다** (여전히 멈추거나 실패):
       ① 테스트/lint/리뷰 Critical 하드 게이트  ② seed-alignment MAJOR-DRIFT 확인
       ③ batch Phase 3 완료성 Hard Gate  ④ gh 미인증 등 Step 0 조기 중단
       ⑤ **Parent Closure Invariant** — run.md Step 9 gate 0(PR 생성 전) · Step 11.9(머지 직전) ·
         batch Phase 3-4.9. 열린 자식이 있으면 그 컨테이너는 머지되지 않는다
         (`rules/zenhub-conventions.md` → "Parent Closure Invariant"). 이 사유로 막힌 Epic 은
         D-2 의 [INCOMPLETE] 처리와 동일하게 기록하고 **다음 Epic 으로 계속**한다 — 전체 중단 금지
         (D-2.5 / D-2.7 예외는 동일하게 적용된다)
       ⑥ **병렬 스폰 계획 승인** — `commands/batch.md` → "2. 병렬 계획 승인"(Orca 워크트리 디스패치
         직전) 과 `commands/run.md` → "Agent Teams Parallel Mode" 사전 확인 4번(팀 구성 계획 승인).
         이 둘은 "머지해도 되는가" 가 아니라 "**세션/워크트리를 늘려도 되는가**" 라서 대상이 다르다
         (`rules/orchestration-graph.md` §4 기질 매트릭스: Agent Teams = 필수, Orca 디스패치 =
         항상 · `--merge=pre-authorized` 도 면제 못 함).
     - `--auto` 는 **승인 클릭만** 생략한다 — 스폰 승인 권한을 주지 않는다. `--auto` 는 하위 호출에
       `--unattended`(답할 사람 없음)를 전파하고, ⑥ 처럼 스폰 승인이 필요한 자리는 **승인 없이
       스폰하지 않고 순차로 강등**된다(`--no-parallel`). 하드 실패가 아니라 기능 차이 없는 강등이며
       소요 시간만 늘어난다(`skills/agent-teams/SKILL.md` → "Fallback Principle").
       무인(`--auto`) 환경에서 응답이 불가하면 그 자리를 순차로 내리는 것은 디자인 에스컬레이션
       4종의 무인 처리와 같은 원칙이다 — **어느 쪽도 무승인 진행을 허가로 바꾸지 않는다.**
       강등은 내구 기록을 남긴다 (batch 쪽 degrade 로그 + 그 레벨 PR body `## Dispatch`).
     - --gated 모드에서는 이 플래그를 전달하지 않는다 (기존 게이트 그대로)
D-4. 각 Epic/이슈 완료 시 1줄 진행 보고: "✅ Epic #N 머지·종료 (Story 3/3) | 다음: #M"
D-4.8. 머지된 항목의 워크트리 회수. 절차·안전 판정·순서·금지의 SoT 는
      `skills/orca-worktree-lifecycle/SKILL.md` — 여기서 재구현하지 않는다.
      - Epic: `/cc-dev:batch` 가 머지 큐 5번에서 자식 워크트리를 이미 회수한다.
        go 는 그 회수를 다시 하지 않고, batch 가 `leak` 으로 남긴 행만 1회 재시도한다.
      - 단독 이슈: `/cc-dev:run` 은 표시만 한다(자기 제거 금지). 그 이슈를 위해 go 가 연
        자식 워크트리가 있으면, `gh pr view` 로 MERGED 를 확인한 직후 go 가 회수한다.
      - ⛔ 지금 이 go 세션이 돌고 있는 워크트리는 여기서 지우지 않는다. Phase E 보고를
        내구 표면에 적은 뒤 E-5 에서만 지운다.
      - `--keep-worktrees` 면 이 절은 no-op 이고, 미회수 목록을 로그에 남긴다.
      - 회수 실패는 경고 후 계속. 머지를 되돌리거나 큐를 멈추지 않는다.
D-4.5. 작업내역 HTML: 각 PR 생성 시 run.md **Step 9** 가 리뷰어용 작업내역을
     `.claude/docs/{scope}/pr-work-{issue}.html` 로 커밋·push 하고 그 경로와 링크를 **PR 본문에**
     넣은 채로 PR을 만든다 (댓글 아님 — 여기서 다시 구현하지 않는다). **Step 10.5** 는 CI 를 기다려
     판정할 뿐 문서를 고치지 않는다 — CI 결과의 정본은 PR 체크다.
     - merge pre-authorization 은 이 단계를 바꾸지 않는다 — 게이트가 아니다
     - 문서 커밋 실패는 비차단 (마크다운 폴백). **CI 통과 요구는 사전 승인이 덮지 못한다**
     - Phase E 집계를 위해 { issue, prNumber, workDocPath | fallback } 을 모은다
D-4.7. 내구 원장(ledger) — D-4 의 진행 1줄은 콘솔에만 두지 않는다. **새 상태 파일은 만들지 않고**
     (Resume Contract 유지) 이미 존재하는 표면에 항목이 확정되는 **즉시** 얹는다:
     - 머지된 항목: 그 PR body 에 `- #{n} MERGED` 1줄 추가 — Step 9 가 이미 만든 표면이므로 새 표면을
       만들지 않는다(D-4.5). 작업내역 HTML 은 고치지 않는다 — 고치려면 커밋이 필요하고, 머지 뒤라
       브랜치도 없다.
     - [INCOMPLETE] · [SKIPPED-BLOCKED] 항목: 해당 이슈 코멘트에 상태 + causeKey(또는 blockedBy #N)
       + 재개 명령. BLOCKED 표기는 `rules/zenhub-conventions.md` → "Blocked Issue Contract" 를 쓴다.
     - **보드(파이프라인)도 이 원장의 일부다** — 코멘트만 남기고 칸을 그대로 두면 보드는 계속
       "진행 중"이라고 말한다. 하위 호출이 `blockIssue()`/`reflectBoardState(_, "aborted")` 로
       이미 반영했어야 하므로, 여기서는 **다시 옮기지 않고 반영됐는지만 확인**한다(이중 이동 금지).
       미반영이면 그 사실을 Phase E 에 `보드 미반영` 으로 함께 싣는다.
     - [SKIPPED-OCCUPIED] 항목: ⛔ **이슈에 아무것도 쓰지 않는다** — 남의 작업 이슈에 우리 상태를
       남기면 상대 세션의 대장·코멘트와 섞인다. 큐 로그와 Phase E 보고에만 남긴다.
     - 이유: Phase E 는 이 기록의 **집계**이며 유일한 사본이 아니다. 큐 중간에 크래시가 나면
       콘솔만 있던 원장은 사라진다(`rules/orchestration-graph.md` §2 `log:` — 잔여 상태와
       탈락시킨 것의 내구 기록. 콘솔은 내구가 아니다).
D-5. 디자인 결정 전파: 구현 중 발생하는 판단은 run.md Step 7.1 이 처리한다 (여기서 다시 구현하지 않는다).
     - merge pre-authorization 은 Step 7.1 의 성격을 바꾸지 않는다 — 애초에 게이트가 아니다
     - 각 이슈의 DDR 은 PR body `## Design Decisions` + `.claude/docs/{scope}/design-decisions.md` 에 남고,
       Phase E 집계를 위해 { issue, ddrCount, lowConfidence[] } 만 모은다
     - 에스컬레이션 4종이 실행 중 발생하면 그 이슈만 확인 대기 — **다른 Epic 은 계속 진행한다**
       (INCOMPLETE 처리 원칙과 동일: 파이프라인 전체를 세우지 않는다. 예외는 D-2.7 회로 차단)

Loop Contract: go.phaseD-execution-queue (Phase D 실행 큐)#

7 필드의 의미는 rules/orchestration-graph.md §2 가 SoT다 — 여기 적는 것은 이 루프의 값뿐이다. 항목 내부의 재시도 예산은 이 루프가 갖지 않는다(batch/run 소관).

inv:      큐의 각 항목은 정확히 한 번만 착수된다 · 착수 시점에 그 항목의 base 브랜치가 실재한다
          · 착수 시점에 그 항목이 다른 세션에 점유돼 있지 않다 (D-2.6)
          항목은 {MERGED | INCOMPLETE | SKIPPED-BLOCKED | SKIPPED-OCCUPIED} 중 하나로 확정되기
          전까지 pending 이며 확정 즉시 D-4.7 내구 표면에 기록된다 (pending 으로 방치 금지.
          단 SKIPPED-OCCUPIED 의 표면은 큐 로그와 Phase E 뿐이다 — 남의 이슈에 쓰지 않는다)
prog:     remaining = 큐에 남은 항목 수, 항목 1건 확정마다 1 강한 감소
          no-prog: 같은 항목을 이 루프에서 재착수하지 않는다 — 재시도는 batch/run 의 stall ladder
          소관이며(`agents/sequential-workflow.md`), 이 루프는 결과를 받아 적기만 한다
term:     remaining == 0 (또는 D-2.7 breaker 정지)
budget:   큐 1회 순회 = 항목 수만큼 착수, 재순회 0회 / breaker: 동일 causeKey 연속 2건 (K=2 —
          SKIPPED-BLOCKED·SKIPPED-OCCUPIED 는 세지 않는다)
exhaust:  breaker 발동 → 큐 정지 + 공통 원인 1줄 + 실패·미착수 목록 + 재개 명령 (무음 계속 금지)
resume:   ZenHub 이슈 상태 + 열린/머지된 PR 재조회로 위치 판정 — go.md 는 자체 상태 파일이 없다.
          `/cc-dev:batch {n}` / `/cc-dev:run {n}` 은 멱등(Closed 항목 건너뜀)
log:      항목당 1줄(D-4) + 같은 줄을 D-4.7 내구 표면에 즉시 기록. 정지 시 남은 항목을 이름으로
          남긴다 — 조용한 절단 금지 (`rules/orchestration-graph.md` §5)

Phase E: Final Report & Wrap#

E-1. 결과 표: 생성 이슈 수 / 머지 PR 목록 / 닫힌 이슈 / BLOCKED·INCOMPLETE 항목(+재개 명령)
     + 작업내역 HTML 경로 목록 (PR 별 1건 — `.claude/docs/{scope}/pr-work-{issue}.html`). 머지된 PR 의
       문서는 base 브랜치의 같은 경로에 있다 — 브랜치 링크는 머지 후 브랜치가 지워지면 404 이므로
       경로로 적는다(`rules/artifact-publishing.md` §7). 커밋이 폴백된 PR 은 `— 마크다운 폴백` 으로 표기한다.
     + 디자인 결정 집계: 총 DDR 수, `신뢰도: low` 항목(⚠️ 재검토 — 이슈 번호와 함께),
       에스컬레이션으로 사람에게 올라간 건수. 결정 0건이면 이 줄은 생략한다.
     이 표는 D-4.7 내구 원장의 **집계**다 — 새로 계산하지 않고 그 기록을 읽어 모은다.
E-1.5. INCOMPLETE / SKIPPED-BLOCKED 는 **causeKey 별로 묶어** 보고한다 — 평평한 목록 금지
     (원인 하나가 N줄로 흩어지면 사람이 N개 문제로 읽는다). 그룹당:
     - causeKey 1줄 + 그 원인에 걸린 이슈 번호 목록 + 그룹 공통 재개 명령 1개
     - D-2.7 breaker 로 정지했다면 그 그룹을 맨 위에 `⛔ 회로 차단 (동일 원인 연속 2건)` 으로 표시하고,
       **착수하지 않은 남은 항목**을 별도 줄로 함께 보여준다 (실패와 미착수를 섞지 않는다)
     - SKIPPED-BLOCKED 는 `blockedBy #N` 을 함께 적는다 — 원인이 자기 자신이 아니다
     - causeKey=`unknown` 은 묶지 않고 항목별로 나열한다 (D-2.7 과 같은 이유)
     - **SKIPPED-OCCUPIED 는 실패 그룹에 넣지 않는다** — 별도 줄로, **점유자별**로 묶는다
       (`🔒 다른 세션 진행 중 — {owner}: #A #B`). causeKey 그룹이 아닌 이유는 원인이 결함이 아니라
       **동시 실행**이기 때문이다. 재개 안내는 "상대 세션 종료 후 `/cc-dev:batch {n}`" 한 줄이며,
       고칠 것이 없다는 사실을 명시한다.
     - 보드 반영이 확인되지 않은 항목(D-4.7)은 `보드 미반영` 을 그 항목 줄에 덧붙인다 —
       조용히 넘기면 다음 실행이 같은 이슈를 In Progress 로 보고 점유 오판을 반복한다.
E-2. BLOCKED 항목이 있으면: "재개하려면 /cc-dev:batch {epic}" (batch Phase 0 멱등 resume 계약)
E-3. --wrap 지정 시 /cc-dev:session:wrap 실행
E-4. Initiative/Project 가 전부 닫혔는지는 batch/run 의 checkAndCloseParent 재귀가 이미 보장 —
      여기서 중복 확인하지 않는다 (미완 Epic 이 있으면 당연히 열려 있는 게 정상)
E-5. 세션 워크트리 회수 — 최상위 `/cc-dev:go` 만. SoT 는
      `skills/orca-worktree-lifecycle/SKILL.md` §1 "최상위 go".
      - 이 실행이 부모 batch 에 디스패치된 워커면 `markWorktreeReclaimable` 만 하고
        제거하지 않는다. 부모가 회수한다.
      - 최상위면 E-1 보고를 PR body 또는 이슈 코멘트에 **먼저** 적는다. 콘솔만 남기고
        워크트리를 지우면 보고가 사라진다.
      - 그 다음 §4 순서로 **이 세션의 워크트리**를 회수한다. R3(자기 제거 금지)는
        이 한 자리에서만 해제된다 — 머지 이후 단계와 Phase E 내구 기록이 끝났고,
        이 체크아웃을 기다리는 부모 머지 큐가 없다. R1·R2·R4 는 그대로다.
        하나라도 미확정이면 보존한다.
      - Orca 없음 · 워크트리 밖 · `--keep-worktrees` 는 조용한 no-op.
      - 실패는 경고 1줄. 사이클을 실패로 만들지 않는다.

Resume Contract#

/cc-dev:go 는 자체 상태 파일을 만들지 않는다. 중단 시 재개는 하위 계약을 그대로 쓴다:

  • 이슈 생성 전 중단 → /cc-dev:go 재실행 (처음부터)
  • 점유(SKIPPED-OCCUPIED)로 건너뛴 항목 → 상대 세션이 끝난 뒤 그 항목의 /cc-dev:batch {n} / /cc-dev:run {n}. 상대가 죽은 채 남았으면 점유 TTL(4h) 경과 후 자동 인수되며, 그 전에 이어받아야 하면 --force-claim. 낡은 점유를 한 번에 정리하려면 /cc-dev:zenhub:manage sweep-stale-claims
  • 이슈 생성 후 중단 → /cc-dev:batch {epic} / /cc-dev:run {issue} 재실행 (멱등 — Closed Story 는 건너뜀)
  • --plan-only 로 남긴 계획 → 동일. 상세 기획 HTML 은 로컬 대기 파일이라 같은 체크아웃에서 이어가야 커밋·링크된다 — 다른 머신에서 이어가면 본문으로 재구성하거나 건너뛴다(비차단)
  • D-2.7 회로 차단으로 정지 → 보고된 공통 원인을 먼저 해결하고, 그 뒤 남은 항목의 재개 명령을 순서대로 실행한다. 원인을 고치지 않고 재실행하면 같은 causeKey 로 2건에서 다시 정지한다.

상태 파일이 없다는 것이 기록이 없다는 뜻은 아니다. 진행 원장은 D-4.7 이 이미 존재하는 표면 (PR body / 이슈 코멘트)에 항목마다 즉시 적으므로, 크래시로 Phase E 를 못 찍어도 "무엇이 머지되고 무엇이 남았는지" 는 GitHub·ZenHub 재조회로 복원된다 — 재개 판정은 항상 그 재조회이며 어떤 로컬 파일도 신뢰하지 않는다.

Error Handling#

상황행동
breakdown 이 이슈 생성 중 부분 실패생성된 것까지 issueMap 에 반영, 실패 항목 보고 후 Phase C 에서 사용자 판단 (--auto 면 생성분만 실행)
한 Epic 이 INCOMPLETE기록 후 다음 Epic 계속 — 전체 중단 금지 (D-2). 단 ① 그 Epic 에 의존하는 후속은 D-2.5, ② 같은 원인 연속 2건은 D-2.7
같은 causeKey 로 Epic 2건 연속 실패회로 차단 — 큐 정지 후 공통 원인 1줄 + 실패/미착수 목록 + 재개 명령 보고 (D-2.7). 원인이 서로 다르면 차단하지 않는다
INCOMPLETE Epic 의 산출물에 의존하는 후속 항목착수하지 않고 [SKIPPED-BLOCKED: blockedBy #N] 기록 (D-2.5) — 없는 base 위에서 착수 금지. 의존 여부 판정 불가도 같게 처리
병렬 스폰 승인이 필요한데 답할 사람이 없음(--auto)순차로 강등(--no-parallel) 후 계속 — 승인 없이 스폰하지 않는다 (D-3 ⑥). 하드 실패 아님, 소요 시간만 늘어남
gh/zenhub 도구 부재run.md Step 0 Degradation Contract 준용 — PR 이 핵심 산출물이므로 Phase D 진입 전 조기 중단
항목이 다른 세션에 점유됨 ([INCOMPLETE: issue_occupied])[SKIPPED-OCCUPIED: heldBy {owner}] 로 기록하고 다음 항목으로 계속 (D-2.6). 보드·대장은 건드리지 않으며 회로 차단 카운트에도 넣지 않는다
같은 이슈에 이미 열린 PR 존재run.md Step 0.5 Duplicate Work Preflight 가 해당 이슈 착수 직전에 잡아 확인을 받는다. 다른 Epic 은 계속 진행한다(INCOMPLETE 처리 원칙과 동일)
MAJOR-DRIFT (LOCKED seed 존재 시)batch Phase 0.5 계약 그대로 — --auto 에서도 경고를 남기고, 대화형이면 확인을 받는다
디자인 판단이 R5 까지 내려감(확신 낮음)결정하고 진행 — 신뢰도: low + Phase E 재검토 목록. 중단 사유가 아니다
디자인 에스컬레이션 4종 발생해당 이슈만 권고안+확인 대기, 다른 Epic 은 계속. 무인(--auto) 환경에서 응답이 불가하면 그 이슈를 [INCOMPLETE] 로 기록하고 다음으로 넘어간다
작업내역 HTML 커밋 실패 (Step 9)중단 사유 아님 — PR 본문에 마크다운 인라인 폴백 후 PR 생성 계속. Phase E 에 — 마크다운 폴백 으로 표기
이슈 상세 기획 HTML 커밋·링크 실패 (run.md Step 4 · batch.md Phase 1.5)중단 사유 아님 — 본문에 마크다운으로 인라인하거나 건너뛴다 (rules/artifact-publishing.md §10)
워크트리 회수 실패 (D-4.8 · E-5)중단 사유 아님 — 경고 1줄 후 계속. 머지를 되돌리지 않는다. 다음 /cc-dev:go 또는 /cc-dev:batch 의 스윕이 재시도한다
  • /cc-dev:zenhub:breakdown — Phase B 가 재사용하는 이슈 계층 생성 프로토콜
  • /cc-dev:batch — Phase D 의 Epic 실행기 (Story/Sub-task 사이클 포함)
  • /cc-dev:run — Phase D 의 단독 이슈 실행기 (13단계 사이클, Step 7.1 디자인 의사결정 포함)
  • /cc-designer:decide — Phase A-5 가 부르는 디자인 판단 확정 진입점 (--batch 다건, --brief 한 줄)
  • /cc-dev:session:wrap — Phase E 의 세션 마무리 (--wrap)
  • agents/dev/pm-spec-agent.md — Phase A 소규모 경로의 PM 정제
  • agents/zenhub-integration-agent.md — breakdown 내부의 계층 생성 워커
  • cc-designer:design-decision — Phase A-5·D(Step 7.1) 디자인 의사결정의 판정 로직 SoT (근거 사다리·에스컬레이션 4종·DDR)
  • cc-designer:designer-index — 결정 유형별 참조 스킬 라우팅
  • cc-dev:pr-work-artifact — Phase D(Step 9) 작업내역 HTML 커밋 + PR 본문 링크 프로토콜 (Step 10.5 는 CI 대기만 한다)
  • cc-dev:orca-worktree-lifecycle — D-4.8·E-5 워크트리 회수의 SoT. go 는 시점만 고정하고 판정·순서는 복제하지 않는다

검색어를 입력하면 문서를 찾습니다.

↑ ↓ 이동 · Enter 열기Esc 닫기