병렬 이슈 해결사 (Parallel Issue Resolver)
GitHub 이슈 배치를 동시에 해결하되, 각 이슈는 자체 git 워크트리에서 격리되어 작업되며, 각각의 풀 리퀘스트를 통해 적용됩니다. 다섯 단계로 진행됩니다: 계획 → 구현 → 리뷰 → 수정 → 적용.
가장 중요한 규칙: 이슈는 GitHub에서 해당 PR이 MERGED 상태로 보고된 경우에만 종결됩니다. 로컬 병합, 워크트리 내 테스트 통과, 서브 에이전트의 진술 등으로 종료되지 않습니다. 모든 종료에는 실제로 구현된 내용을 설명하는 코멘트가 포함됩니다.
작업은 사람이 하는 방식과 동일하게 main 브랜치에 도달합니다: 브랜치 → PR → CI → 스쿼시 머지. CI가 확인하지 않은 것은 어떤 것도 적용되지 않습니다.
빠른 시작
사용자가 "#12 #15 #18을 병렬로 해결해"라고 말합니다.
- 사전 검사:
bash <skill-dir>/scripts/preflight.sh— 아무것도 실행하기 전에 반드시 0으로 종료되어야 합니다. 별도의 설정 단계는 없으며, 첫 실행 시 리포지토리 자체를 구성합니다. - 계획: 각 이슈를 읽고, 의존성 그래프를 구축한 후, 충돌 없이 지금 실행할 수 있는 이슈를 선택합니다.
- 구현: 차단되지 않은 각 이슈에 대해
isolation: "worktree"설정으로 하나의 서브 에이전트를 단일 메시지로 모두 생성하여 동시에 실행합니다. 각 서브 에이전트는 구현, 커밋, 푸시, PR 생성, 핸드오프 파일 작성을 수행합니다. - 리뷰: 각 이슈에 대해 별도의 리뷰어 서브 에이전트(절대 작성자 아님)가 diff와 이슈를 비교하여
approve또는changes-requested를 반환합니다. - 수정: 차단 피드백을 원래 구현자에게 보내고, 재리뷰합니다. 최대 2라운드입니다.
- 적용: 승인된 각 이슈에 대해
bash <skill-dir>/scripts/land.sh <issue> <branch> <comment-file>을 하나씩 실행합니다. - 반복: 새로 차단 해제된 이슈가 있으면 계속합니다.
첫 실행 전에 작동 방식, 명령 감지, 주의사항에 대해 REFERENCE.md를 읽으세요.
0단계 — 사전 검사 (Preflight)
모든 배치 전에 실행하세요. 이 스킬의 유일한 설정 명령입니다:
bash <skill-dir>/scripts/preflight.sh # --fix를 추가하여 안전한 잔여물을 정리합니다
이 명령은 아직 구성되지 않은 모든 것을 부트스트랩합니다 — .worktreeinclude (gitignore된 .env/비밀 파일이 모든 워크트리에 복사되도록), 무시 규칙, worktree.baseRef: "head", 그리고 실행이 실제로 성공하는지 확인합니다: 필요한 도구 존재, 작업 트리 깔끔함, gh 인증됨, 베이스가 origin과 동기화됨, CI가 pull_request에서 트리거됨, 충돌을 일으킬 수 있는 agent/issue-* 브랜치나 고아 워크트리가 남아있지 않음.
부트스트래핑은 멱등적이며 무언가 변경할 때만 출력하므로, 두 번째 실행부터는 순수하게 검사만 수행합니다. 추적 파일을 쓰지 않습니다 — 무시 규칙은 .git/info/exclude에 기록되므로, 스킬은 절대 리포지토리에 diff를 남기지 않습니다.
0이 아닌 값으로 종료되면 멈추고 수정하세요 — 에이전트를 생성하지 마세요. 발견한 내용을 사용자에게 보고합니다.
베이스 브랜치를 캡처하세요: git branch --show-current → BASE. 모든 PR은 BASE를 대상으로 합니다.
1단계 — 계획 (Plan, 오케스트레이터, 인라인)
각 이슈에 대해: gh issue view <id> --json number,title,body,labels,state,comments. 이슈가 상위 PRD/에픽을 참조하는 경우 해당 내용도 읽습니다.
이미 CLOSED 상태이거나 이미 열린 PR이 있는 이슈는 건너뜁니다 (gh pr list --search "<id> in:body") — 작업을 중복하지 않고 그 사실을 알립니다.
의존성 그래프를 구축합니다. 이슈 B는 A에 의해 차단됩니다. 다음 조건 중 하나라도 해당하는 경우:
- B가 A가 도입하는 코드/인프라가 필요합니다.
- B와 A가 겹치는 파일/모듈을 수정합니다 → 동시 편집 시 충돌합니다.
- B가 A가 확립하는 API 형태나 결정에 의존합니다.
이슈가 이 배치에 있는 다른 이슈에 대한 차단 의존성이 전혀 없으면 차단 해제됩니다. 차단 해제된 이슈만 이번 라운드에서 실행됩니다. 모든 이슈가 차단된 경우, 사이클을 끊기 위해 의존성이 가장 약한 이슈 하나만 실행합니다.
각각에 대해 결정적 브랜치를 할당합니다: agent/issue-<id>. 생성 전에 사용자에게 배치 계획을 알립니다 — 지금 실행할 이슈, 대기할 이슈, 그 이유.
2단계 — 구현 (구현, 병렬 서브 에이전트)
차단 해제된 각 이슈에 대해, Agent 도구를 사용하여 isolation: "worktree" 설정으로 하나의 서브 에이전트를 생성합니다. 모든 생성을 하나의 메시지에 넣어 동시에 실행합니다.
- 서브 에이전트 유형:
general-purpose(편집 + bash 필요). - 이름을
impl-<id>로 지정 — 4단계에서 리뷰 결과를 원래 컨텍스트가 유지된 상태로 보내기 위해 이 이름이 필요합니다. - 프롬프트: prompts/implement.md의 내용으로,
{{ISSUE_ID}},{{BRANCH}}(=agent/issue-<id>),{{BASE}},{{STATE_DIR}}(<repo>/.claude/pir의 절대 경로)가 채워집니다.
각 서브 에이전트는 구현, 자체 diff 정리, 푸시, PR 생성, 그리고 두 개의 핸드오프 파일을 {{STATE_DIR}}에 씁니다. 이 파일들은 내구성 있는 기록입니다 — 컨텍스트 압축에서 살아남지만 RESULT 줄은 그렇지 않습니다. REFERENCE.md를 참조하세요.
3단계 — 독립 리뷰 (리뷰, 병렬 서브 에이전트)
구현 에이전트는 자신의 작업을 리뷰하지 않습니다. complete 상태로 돌아오고 열린 PR이 있는 각 이슈에 대해, 별도의 리뷰어를 생성합니다 — 역시 모두 하나의 메시지에 넣어.
- 서브 에이전트 유형:
general-purpose. 이름을review-<id>로 지정. isolation: "worktree"없음 — 리뷰는 읽기 전용이며 기본 체크아웃에서git diff {{BASE}}...{{BRANCH}}를 사용하여 작업합니다. 생성하거나 정리할 워크트리가 없습니다.- 프롬프트: prompts/review.md로,
{{ISSUE_ID}},{{BRANCH}},{{BASE}},{{PR}},{{STATE_DIR}}이 채워집니다.
리뷰어는 {{STATE_DIR}}/issue-<id>.review.json 파일을 작성하며, approve 또는 changes-requested의 평결과 함께 발견 사항을 포함합니다. 리뷰어는 절대 편집, 푸시, 병합, 코멘트를 하지 않습니다 — 보고만 하면, 당신이 결정합니다.
평결을 PR에 게시하여 그 근거가 사람이 찾을 수 있는 곳에 기록되도록 합니다:
gh pr comment <PR> --body "$(jq -r '\"**Automated review: \(.verdict)**\n\n\(.summary)\"' .claude/pir/issue-<id>.review.json)"
4단계 — 수정 라운드 (Fix round, changes-requested인 경우만)
차단 발견 사항을 원래 구현자에게 보냅니다. 구현자는 여전히 코드를 컨텍스트로 가지고 있습니다:
SendMessage → to: "impl-<id>"
PR #에 대한 독립 리뷰에서 개의 차단 문제를 발견했습니다. 이것들만 수정하고, 검사를 다시 실행하고, 동일한 브랜치에 푸시하고, 핸드오프
.md를 최종 상태와 일치하도록 업데이트하세요.<
blocking배열, 그대로>발견 사항이 잘못되었다고 생각되면, 옳다고 믿는 코드를 변경하는 대신 그 이유를 말하세요.
그런 다음 해당 이슈에 대해 3단계를 다시 실행합니다 (새로운 review-<id> 에이전트 — 2라운드).
최대 2번의 리뷰 라운드로 제한합니다. 2라운드 후에도 이슈가 여전히 changes-requested 상태이면 중단합니다: PR과 이슈를 열린 상태로 두고, 리뷰어의 발견 사항과 함께 사용자에게 해결되지 않은 내용을 알립니다. 3라운드는 이슈가 불완전하게 명시되었거나 의견 차이를 사람이 해결해야 함을 의미하며, 추가 라운드는 수렴 없이 토큰만 소모합니다.
구현자가 수정 대신 발견 사항에 대해 이의를 제기하면, 두 주장을 모두 읽고 직접 판단하세요. 단순히 다시 전달하지 마세요 — 그것이 루프가 형성되는 방식입니다.
5단계 — 적용 (Land, 오케스트레이터, BASE 체크아웃에서)
이슈를 하나씩, 직렬로 적용합니다 — 절대 병렬로 하지 마세요. 각 병합은 BASE를 변경하며, 이로 인해 다음 PR이 오래될 수 있습니다; land.sh는 GitHub가 충돌을 보고할 때 리베이스하며, 이는 이미 업데이트된 베이스에 대해서만 작동합니다.
핸드오프 상태가 status: "complete" 이고 리뷰 평결이 approve인 각 이슈에 대해:
bash <skill-dir>/scripts/land.sh <issue> agent/issue-<issue> .claude/pir/issue-<issue>.md
스크립트는 유일하게 올바른 순서로 전체 테일을 수행합니다: 리뷰 평결 확인 → 워크트리 해제 → 충돌 시 리베이스 → CI가 녹색이 될 때까지 폴링 → 스쿼시 머지 → GitHub가 MERGED를 보고하는지 확인 → 핸드오프 코멘트로 이슈 종료 → BASE를 빨리 감기(fast-forward) → 브랜치 삭제 → 워크트리 정리.
디스크에 approve 평결이 없으면 아무것도 적용하지 않으므로, 리뷰는 습관이 아닌 게이트 역할을 합니다. PIR_SKIP_REVIEW=1이 이를 무시합니다 — 사용하는 경우, CI가 수행할 수 없는 유일한 검사를 제거하는 것이므로 큰 소리로 말하세요.
종료 코드에 따라 분기합니다:
| 코드 | 의미 | 수행할 작업 |
|---|---|---|
0 | 적용됨, 종료됨, 정리됨 | 다음 이슈로 계속 |
2 | 사전 조건 실패 | 수정하고 재실행; 강제로 진행하지 마세요 |
3 | 스크립트가 해결할 수 없는 리베이스 충돌 | 해당 브랜치에서 수동으로 해결하고, 푸시한 후 land.sh 재실행 |
4 | CI 실패 또는 시간 초과 | 실패한 검사를 읽고, 브랜치에서 수정한 후 푸시하고 land.sh 재실행 |
5 | 병합/종료 문제 | PR 검사 — 병합되었지만 이슈가 여전히 열려 있을 수 있음 |
0이 아닌 것은 PR 과 이슈를 의도적으로 열린 상태로 둡니다. PR 링크와 함께 사용자에게 보고하세요; 맹목적으로 재시도하지 마세요.
그런 다음 차단된 이슈가 남아 있으면 1단계로 돌아가 반복합니다.
6단계 — 보고 (Report)
각 이슈에 대해 사용자에게 알립니다: 적용됨 (PR # + 링크), 열린 상태로 남음과 그 이유, 또는 건너뜀과 그 이유. 2번의 리뷰 라운드 후에도 열려 있는 항목에 대해 리뷰어의 미해결 차단 발견 사항을 포함합니다. 병합된 PR 번호 없이 이슈가 완료되었다고 절대 주장하지 마세요.
요구 사항
Claude Code에서 실행됩니다: isolation: "worktree", SendMessage, .worktreeinclude가 있는 서브 에이전트에 의존합니다. npx skills add dhiraj-verhelm/agent-skills --skill parallel-issue-resolver로 설치하거나, 이 디렉토리를 ~/.claude/skills/ 또는 리포지토리의 .claude/skills/에 복사하세요. 리포지토리별 설정, 편집할 구성, 수정할 경로가 없습니다.
머신에 필요한 것: git, gh (인증됨), jq. 사전 검사는 이 세 가지를 모두 확인하고 누락된 항목을 알려줍니다.
리포지토리에 필요한 것: GitHub 원격 저장소, 그리고 풀 리퀘스트에 대한 검사를 보고하는 CI. 사전 검사는 그러한 CI가 없으면 경고합니다. PIR_REQUIRE_CI=0으로 설정하면 CI 게이트 없이도 PR을 적용할 수 있습니다. 사용하는 경우 큰 소리로 말하세요. 이 스킬의 주요 안전 속성을 제거하기 때문입니다.
리포지토리에 대해 하지 않는 일: 추적 파일을 수정하지 않습니다. 무시 규칙은 .git/info/exclude에 기록되므로, 부트스트래핑은 diff를 남기지 않으며 어떤 것도 커밋에 누출될 수 없습니다.
스크립트는 bash <path>로 호출되므로, 복사 중 실행 비트가 손실되어도 문제가 발생하지 않습니다.
안전 및 게이트
- 절대 BASE에
git push하지 마세요, 그리고 에이전트 자신의 브랜치 외에는--force를 절대 사용하지 마세요 (--force-with-lease,land.sh의 리베이스 내에서만). - 절대
git add -A/git add .사용하지 마세요 — 명시적 경로만 스테이징하세요. - 절대 PR 본문에
Closes #N/Fixes #N을 넣지 마세요. GitHub가 수행된 작업에 대한 코멘트 없이 이슈를 조용히 종료하게 만듭니다.Refs #N을 사용하세요; 종료는 명시적이며, 확인된 병합에 의해 제어되며, 항상 요약을 포함합니다. --admin으로 절대 병합하지 마세요, 그리고 빨간 검사를 절대 건너뛰지 마세요.- 이슈당 하나의 서브 에이전트, 자신의 이슈에 대해서만 작업합니다.
- 사전 검사가 실패하면 멈추고 사용자에게 알립니다. 작업 트리가 더티(dirty)하면 멈추세요 — 워크트리는 HEAD에서 브랜치됩니다.