108 lines
5.4 KiB
Markdown
108 lines
5.4 KiB
Markdown
# 요구사항
|
|
|
|
각 요구사항 문서는 Markdown 본문 앞에 JSON 프런트 매터를 둔다.
|
|
|
|
## 정본
|
|
|
|
요구사항 작성·검토에는 이 디렉터리의 `README.md`와 `TEMPLATE.md` 및 이와 byte parity가 검증된 trusted bundle만 정본으로 사용한다. 대상 저장소에 기존 `docs/requirements/README.md` 또는 `docs/requirements/TEMPLATE.md`가 있더라도 그 내용·schema·lifecycle·문서 구조를 작성 정책이나 템플릿으로 사용하지 않는다. 대상 저장소에서는 실제 `req-NNN_<slug>.md` 파일만 ID 충돌과 기존 정본 산출물 여부를 판정하기 위해 조사한다.
|
|
|
|
## 저장 위치
|
|
|
|
완성된 요구사항명세서는 대상 저장소 루트 기준 다음 경로에 저장한다.
|
|
|
|
```text
|
|
docs/requirements/req-NNN_<slug>.md
|
|
```
|
|
|
|
같은 `REQ-NNN`의 문서가 이미 존재하면 별도 파일을 만들지 않고 기존 정본 문서를 갱신한다. 이 디렉터리의 [`README.md`](README.md)와 [`TEMPLATE.md`](TEMPLATE.md)는 하네스의 작성 규칙과 템플릿이며 대상 저장소에 저장하는 산출물이 아니다.
|
|
|
|
## 파일 이름 규칙
|
|
|
|
```text
|
|
req-NNN_<slug>.md
|
|
```
|
|
|
|
- `NNN`: 요구사항 ID를 나타내는 세 자리 십진수
|
|
- `<slug>`: 요구사항 제목을 나타내는 소문자 케밥 표기법의 ASCII 슬러그
|
|
|
|
## 메타데이터 스키마
|
|
|
|
```json
|
|
{
|
|
"schema": "gitea-agent.requirement/v1",
|
|
"id": "${requirement_id}",
|
|
"title": "${title}",
|
|
"revision": "1.0",
|
|
"status": "approved",
|
|
"depends_on": [],
|
|
"applies_to": ["${product_area}"],
|
|
"language": "ko"
|
|
}
|
|
```
|
|
|
|
- `id`: 저장소 안에서 고유한 `REQ-NNN` 형식의 요구사항 식별자. 파일 이름의 `NNN` 및 H1과 일치해야 한다.
|
|
- `revision`: 최초 작성 시 `1.0`으로 시작하며 요구사항의 의미가 변경될 때 올린다.
|
|
- `status`: 구현 에이전트가 승인된 Discovery를 근거로 작성하므로 항상 `approved`로 기록한다. 다른 값은 허용하지 않는다.
|
|
- `depends_on`: 선행 요구사항 식별자 배열. 선행 요구사항이 없으면 빈 배열을 사용한다.
|
|
- `applies_to`: 요구사항이 적용되는 제품 영역 식별자 배열. 하나 이상의 값을 기록한다.
|
|
|
|
### 메타데이터 배열 규칙
|
|
|
|
- 배열 값은 중복 없이 안정적인 순서로 기록한다.
|
|
- `depends_on` 값은 같은 저장소의 유효한 `REQ-NNN`만 허용하며 자기 자신과 직접·간접 순환 참조를 금지한다.
|
|
- `applies_to` 값은 소문자 케밥 표기법의 제품 영역 식별자를 사용한다.
|
|
|
|
## Placeholder와 반복 블록
|
|
|
|
- 교체 대상은 `${lowercase_snake_case}` 형식만 사용한다.
|
|
- TEMPLATE의 모든 `${...}` placeholder를 실제 값으로 교체하며 완성 문서에 하나도 남기지 않는다.
|
|
- `## 5. 요구사항`의 H3 블록은 독립 요구사항 수만큼 복제하고 `REQ-NNN.01`부터 연속 식별자를 부여한다.
|
|
- `## 7. 인수 기준`의 H3 블록은 각 요구사항에 하나 이상 두고 `REQ-NNN.XX-AC01`부터 요구사항별로 연속 식별자를 부여한다.
|
|
- 사용하지 않는 예시 블록이나 작성 안내 문구를 완성 문서에 남기지 않는다.
|
|
|
|
## 완성 문서 검증
|
|
|
|
- 파일 이름의 `NNN`, 프런트 매터의 `id`, H1의 요구사항 식별자가 일치해야 한다.
|
|
- 요구사항과 인수 기준 식별자는 각각 `01`부터 빠짐없이 연속되어야 한다.
|
|
- 모든 필수 섹션을 채우고 해당 사항이 없으면 `없음`으로 기록한다.
|
|
- 프런트 매터는 유효한 JSON이어야 하며 `schema`, `status`, `language`는 정해진 값을 정확히 사용해야 한다.
|
|
|
|
## 제약과 불변조건 작성 방법
|
|
|
|
구현 방식과 무관하게 유지해야 하는 데이터·상태·보안·원자성·정밀도·동시성·순서 조건을 기록한다. 하위 호환성은 이 섹션에 중복하지 않는다.
|
|
|
|
## 하위 호환성 작성 방법
|
|
|
|
문서 전체에 적용되는 공통 하위 호환 계약을 기록한다.
|
|
|
|
- 유지해야 하는 기존 API, 설정, 데이터, 사용자 흐름을 명시한다.
|
|
- 의도적으로 변경되는 동작은 적용 경계와 마이그레이션 방법을 함께 기록한다.
|
|
- 개별 요구사항에만 해당하는 내용은 해당 요구사항의 `영향 범위 > 호환성`에 기록한다.
|
|
- 기존 계약에 영향이 없으면 `없음`으로 기록한다.
|
|
|
|
## 추적성 작성 방법
|
|
|
|
요구사항명세서는 구현 에이전트가 승인된 Discovery를 근거로 초기 구현과 함께 작성한다.
|
|
|
|
- 같은 저장소의 근거 이슈는 `#NNN` 형식으로 기록한다.
|
|
- 초기 작성 시점에는 구현 PR이 아직 없으므로 `구현 PR`은 `미정`으로 기록하며 번호를 추측하지 않는다.
|
|
- 다른 저장소의 Issue 또는 PR을 참조할 때는 `owner/repository#NNN` 형식으로 저장소를 명시한다.
|
|
- 관련 설계 문서는 저장소 기준 상대 경로로 기록한다.
|
|
- 관련 요구사항은 `REQ-NNN` 식별자로 기록한다.
|
|
- 여러 값은 쉼표로 구분하고, 해당 항목이 없으면 `없음`으로 기록한다.
|
|
|
|
## Python 파싱
|
|
|
|
프런트 매터 본문은 JSON이므로 별도 의존성 없이 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 프런트 매터의 `revision`과 `status`가 문서의 기준값이다.
|