Initialize gitea-agent harness
This commit is contained in:
@@ -0,0 +1,107 @@
|
||||
# 요구사항
|
||||
|
||||
각 요구사항 문서는 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`가 문서의 기준값이다.
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
{
|
||||
"schema": "gitea-agent.requirement/v1",
|
||||
"id": "${requirement_id}",
|
||||
"title": "${title}",
|
||||
"revision": "1.0",
|
||||
"status": "approved",
|
||||
"depends_on": [],
|
||||
"applies_to": ["${product_area}"],
|
||||
"language": "ko"
|
||||
}
|
||||
---
|
||||
|
||||
# ${requirement_id} — ${title}
|
||||
|
||||
## 1. 목적
|
||||
|
||||
${purpose}
|
||||
|
||||
## 2. 배경
|
||||
|
||||
${background}
|
||||
|
||||
## 3. 범위
|
||||
|
||||
### 포함
|
||||
|
||||
${in_scope}
|
||||
|
||||
### 제외
|
||||
|
||||
${out_of_scope}
|
||||
|
||||
## 4. 용어와 기준
|
||||
|
||||
${terms_and_authorities}
|
||||
|
||||
## 5. 요구사항
|
||||
|
||||
### ${requirement_item_id} — ${requirement_item_title}
|
||||
|
||||
${requirement_statement}
|
||||
|
||||
**영향 범위**
|
||||
|
||||
- 인터페이스: ${interfaces_or_none}
|
||||
- 영속성: ${persistence_or_none}
|
||||
- 후속 사용 주체: ${downstream_consumers_or_none}
|
||||
- 마이그레이션: ${migration_or_none}
|
||||
- 호환성: ${compatibility_or_none}
|
||||
- 배포 전제 조건: ${deployment_prerequisites_or_none}
|
||||
|
||||
## 6. 제약과 불변조건
|
||||
|
||||
${constraints_and_invariants}
|
||||
|
||||
## 7. 인수 기준
|
||||
|
||||
### ${acceptance_criterion_id} — ${acceptance_criterion_title}
|
||||
|
||||
**판정 기준**
|
||||
|
||||
${judgment}
|
||||
|
||||
**검증**
|
||||
|
||||
${verification}
|
||||
|
||||
**검증 분류**
|
||||
|
||||
- 수준: ${verification_level}
|
||||
- 백엔드: ${verification_backend_or_none}
|
||||
- 케이스: ${verification_cases}
|
||||
|
||||
**상태 불변조건**
|
||||
|
||||
${state_invariants}
|
||||
|
||||
## 8. 오류 및 충돌 계약
|
||||
|
||||
${error_and_conflict_contract}
|
||||
|
||||
## 9. 데이터 및 인터페이스 계약
|
||||
|
||||
${data_and_interface_contract}
|
||||
|
||||
## 10. 하위 호환성
|
||||
|
||||
${backward_compatibility}
|
||||
|
||||
## 11. 추적성
|
||||
|
||||
- 근거 이슈: ${source_issue_id}
|
||||
- 구현 PR: 미정
|
||||
- 관련 설계 문서: ${related_design_documents_or_none}
|
||||
- 관련 요구사항: ${related_requirements_or_none}
|
||||
Reference in New Issue
Block a user