orca-orchestration-dev

Orca ADE의 오케스트레이션(감독형 멀티 에이전트) 으로 웹앱·앱 기능을 개발하는 Claude Skill.

PRD를 주면 환경 조사 → 계약 확정 → Task DAG 설계 → 병렬 구현 → 통합 → 점검 순서로 진행하며, 파일 소유권 배정·결정 게이트·독립 검증 절차를 강제합니다.

⚠️ 검증 환경: Orca appVersion 1.4.161 / macOS (dmg 직접 설치) / CLI /usr/local/bin/orca 이 빌드는 공식 문서(onorca.dev/docs)와 명령 체계가 다릅니다. 자세한 내용은 명령 레퍼런스 참조.

---

무엇을 해결하나

에이전트 하나에게 "로그인 기능 만들어줘"라고 시키면 조사·구현·테스트를 혼자 순차로 합니다. 느리고, 중간에 뭘 하는지 안 보이고, 잘못된 판단을 해도 끝날 때까지 모릅니다.

이 스킬은 작업을 쪼개서 여러 에이전트에 나눠주고, 누가 무엇을 어디까지 했는지 추적하고 검증하는 절차를 강제합니다.

핵심은 "빠르게"가 아니라 “통제 가능하게” 입니다. 병렬은 종속성이 허락할 때 얻는 부수 이득이지 목적이 아닙니다.

---

적용 범위

웹앱 개발 12단계 중 개발 구간에만 적용됩니다.

배포는 대행하지 않습니다. 되돌리기 어렵고 실사용자에게 영향이 가기 때문입니다.

---

설치

전역 (모든 프로젝트)

mkdir -p ~/.claude/skills
git clone https://github.com/nergury74/orca-orchestration-dev.git ~/.claude/skills/orca-orchestration-dev

프로젝트 전용 (팀 공유)

cd 
mkdir -p .claude/skills
git clone https://github.com/nergury74/orca-orchestration-dev.git .claude/skills/orca-orchestration-dev

프로젝트 스킬이 전역 스킬보다 우선합니다.

확인

find ~/.claude/skills/orca-orchestration-dev -name SKILL.md

~/.claude/skills/orca-orchestration-dev/SKILL.md 하나만 나와야 정상입니다. 한 단계 더 깊게 넣으면 인식되지 않습니다.

설치 후 Claude Code 세션을 재시작하세요.

Orca의 코디네이터가 Claude Code이므로, ~/.claude/skills에 설치하면 Orca 안의 코디네이터도 이 스킬을 읽습니다. 별도 설치가 필요 없습니다.

---

사전 조건

---

사용법

Orca의 코디네이터 에이전트(Claude Code 탭)에 입력합니다.

첫 마디

오케스트레이션으로 개발해줘.

[PRD]
(PRD 붙여넣기)

스킬이 자동으로 다음을 진행합니다.

1. 스킬 가이드·명령 스키마 로드
2. 프로젝트 환경 조사 (없는 라이브러리, 테스트 설정, 빌드 명령)
3. Task 쪼개기 + 파일 소유권 배정
4. 프리앰블 검수
5. 계획 제시 후 정지

두 번째 마디

계획을 검토한 뒤:

승인. 시작해.

이후는 질문에 답하고, 완료 보고를 받고, 커밋 여부를 결정하면 끝입니다.

계획 검토 시 확인할 것

---

트리거 문구

• 오케스트레이션으로 개발 (기본)
• 오케스트레이션으로 만들어줘 / Orca로 병렬 개발 / 멀티 에이전트로 구현
• 여러 에이전트에 나눠서 개발 / 워커 나눠서 구현 / PRD로 Task 쪼개서 개발

PRD·기획서를 주면서 구현을 맡기는 경우에도 발동합니다.

---

진행 중 주의사항

별도 터미널에서 orca orchestration check를 플래그 없이 치지 마세요.

이 명령은 메시지를 읽음 처리해서, 코디네이터가 받아야 할 완료 보고를 가로챕니다. 그러면 코디네이터가 영원히 대기합니다.

상태 조회는 이것들을 쓰세요.

orca orchestration task-list --json          # 진행 상황
orca orchestration inbox --limit 20 --json   # 메시지 이력
orca worktree ps --json                      # 전체 요약
orca orchestration check --peek              # 소비하지 않고 미읽음 확인

---

구성

orca-orchestration-dev/
├── SKILL.md                  # 절차 (STEP 0~7, spec 원칙, 절대 규칙 12개)
└── references/
    └── commands.md           # 명령 문법, 트러블슈팅 13건, 쿼터

명령 레퍼런스를 분리한 이유는 버전이 올라가면 그 파일만 교체하면 되기 때문입니다. 절차는 버전과 무관하게 유효합니다.

---

이 스킬이 강제하는 것

---

알려진 빌드 특성 (1.4.161)

실측으로 확인한 것들입니다. 공식 문서에 없습니다.

ready 승격이 소급되지 않음

의존성 해소는 선행 Task 완료 시점의 이벤트로만 발생합니다. 이미 완료된 Task에 --deps를 걸어 새 Task를 만들면 영구히 pending에 머뭅니다.

Task task_xxx is pending; only ready tasks can be dispatched

복구: orca orchestration task-update --id --status ready --json 예방: DAG 전체를 dispatch 전에 한 번에 생성

프리앰블이 게이트 결정을 싣지 않음

--inject 프리앰블에 게이트 해소 내용이 포함되지 않고, task-update에 --spec도 없어 사후 수정이 불가능합니다.

해법 (4단계 순서 준수):

1. gate-create → gate-resolve
2. 워커에게 확정문 릴레이 ("아직 작업하지 말고 접수만 하라")
3. 워커의 접수 확인
4. 정식 dispatch --inject

---

쓰지 말아야 할 때

• 수정할 파일이 1~2개
• Task로 쪼갤 것이 3개 미만
• 빌드가 매우 무거워 워커들이 빌드 자원을 두고 계속 충돌하는 프로젝트
• “넘겨줘 / handoff / 다른 에이전트에게 줘” — 소유권 이전이며 감독형이 아님

스킬이 이 조건을 감지하면 스스로 물러납니다. 강제로 쓰려면 "작아도 오케스트레이션으로 해줘"라고 명시하세요.

---

비용

에이전트 수에 비례해 쿼터를 소모합니다.

멀티 프로바이더 배분은 스타일이 아니라 쿼터 관리 수단입니다. 코디네이터만 최상위 모델을 쓰고 워커는 하위 모델로 배치하는 방식을 권장합니다.

---

제약

• Orca 오케스트레이션은 실험적 기능입니다. 버전 간 명령 표면이 바뀝니다.
• 이 스킬은 1.4.161 기준입니다. 버전이 다르면 orca skills get orchestration --full과 orca agent-context --json의 출력이 우선합니다. 스킬 내부에도 이 우선순위가 명시돼 있습니다.
• 실패 경로(escalation, 재시도, 회로 차단)는 아직 실측 검증되지 않았습니다.

---

라이선스

MIT