| name | be-orchestrate |
| description | JamPlay 백엔드 작업을 Notion API 동기화→설계→구현→QA 4단계로 오케스트레이션하는 스킬. "API 추가해줘", "모듈 구현해줘", "기능 개발해줘", "백엔드 작업해줘", "Service 메서드 추가", "Repository 수정", "다시 해줘", "수정해줘", "재실행", "이전 결과 기반으로 보완해줘", "[모듈]만 다시" 등 백엔드 기능 구현 및 후속 작업 요청 시 반드시 이 스킬을 사용한다. 단순 질문·코드 설명·하네스 설정 변경은 트리거하지 않는다. |
Be-Orchestrate — 백엔드 오케스트레이션 스킬
백엔드 작업을 Notion API 동기화 → 설계 → 구현 → QA 4단계로 수행한다.
be-api-sync, be-designer, be-qa 서브 에이전트를 조율하며 하네스 규칙 준수를 보장한다.
Phase 0: 컨텍스트 확인
_workspace/ 디렉토리 존재 여부로 실행 모드를 결정한다:
| 상황 | 처리 |
|---|
_workspace/ 미존재 | 초기 실행 → Phase 1부터 |
_workspace/ 존재 + 부분 수정 요청 | 부분 재실행 → 해당 Phase만 |
_workspace/ 존재 + 새 작업 요청 | 이전 작업이 완료되지 않은 것. 사용자에게 알리고 _workspace/를 삭제한 뒤 Phase 1부터 시작 |
Phase 1: API 문서 동기화 (be-api-sync 서브 에이전트)
docs/backend/api-docs/{module}.md가 없거나 사용자가 갱신을 원하면 be-api-sync 서브 에이전트를 실행한다. 실행 전 .claude/agents/be-api-sync.md를 읽는다.
Agent({
subagent_type: "be-api-sync",
model: "sonnet",
description: "Notion API 명세 동기화",
prompt: `
{모듈명} 모듈의 API 명세를 Notion에서 가져와 docs/backend/api-docs/{모듈명}.md에 저장하라.
.claude/agents/be-api-sync.md의 동기화 프로세스를 따르라.
`
})
이미 docs/backend/api-docs/{module}.md가 존재하고 사용자가 갱신을 요청하지 않았으면 이 Phase를 건너뛴다.
Gap 리포트 처리:
be-api-sync가 보완 필요 항목을 보고하면 사용자에게 제시하고 진행 방식을 확인한다:
- "사용자 확인 필요" 항목이 있으면 → 사용자가 Notion을 업데이트하거나 직접 내용을 제공할 때까지 대기
- "자동 보완 가능" 항목만 있으면 → 설계 단계에서 자동 보완 진행을 알리고 Phase 2로 이동
Phase 2: 설계 (be-designer 서브 에이전트)
be-designer 서브 에이전트를 실행한다. 실행 전 .claude/agents/be-designer.md를 읽는다.
Agent({
subagent_type: "be-designer",
model: "sonnet",
description: "백엔드 모듈 설계",
prompt: `
다음 작업을 설계하라: {사용자 요청 내용}
반드시:
1. docs/backend/api-docs/{모듈명}.md를 읽고 API 명세를 검증하라
2. CLAUDE.md의 모듈 문서 테이블에서 관련 모듈 doc을 찾아 읽어라
3. prisma/schema.prisma에서 관련 모델을 확인하라
4. .claude/agents/be-designer.md의 설계 문서 구조를 따라 _workspace/design.md를 작성하라
`
})
설계 완료 후 _workspace/design.md를 사용자에게 제시하고 승인을 받는다.
API 명세와 사용자 요청이 충돌하면 설계자가 불일치 내용을 명시한 것을 확인하고 사용자에게 처리 방향을 확인받는다.
승인 없이 구현을 시작하지 않는다.
Phase 3: 구현
사용자 승인 후 _workspace/design.md의 작업 범위와 설계를 기반으로 구현한다.
구현 중 확인:
- 설계의 Repository 인터페이스와 Service 비즈니스 규칙을 그대로 따른다
- 스키마 변경이 있으면
pnpm run prisma:generate를 실행한다
- 설계와 다르게 구현해야 할 이유가 생기면 사용자에게 먼저 보고한다
Phase 4: QA (be-qa 서브 에이전트)
구현 완료 후 be-qa 서브 에이전트를 실행한다. 실행 전 .claude/agents/be-qa.md를 읽는다.
Agent({
subagent_type: "be-qa",
model: "sonnet",
description: "백엔드 QA 검증",
prompt: `
구현된 코드를 검증하라.
반드시:
1. git diff --name-only HEAD로 변경 파일을 확인하라
2. _workspace/design.md의 설계와 실제 구현의 일치 여부를 확인하라
3. .claude/agents/be-qa.md의 하네스 체크리스트를 실행하라
4. sh ./scripts/verify.sh를 실행하라
5. QA 리포트 형식으로 결과를 보고하라
`
})
QA 실패 항목이 있으면 수정 후 QA를 재실행한다. verify.sh를 통과해야만 작업을 완료로 선언한다.
QA 통과 후 설계 문서 보관:
verify.sh가 통과하면 _workspace/design.md를 docs/backend/designs/{module}/{feature}.md로 이동하고 _workspace/를 삭제한다.
{module}: 작업 대상 모듈명 (예: users, spaces){feature}: 작업 내용을 kebab-case로 표현한 이름 (예: update-nickname, create-space)- 파일명은 설계 내용을 기반으로 자동 결정한다
docs/backend/designs/{module}/ 디렉토리가 없으면 생성한다- 이동 후
_workspace/ 디렉토리를 삭제한다
에러 핸들링
| 상황 | 처리 |
|---|
| API 동기화 실패 (Notion 페이지 없음) | 사용자에게 URL/ID 요청. 없으면 설계자가 사용자 요청만으로 설계 |
| 설계자 에러 | 사용자에게 보고 후 재설계 여부 확인 |
| API 명세-요청 불일치 | 설계자가 불일치 명시 → 사용자에게 처리 방향 확인 |
| QA 실패 | 실패 항목 수정 → QA 재실행 |
| verify.sh 실패 | 에러 내용 분석 → 수정 → 재실행. 2회 연속 실패 시 사용자에게 보고 |
테스트 시나리오
정상 흐름: users 모듈에 닉네임 수정 API 추가해줘 → Notion 명세 동기화 → 설계 생성 → 승인 → 구현 → QA 통과 → 완료
API 명세 없음: spaces 모듈 구현해줘 + Notion 검색 실패 → 사용자에게 URL 요청 → URL 입력 → 동기화 → 설계 → 구현 → QA
재실행: 설계 수정해줘 → _workspace/design.md 존재 확인 → 설계자 재실행 → 수정된 설계 제시
