64 lines
2.8 KiB
Markdown
64 lines
2.8 KiB
Markdown
# Requirements
|
|
|
|
각 requirement는 `req-NNN/` 폴더에 정본과 관련 검증 자료를 함께 둔다. 정본 requirement 문서만 Markdown body 앞에 JSON front matter를 둔다.
|
|
|
|
## Directory layout and file naming
|
|
|
|
```text
|
|
docs/requirements/
|
|
README.md
|
|
TEMPLATE.md
|
|
req-NNN/
|
|
req-NNN_<slug>.md
|
|
test-catalog.md
|
|
test-evidence.md
|
|
history/
|
|
provenance-reapproval-request.md
|
|
README.md
|
|
```
|
|
|
|
- `NNN`: requirement ID의 세 자리 decimal number. 폴더명과 정본 파일의 번호는 일치해야 한다.
|
|
- `<slug>`: requirement title을 나타내는 lowercase kebab-case ASCII slug
|
|
- `req-NNN/`는 하나의 requirement 묶음이며, 그 안의 `req-NNN_<slug>.md`만 정본이다.
|
|
- `test-catalog.md`는 AC와 실행 가능한 테스트의 연결을, `test-evidence.md`는 특정 commit·환경에서의 실행 결과를 기록한다. 이들은 보조 문서이며 별도 REQ ID, revision 또는 approval status를 부여하지 않는다.
|
|
- 과거 승인 요청·정정 절차 기록은 필요할 때 `history/`에 보존한다. 당시 요청서와 현재 완료 상태를 구분하고, 완료 상태 및 승인 근거는 `history/README.md`에 기록한다.
|
|
- `docs/requirements/` 바로 아래에는 공통 README/TEMPLATE와 requirement별 폴더를 둔다. 개별 REQ나 보조 문서를 이 위치에 혼재시키지 않는다.
|
|
- 문서 검색·수집은 하위 폴더까지 탐색하고, 파일 접두사만이 아니라 JSON front matter의 `schema`와 `id`로 정본을 식별한다.
|
|
- 배치 변경만으로 승인된 정본의 내용·ID·revision·status를 변경하지 않는다.
|
|
|
|
## 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/req-001_manual-cash-dividend.md").read_text(encoding="utf-8")
|
|
_, metadata_json, _ = text.split("---", 2)
|
|
metadata = json.loads(metadata_json)
|
|
```
|
|
|
|
JSON front matter의 `revision`과 `status`가 문서의 단일 source of truth다.
|