에이전트 패턴
개요
Agent Patterns은 Sprint 플러그인 내에서 다중 에이전트 스프린트 실행을 위한 조정 프로토콜을 정의합니다. 이는 프로젝트 아키텍트가 구현 및 테스트 에이전트를 생성하는 방법, 에이전트가 구조화된 보고서를 통해 결과를 전달하는 방법, 그리고 병렬 에이전트가 충돌을 방지하는 방법을 제어합니다.
전제 조건
- Sprint 플러그인이 설치 및 구성되어 있어야 합니다 (
/plugin install sprint) - Sprint 디렉토리가
.claude/sprint/[N]/에 초기화되어 있어야 합니다 specs.md가 명확한 범위와 테스트 구성으로 작성되어 있어야 합니다- Sprint 단계 수명 주기에 대한 이해가 필요합니다 (
sprint-workflow스킬 참조)
지침
- 모든 에이전트 생성을 SPAWN REQUEST 형식을 사용하여 구조화하세요. 에이전트 이름, 읽어야 할 사양 파일, 범위 제약 조건을 포함합니다:
SPAWN REQUEST Agent: python-dev Specs: .claude/sprint/1/backend-specs.md Contract: .claude/sprint/1/api-contract.md Scope: 인증 엔드포인트만 - 생성된 각 에이전트가 자신의 범위에 관련된 파일만 받도록 하세요. 백엔드와 프론트엔드 에이전트가 동기화 상태를 유지하도록
api-contract.md를 공유 인터페이스로 전달하세요. - 완료된 모든 에이전트로부터 구조화된 보고서를 수집하세요. 각 보고서에는 완료된 작업, 수정된 파일, 추가된 테스트, 사양에 대한 적합성 상태가 포함되어야 합니다.
- 병렬로 에이전트를 실행할 때는 도메인 경계(예: 백엔드 vs 프론트엔드 vs CI/CD)를 기준으로 작업을 분할하세요. 동시 에이전트에 중복되는 파일 경로를 절대 할당하지 마세요.
- 에이전트 보고서를 검토를 위해 프로젝트 아키텍트에게 전달하세요. 아키텍트는 반복(범위를 좁혀 다시 생성)하거나 다음 단계로 진행할지 결정합니다.
- 테스트 에이전트의 경우,
${CLAUDE_SKILL_DIR}/references/ui-test-report.md에 표시된 UI 테스트 보고서 형식을 전달하여 결과가 테스트 개수, 커버리지, 실패, 콘솔 오류를 포함한 일관된 스키마를 따르도록 하세요.
출력
- 스프린트 오케스트레이터가 에이전트를 실행하기 위해 소비하는 SPAWN REQUEST 블록
- 요약, 변경된 파일, 테스트 결과, 적합성 상태를 포함한 구조화된 에이전트 보고서
- 통과/실패 개수, 커버리지 세부 정보, 실패 설명, 콘솔 오류 로그를 포함한 UI 테스트 보고서
- 각 반복 후 완료 및 남은 작업을 반영하는 업데이트된
status.md
오류 처리
| 오류 | 원인 | 해결책 |
|---|---|---|
| 에이전트가 잘못된 사양 파일을 받음 | SPAWN REQUEST의 경로가 올바르지 않음 | 생선 전에 스프린트 디렉토리 번호와 파일 이름을 확인하세요 |
| 병렬 에이전트의 중복 파일 수정 | 범위 경계가 명확하게 정의되지 않음 | 도메인별로 작업을 분할하고 각 에이전트에 별도 디렉토리를 할당하세요 |
| 에이전트 보고서에 필수 필드 누락 | 에이전트 지침에 보고서 형식이 없음 | 구조화된 보고서 템플릿을 에이전트 프롬프트에 포함하세요 |
| 무한 반복 루프 | 사양이 완전히 충족되지 않음 | status.md에서 차단 문제를 확인하세요. 오케스트레이터는 5회 반복 후 중단됩니다 |
| 에이전트를 찾을 수 없음 | SPAWN REQUEST의 에이전트 이름이 잘못 입력됨 | agents/ 디렉토리에 에이전트 마크다운 파일이 존재하는지 확인하세요 |
예제
병렬 구현 에이전트 생성:
SPAWN REQUEST
Agent: python-dev
Specs: .claude/sprint/1/backend-specs.md
Contract: .claude/sprint/1/api-contract.md
SPAWN REQUEST
Agent: nextjs-dev
Specs: .claude/sprint/1/frontend-specs.md
Contract: .claude/sprint/1/api-contract.md
두 에이전트 모두 동일한 api-contract.md를 사용하여 API 호환성을 보장합니다.
구조화된 에이전트 보고서 형식:
AGENT REPORT
Agent: python-dev
Status: COMPLETE
Files Modified: src/auth/routes.py, src/auth/models.py, tests/test_auth.py
Tests: 12 passed, 0 failed
Conformity: 모든 backend-specs 요구 사항 구현됨
Notes: JWT 토큰 만료 시간은 사양에 따라 24시간으로 설정됨
테스트 에이전트 조정:
SPAWN REQUEST
Agent: qa-test-agent
Specs: .claude/sprint/1/specs.md
Run After: python-dev, nextjs-dev
SPAWN REQUEST
Agent: ui-test-agent
Specs: .claude/sprint/1/specs.md
Run After: qa-test-agent
리소스
${CLAUDE_SKILL_DIR}/references/ui-test-report.md-- 커버리지 및 실패 추적을 포함한 구조화된 UI 테스트 보고서 형식- 단계 수명 주기 컨텍스트를 위한 Sprint 워크플로우 스킬
- 공유 인터페이스 설계를 위한 API 계약 스킬
- 에이전트 아키텍처 개요를 위한 Sprint 플러그인 README