From fc9ada51d6ee67fbe7a4144361608c1096227720 Mon Sep 17 00:00:00 2001 From: Justin Ko Date: Wed, 9 Sep 2026 22:23:51 +0900 Subject: [PATCH] add requirements doc template --- docs/requirements/README.md | 48 ++++++++ docs/requirements/TEMPLATE.md | 212 ++++++++++++++++++++++++++++++++++ 2 files changed, 260 insertions(+) create mode 100644 docs/requirements/README.md create mode 100644 docs/requirements/TEMPLATE.md diff --git a/docs/requirements/README.md b/docs/requirements/README.md new file mode 100644 index 0000000..505539c --- /dev/null +++ b/docs/requirements/README.md @@ -0,0 +1,48 @@ +# Requirements + +각 requirement 문서는 Markdown body 앞에 JSON front matter를 둔다. + +## File naming + +```text +req-NNN_.md +``` + +- `NNN`: requirement ID의 세 자리 decimal number +- ``: requirement title을 나타내는 lowercase kebab-case ASCII slug + +## Metadata schema + +```json +{ + "schema": "proofline.requirement/v1", + "id": "REQ-NNN", + "title": "사람이 읽는 제목", + "revision": "major.minor", + "status": "draft | approved | retired", + "depends_on": ["REQ-NNN"], + "applies_to": ["algorithm-name"], + "language": "ko" +} +``` + +- `id`: repository 안에서 고유한 requirement identifier +- `revision`: 사람이 읽는 requirement revision. `draft` 상태에서 본문을 수정해도 올리지 않으며, `approved` 상태로 전환할 때 또는 승인된 requirement의 의미를 변경하기 위해 재승인할 때만 올린다. +- `status`: requirement lifecycle 상태. `approved`는 명시적인 사용자 승인을 의미한다. +- `depends_on`: 선행 requirement identifier 목록 +- `applies_to`: requirement가 적용되는 algorithm 또는 product 영역 + +## Python parsing + +front matter body는 JSON이므로 별도 dependency 없이 Python 표준 라이브러리로 읽을 수 있다. + +```python +import json +from pathlib import Path + +text = Path("docs/requirements/req-001_algorithm-input-contract.md").read_text(encoding="utf-8") +_, metadata_json, _ = text.split("---", 2) +metadata = json.loads(metadata_json) +``` + +JSON front matter의 `revision`과 `status`가 문서의 단일 source of truth다. diff --git a/docs/requirements/TEMPLATE.md b/docs/requirements/TEMPLATE.md new file mode 100644 index 0000000..0914054 --- /dev/null +++ b/docs/requirements/TEMPLATE.md @@ -0,0 +1,212 @@ +--- +{ + "schema": "proofline.requirement/v1", + "id": "REQ-NNN", + "title": "요구사항 제목", + "revision": "0.1", + "status": "draft", + "depends_on": [], + "applies_to": ["product-area"], + "language": "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 예시: + +```text +Test ID: TC-NNN-001 +Verifies: +- REQ-NNN.01-AC01 +Test reference: +Automated: true | false +``` + +Execution evidence 예시: + +```text +Test ID: TC-NNN-001 +Requirement revision: REQ-NNN@major.minor +Commit: +Environment: +Result: PASS | FAIL | BLOCKED +Executed at: +``` + +## 12. 추적성 + +- 근거 이슈: `` +- 구현 PR: `` +- 관련 설계 문서: `` +- 관련 requirement: `` + +## 13. 확정된 결정 + +- 사용자와 확정한 제품·정책 결정을 기록한다. +- 확정된 결정은 Open Question으로 다시 남기지 않는다. + +## 14. Open Questions + +`approved` 전 반드시 결정해야 하며, 각 항목에는 선택지, 권장안, 결정 주체와 종료 조건을 둔다. 미결정 항목이 없으면 `없음`으로 기록한다. + +- 없음 + +## 15. 승인 기록 + +- 상태: `draft` +- 승인 주체: 미승인 +- 승인 근거: 없음