73 lines
5.6 KiB
Markdown
73 lines
5.6 KiB
Markdown
# Discovery 작성 방법
|
|
|
|
Discovery는 Gitea Issue 본문으로 작성한다.
|
|
|
|
1. [`TEMPLATE.md`](TEMPLATE.md)를 복사한다.
|
|
2. 첫 번째 marker와 섹션 순서를 유지한다.
|
|
3. `${...}` placeholder를 저장소 근거에 기반한 한국어 내용으로 교체한다.
|
|
4. 템플릿에 없는 hidden state, marker 또는 metadata를 추가하지 않는다.
|
|
5. 미해결 질문이 없으면 `없음`으로 작성한다.
|
|
|
|
## Discovery marker 정책
|
|
|
|
`<!-- gitea-agent:discovery-draft/v2 -->`는 Discovery body의 문서 유형과 템플릿 버전을 식별하는 marker다.
|
|
|
|
- body의 첫 줄에 exact bytes로 한 번만 둔다.
|
|
- marker에 속성, 상태 또는 payload를 추가하지 않는다.
|
|
- 작성·검증·재실행 시 marker와 템플릿의 섹션 순서를 함께 확인한다.
|
|
- marker가 없거나 값이 다르거나 알 수 없는 버전이면 유효한 Discovery 초안으로 취급하지 않는다.
|
|
- 다른 버전을 임의로 생성하거나 자동 변환하지 않는다.
|
|
|
|
각 섹션에는 요약, 문제, 포함·제외 범위, 제약 조건, 확정된 결정, 저장소 근거, 문서 영향과 미해결 질문을 기록한다.
|
|
|
|
## 문서 영향 및 산출물 작성 방법
|
|
|
|
`문서 영향 및 산출물`에는 다음 문서 유형을 순서대로 모두 기록한다. 영향이 없는 문서도 생략하지 않는다.
|
|
|
|
1. 요구사항명세서 — `docs/requirements/req-NNN_<slug>.md` 형식의 exact 경로
|
|
2. 데이터 모델 — `docs/data-model.md`
|
|
3. 인터페이스 계약 — `docs/interface-contract.md`
|
|
4. 프로젝트 구조 — `docs/project-structure.md`
|
|
5. 런타임 흐름 — `docs/runtime-flow.md`
|
|
|
|
각 문서 유형은 다음 형식으로 작성한다.
|
|
|
|
```markdown
|
|
### 문서 이름
|
|
|
|
- 조치: 신규 작성 | 갱신 | 영향 없음
|
|
- 경로: `대상 저장소 기준 경로`
|
|
- 변경 내용: 추가하거나 변경할 계약과 범위
|
|
- 근거: 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 부재를 확인한다.
|
|
- 내용 검토: 저장소 근거가 작성 내용을 뒷받침하는지, 요구사항 문서의 갱신·신규 선택이 적절한지, 확정된 결정과 미해결 질문이 서로 모순되지 않는지 확인한다.
|
|
- 형식 검증 통과만으로 내용 검토나 구현 준비가 완료됐다고 판단하지 않는다. 미해결 질문이 있는 초안은 질문을 남긴 상태로 게시할 수 있으며, 완료 보고에 이를 명시한다.
|
|
|
|
## OQ(${open_questions}) 작성 방법
|
|
|
|
각 OQ에는 질문에 대한 설명과 선택지를 작성하고 추천안을 표시한다. 모든 선택지는 체크박스(`[ ]`)를 사용한다.
|
|
|
|
```markdown
|
|
### OQ-001 — 질문
|
|
|
|
질문에 대한 설명
|
|
|
|
- [ ] 선택지 A (추천)
|
|
- [ ] 선택지 B
|
|
```
|