requirements-review

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

완료 확인

각 서브에이전트 실행 후 다음을 모두 만족하면 성공으로 판정한다:

1. 서브에이전트가 "done"을 반환
2. docs/requirements-review-agent-{file_number}.md 파일이 실제로 존재
3. 파일이 비어있지 않고 "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: 답변 검증

사용자가 완료를 알리면:

1. 질문 파일을 Read로 읽고 모든 [Answer]: 태그의 답변을 추출
2. 미답변 항목이 있으면 사용자에게 구체적으로 알리고 질문 파일에 다시 답해달라고 요청 → 사용자 완료 신호 시 1번부터 재실행
3. 유효하지 않은 답변(선택지에 없는 문자)이 있으면 사용자에게 구체적으로 알리고 질문 파일에 다시 답해달라고 요청 → 사용자 완료 신호 시 1번부터 재실행
4. 답변 간 모순이 있으면 사용자에게 모순 내용을 구체적으로 알리고 질문 파일에 다시 답해달라고 요청 → 사용자 완료 신호 시 1번부터 재실행

모든 답변이 유효하고 모순이 없을 때 Phase 4로 진행.

재답변 요청 시에는 별도의 clarification 파일을 만들지 않는다. 동일한 질문 파일을 그대로 재사용한다.

Phase 4: Requirements 문서 적용

⚠️ Phase 4는 Requirements 문서를 직접 수정합니다. 실행 전에 git commit 또는 파일 백업을 권장합니다. Git 저장소에서 실행되었다면 git diff로 변경 사항을 확인할 수 있습니다.

메인에이전트가 직접 검증된 답변을 기반으로 Requirements 문서를 수정한다.

적용 규칙

1. 각 질문의 답변에 따라 해당 이슈의 해결 방안을 Requirements 문서에 반영
2. 수정 시 새로운 모순을 만들지 않도록 관련 요구사항을 교차 확인
3. 원본 문서가 EARS 형식을 따르는 경우에만 EARS 형식을 준수하여 수정 (WHEN/THEN/SHALL, IF/THEN/SHALL 등). 비-EARS 구조 문서는 원본 스타일을 따른다
4. Other 답변은 사용자가 기술한 내용을 충실히 반영
5. 수정 완료 후 변경 사항 요약을 사용자에게 보고

변경 사항 보고 형식

## Requirements 문서 수정 완료

### 적용된 변경 사항
| # | 이슈 | 사용자 선택 | 적용 내용 |
|---|------|-----------|----------|

### 수정된 요구사항
- 요구사항 X: {변경 요약}
- 요구사항 Y: {변경 요약}

### 참고 사항
(수정 시 발견된 추가 고려사항이 있으면 기술)