Discovery 작성 방법

Discovery는 Gitea Issue 본문으로 작성한다.

TEMPLATE.md를 복사한다.
첫 번째 marker와 섹션 순서를 유지한다.
${...} placeholder를 저장소 근거에 기반한 한국어 내용으로 교체한다.
템플릿에 없는 hidden state, marker 또는 metadata를 추가하지 않는다.
미해결 질문이 없으면 없음으로 작성한다.

Discovery marker 정책

는 Discovery body의 문서 유형과 템플릿 버전을 식별하는 marker다.

body의 첫 줄에 exact bytes로 한 번만 둔다.
marker에 속성, 상태 또는 payload를 추가하지 않는다.
작성·검증·재실행 시 marker와 템플릿의 섹션 순서를 함께 확인한다.
marker가 없거나 값이 다르거나 알 수 없는 버전이면 유효한 Discovery 초안으로 취급하지 않는다.
다른 버전을 임의로 생성하거나 자동 변환하지 않는다.

각 섹션에는 요약, 문제, 포함·제외 범위, 제약 조건, 확정된 결정, 저장소 근거, 문서 영향과 미해결 질문을 기록한다.

문서 영향 및 산출물 작성 방법

문서 영향 및 산출물에는 다음 문서 유형을 순서대로 모두 기록한다. 영향이 없는 문서도 생략하지 않는다.

요구사항명세서 — docs/requirements/req-NNN_<slug>.md 형식의 exact 경로
데이터 모델 — docs/data-model.md
인터페이스 계약 — docs/interface-contract.md
프로젝트 구조 — docs/project-structure.md
런타임 흐름 — docs/runtime-flow.md

각 문서 유형은 다음 형식으로 작성한다.

### 문서 이름

- 조치: 신규 작성 | 갱신 | 영향 없음
- 경로: `대상 저장소 기준 경로`
- 변경 내용: 추가하거나 변경할 계약과 범위
- 근거: Discovery 범위 또는 pinned source revision에서 확인한 저장소 근거

조치는 세 값 중 하나만 사용한다.
pinned source revision에 정본 문서가 없고 문서 영향이 있으면 신규 작성, 정본 문서가 있고 문서 영향이 있으면 갱신으로 기록한다.
영향 없음인 경우에도 변경 내용에 영향이 없는 이유를 기록한다.
요구사항명세서는 pinned source revision의 기존 docs/requirements/req-NNN_<slug>.md 파일을 조사해 이번 변경을 기존 문서에 반영할지, 별도 문서로 작성할지 판단한다. 기존 기능의 동작이나 정책을 변경·확장하는 경우에는 기존 ID와 경로를 유지하여 갱신한다. 독립된 기능을 추가하는 경우에는 신규 작성하며, 선택 이유를 근거에 간단히 기록한다. 기존 문서가 승인됐거나 변경 내용이 기존 제외 범위에 있었다는 사실만으로 신규 문서를 만들지는 않는다.
기존 문서를 갱신할 때는 변경 내용에 변경할 계약, 유지할 계약, revision 및 추적성 갱신을 기록한다. 신규 작성할 때만 기존 ID를 조사해 충돌하지 않는 다음 REQ-NNN과 exact 경로를 결정한다. 기존 요구사항 파일이 없으면 REQ-001부터 시작한다. 기존 ID가 REQ-001부터 빠짐없이 연속이면 가장 큰 ID의 다음 값을 사용한다. 기존 ID가 중복·비연속·형식 오류 상태이거나 exact 파일명을 안전하게 결정할 수 없으면 값을 추측하지 않고 Discovery 작성을 중단한다. 확정된 범위를 나타내는 소문자 ASCII 케밥 표기법의 slug를 사용해 exact 경로를 기록한다. README와 TEMPLATE는 할당된 요구사항 ID로 세지 않는다.
요구사항명세서 항목에는 문서 ID, 제목, 포함할 내용, 제외할 내용을 추가한다. 포함할 내용은 구현 에이전트가 요구사항과 acceptance criteria로 내려야 할 동작, 오류, 보안, 데이터·인터페이스, 호환성 및 추적성 계약을 구체적으로 나열한다.
데이터 모델은 변경할 엔터티·필드·관계·불변조건·마이그레이션을, 인터페이스 계약은 입력·출력·인증·오류·호환성을, 프로젝트 구조는 경로·책임·의존 방향·배치 규칙을, 런타임 흐름은 시작 조건·단계·상태 변경·외부 호출·실패 복구·동시성·관찰 가능성을 변경 내용에 기록한다.
문서가 영향 없음이면 해당 문서 계약이 왜 바뀌지 않는지 확정 범위와 저장소 근거를 사용해 설명한다.
변경 내용에는 구현 에이전트가 문서에 반영할 계약과 범위만 기록한다. Discovery 작성 중 후속 문서를 생성하거나 수정하지 않는다.
저장소 근거나 확정된 결정 없이 엔터티, 인터페이스, 디렉터리, 실행 흐름 또는 문서 변경을 만들어내지 않는다.

작성 후 검증

형식 검증: TEMPLATE의 marker·섹션 순서, 필수 항목과 placeholder 부재를 확인한다.
내용 검토: 저장소 근거가 작성 내용을 뒷받침하는지, 요구사항 문서의 갱신·신규 선택이 적절한지, 확정된 결정과 미해결 질문이 서로 모순되지 않는지 확인한다.
형식 검증 통과만으로 내용 검토나 구현 준비가 완료됐다고 판단하지 않는다. 미해결 질문이 있는 초안은 질문을 남긴 상태로 게시할 수 있으며, 완료 보고에 이를 명시한다.

범위 분류와 blocking 판단

새 OQ 또는 인수 조건을 제안하기 전에 원본 요청, 현재 사용자 결정과 pinned source의 기존 계약을 근거로 다음 중 하나로 분류한다.

핵심 요청: 원래 문제 해결에 직접 필요한 조건.
기존 호환성: 기존 동작·인증·보안·데이터 계약을 보존하는 조건. 핵심 요청 밖이라는 이유로 선택적 확장으로 낮추지 않는다.
선택적 확장: 원래 요청·기존 계약에 없는 추가 기능. 명시적으로 채택되지 않은 선택적 확장은 필수 범위·acceptance criterion·blocking OQ로 승격하지 않는다.

분류와 승인 근거는 trusted workflow의 검토 기록에 남긴다. Discovery marker·H2 순서·hidden metadata나 제품 문서 schema는 변경하지 않는다. 선택적 제안을 남긴다면 현재 승인 범위가 아님을 명시하고 핵심 해결을 차단하지 않는다.

Blocking OQ는 핵심 요청 또는 기존 호환성을 안전하게 확정하는 데 실제 사용자 결정이 필요한 경우에만 만든다. 구현 후 실행할 acceptance 검증과 사용자 선택이 필요한 결정 공백을 구분한다.
이미 사용자가 명시적으로 채택한 추가 요구나 기존 미선택 OQ를 분류만으로 임의 삭제·해결 처리하지 않는다. 재분류로 기존 결정과 충돌하면 원문 선택을 보존하고 사용자 판단을 받는다.
작성 후 각 새 OQ·인수 조건의 분류와 승인 근거를 확인하고, 미채택 선택적 확장이 핵심 해결의 blocker가 되지 않았는지 검증한다.

OQ(${open_questions}) 작성 방법

각 OQ에는 질문에 대한 설명과 선택지를 작성하고 추천안을 표시한다. 모든 선택지는 체크박스([ ])를 사용한다.

추천안을 포함한 모든 선택지는 원본 요청의 필수 범위, 확정된 결정과 기존 호환성 불변조건을 보존해야 한다. 미검증 전제를 확정된 사실로 취급하지 않는다. 요구 철회나 기존 계약 변경을 제안할 때는 일반 구현 대안과 구분하고 변경 대상과 영향을 명시한다.

### OQ-001 — 질문

질문에 대한 설명

- [ ] 선택지 A (추천)
- [ ] 선택지 B