| name | requirements-review |
| description | Requirements 문서를 서브에이전트 3명이 독립 리뷰하고, 가중 투표로 취합한 뒤, 사용자에게 해결 방향을 질문하여 Requirements 문서에 반영합니다. |
| argument-hint | <requirements파일경로> |
| disable-model-invocation | true |
Requirements 문서 리뷰
입력
$ARGUMENTS (requirements 파일 경로)
- 파일이 존재하는지 확인. 없으면 에러 출력 후 종료.
- 아래 3개 helper 파일이 스킬 디렉토리에 존재하는지 확인. 하나라도 없으면 에러 출력 후 종료:
${CLAUDE_SKILL_DIR}/review-requirements-prompt.md${CLAUDE_SKILL_DIR}/aggregation-rules.md${CLAUDE_SKILL_DIR}/question-generation-rules.md
스킬 준비 (필수)
Phase 진입 전에 메인에이전트는 아래 3개 helper 파일을 Read 도구로 반드시 읽어 context에 로드한다. 이 파일들은 자동 로드되지 않는다.
${CLAUDE_SKILL_DIR}/review-requirements-prompt.md — Phase 1 sub-agent 리뷰 지시문 전체${CLAUDE_SKILL_DIR}/aggregation-rules.md — Phase 1 취합 절차${CLAUDE_SKILL_DIR}/question-generation-rules.md — Phase 2 질문 생성 절차
Sub-agent는 부모 skill 컨텍스트를 상속하지 않는다. 따라서 Phase 1에서 sub-agent를 호출할 때는 review-requirements-prompt.md의 전체 내용을 프롬프트 문자열에 직접 인라인 주입해야 한다 (markdown 링크는 sub-agent가 resolve 할 수 없다).
역할 분담
- 서브에이전트: Phase 1 독립 리뷰 3회만 담당 (병렬 실행, 독립성 유지)
- 메인에이전트: 취합, 질문 생성, 답변 검증, Requirements 문서 수정을 직접 수행
docs/ 디렉토리가 없으면 사용자 프로젝트 루트에 먼저 mkdir -p docs 로 생성한다.
Phase 1: 리뷰 및 취합
서브에이전트 파일 번호 결정
docs/requirements-review-agent-*.md 패턴으로 기존 파일을 Glob/Bash ls로 검색하여 가장 높은 번호를 찾는다. 이 값을 {agent_start_idx} 로 기록한다.
- 기존 파일이 없으면
{agent_start_idx} = 1
- 기존 파일이 있으면
{agent_start_idx} = (가장 높은 번호 + 1)
- 예: 기존에 1,2,3이 있으면 → 4,5,6 / 기존에 4,5,6이 있으면 → 7,8,9
서브에이전트 3명을 병렬로 실행
서브에이전트 3명을 병렬로 호출한다. 독립성 유지를 위해 다음 금지 사항을 지킨다:
- ❌ 한 서브에이전트의 출력을 다른 서브에이전트에게 전달
- ❌ 프롬프트에 다른 리뷰어를 언급
- ❌ 뒤 리뷰어가 앞 리뷰어의 출력 파일을 읽도록 허용
각 서브에이전트에게 다음 구성의 프롬프트 문자열을 전달한다. 변수는 실제 값으로 치환한다:
<review-requirements-prompt.md 전체 내용을 여기에 인라인 주입>
=== 실행 파라미터 ===
리뷰 대상 requirements 파일 경로: {requirements_file_path}
결과 저장 경로: docs/requirements-review-agent-{file_number}.md
=== 작업 순서 ===
1. 위 리뷰 대상 파일을 Read 도구로 읽는다
2. 8가지 관점(EARS 형식 준수, 요구사항 완전성, 요구사항 명확성, 요구사항 간 일관성, 테스트 가능성, 사용자 스토리 적절성, 범위 적절성, 비기능 및 제약 요건 식별)으로 리뷰한다
3. 이슈마다 ISS-번호, 심각도(CRITICAL/MAJOR/MINOR), 확신도(1-10), 근거강도(1-5), 원문 인용, 제안을 기술한다
4. 결과를 위 "결과 저장 경로"에 Write 도구로 저장한다
5. 저장 완료 후 "done"을 반환한다
- 치환 변수:
{requirements_file_path} ← $ARGUMENTS{file_number} ← 서브에이전트마다 {agent_start_idx}, {agent_start_idx}+1, {agent_start_idx}+2
완료 확인
각 서브에이전트 실행 후 다음을 모두 만족하면 성공으로 판정한다:
- 서브에이전트가 "done"을 반환
docs/requirements-review-agent-{file_number}.md 파일이 실제로 존재- 파일이 비어있지 않고 "ISS-" 로 시작하는 이슈 블록이 최소 1개 이상 포함 (또는 "이슈 없음" 명시)
실패 시 대응:
- 1명이 실패하면 나머지 2명으로 진행하고 최종 리포트 상단에
"Reviewer X 실패 — N=2로 집계됨" 명시
- 2명 이상 실패하면 사용자에게 중단 보고
- 같은 실패한 서브에이전트를 동일 프롬프트로 재시도하지 않는다
취합 (메인에이전트가 직접 수행)
docs/requirements-review-aggregated-v*.md 패턴으로 기존 파일을 검색하여 가장 높은 버전을 찾는다. 이 값을 {aggregated_ver} 로 기록한다.
- 기존 파일이 없으면
{aggregated_ver} = 1
- 기존 파일이 있으면
{aggregated_ver} = (가장 높은 버전 + 1)
3명 모두 완료 후, 메인에이전트가 직접 3개 파일을 Read로 읽고, 스킬 준비 단계에서 로드한 aggregation-rules.md의 절차로 취합한다. 취합 결과를 docs/requirements-review-aggregated-v{aggregated_ver}.md 에 저장한다.
Phase 2: 질문 생성
docs/requirements-review-questions-v*.md 패턴으로 기존 파일을 검색하여 가장 높은 버전을 찾는다. 이 값을 {questions_ver} 로 기록한다 (기존 없으면 1, 있으면 +1).
메인에이전트가 직접 aggregated-v{aggregated_ver}.md에서 🔴 High Confidence와 🟡 Needs Review 이슈 중 CRITICAL/MAJOR 심각도만 추출하여, 스킬 준비 단계에서 로드한 question-generation-rules.md의 절차에 따라 질문 파일을 생성한다.
- 파일명:
docs/requirements-review-questions-v{questions_ver}.md
- 생성된 질문 개수를
{question_count} 로 기록한다
사용자 안내
질문 파일 생성 후 사용자에게 다음을 전달:
리뷰 결과를 바탕으로 {question_count}개의 질문을 생성했습니다.
docs/requirements-review-questions-v{questions_ver}.md 파일에서
각 질문의 `[Answer]:` 태그 뒤에 선택한 알파벳을 입력해 주세요.
Other를 선택하시면 원하는 내용을 직접 설명해 주세요.
완료되면 알려주세요.
답변 대기
사용자가 "done", "완료", "finished", "답변했습니다" 등으로 완료를 알릴 때까지 대기. 진행하지 말 것.
Phase 3: 답변 검증
사용자가 완료를 알리면:
- 질문 파일을 Read로 읽고 모든
[Answer]: 태그의 답변을 추출
- 미답변 항목이 있으면 사용자에게 구체적으로 알리고 질문 파일에 다시 답해달라고 요청 → 사용자 완료 신호 시 1번부터 재실행
- 유효하지 않은 답변(선택지에 없는 문자)이 있으면 사용자에게 구체적으로 알리고 질문 파일에 다시 답해달라고 요청 → 사용자 완료 신호 시 1번부터 재실행
- 답변 간 모순이 있으면 사용자에게 모순 내용을 구체적으로 알리고 질문 파일에 다시 답해달라고 요청 → 사용자 완료 신호 시 1번부터 재실행
모든 답변이 유효하고 모순이 없을 때 Phase 4로 진행.
재답변 요청 시에는 별도의 clarification 파일을 만들지 않는다. 동일한 질문 파일을 그대로 재사용한다.
Phase 4: Requirements 문서 적용
⚠️ Phase 4는 Requirements 문서를 직접 수정합니다. 실행 전에 git commit 또는 파일 백업을 권장합니다. Git 저장소에서 실행되었다면 git diff로 변경 사항을 확인할 수 있습니다.
메인에이전트가 직접 검증된 답변을 기반으로 Requirements 문서를 수정한다.
적용 규칙
- 각 질문의 답변에 따라 해당 이슈의 해결 방안을 Requirements 문서에 반영
- 수정 시 새로운 모순을 만들지 않도록 관련 요구사항을 교차 확인
- 원본 문서가 EARS 형식을 따르는 경우에만 EARS 형식을 준수하여 수정 (WHEN/THEN/SHALL, IF/THEN/SHALL 등). 비-EARS 구조 문서는 원본 스타일을 따른다
- Other 답변은 사용자가 기술한 내용을 충실히 반영
- 수정 완료 후 변경 사항 요약을 사용자에게 보고
변경 사항 보고 형식
## Requirements 문서 수정 완료
### 적용된 변경 사항
| # | 이슈 | 사용자 선택 | 적용 내용 |
|---|------|-----------|----------|
### 수정된 요구사항
- 요구사항 X: {변경 요약}
- 요구사항 Y: {변경 요약}
### 참고 사항
(수정 시 발견된 추가 고려사항이 있으면 기술)
