6.9 KiB
6.9 KiB
schema, id, title, revision, status, depends_on, applies_to, language
| schema | id | title | revision | status | depends_on | applies_to | language | |
|---|---|---|---|---|---|---|---|---|
| proofline.requirement/v1 | REQ-NNN | 요구사항 제목 | 0.1 | draft |
|
ko |
REQ-NNN — 요구사항 제목
1. 목적
이 요구사항으로 달성해야 하는 사용자 또는 시스템의 결과를 기술한다.
2. 배경
현재 문제, 요구사항이 필요한 이유, 관련된 운영·도메인 맥락을 기술한다. 구현 방법보다 해결해야 할 문제에 집중한다.
3. 범위
포함
- 이 요구사항이 제공하거나 변경해야 하는 동작
- 영향을 받는 API, 데이터, 제품 영역 또는 운영 흐름
제외
- 이번 요구사항에서 다루지 않는 기능
- 별도 requirement 또는 후속 작업으로 분리할 항목
4. 용어와 기준
- 용어: 이 문서에서 사용하는 의미
- 정본 기준: 값이나 상태의 canonical source
5. 요구사항
REQ-NNN은 문서와 기능 묶음의 identifier다. 고객에게 전달할 요구사항명세리스트와 구현 추적에서는 독립적으로 구현·검증할 수 있는 각 요구사항을 REQ-NNN.01, REQ-NNN.02 형식으로 식별한다.
각 요구사항에는 하네스가 변경 영향과 필요한 회귀 범위를 판정할 수 있도록 Impact를 기록한다.
REQ-NNN.01 — 요구사항 이름
시스템은 관찰 가능한 결과를 명확하게 기술한 조건을 충족해야 한다.
Impact
- Interfaces:
<영향받는 API, event 또는 없음> - Persistence:
<영향받는 table, state 또는 없음> - Consumers:
<영향받는 downstream consumer 또는 없음> - Migration:
<필요 여부와 범위> - Compatibility:
<유지해야 하는 기존 동작> - Deployment prerequisites:
<배포 전제조건 또는 없음>
REQ-NNN.02 — 요구사항 이름
시스템은 정상 동작뿐 아니라 실패·경계·변경 없음 조건도 명확히 충족해야 한다.
Impact
- Interfaces:
<영향받는 API, event 또는 없음> - Persistence:
<영향받는 table, state 또는 없음> - Consumers:
<영향받는 downstream consumer 또는 없음> - Migration:
<필요 여부와 범위> - Compatibility:
<유지해야 하는 기존 동작> - Deployment prerequisites:
<배포 전제조건 또는 없음>
6. 제약과 불변조건
- 구현 방식과 무관하게 항상 유지해야 하는 데이터·상태 불변조건
- 기존 호출자와 저장 데이터에 대해 유지해야 하는 하위호환 조건
- 인증·권한·민감정보 처리 조건
- 원자성, 정밀도, 동시성 또는 순서 보장 조건
7. Acceptance Criteria
Acceptance Criterion은 소속 요구사항을 포함한 REQ-NNN.01-AC01 형식으로 식별한다. 문서 전체에서만 고유한 AC-001 형식은 사용하지 않는다.
REQ-NNN.01-AC01 — 판정 가능한 결과
Criterion
- 하나의 지속적인 요구사항을 PASS 또는 FAIL로 판정할 수 있게 기술한다.
- 특정 함수명이나 내부 구현보다 외부에서 관찰 가능한 결과를 명시한다.
Verification
- 정상 경로 검증 방법
- 실패 및 경계 조건 검증 방법
- 변경되면 안 되는 상태의 검증 방법
- 필요한 경우 실제 persistence backend 또는 production entry point 검증 방법
Verification Classification
- Level:
unit | API | integration | end-to-end - Backend:
<검증 대상 backend 또는 없음> - Cases:
positive | negative | boundary | unchanged-state | concurrency
State Invariants
- 성공 시 반드시 변경되어야 하는 상태
- 성공하더라도 변경되면 안 되는 상태
- 실패 시 부분 기록 없이 유지되어야 하는 상태
REQ-NNN.02-AC01 — 판정 가능한 결과
Criterion
- 두 번째 독립 요구사항을 기술한다.
Verification
- Criterion 전체를 입증할 검증 절차와 기대 결과를 기술한다.
Verification Classification
- Level:
unit | API | integration | end-to-end - Backend:
<검증 대상 backend 또는 없음> - Cases:
positive | negative | boundary | unchanged-state | concurrency
State Invariants
- 성공 시 반드시 변경되어야 하는 상태
- 성공하더라도 변경되면 안 되는 상태
- 실패 시 부분 기록 없이 유지되어야 하는 상태
8. 오류 및 충돌 계약
- 입력 오류: 상태 코드 또는 오류 분류와 무변경 조건
- 상태 충돌: 재시도·확인·중복 처리 정책
- 저장 실패: transaction rollback과 부분 기록 방지 조건
9. 데이터 및 인터페이스 계약
- 입력 field와 필수·선택 여부
- 출력 field와 의미
- 저장해야 하는 canonical 값과 metadata
- 시간대, 단위, 정밀도 및 식별자 규칙
10. 하위호환성
- 유지해야 하는 기존 동작과 호출 방식
- 기존 데이터에 적용할 규칙
- 의도적으로 변경되는 동작이 있다면 그 경계
11. 검증 계획
- Unit/API contract 검증
- Persistence migration 및 round-trip 검증
- 동시성·중복·재시도 검증
- 기존 기능 회귀 검증
- OpenAPI 또는 사용자-facing 문서 정합성 검증
Test Traceability Contract
- Requirement 문서에는 검증 의도와 판정 조건만 기록한다.
- 실행 가능한 테스트 정의는 별도 test catalog artifact에서 관리한다.
- 각 테스트 케이스는 안정적인 identifier를 사용하고
verifies로 Acceptance Criterion을 참조한다. - 하나의 테스트가 여러 Criterion을 검증할 수 있으며, 각 연결을 빠짐없이 기록한다.
- 실행 결과는 requirement 또는 test definition에 덮어쓰지 않고 별도 evidence artifact에 기록한다.
- Evidence는 requirement revision, 검증한 commit, 환경과 실행 시각에 결합한다.
- 테스트 정의의 존재, 자동화 여부, 특정 commit에서의 실행 여부와 PASS 결과를 서로 다른 상태로 취급한다.
Test definition 예시:
Test ID: TC-NNN-001
Verifies:
- REQ-NNN.01-AC01
Test reference: <test file, case 또는 harness selector>
Automated: true | false
Execution evidence 예시:
Test ID: TC-NNN-001
Requirement revision: REQ-NNN@major.minor
Commit: <commit SHA>
Environment: <runtime 및 backend>
Result: PASS | FAIL | BLOCKED
Executed at: <timestamp>
12. 추적성
- 근거 이슈:
<issue URL 또는 ID> - 구현 PR:
<PR URL 또는 ID> - 관련 설계 문서:
<repository-relative path> - 관련 requirement:
<REQ-NNN 또는 없음>
13. 확정된 결정
- 사용자와 확정한 제품·정책 결정을 기록한다.
- 확정된 결정은 Open Question으로 다시 남기지 않는다.
14. Open Questions
approved 전 반드시 결정해야 하며, 각 항목에는 선택지, 권장안, 결정 주체와 종료 조건을 둔다. 미결정 항목이 없으면 없음으로 기록한다.
- 없음
15. 승인 기록
- 상태:
draft - 승인 주체: 미승인
- 승인 근거: 없음