Add /parallel-issues skill for taskMaestro-driven parallel issue execution with AUTO mode #746
Description
배경
GitHub 이슈 다수를 병렬로 구현할 때, 매번 수동으로:
- 이슈 분석 (의존성, 파일 겹침, 복잡도)
- Wave 분할 (병렬 가능 그룹 분류)
- 워커 프롬프트 작성 (AUTO 모드 + subAgent 지시)
- taskMaestro 실행 (start → assign → watch → stop)
- Wave 전환 및 최종 정리
이 과정을 반복하고 있다. 이를 단일 스킬로 자동화하면 /parallel-issues 732-743 한 줄로 전체 워크플로우를 실행할 수 있다.
실제 사례: #731 하위 이슈 12개(#732-#743)를 3-Wave로 분할하여 taskMaestro + codingbuddy AUTO 모드로 병렬 실행한 경험 기반.
스킬 사양
Frontmatter
---
name: parallel-issues
description: >-
Execute multiple GitHub issues in parallel using taskMaestro worktrees.
Use when you have 2+ independent issues to implement simultaneously.
Analyzes dependencies, groups into waves, generates AUTO mode worker prompts,
and orchestrates parallel execution with quality gates.
disable-model-invocation: true
argument-hint: [issue-numbers-or-range]
allowed-tools: Bash, Read, Write, Edit, Grep, Glob, Agent
---호출 예시
# 이슈 번호 나열
/parallel-issues 732 733 734 735 736
# 범위 지정
/parallel-issues 732-743
# 특정 이슈 이후 열린 이슈
/parallel-issues --after 731
# pane 수 제한
/parallel-issues 732-743 --panes 3SKILL.md 워크플로우 설계
Phase 1: 이슈 수집 및 분석
1. 인수 파싱 → GitHub issue 번호 목록 확정
2. gh issue view로 각 이슈 상세 수집 (title, body, labels)
3. 의존성 그래프 추출:
- body에서 "depends on", "after", "Parent:" 등 패턴 파싱
- sub-issue 관계 추출
4. 대상 파일 추출:
- body에서 파일 경로 패턴 추출
- 파일 겹침 매트릭스 생성
5. 복잡도 판정:
- Simple: YAML 필드 추가, 설정 변경 등 (1-5 파일, 단순 수정)
- Medium: 새 파일 생성, 문서 작성 등 (여러 파일, 콘텐츠 작성)
- Complex: 코드 구현, 스크립트 작성 등 (로직 포함)
Phase 2: Wave 분할 및 계획 생성
1. 의존성 그래프 기반 위상 정렬 (topological sort)
- 의존성 없는 이슈 → Wave 1
- Wave 1 이슈에 의존하는 이슈 → Wave 2
- 재귀적으로 Wave N 결정
2. 같은 Wave 내에서 파일 겹침 경고 (병렬 가능하지만 rebase 필요)
3. 머지 순서 결정 (priority label 기반)
4. docs/plans/YYYY-MM-DD-parallel-issues.md에 계획 문서 자동 생성
5. 사용자에게 계획 요약 출력 + 승인 요청 (AskUserQuestion)
Phase 3: 워커 프롬프트 생성
각 이슈에 대해 아래 구조의 워커 프롬프트 자동 생성:
[공통 접두사: AUTO 모드 방법론]
- PLAN: parse_mode → analyze_task → generate_checklist → update_context
- ACT: dispatch_agents → 구현 (subAgent 병렬화 권장) → update_context
- EVAL: generate_checklist → specialist subAgent 병렬 파견 → severity 분류
- 탈출: Critical=0 AND High=0 → /ship, 아니면 ACT 복귀
- Medium/Low → PR description에 기록
[이슈별 상세]
- 이슈 제목, 번호
- 목표, 대상 파일, 수정 방법
- Acceptance Criteria (이슈 body에서 추출)
- 복잡도별 subAgent 전략
- /ship <이슈번호> 로 마무리
Phase 4: taskMaestro 실행
각 Wave에 대해:
1. /taskmaestro start --panes <wave_size>
2. 각 pane에 /taskmaestro assign <n> "<워커 프롬프트>"
3. /taskmaestro watch (30초 주기 감시)
4. 모든 pane idle + /ship 완료 확인
5. /taskmaestro stop all
6. 다음 Wave로 전환 (의존 이슈 PR 머지 확인)
Phase 5: 정리 및 보고
1. gh pr list로 생성된 PR 목록 수집
2. 머지 순서 안내 출력
3. parent issue가 있으면 체크리스트 업데이트 안내
4. docs/plans/ 계획 문서에 결과 추가
Self-Contained 설계 (Context Clear 대응)
스킬이 context clear 후에도 작동하려면:
- SKILL.md에 전체 방법론 포함: AUTO 모드 이터레이션, 탈출 조건, subAgent 전략이 SKILL.md 본문에 완전히 기술
- 외부 의존 최소화: codingbuddy MCP 도구(parse_mode 등)는 선택적 사용, 없어도 동작
- 상태 파일:
~/.claude/taskmaestro-state.json+docs/plans/계획 문서로 상태 복구 가능 - 워커 프롬프트 자기 완결: 각 워커 프롬프트가 이슈 context + 방법론을 모두 포함
지원 파일 구조
.claude/skills/parallel-issues/
├── SKILL.md # 메인 (Phase 1-5 워크플로우)
├── references/
│ ├── auto-mode-template.md # 워커 공통 접두사 템플릿
│ ├── wave-analysis-guide.md # 의존성 분석 + Wave 분할 알고리즘
│ └── eval-criteria.md # EVAL severity 기준 상세
└── examples/
└── 2026-03-21-parallel-issues.md # 실제 사례 (#732-#743)
taskMaestro 스킬과의 관계
| 스킬 | 역할 | 레벨 |
|---|---|---|
/taskmaestro |
tmux pane 인프라 관리 (start/assign/watch/stop) | Low-level |
/parallel-issues |
이슈 분석 + Wave 계획 + 워크플로우 오케스트레이션 | High-level |
/ship |
PR 생성 + CI 체크 | 마무리 |
/parallel-issues는 /taskmaestro를 내부적으로 호출하는 상위 스킬.
Iron Rule: Zero-Conflict Guarantee
병렬 작업의 핵심 전제는 각 worktree의 변경사항이 절대 conflict를 발생시키지 않는 것이다.
교훈 (2026-03-21 사례)
Wave 1에서 #733(allowed-tools)과 #734(argument-hint)를 병렬 실행 → PR #750, #751에 merge conflict 발생. 파일 겹침 매트릭스를 만들어놓고도 '다른 YAML 필드라 trivial rebase'로 낙관적 판단한 것이 원인.
원칙
- 파일 단위 독립성 검증: 같은 파일을 수정하는 이슈는 반드시 다른 Wave로 분리
- 낙관적 판단 금지: 'trivial rebase', '다른 필드라 괜찮다' 같은 판단 불허
- Zero-tolerance: 파일 겹침이 1개라도 발견되면 순차 실행
- Wave 분할 알고리즘: Phase 2에서 파일 겹침 매트릭스 생성 후, 겹침 있는 이슈 쌍은 반드시 다른 Wave에 배치
- 검증 체크리스트: Wave 확정 전 '같은 Wave 내 모든 이슈 쌍이 파일 겹침 0인가?' 검증 필수
Acceptance Criteria 추가
- Phase 2 Wave 분할에 파일 겹침 검증 단계 포함
- 겹침 발견 시 자동으로 다른 Wave로 분리하는 로직 명시
- SKILL.md에 Iron Rule로 문서화
Acceptance Criteria
-
.claude/skills/parallel-issues/SKILL.md생성됨 - 5개 Phase 워크플로우 포함 (수집→계획→프롬프트→실행→정리)
- AUTO 모드 이터레이션 방법론이 self-contained로 포함
- 탈출 조건 (Critical=0 AND High=0) 명시
- 워커 내부 subAgent 병렬화 가이드 포함
- 의존성 분석 및 Wave 자동 분할 로직
- 파일 겹침 매트릭스 자동 생성
- 지원 파일 (references/, examples/) 포함
- context clear 후에도 SKILL.md만으로 실행 가능
-
/parallel-issues 732-743형태로 호출 가능 - 실제 사례 ([P0] Add disable-model-invocation: true to side-effect skills #732-[E] Implement skill-creator assets/ + eval-viewer/ viewers and templates #743) 기반 examples/ 포함
References
- 실제 사례 계획 문서:
docs/plans/2026-03-21-skill-metadata-parallel.md - taskMaestro 스킬:
.claude/skills/taskmaestro/SKILL.md - ship 스킬:
.claude/skills/ship/SKILL.md - codingbuddy AUTO 모드:
packages/rules/.ai-rules/rules/core.md