# 요구사항

각 요구사항 문서는 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`가 문서의 기준값이다.