요구사항

각 요구사항 문서는 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 충돌과 기존 정본 산출물 여부를 판정하기 위해 조사한다.

저장 위치

완성된 요구사항명세서는 대상 저장소 루트 기준 다음 경로에 저장한다.

docs/requirements/req-NNN_<slug>.md

같은 REQ-NNN의 문서가 이미 존재하면 별도 파일을 만들지 않고 기존 정본 문서를 갱신한다. 이 디렉터리의 README.md와 TEMPLATE.md는 하네스의 작성 규칙과 템플릿이며 대상 저장소에 저장하는 산출물이 아니다.

파일 이름 규칙

req-NNN_<slug>.md

NNN: 요구사항 ID를 나타내는 세 자리 십진수
<slug>: 요구사항 제목을 나타내는 소문자 케밥 표기법의 ASCII 슬러그

메타데이터 스키마

{
  "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 표준 라이브러리로 읽을 수 있다.

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가 문서의 기준값이다.