---
description: 요구사항을 체크리스트로 구조화하고 구현 충실도를 검증한다. 구현 전 요구사항을 [REQ-카테고리-번호] ID로 추출해 체크리스트를 만들고(checklist 모드), 구현 후 diff와 대조해 커버리지 갭을 심각도별로 보고한다(verify 모드). "요구사항 검증", "구현 충실도 확인", "요구사항 체크리스트", "스펙 커버리지", "구현이 요구를 만족하는지", "requirement verification", "spec compliance" 요청에서 사용한다. 데이터 흐름 정합성은 devoks-sdlc:verify-data-flow, 코드 품질 리뷰는 devoks-sdlc:code-review-diff-branch, 실제 앱 조작을 통한 실동작 확인은 devoks-sdlc:verify-acceptance-test 를 쓴다.
metadata:
  author: ridsync
  version: 1.0.2
---

# verify-requirements — 요구사항 체크리스트·구현 충실도 검증

기능 구현 전 **요구사항을 체크리스트로 구조화**하고, 구현 완료 후 **코드와 요구사항의 충실도를 체계적으로 검증**한다. 두 단계가 동일한 추적 ID(`[REQ-카테고리-번호]`)를 공유해 사전-사후가 연결된 하나의 검증 워크플로우를 구성한다.

---

## 범위 (중요)

**한다:**
- 요구사항 문서에서 항목을 추출해 추적 가능한 체크리스트 생성(checklist 모드).
- 구현 diff를 체크리스트와 대조해 구현/부분/미구현 분류 및 심각도별 갭 보고(verify 모드).

**안 한다:**
- 코드 자동 수정(갭 보고만, 보완 진행은 사용자 승인 후).
- 데이터 값 정합성 실측 → `devoks-sdlc:verify-data-flow`.
- 코드 품질·보안 리뷰 → `devoks-sdlc:code-review-diff-branch`, `devoks-sdlc:code-security-review`.
- 실제 앱을 조작한 실동작 확인(UI 조작+상태 영속) → `devoks-sdlc:verify-acceptance-test`.

---

## 호출 방법

```
/devoks-sdlc:verify-requirements [mode=checklist|verify] [spec=<요구사항 문서 경로>]
```

| 모드 | 시점 | 목적 |
|------|------|------|
| `mode=checklist` | 구현 시작 전 | 요구사항 추출 → 구현 목표 체크리스트 생성 |
| `mode=verify` (기본) | 구현 완료 후 | 체크리스트 + diff traceability → 커버리지 갭 보고 |

`spec` 로 요구사항 문서 경로를 직접 지정할 수 있다. 미지정 시 자동 탐색한다.

---

## 공통 Steps (두 모드 모두 실행)

### S1. 모드 판별

`mode=checklist` 면 **체크리스트 생성 모드**, `mode=verify` 또는 미지정이면 **구현 검증 모드**로 분기한다.

### S2. 요구사항 문서 탐색 및 로딩

1. **`spec` 인자 확인** — 지정된 경로를 요구사항 문서로 해석한다.
2. **자동 탐색** — 경로가 없으면 다음 위치를 순서대로 탐색한다:
   - `.claude/workspace/` — PRD, 워크플로우, 비즈니스 로직 SSOT
   - `.claude/plans/` — 구현 플랜 파일 (가장 최신 플랜 우선)
   - `doc/` — 기타 아키텍처/기능 문서
3. **브랜치명 키워드 매칭** — `git branch --show-current` 결과로 관련 문서를 좁힌다.
4. 탐색된 문서 목록을 출력하고, 추가/제외가 필요하면 사용자에게 한 줄 확인 후 진행한다.

### S3. 참조 문서 로딩

다음 문서를 읽고 검증 기준으로 적용한다:
- `.claude/refs/engineering-principles.md` — SSOT, Contract Validation, Fail-Fast 원칙
- `.claude/rules/agent-principles.md` — Spec Compliance, Fail Fast 정의
- `.claude/CLAUDE.md` — 도메인 용어, 아키텍처 개요

### S4. 요구사항 체크리스트 추출

요구사항 문서에서 다음 5개 카테고리로 항목을 추출하고 `[REQ-카테고리-번호]` ID를 부여한다.

| 카테고리 (약어) | 추출 대상 예시 |
|----------------|---------------|
| **기능 요구사항** (F) | 스텝 분기, 버튼 동작, 자동 진행 조건 |
| **비즈니스 로직** (B) | 임계값 계산식, PASS 판정 조건, 보정값 적용 순서 |
| **UI/UX 사양** (U) | 화면 레이아웃, i18n 키, 버튼 활성 조건, 색상 인디케이터 |
| **엣지케이스·에러처리** (E) | 최대 재시도 횟수, 에러 모달 분기, max cycle 처리 |
| **데이터·상태 계약** (D) | 저장 대상 키, 누적 방향, 동기화 조건 |

추적 ID 예시: `[REQ-F-01]`, `[REQ-B-03]`, `[REQ-U-02]`

---

## 체크리스트 생성 모드 전용 Steps (`mode=checklist`)

### C1. 체크리스트 출력

S4에서 추출한 항목을 카테고리별로 정렬하고 아래 **체크리스트 생성 템플릿**으로 출력한다.  
각 항목은 `[ ]` 체크박스 형식 — 구현자가 직접 체크하며 진행할 수 있도록 한다.

### C2. 체크리스트 파일 저장

체크리스트를 다음 경로에 파일로 저장한다:

```
.claude/workspace/checklists/<feature-name>.md
```

- `<feature-name>` 은 `$ARGUMENTS`의 요구사항문서를 확인하고 적절한 {feature-name}-{date} 형식으로 작성한다.
- `.claude/workspace/checklists/` 디렉토리가 없으면 생성한다.
- 파일이 이미 존재하면 덮어쓰기 전 사용자에게 한 줄 확인한다.

### C3. 구현 준비 확인

체크리스트 저장 후 사용자에게 다음을 확인한다:
- 누락된 항목이 있으면 추가 (파일도 함께 갱신)
- 범위에서 제외할 항목이 있으면 표시 (파일도 함께 갱신)
- 저장 경로를 안내하고 구현을 시작하도록 안내

---

## 구현 검증 모드 전용 Steps (기본)

### V0. 기존 체크리스트 파일 확인

`.claude/workspace/checklists/<feature-name>.md` 파일이 존재하는지 확인한다.

- **파일이 있으면** → 해당 파일을 로드해 `[REQ-*]` ID 목록을 재사용한다. S4(요구사항 재추출)를 건너뛴다.
- **파일이 없으면** → S4에서 요구사항 문서를 재추출해 ID를 새로 생성한다.

### V1. 브랜치 변경 범위 확보

1. `git log --oneline <base>..HEAD` — 커밋 목록 (변경 의도 파악)
2. `git diff <base>...HEAD --name-only` — 변경 파일 목록
3. 필요 시 `git diff <base>...HEAD` — 상세 diff (구현 위치 매핑용)

### V2. 구현 추적 (Traceability Mapping)

S4에서 추출한 각 요구사항 항목에 대해:
1. diff 및 변경 파일에서 **구현 위치(파일:라인)** 를 찾는다.
2. 다음 3가지 상태로 분류한다:
   - ✅ **구현 완료** — 요구사항과 코드가 일치
   - ⚠️ **부분 구현** — 일부만 구현되었거나 의도와 다르게 구현됨
   - ❌ **미구현** — 코드에서 대응 구현을 찾을 수 없음
3. 부분/미구현 항목은 아래 심각도 기준으로 판정한다.

### V3. 심각도 판정 기준

> 심각도 분류 SSOT: `.claude/refs/code-review.md §8`. 아래는 요구사항 커버리지 갭 맥락으로 좁힌 특수화이며, SSOT의 일반 정의(보안/데이터손실/시스템오류 등)와 축은 동일하다.

| 심각도 | 기준 |
|--------|------|
| 🔴 Critical | 핵심 비즈니스 로직 미구현, 데이터 손실/오염 위험, 보안 계약 위반 |
| 🟠 High | 주요 기능 요구사항 누락, 잘못된 알고리즘/수식 구현, 상태 기계 분기 오류 |
| 🟡 Medium | UI 사양 불일치, i18n 키 누락, 엣지 케이스 미처리, 부분적 구현 |
| 🔵 Low | 문서와 다른 변수명·주석, 로깅 누락, 미세 레이아웃 차이 |

### V4. 충실도 보고서 출력

아래 **구현 검증 템플릿**으로 작성한다.  
**템플릿에 포함된 이모지(📋 🧭 ✅ ⚠️ ❌ 📐 🔍 🔴 🟠 🟡 🔵 📊 🚀)를 반드시 그대로 포함하여 출력한다.**

### V5. 보완 진행 여부 확인

보고서 출력 후 사용자에게 반영 범위를 확인한다:
- 전체 반영 / High 이상 / Medium 이상 / Low 이상 4가지 선택지
- 확인이 필요한 사항이 있으면 먼저 질문하고 계획을 세운다.

---

## 출력 템플릿 — 체크리스트 생성 모드 (`mode=checklist`)

```markdown
## 📋 구현 체크리스트
- 브랜치: feat/xxx
- 참조 요구사항 문서: (문서 경로 목록)
- 추출 항목 수: N개 (기능 N / 비즈니스로직 N / UI N / 엣지케이스 N / 데이터계약 N)
- 저장 위치: `.claude/workspace/checklists/feat-xxx.md`

---

## 🏗️ 기능 요구사항 (F)

- [ ] [REQ-F-01] (요구사항 항목 한줄 요약)
- [ ] [REQ-F-02] ...

## ⚙️ 비즈니스 로직 (B)

- [ ] [REQ-B-01] (알고리즘/수식/판정 조건 한줄 요약)
- [ ] [REQ-B-02] ...

## 🖼️ UI/UX 사양 (U)

- [ ] [REQ-U-01] (화면/컴포넌트/i18n 한줄 요약)
- [ ] [REQ-U-02] ...

## 🚨 엣지케이스·에러처리 (E)

- [ ] [REQ-E-01] (에러/분기 조건 한줄 요약)
- [ ] [REQ-E-02] ...

## 💾 데이터·상태 계약 (D)

- [ ] [REQ-D-01] (저장 키/동기화 조건 한줄 요약)
- [ ] [REQ-D-02] ...

---

## 🚀 다음 단계
- 위 체크리스트를 기준으로 구현을 진행한다.
- 구현 완료 후 `/devoks-sdlc:verify-requirements mode=verify` (구현 검증 모드)로 커버리지를 확인한다.
```

---

## 출력 템플릿 — 구현 검증 모드 (기본)

```markdown
## 📋 검증 대상
- 브랜치: feat/xxx → main
- 참조 요구사항 문서: (문서 경로 목록)
- 추출 요구사항 항목 수: N개 (기능 N / 비즈니스로직 N / UI N / 엣지케이스 N / 데이터계약 N)
- 변경 파일: N개

## 🧭 전체 평가
- 결과: ✅ 충실 / ⚠️ 부분 충실 / ❌ 갭 존재
- 커버리지: N/N항목 구현 완료 (N%)
- 한줄 요약:

## 📐 요구사항 커버리지

| 카테고리 | 전체 | ✅ 완료 | ⚠️ 부분 | ❌ 누락 |
|----------|------|---------|---------|---------|
| 기능 요구사항 (F) | N | N | N | N |
| 비즈니스 로직 (B) | N | N | N | N |
| UI/UX 사양 (U) | N | N | N | N |
| 엣지케이스·에러처리 (E) | N | N | N | N |
| 데이터·상태 계약 (D) | N | N | N | N |
| **합계** | **N** | **N** | **N** | **N** |

## ✅ 구현 완료 항목 (주요)

1. [REQ-F-01] 항목 요약 — `파일명:라인범위`
2. ...

---

## 🔍 갭 목록 (심각도 순)

## 🔴 Critical (즉시 수정)

### [REQ-xxx] [항목 제목]
- 요구사항: (문서에 명시된 내용)
- 현재 구현: (구현 상태 또는 미구현)
- 영향: (미구현 시 발생하는 문제)
- 권장: (수정 방향)
- 위치: `파일명:라인번호` (또는 "구현 없음")

---

## 🟠 High (필수 수정)

### [REQ-xxx] [항목 제목]
- 요구사항:
- 현재 구현:
- 권장:
- 위치:

---

## 🟡 Medium (권장 수정)

### [REQ-xxx] [항목 제목]
- 요구사항:
- 현재 구현:
- 권장:
- 위치:

---

## 🔵 Low (선택 개선)

### [REQ-xxx] [항목 제목]
- 요구사항:
- 현재 구현:
- 권장:
- 위치:

## 📊 갭 요약

| 심각도 | 개수 | 조치 |
|--------|------|------|
| 🔴 Critical | N | 즉시 수정 |
| 🟠 High | N | 필수 수정 |
| 🟡 Medium | N | 권장 수정 |
| 🔵 Low | N | 선택 |

---

## 🚀 다음 액션 제안
- 즉시:
- 다음 배치:
- 보류:
```

---

## 참고

- **권장 워크플로우**:
  1. 구현 전 → `/devoks-sdlc:verify-requirements mode=checklist` — 구현 목표 체크리스트 확보
  2. 구현 후 → `/devoks-sdlc:verify-requirements mode=verify` — 커버리지 갭 검증
  3. 코드 품질 → `/devoks-sdlc:code-review-diff-branch` — 별개로 병행 실행
- **체크리스트 저장 위치**: `.claude/workspace/checklists/<feature-name>.md` — 브랜치명 그대로 파일명 사용
- **요구사항 문서 기본 위치**: `doc/workspace/` (PRD, 워크플로우), `.claude/plans/` (구현 플랜)
- **프로젝트 원칙**: `.claude/refs/engineering-principles.md`, `.claude/rules/agent-principles.md`
- **추적 ID 형식**: `[REQ-카테고리약어-번호]` — 예: `[REQ-F-01]` (기능), `[REQ-B-01]` (비즈니스로직), `[REQ-U-01]` (UI), `[REQ-E-01]` (엣지케이스), `[REQ-D-01]` (데이터계약)
- **ID 연속성**: `mode=checklist`에서 생성된 ID가 구현 검증 모드에서 동일하게 사용됨 — 사전/사후 추적 가능