klaus/voiceon-character-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(agent-guide): 문서 작성 규칙 정리

Browse Source
This commit is contained in:
Yu Sung
2026-07-27 15:03:24 +09:00
parent f8a313031c
commit 185cce6177
9 changed files with 936 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
AGENTS.md
View File

@@ -4,6 +4,9 @@
- [커뮤니케이션 규칙](docs/agent-guide/communication.md) - [커뮤니케이션 규칙](docs/agent-guide/communication.md)
- [문서 유지보수 규칙](docs/agent-guide/documentation.md) - [문서 유지보수 규칙](docs/agent-guide/documentation.md)
- [PRD 작성 및 유지보수 규칙](docs/agent-guide/prd.md)
- [Goal 실행형 구현 계획 규칙](docs/agent-guide/goal-plan.md)
- [코드 리뷰 및 QA 기록 규칙](docs/agent-guide/review.md)
- [에이전트 동작 원칙](docs/agent-guide/agent-behavior.md) - [에이전트 동작 원칙](docs/agent-guide/agent-behavior.md)
- [실행 스크립트](docs/agent-guide/scripts.md) - [실행 스크립트](docs/agent-guide/scripts.md)
- [환경 변수](docs/agent-guide/environment.md) - [환경 변수](docs/agent-guide/environment.md)

4
docs/agent-guide/documentation.md
View File

@@ -3,6 +3,8 @@
- PRD 문서와 구현 계획/TASK 문서는 `docs/[날짜]_구현할내용한글/` 아래에 함께 둔다. - PRD 문서와 구현 계획/TASK 문서는 `docs/[날짜]_구현할내용한글/` 아래에 함께 둔다.
- 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다. - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
- PRD 문서 파일명은 `prd.md`, 구현 계획/TASK 문서 파일명은 `plan-task.md`를 사용한다. - PRD 문서 파일명은 `prd.md`, 구현 계획/TASK 문서 파일명은 `plan-task.md`를 사용한다.
- 공통 샘플 문서는 `docs/sample/`에 두며 기능별 문서 디렉터리에 복제하지 않는다.
- PRD를 작성·변경할 때는 [PRD 작성 및 유지보수 규칙](./prd.md)과 [PRD 샘플](../sample/sample-prd.md)을 따른다.
- 구현 항목은 기능/작업 단위로 분리해 체크박스(`- [ ]`) 목록으로 작성한다. - 구현 항목은 기능/작업 단위로 분리해 체크박스(`- [ ]`) 목록으로 작성한다.
- 구현 완료 시마다 체크박스를 `- [x]`로 갱신하고, 각 항목이 정상 구현되었는지 확인한다. - 구현 완료 시마다 체크박스를 `- [x]`로 갱신하고, 각 항목이 정상 구현되었는지 확인한다.
- 작업 도중 범위가 변경되면 계획 문서의 체크박스 항목을 먼저 업데이트한 뒤 구현을 진행한다. - 작업 도중 범위가 변경되면 계획 문서의 체크박스 항목을 먼저 업데이트한 뒤 구현을 진행한다.
@@ -11,3 +13,5 @@
- 검증 기록은 단계별로 `무엇을/왜/어떻게`를 유지해 작성하고, 이전 단계와 구분이 되도록 명시한다. - 검증 기록은 단계별로 `무엇을/왜/어떻게`를 유지해 작성하고, 이전 단계와 구분이 되도록 명시한다.
- 단계별 `어떻게`에는 실제 실행한 검증 명령과 결과(성공/실패/불가 사유)를 함께 기록한다. - 단계별 `어떻게`에는 실제 실행한 검증 명령과 결과(성공/실패/불가 사유)를 함께 기록한다.
- 기존 기록 정정이 필요하면 원문을 지우지 말고 `정정` 항목을 추가해 사유와 변경 내용을 남긴다. - 기존 기록 정정이 필요하면 원문을 지우지 말고 `정정` 항목을 추가해 사유와 변경 내용을 남긴다.
- goal 기능으로 실행할 구현 계획은 [Goal 실행형 구현 계획 규칙](./goal-plan.md)과 [Goal 실행형 계획 샘플](../sample/sample-plan-task.md)을 따른다.
- 완료된 Phase 또는 Task의 코드 리뷰·QA 결과 문서는 해당 `prd.md`와 같은 디렉터리에 두고, 상세 형식과 후속 처리에는 [코드 리뷰 및 QA 기록 규칙](./review.md)을 따른다.

79
docs/agent-guide/goal-plan.md Normal file
View File

@@ -0,0 +1,79 @@
# Goal 실행형 구현 계획 규칙
## 1. 적용 시점
- 사용자가 goal 기능으로 구현을 진행하거나, goal에 적합한 `plan-task.md` 작성·보완을 요청하면 이 문서를 따른다.
- 구현 전에 [PRD 작성 및 유지보수 규칙](./prd.md), 대상 기능의 `prd.md`, `api-contract.md`, 기존 `plan-task.md`, 관련 코드·test와 저장소 가이드를 읽는다.
- 계획 작성 요청은 문서 변경 범위다. 사용자가 구현까지 요청하지 않았다면 애플리케이션 코드와 설정을 변경하지 않는다.
## 2. 기준 템플릿과 위치
- `plan-task.md`는 해당 `prd.md`와 같은 `docs/YYYYMMDD_구현할내용한글/` 디렉터리에 둔다.
- [Goal 실행형 계획 샘플](../sample/sample-plan-task.md)을 원본 템플릿으로 사용하고 필수 section과 goal 필드를 임의로 생략하지 않는다.
- 실제 계획에서는 `<...>`, 예시 명령, 선택지와 설명용 placeholder를 모두 정확한 값으로 교체한다. placeholder가 남아 있는 Task는 goal로 시작하지 않는다.
## 3. 필수 문서 구조
`plan-task.md`에는 다음 section을 둔다.
1. 목표
2. 현재 상태
3. 범위의 포함·제외
4. 기술적 제약
5. 하나 이상의 Phase
6. 실행 순서와 의존성
7. 변경 금지 항목
8. 의사결정 및 중단 규칙
9. Progress
10. Decision Log
11. 발견된 문제
12. 최종 보고 형식
각 Phase에는 다음 내용을 둔다.
- 사용자가 직접 확인할 수 있는 Phase 결과
- 선행조건과 Phase 완료 조건
- 하나 이상의 Task
- Task 전체 완료 조건
- 자동·수동 검증 방법과 Phase Gate
## 4. Task와 goal 작성 규칙
- Phase는 실행 흐름과 의존성을 묶는 상위 경계다. `create_goal`에는 Task 또는 Phase Gate 하나만 등록한다.
- 모든 Task에는 고유 Goal ID, 한 문장 objective, 시작 조건, 완료 증거와 범위 밖을 둔다.
- Goal ID는 `P<Phase>-T<Task>`를 사용한다. Phase Gate는 `P<Phase>-GATE`, 완료 범위의 회귀 수정은 `P<Phase>-R<번호>`를 사용한다.
- Task는 독립 reviewer가 이웃 Task와 별도로 승인·거절할 수 있고, 자체 test cycle로 검증할 수 있는 최소 결과 단위로 나눈다.
- Task마다 생성·수정·test 파일의 정확한 경로를 기록한다. 선행 Task contract를 소비하거나 후속 Task에 제공하면 `Interfaces`에 정확한 type·function·component를 기록한다.
- 구현 체크박스는 실패 test 작성 → 의도한 실패 확인 → 최소 구현 → focused test 성공 → 관련 품질 검증 → Progress 기록 순서를 포함한다.
- “적절히 처리”, “나중에 구현”, “위와 동일”처럼 실행자가 다시 추측해야 하는 표현을 사용하지 않는다.
## 5. 완료와 차단 판정
- 동시에 하나의 미완료 goal만 운용한다. 활성 goal이 있으면 새 goal을 만들지 않고 같은 Task를 이어서 수행한다.
- 사용자가 명시적으로 요청하지 않으면 token budget을 설정하지 않는다.
- 코드 작성이나 일부 test만 끝난 상태는 완료가 아니다. 체크박스, 완료 증거, 실제 검증과 Progress 기록까지 충족한 뒤에만 goal을 `complete`로 갱신한다.
- Phase의 모든 활성 Task goal을 완료한 뒤 Phase Gate를 별도 goal로 실행한다.
- 외부 계약이나 권한 같은 동일 차단 사유가 최초 시도와 자동 후속을 포함해 3회 연속 반복되고, 문서화·독립 작업 등 의미 있는 진전도 불가능할 때만 goal을 `blocked`로 갱신한다.
- 계약이 없어 안전하게 구현할 수 없으면 추정하지 않는다. 담당 주체·영향·재개 조건을 기록하고 PRD 결정 기록 → API Contract → `plan-task.md` 순서로 제외 또는 후속 결정을 반영한다.
- 완료된 Task를 묵시적으로 다시 열지 않는다. 후속 수정은 발견된 문제와 별도 회귀 수정 Task·goal로 관리한다.
## 6. 계획 유지보수
- 범위나 구현 방식이 바뀌면 코드를 수정하기 전에 관련 체크박스, Files, Interfaces, 완료 증거와 Decision Log를 갱신한다.
- Progress와 Decision Log의 기존 기록은 삭제하거나 덮어쓰지 않는다. 정정은 날짜·사유와 함께 새 기록으로 추가한다.
- 실행한 명령만 기록하고 성공/실패, exit code, test 수 또는 불가 사유를 남긴다.
- 구현 중 발견한 범위 내 문제는 `발견된 문제`에 기록한다. 완료 범위의 상세 리뷰·QA는 [코드 리뷰 및 QA 기록 규칙](./review.md)에 따라 별도 review 문서로 관리한다.
- Phase 완료 후 현재 상태 표와 체크박스를 갱신하고 Phase Gate의 최신 증거를 Progress에 누적한다.
## 7. 실행 전 자체 검토
goal을 만들기 전에 다음을 확인한다.
- 목표와 포함·제외 범위가 서로 충돌하지 않는다.
- 모든 확정 요구사항이 최소 하나의 Task와 완료 증거로 추적된다.
- 모든 Task의 시작 조건과 선행 Goal ID가 실제로 존재한다.
- Files와 Interfaces의 이름이 앞뒤 Task에서 일치한다.
- 외부 의존과 안전한 기본값이 구분돼 있다.
- 실제 검증 명령과 Expected가 구체적이다.
- placeholder, 미정 값, 추정 계약이 없다.
- 변경 금지 항목과 중단 규칙이 명시돼 있다.

51
docs/agent-guide/prd.md Normal file
View File

@@ -0,0 +1,51 @@
# PRD 작성 및 유지보수 규칙
## 1. 적용 시점
- 사용자가 새 기능의 요구사항 정리, PRD 작성·보완 또는 구현 계획 전 요구사항 명확화를 요청하면 이 문서를 따른다.
- PRD 작성 전에 관련 사용자 요청, 기존 제품 문서, API Contract, 구현 코드와 알려진 제약을 확인한다.
- PRD 작업은 요구사항 문서 범위다. 사용자가 구현까지 요청하지 않았다면 애플리케이션 코드와 설정을 변경하지 않는다.
## 2. 기준 템플릿과 위치
- 실제 PRD는 `docs/YYYYMMDD_구현할내용한글/prd.md`에 둔다.
- [PRD 샘플](../sample/sample-prd.md)을 원본 템플릿으로 사용하고 필수 section과 추적 필드를 임의로 생략하지 않는다.
- 공통 샘플은 `docs/sample/`에서만 관리하며 기능별 문서 디렉터리에 복제하지 않는다.
- 실제 PRD에서는 `<...>`, 예시 ID, 선택지와 설명용 placeholder를 모두 구체적인 값으로 교체한다.
## 3. 요구사항 작성 규칙
- 요구사항 ID는 `<DOMAIN>-NNN` 형식을 사용하고 한 행에는 독립적으로 판정 가능한 요구사항 하나만 기록한다.
- 상태는 `확정`, `미결`, `외부 의존`, `권고`, `제외`만 사용한다.
- 모든 확정 요구사항에는 사용자가 관찰하거나 test로 판정할 수 있는 수용 기준을 둔다.
- 미결 항목에는 현재 권고, 결정 주체와 결정 시점 또는 다음 행동을 기록한다.
- 외부 의존에는 담당 주체, 영향받는 기능과 재개 조건을 기록한다. endpoint·DTO·enum·오류 status/key를 추정하지 않는다.
- 제외 항목에는 제외 이유, 결정 기록과 다시 포함할 조건을 둔다.
- Non-Goal, 반응형 capability, 접근성, 보안·데이터 처리, 성능과 지원 환경을 명시한다.
## 4. 문서 간 추적
- 제품 결정과 사용자 요구는 PRD가 소유한다.
- request/response/error와 endpoint 세부 계약은 `api-contract.md`가 소유한다.
- 구현 순서, Files, Interfaces, Task/Goal과 완료 증거는 `plan-task.md`가 소유한다.
- 모든 확정 요구사항을 API Contract section 또는 명시적인 contract 불필요 판정, 하나 이상의 Phase/Goal, 자동·수동 검증으로 연결한다.
- Open Question과 외부 의존을 혼합하지 않는다. 제품이 결정할 수 없는 backend 계약은 별도 외부 의존 ID로 관리한다.
## 5. 변경과 결정 기록
- 요구사항이 변경되면 PRD Decision Log → 관련 요구사항·수용 기준 → API Contract → `plan-task.md` 순서로 갱신한다.
- 기존 결정은 삭제하거나 덮어쓰지 않는다. 정정은 날짜·사유·영향 범위와 함께 새 Decision Log 행으로 추가한다.
- 구현 중 범위가 달라지면 코드 변경 전에 PRD와 `plan-task.md`를 먼저 갱신한다.
- 완료된 요구사항의 회귀나 위반은 [코드 리뷰 및 QA 기록 규칙](./review.md)에 따라 review 문서에 기록하고, 확정된 문제만 회귀 수정 Task/Goal로 전환한다.
## 6. 계획 작성 전 자체 검토
`plan-task.md`를 만들기 전에 다음을 확인한다.
- 목표, Non-Goal과 포함·제외 범위가 충돌하지 않는다.
- 사용자·권한·핵심 흐름과 라우팅 경계가 명확하다.
- 모든 요구사항 ID가 고유하고 상태·수용 기준을 가진다.
- 미결·외부 의존·제외 항목에 다음 행동과 담당 주체가 있다.
- API endpoint와 payload 규칙이 `api-contract.md`로 추적된다.
- 기능·UX·보안·성능 성공 기준이 자동 또는 수동 검증 가능한 표현이다.
- placeholder, 근거 없는 최대값과 추정 계약이 없다.

50
docs/agent-guide/review.md Normal file
View File

@@ -0,0 +1,50 @@
# 코드 리뷰 및 QA 기록 규칙
## 1. 적용 시점
- 사용자가 코드 리뷰, QA, 완료된 Phase 검증 또는 요구사항 충족 감사를 요청하면 이 문서를 따른다.
- 리뷰 요청은 기본적으로 읽기·진단 범위다. 사용자가 수정을 함께 요청하지 않았다면 코드, test, 설정과 구현 계획을 변경하지 않는다.
- 리뷰 결과를 재현하고 판정하는 데 필요한 test·typecheck·lint·build·E2E 같은 비파괴 검증은 실행할 수 있다.
## 2. 기준 문서와 템플릿
- 리뷰 전에 대상 기능 디렉터리의 `prd.md`, `api-contract.md`, `plan-task.md`와 관련 구현·test를 읽는다.
- 리뷰 문서는 대상 `prd.md`와 같은 디렉터리에 만든다.
- [코드 리뷰 보고서 샘플](../sample/sample-review.md)을 원본 템플릿으로 사용하고, section·필드·상태 의미를 임의로 축소하지 않는다.
- 실제 리뷰 문서 파일명은 범위가 드러나게 작성한다. 예: `review-phase-0-1.md`, `review-auth.md`.
## 3. 리뷰 수행 원칙
- 요구사항과 계약 위반, 버그, 보안·데이터 위험, 회귀, test 누락을 우선 찾는다. 요약이나 칭찬보다 발견 사항을 먼저 보고한다.
- 모든 발견 후보에는 고유 ID, 심각도, 상태, 관련 요구사항·계약, 소유 Task, 코드/test/문서 근거와 재현 또는 검증 절차를 기록한다.
- 심각도는 `Blocker`, `High`, `Medium`, `Low`만 사용한다.
- 상태는 `후보`, `확정`, `오탐`, `보류`, `수정 완료`만 사용한다.
- 실행하지 않은 명령을 실행한 것처럼 기록하지 않는다. 실제 명령, exit code, test 수, 실패 내용 또는 실행 불가 사유를 남긴다.
- endpoint, DTO, 오류 status/message key, validation 상한처럼 제공되지 않은 계약을 추정하지 않는다. 외부 계약이 필요한 항목은 `보류`로 판정하고 담당 주체와 재개 조건을 기록한다.
- 발견 사항이 없더라도 “확정 발견 사항 없음”을 명시하고 검토 범위와 실행 증거를 남긴다.
## 4. 판정과 후속 처리
- 발견 후보는 재현 또는 문서·코드 근거 확인 후 `확정`, `오탐`, `보류` 중 하나로 판정한다.
- `오탐`과 `보류` 기록도 삭제하지 않는다. 후속 정정은 기존 내용을 덮어쓰지 않고 판정 기록에 날짜와 사유를 추가한다.
- 확정 발견 사항만 구현 전에 `plan-task.md`의 신규 회귀 수정 Task로 옮긴다. 기존 완료 체크박스와 검증 기록은 되돌리거나 삭제하지 않는다.
- 신규 회귀 수정 Task에는 review ID, goal ID, 시작 조건, 완료 증거, 범위 밖, 실패 재현 test, 관련 Phase Gate와 검증 기록 항목을 포함한다.
- 확정 항목의 수정은 review 작업과 분리된 goal로 수행한다. focused test와 관련 Phase Gate, `plan-task.md` 검증 기록이 끝나기 전에는 goal을 완료 처리하지 않는다.
- 수정 후 review 문서의 상태를 `수정 완료`로 바꾸고 실제 검증 명령과 결과를 “수정 후 검증 기록”에 누적한다.
## 5. 리뷰 종료 조건
다음을 모두 만족해야 리뷰를 종료한다.
- 검토 범위와 제외 범위가 문서에 명시돼 있다.
- 모든 후보가 `확정`, `오탐`, `보류`, `수정 완료` 중 하나로 판정돼 있다.
- 확정 항목은 `plan-task.md` 회귀 수정 Task로 전환됐거나, 사용자가 수정하지 않기로 한 결정이 기록돼 있다.
- 보류 항목에는 담당 주체와 재개 조건이 있다.
- 실행한 자동·수동 검증과 결과 또는 불가 사유가 기록돼 있다.
- 최종 결론과 남은 항목이 명시돼 있다.
## 6. 사용자 결과 보고
- 발견 사항이 있으면 심각도 순으로 review ID, 핵심 근거, 영향과 후속 조치를 먼저 전달한다.
- 발견 사항이 없으면 검토 범위, 실행한 검증과 남은 위험 또는 검증하지 못한 범위를 함께 전달한다.
- 확정 문제를 아직 수정하지 않았다면 완료·해결됐다고 표현하지 않는다.

106
docs/sample-prd.md
View File

@@ -1,106 +0,0 @@
# PRD: [제품명]
## 1. Overview
이 제품이 무엇인지 한 줄 설명
---
## 2. Problem
어떤 문제를 해결하는가?
- 현재 사용자의 불편
- 기존 방식의 한계
- 왜 지금 필요한가
---
## 3. Goals
성공 기준
예:
- 가입 전환율 20%
- 작업 시간 50% 감소
---
## 4. Non-Goals
이번에 하지 않을 것
매우 중요함.
예:
- 모바일 앱 지원 안 함
- 실시간 협업 제외
- 다국어 제외
---
## 5. Target Users
누가 사용하는가?
- 초보 개발자
- PM
- 디자이너
---
## 6. User Stories
사용자 행동 시나리오
예:
- 사용자는 버튼 하나로 요약하고 싶다
- 사용자는 로그인 없이 체험하고 싶다
---
## 7. Core Features
### Feature A
설명
#### Requirements
- must
- should
- constraints
#### Edge Cases
- 빈 입력
- timeout
- 중복 요청
---
## 8. UX / UI Expectations
- 반응속도
- 클릭 수
- 모바일 대응
- 접근성
---
## 9. Technical Constraints
- Next.js 사용
- PostgreSQL 사용
- API latency 2초 이하
---
## 10. Metrics
무엇을 측정할 것인가?
- retention
- DAU
- conversion
---
## 11. Open Questions
아직 결정 안 된 것
- OAuth 제공?
- pricing?
- offline mode?

294
docs/sample/sample-plan-task.md Normal file
View File

@@ -0,0 +1,294 @@
# Goal 실행형 구현 계획 샘플
> 이 문서는 goal 기능으로 구현 계획을 실행하기 위한 템플릿이다. 실제 `plan-task.md`를 만들 때 `<...>` placeholder를 모두 구체적인 값으로 교체한다. Phase는 결과와 의존성을 묶고, `create_goal`에는 Task 또는 Phase Gate 하나만 등록한다.
| 문서 항목 | 내용 |
|---|---|
| 상태 | 계획 작성 중 / 구현 중 / 외부 조건 대기 / 구현 완료 |
| 작성일 | `YYYY-MM-DD` |
| 요구사항 기준 | `<대상 prd.md 경로>` |
| API 기준 | `<대상 api-contract.md 경로>` |
| 현재 Phase | `<Phase 번호와 이름>` |
| 현재 활성 Goal | `<없음 또는 Goal ID>` |
## 목표
`<사용자가 얻는 최종 결과를 한 문장으로 작성한다. 구현 수단보다 완결된 사용자 흐름을 먼저 쓴다.>`
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 대기 / 진행 중 / 완료 / 제외 | `0/N` | `P1-T1` | `<없음 또는 조건>` |
| 2 | 대기 / 진행 중 / 완료 / 제외 | `0/N` | `P2-T1` | `<없음 또는 조건>` |
- 동시에 하나의 미완료 goal만 운용한다.
- 완료된 Task와 검증 기록은 되돌리거나 삭제하지 않는다. 후속 수정은 회귀 수정 Task와 새 goal ID를 추가한다.
- 사용자가 명시적으로 요청하지 않으면 goal에 token budget을 설정하지 않는다.
## 범위
### 포함
- `<구현할 사용자 흐름>`
- `<구현할 route/API/UI 범위>`
- `<필수 오류·반응형·접근성·test 범위>`
### 제외
- `<이번 릴리스에서 만들지 않을 기능>`
- `<외부 시스템 또는 다음 Phase 소유 범위>`
- `<복원, hard delete처럼 명시적으로 금지한 기능>`
## 기술적 제약
- 기술 스택: `<언어, framework, 주요 library와 version 기준>`
- 아키텍처: `<상태·API·UI·파일 책임 경계>`
- 데이터·보안: `<저장 위치, 인증, 민감정보 비기록 규칙>`
- 호환성: `<지원 browser, viewport, runtime>`
- 의존성: 실제 소비 Task에서 필요한 최소 dependency만 추가한다.
- 계약: 제공되지 않은 endpoint, DTO, enum, 오류 status/key와 validation 상한을 추정하지 않는다.
- 구현: 모든 기능은 가장 작은 실패 test를 먼저 만들고 최소 구현으로 통과시킨다.
## Phase 1
**Phase 결과:** `<이 Phase가 끝나면 사용자가 완료할 수 있는 흐름>`
**선행조건:** `<없음 또는 선행 Goal/Gate ID>`
**Phase 완료 조건:** `P1-T1`~`P1-TN`과 `P1-GATE` 완료, 검증 기록 누적.
### 구현 항목
#### Task 1.1 `<독립적으로 검토 가능한 결과>`
**Goal 실행 `P1-T1`:** `<이 Task가 만드는 결과를 한 문장으로 작성한다.>`
- **시작 조건:** `<선행 Goal, 요구사항 ID, API Contract section>`
- **완료 증거:** `<체크박스 전체, focused test, 산출물, 문서 기록>`
- **범위 밖:** `<다음 Task 또는 다른 Phase가 소유하는 항목>`
**Files:**
- Create: `<정확한 파일 경로>`
- Modify: `<정확한 파일 경로>`
- Test: `<정확한 test 파일 경로>`
**Interfaces:**
- Consumes: `<선행 Task가 제공하는 type/function/component contract>`
- Produces: `<후속 Task가 사용할 정확한 type/function/component contract>`
- [ ] 가장 작은 실패 test를 작성한다.
- [ ] `<focused test 명령>`을 실행해 의도한 assertion 실패를 확인한다.
- [ ] test를 통과시키는 최소 구현을 작성한다.
- [ ] `<focused test 명령>`을 다시 실행해 성공을 확인한다.
- [ ] 관련 typecheck·lint를 실행하고 실제 결과를 Progress에 기록한다.
#### Task 1.2 `<두 번째 독립 결과>`
**Goal 실행 `P1-T2`:** `<이 Task가 만드는 결과를 한 문장으로 작성한다.>`
- **시작 조건:** `P1-T1` 완료와 `<필요한 계약>`.
- **완료 증거:** `<체크박스 전체, test와 문서 기록>`
- **범위 밖:** `<이 Task에서 다루지 않는 항목>`
**Files:**
- Create: `<정확한 파일 경로>`
- Modify: `<정확한 파일 경로>`
- Test: `<정확한 test 파일 경로>`
**Interfaces:**
- Consumes: `<P1-T1이 제공한 정확한 contract>`
- Produces: `<Phase 2 또는 Gate가 사용할 정확한 contract>`
- [ ] 가장 작은 실패 test를 작성하고 의도한 실패를 확인한다.
- [ ] 최소 구현으로 focused test를 통과시킨다.
- [ ] 오류·loading·empty·success와 접근성 상태를 검증한다.
- [ ] 관련 test·typecheck·lint 결과를 Progress에 기록한다.
### 완료 조건
- [ ] `P1-T1`, `P1-T2`의 체크박스와 완료 증거가 모두 충족됐다.
- [ ] Phase 1의 확정 요구사항이 구현·명시적 제외·후속 결정 중 하나로 추적된다.
- [ ] 알려진 문서와 구현의 차이가 없다.
### 검증 방법
#### Phase 1 Gate
**Goal 실행 `P1-GATE`:** Phase 1의 사용자 흐름과 공통 품질 기준을 최종 판정한다.
- **시작 조건:** Phase 1의 모든 활성 Task goal 완료.
- **완료 증거:** 아래 자동·수동 검증 통과와 Progress 기록.
- **범위 밖:** Gate 통과를 위한 test 삭제·완화와 관련 없는 기능 수정.
```bash
<focused unit/integration test 명령>
<Phase 전용 E2E 명령>
<typecheck 명령>
<lint 명령>
<build 명령>
```
**Expected:** `<0 exit code, test 수, 사용자가 완료할 흐름, 금지 요청 0회 등 관찰 가능한 결과>`
수동 검증:
- [ ] `<viewport와 사용자 흐름>`
- [ ] `<keyboard·focus·zoom·접근성 검사>`
- [ ] `<민감정보·network request 검증>`
## Phase 2
**Phase 결과:** `<Phase 1 결과를 소비해 완성하는 다음 사용자 흐름>`
**선행조건:** `P1-GATE` 또는 `<Phase 1의 부분 contract Goal ID>` 완료.
**Phase 완료 조건:** `P2-T1`~`P2-TN`과 `P2-GATE` 완료, 검증 기록 누적.
### 구현 항목
#### Task 2.1 계약·상태 확인
**Goal 실행 `P2-T1`:** Phase 2 구현에 필요한 계약, 상태/action inventory와 component/file map을 확정한다.
- **시작 조건:** `<선행 Goal>` 완료, 관련 PRD/API Contract 확인.
- **완료 증거:** 계약 제공 또는 제외 결정이 기준 문서에 일치하고 구현 map이 기록됨.
- **범위 밖:** 계약을 추정한 production adapter와 실제 기능 구현.
- [ ] 필요한 endpoint·DTO·오류·pagination 계약을 확인한다.
- [ ] loading·empty·error·success·read-only·viewport 상태와 action을 inventory한다.
- [ ] 계약이 없으면 담당 주체·영향·재개 조건과 제외/후속 결정을 문서화한다.
- [ ] Page·feature·shared component와 test file 책임을 확정한다.
#### Task 2.2 `<Phase 2의 독립 구현 결과>`
**Goal 실행 `P2-T2`:** `<사용자가 직접 확인할 수 있는 흐름을 한 문장으로 작성한다.>`
- **시작 조건:** `P2-T1` 완료.
- **완료 증거:** `<contract/UI/E2E test와 문서 기록>`
- **범위 밖:** `<다음 Task 또는 후속 Phase>`
**Files:**
- Create: `<정확한 파일 경로>`
- Modify: `<정확한 파일 경로>`
- Test: `<정확한 test 파일 경로>`
- [ ] contract와 serializer의 실패 test를 먼저 작성한다.
- [ ] UI 상태와 사용자 action의 실패 test를 먼저 작성한다.
- [ ] 최소 구현으로 focused test를 통과시킨다.
- [ ] 관련 integration/E2E와 공통 품질 명령을 실행한다.
- [ ] 실제 결과와 남은 항목을 Progress에 기록한다.
### 완료 조건
- [ ] `P2-T1`, `P2-T2`의 체크박스와 완료 증거가 모두 충족됐다.
- [ ] 외부 의존은 제공 계약 구현 또는 명시적 제외/후속 결정으로 종결됐다.
- [ ] Phase 2의 사용자 흐름과 오류·반응형·접근성 상태가 검증됐다.
### 검증 방법
#### Phase 2 Gate
**Goal 실행 `P2-GATE`:** Phase 2의 contract, 사용자 흐름과 회귀 방지를 최종 판정한다.
- **시작 조건:** Phase 2의 모든 활성 Task goal 완료.
- **완료 증거:** 아래 명령과 Expected 통과, Progress에 실제 결과 누적.
- **범위 밖:** 실패와 무관한 다음 Phase 구현.
```bash
<Phase 2 focused test 명령>
<Phase 2 E2E 명령>
<typecheck·lint·build 명령>
```
**Expected:** `<사용자 journey, 오류 처리, request payload와 금지 동작을 포함한 최종 결과>`
## 실행 순서와 의존성
| 순서 | Goal | 선행조건 | 병행 가능 | 차단 시 다음 행동 |
|---:|---|---|---|---|
| 1 | `P1-T1` | 없음 | 아니요 | 근거 문서 보정 |
| 2 | `P1-T2` | `P1-T1` | 아니요 | 독립 검증 계속 |
| 3 | `P1-GATE` | Phase 1 Task 전체 | 아니요 | 실패 소유 Task의 회귀 수정 goal 생성 |
| 4 | `P2-T1` | `P1-GATE` | 아니요 | 외부 계약 담당·재개 조건 기록 |
| 5 | `P2-T2` | `P2-T1` | `<예/아니요>` | 독립 범위만 계속 수행 |
| 6 | `P2-GATE` | Phase 2 Task 전체 | 아니요 | 실패 소유 Task로 되돌림 |
```text
P1-T1 → P1-T2 → P1-GATE → P2-T1 → P2-T2 → P2-GATE
```
## 변경 금지 항목
- 확정된 요구사항·API Contract를 근거 없이 변경하지 않는다.
- 기존 완료 체크박스와 Progress·Decision Log·검증 기록을 삭제하거나 덮어쓰지 않는다.
- 제공되지 않은 endpoint·DTO·enum·오류 값과 validation 상한을 만들지 않는다.
- 요청 범위 밖의 리팩터링, dependency 추가와 공통 abstraction을 확장하지 않는다.
- test를 삭제·skip·완화하거나 타입 오류를 우회해 Gate를 통과시키지 않는다.
- JWT, password, signed URL, 파일 본문 같은 민감정보를 log·fixture·문서에 기록하지 않는다.
## 의사결정 및 중단 규칙
- PRD와 API Contract가 충돌하면 프로젝트가 정한 우선순위에 따라 결정하고 Decision Log에 근거를 남긴다.
- 구현 범위가 바뀌면 `plan-task.md` 체크박스와 범위를 먼저 갱신한 뒤 코드를 수정한다.
- 안전한 최소 기본값이 문서에 있으면 그 값만 구현한다. 안전하게 구현할 수 없으면 추정하지 않는다.
- 계약 미제공 기능을 제외할 때는 PRD 결정 기록 → API Contract → 이 계획 순서로 갱신한다.
- 같은 차단 사유가 최초 시도와 자동 후속을 포함해 3회 연속 반복되고, 문서화나 독립 작업도 불가능할 때만 goal을 `blocked`로 갱신한다.
- 체크박스 일부, test 일부 또는 코드 작성만 끝난 상태에서는 goal을 `complete`로 갱신하지 않는다.
- 완료 증거와 Progress 기록까지 충족한 뒤에만 goal을 `complete`로 갱신한다.
## Progress
기존 기록을 삭제하거나 덮어쓰지 않고 실제 실행 결과를 차수별로 누적한다.
### `<Goal ID>` N차 실행 — YYYY-MM-DD
- 상태: 진행 중 / 완료 / 차단 감사 중 / 차단
- 무엇을: `<이번 실행에서 완료한 체크박스와 산출물>`
- 왜: `<Task objective와 요구사항 근거>`
- 어떻게:
- `<실행 명령>` — `<성공/실패, exit code, test 수와 핵심 결과>`
- `<수동 검증>` — `<성공/실패/불가 사유>`
- 남은 항목: `<체크박스, 외부 조건 또는 없음>`
- 다음 행동: `<같은 goal에서 이어서 할 가장 작은 단계>`
## Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 |
|---|---|---|---|---|---|
| `YYYY-MM-DD` | `DEC-001` | 제안 / 확정 / 정정 | `<결정 내용>` | `<요구사항, 계약, 검증 근거>` | `<Goal ID와 문서>` |
- 기존 결정을 정정할 때 원문을 지우지 않고 새 `정정` 행을 추가한다.
- 외부 의존 제외, 새로운 dependency, 범위 변경, 안전한 기본값 선택은 반드시 기록한다.
## 발견된 문제
| ID | 심각도 | 상태 | 발견 내용 | 영향 Goal | 처리 계획 |
|---|---|---|---|---|---|
| `ISSUE-001` | Blocker / High / Medium / Low | 후보 / 확정 / 보류 / 해결 | `<관찰 사실>` | `<Goal ID>` | `<수정 Task, 외부 담당 또는 없음>` |
- 구현 중 발견한 범위 내 문제는 근거와 재현 방법을 기록하고 해당 Task에서 처리한다.
- 완료된 범위의 회귀는 기존 Task를 다시 열지 않고 별도 회귀 수정 Task와 goal을 만든다.
- 범위 밖 문제는 임의로 수정하지 않고 사용자에게 보고하거나 후속 Task로 결정한다.
- 상세 코드 리뷰 결과가 필요하면 `sample-review.md` 형식의 별도 review 문서를 사용한다.
## 최종 보고 형식
```markdown
구현 결과: <완료한 Phase와 사용자 흐름>
- 변경: <주요 파일과 동작>
- 결정: <중요한 Decision Log ID와 내용>
- 검증:
- `<실행 명령>` — <성공/실패와 핵심 수치>
- `<수동 검증>` — <성공/실패/불가 사유>
- 남은 항목: <외부 의존, 후속 범위 또는 없음>
- 문서: <갱신한 PRD/API Contract/plan/review 링크>
```
최종 보고는 성공을 추정하지 않는다. 실제 실행한 최신 검증 결과와 완료되지 않은 범위를 함께 전달한다.

270
docs/sample/sample-prd.md Normal file
View File

@@ -0,0 +1,270 @@
# 제품 요구사항 문서(PRD) 샘플
> 이 문서는 요구사항을 API Contract와 goal 실행형 `plan-task.md`로 연결하기 위한 템플릿이다. 실제 `prd.md`를 만들 때 `<...>` placeholder와 예시 ID를 모두 제품의 구체적인 값으로 교체한다.
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 초안 / 검토 중 / 구현 기준 확정 / 구현 완료 |
| 작성일 | `YYYY-MM-DD` |
| 최종 수정일 | `YYYY-MM-DD` |
| 대상 제품 | `<제품 또는 기능 이름>` |
| 작성자·결정권자 | `<이름 또는 역할>` |
| 관련 API Contract | `<대상 api-contract.md 경로>` |
| 관련 구현 계획 | `<대상 plan-task.md 경로>` |
| 관련 review | `<없음 또는 review 문서 링크>` |
### 요구사항 상태
| 상태 | 의미 | 구현 처리 |
|---|---|---|
| 확정 | 제품·기술 결정이 완료되어 구현 기준으로 사용 | `plan-task.md`의 Task와 완료 증거로 추적 |
| 미결 | 제품·UX·운영 결정이 더 필요함 | 권고안과 결정 주체·기한을 기록하고 임의 구현 금지 |
| 외부 의존 | 프론트엔드 밖의 계약·권한·환경 제공이 필요함 | 담당 주체·영향·재개 조건을 기록하고 추정 구현 금지 |
| 권고 | 미결 항목에 대한 현재 추천안 | 확정되기 전 계약이나 수용 기준으로 사용하지 않음 |
| 제외 | 현재 릴리스에서 구현하지 않기로 결정 | 제외 이유와 후속 조건을 Decision Log에 기록 |
### 문서 우선순위와 갱신 순서
1. 사용자·제품 결정은 이 PRD에 기록한다.
2. request/response/error 계약은 `api-contract.md`에 정규화한다.
3. 구현 범위·순서·완료 증거는 `plan-task.md`에 반영한다.
4. 요구사항이 바뀌면 Decision Log → 관련 요구사항·수용 기준 → API Contract → plan 순서로 갱신한다.
5. 기존 결정과 검증 기록은 삭제하거나 덮어쓰지 않고 정정 기록을 누적한다.
## 1. Overview
`<누가 어떤 상황에서 어떤 가치를 얻는 제품인지 2~4문장으로 설명한다.>`
## 2. Problem Statement
현재 사용자는 다음 문제를 겪는다.
- `<관찰 가능한 현재 문제>`
- `<기존 방식의 비용·위험·제약>`
- `<해결하지 않을 때의 사용자 또는 사업 영향>`
문제를 해결했다는 판단은 `<측정하거나 직접 확인할 결과>`로 한다.
## 3. Goals
### 3.1 제품 목표
- `<사용자가 완료할 수 있어야 하는 핵심 결과>`
- `<안전성·운영 효율·데이터 품질 목표>`
- `<릴리스 후 측정 가능한 성공 목표>`
### 3.2 UX 목표
- `<핵심 흐름의 명확성·속도 목표>`
- `<오류·loading·empty·success feedback 목표>`
- `<반응형·keyboard·접근성 목표>`
## 4. Non-Goals
- `<명시적으로 구현하지 않을 기능>`
- `<다음 릴리스 또는 외부 시스템 소유 범위>`
- `<복원, hard delete, 자동 갱신처럼 금지할 동작>`
Non-Goal을 변경하려면 Decision Log와 `plan-task.md` 범위를 먼저 갱신한다.
## 5. Target Users and Permissions
### 5.1 사용자
| 사용자 | 목표 | 주요 작업 | 사용 환경 |
|---|---|---|---|
| `<역할>` | `<달성 목표>` | `<조회·생성·수정 등>` | `<desktop/mobile 등>` |
### 5.2 권한
- 인증 주체: `<사용자 또는 시스템>`
- 허용 역할: `<role 목록>`
- 거부 조건: `<401/403 또는 제품 정책>`
- 리소스 소유권: `<tenant, characterId, ownerId 등 격리 기준>`
- read-only 조건: `<비활성·권한 부족·외부 상태 등>`
## 6. 핵심 사용자 흐름
1. `<시작 조건과 진입점>`
2. `<대상 탐색·선택>`
3. `<핵심 생성·조회·수정 동작>`
4. `<성공 feedback과 다음 화면>`
5. `<오류·권한·session 만료 복구>`
각 흐름은 `plan-task.md`의 최소 하나의 Phase 결과와 E2E 완료 증거로 연결한다.
## 7. 정보 구조와 라우팅
```text
/<entry>
/<resource>
/<resource>/:resourceId
/<child-resource>
```
- 전역 화면과 선택된 리소스 문맥의 경계를 명시한다.
- URL path와 query에 보존할 식별자·검색·filter·page 상태를 명시한다.
- 직접 링크·새로고침이 가능한 화면과 collection modal/Sheet처럼 별도 route가 없는 화면을 구분한다.
- 존재하지 않음, 다른 소유자, 비활성 리소스의 처리는 서버 계약과 공통 오류 정책을 따른다.
## 8. 기능 요구사항
요구사항 ID는 `<DOMAIN>-NNN` 형식을 사용한다. 하나의 행에는 독립적으로 판정 가능한 요구사항 하나만 작성한다.
### 8.1 `<도메인 A>`
| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
|---|---|---|---|---|
| `DOMAINA-001` | 확정 | `<사용자가 할 수 있어야 하는 동작>` | `<관찰 가능한 성공·오류 결과>` | `api-contract.md §<번호>`, `P1-T1` |
| `DOMAINA-002` | 확정 | `<payload·상태·권한 불변식>` | `<보내야/보내지 말아야 할 값과 test>` | `P1-T2` |
| `DOMAINA-003` | 외부 의존 | `<외부 제공이 필요한 계약>` | `<제공 전 network integration 0건>` | `EXT-001`, `P1-T1` |
### 8.2 `<도메인 B>`
| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
|---|---|---|---|---|
| `DOMAINB-001` | 확정 | `<목록·상세·mutation 흐름>` | `<loading·empty·error·success 포함>` | `api-contract.md §<번호>`, `P2-T2` |
| `DOMAINB-002` | 미결 | `<제품 결정이 필요한 항목>` | `<확정 전 최대값·동작 추정 금지>` | `OQ-001` |
### 8.3 공통 파일·데이터 정책
| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
|---|---|---|---|---|
| `FILE-001` | 확정 | `<허용 확장자·MIME·크기>` | `<정확한 byte 경계 test>` | `api-contract.md §<번호>`, `<Goal ID>` |
| `DATA-001` | 확정 | `<날짜·가격·enum·pagination 규칙>` | `<formatter/schema/contract test>` | `<Goal ID>` |
## 9. 반응형 기능 범위
| 기능 | Desktop | Tablet | Mobile | 비고 |
|---|---:|---:|---:|---|
| 조회 | 전체 | 전체 | 전체 | `<예외>` |
| 생성·수정 | 허용 | 허용 | 허용 / 조회 전용 | `<직접 route 차단 정책>` |
| 파일 upload | 허용 | 허용 | 허용 / 미지원 | `<이유>` |
- 화면에서 action을 숨기는 것뿐 아니라 직접 route와 mutation capability도 같은 정책으로 차단한다.
- 최소 viewport, zoom, touch target과 virtual keyboard 조건을 수용 기준에 연결한다.
## 10. UI/UX Expectations
### 10.1 디자인과 component 원칙
- `<브랜드 token, theme 범위, typography>`
- Page는 route·query·permission·component 조합을 담당한다.
- 도메인 표시·입력·상호작용은 feature component가 담당한다.
- 두 개 이상 Phase에서 같은 의미·동작으로 재사용할 때만 shared component로 올린다.
### 10.2 화면 상태
- 모든 비동기 화면에 loading·empty·error·success 상태를 정의한다.
- mutation에는 진행 중·성공·실패·재시도·중복 제출 정책을 정의한다.
- destructive action에는 대상·영향·복구 여부를 알리는 확인 절차를 둔다.
### 10.3 접근성
- 모든 input은 visible label과 연결된 오류를 가진다.
- keyboard-only 흐름, focus 표시·복귀, skip link와 live region 기준을 명시한다.
- 색상만으로 상태를 전달하지 않고 목표 대비와 touch target을 명시한다.
- `<지원 viewport>`, 200% zoom과 axe critical·serious 0건을 수용 기준으로 사용한다.
## 11. API 계약
### 11.1 공통 규칙
- base URL과 인증 header: `<값>`
- locale: `<header와 값>`
- 성공 envelope: `<type 또는 예시>`
- 오류 envelope와 status: `<type 또는 예시>`
- pagination: `<page/size/total/hasNext 규칙>`
- multipart JSON part: `<이름>`
### 11.2 Endpoint 추적
| 요구사항 | Method | Path | 계약 상태 | API Contract | 소유 Goal |
|---|---|---|---|---|---|
| `DOMAINA-001` | `<METHOD>` | `<path>` | 제공됨 / 보정 필요 / 제공 대기 | `§<번호>` | `<Goal ID>` |
### 11.3 외부 제공 대기 계약
| ID | 우선순위 | 제공 필요 계약 | 담당 주체 | 구현 영향 | 재개 조건 |
|---|---:|---|---|---|---|
| `EXT-001` | P0 / P1 | `<endpoint·DTO·오류 규칙>` | `<팀/역할>` | `<차단되는 흐름>` | `<문서와 fixture 제공>` |
- P0 계약이 없으면 영향을 받는 network flow를 완료로 표시하지 않는다.
- 계약에 의존하지 않는 UI shell·상태 inventory·문서화는 독립적으로 진행할 수 있다.
## 12. 보안과 데이터 취급
- 인증 정보 저장 위치와 lifecycle: `<정확한 정책>`
- log·분석·오류 리포트 금지 값: `<token, password, signed URL 등>`
- 업로드 파일명·MIME·본문 취급: `<정책>`
- 리소스 격리와 ownership 검증: `<정책>`
- 401·403·동시 실패 처리: `<정책>`
- 감사 로그: `<포함, 외부 의존 또는 후속 범위>`
## 13. 성능과 품질 요구사항
- 목록 pagination과 전체 로드 예외: `<정책>`
- 검색 debounce와 기존 데이터 유지: `<정책>`
- image layout shift와 lazy loading: `<정책>`
- mutation 중복 제출·upload 취소/재시도: `<정책>`
- 지원 runtime·browser: `<정확한 범위>`
- test stack과 필수 Gate: `<unit/integration/E2E/typecheck/lint/build>`
## 14. 성공 기준
### 14.1 기능 수용 기준
- [ ] `<핵심 사용자 journey가 성공한다.>` (`DOMAINA-001`, `P1-GATE`)
- [ ] `<권한·오류·payload 불변식이 검증된다.>` (`DOMAINA-002`, `<test>`)
- [ ] `<외부 의존의 구현 또는 제외 결정이 문서화된다.>` (`EXT-001`)
### 14.2 UI/UX 수용 기준
- [ ] loading·empty·error·success 상태가 있다.
- [ ] keyboard-only로 핵심 흐름을 완료한다.
- [ ] `<최소 viewport>`와 200% zoom에서 핵심 control이 가려지지 않는다.
- [ ] axe critical·serious 위반이 0건이다.
### 14.3 추적성 완료 기준
- [ ] 모든 `확정` 요구사항이 API Contract와 하나 이상의 Task/Goal 완료 증거로 연결된다.
- [ ] 모든 `미결` 항목에 결정 주체와 다음 행동이 있다.
- [ ] 모든 `외부 의존` 항목에 담당 주체·영향·재개 조건이 있다.
- [ ] `제외` 항목에 Decision Log와 후속 조건이 있다.
## 15. Open Questions
| ID | 상태 | 결정 필요 사항 | 현재 권고 | 결정 주체 | 결정 기한/시점 | 영향 Goal |
|---|---|---|---|---|---|---|
| `OQ-001` | 미결 | `<질문>` | `<권고안 또는 없음>` | `<역할>` | `<날짜 또는 UI 작성 후>` | `<Goal ID>` |
- Open Question과 외부 의존을 혼합하지 않는다. 제품이 결정할 수 없는 backend 계약은 `EXT-*`로 관리한다.
- 미결 값을 임의의 상수·enum·endpoint로 구현하지 않는다.
## 16. 요구사항 추적표
| 요구사항 범위 | API Contract | 계획 Phase | Goal | 자동 검증 | 수동 검증 |
|---|---|---:|---|---|---|
| `DOMAINA-001~003` | `§<번호>` | 1 | `P1-T1`, `P1-T2`, `P1-GATE` | `<test 경로>` | `<흐름>` |
| `DOMAINB-001~002` | `§<번호 또는 제공 대기>` | 2 | `P2-T1`, `P2-T2`, `P2-GATE` | `<test 경로>` | `<흐름>` |
## 17. Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·계약·Goal |
|---|---|---|---|---|---|
| `YYYY-MM-DD` | `DEC-001` | 확정 / 정정 / 폐기 | `<결정 내용>` | `<인터뷰·계약·검증 근거>` | `<ID와 문서 section>` |
- 기존 결정을 수정할 때 원문을 지우지 않고 `정정` 행을 추가한다.
- 범위 변경, Non-Goal 변경, 외부 의존 제외, 안전한 기본값과 주요 기술 선택을 기록한다.
## 18. 변경 관리
요구사항 변경 시 다음을 확인한다.
- [ ] Decision Log에 변경 이유와 날짜를 기록했다.
- [ ] 관련 요구사항 상태·본문·수용 기준을 갱신했다.
- [ ] API Contract의 request/response/error와 fixture를 갱신했다.
- [ ] `plan-task.md`의 범위·Files·Interfaces·체크박스·완료 증거를 코드 변경 전에 갱신했다.
- [ ] 기존 Progress·review·검증 기록을 삭제하거나 덮어쓰지 않았다.

185
docs/sample/sample-review.md Normal file
View File

@@ -0,0 +1,185 @@
# 코드 리뷰 보고서 샘플
> 이 문서는 완료된 Phase를 다시 검토할 때 사용하는 템플릿이다. 리뷰에서 발견한 후보를 먼저 검증하고, **확정**된 항목만 `plan-task.md`의 회귀 수정 Task와 goal로 전환한다. 기존 완료 체크박스와 검증 기록은 삭제하거나 되돌리지 않는다.
## 1. 리뷰 정보
| 항목 | 내용 |
|---|---|
| 리뷰 대상 | Phase `<번호>` / Task `<번호 또는 범위>` |
| 기준 commit 또는 working tree | `<commit SHA 또는 변경 상태>` |
| 리뷰 일자 | `YYYY-MM-DD` |
| 리뷰어 | `<이름 또는 agent>` |
| 기준 문서 | `<대상 prd.md, api-contract.md, plan-task.md 경로>` |
| 리뷰 상태 | 진행 중 / 판정 완료 / 수정 검증 완료 |
## 2. 리뷰 목적과 범위
### 목적
- `<예: Phase 0~1 구현이 요구사항과 API Contract를 충족하는지 확인한다.>`
- `<예: 완료 체크박스와 실제 코드·test·검증 기록이 일치하는지 확인한다.>`
### 포함 범위
- 코드: `<검토할 경로>`
- 테스트: `<검토할 unit/integration/E2E 경로>`
- 문서: `<검토할 요구사항·계약·Task 범위>`
- 수동 검증: `<브라우저, viewport, keyboard, 접근성 등>`
### 제외 범위
- `<이번 리뷰에서 다루지 않는 Phase, 기능 또는 외부 계약>`
## 3. 판정 기준
### 심각도
| 심각도 | 기준 |
|---|---|
| Blocker | 보안·데이터 손실 위험, 핵심 흐름 불능, 완료 판정을 무효화하는 문제 |
| High | 확정 요구사항·API Contract 위반 또는 주요 회귀 |
| Medium | 제한된 조건에서 발생하는 기능·접근성·복구 문제 |
| Low | 유지보수성, 문서 정합성 또는 비핵심 UX 문제 |
### 상태
| 상태 | 의미 | 후속 처리 |
|---|---|---|
| 후보 | 근거를 발견했지만 아직 재현·판정하지 않음 | 검증 후 상태 변경 |
| 확정 | 코드·test·문서 근거로 문제가 확인됨 | `plan-task.md` 회귀 수정 Task 후보 |
| 오탐 | 요구사항이나 실행 결과상 문제가 아님 | 근거를 남기고 종료 |
| 보류 | 외부 계약·환경·제품 결정이 필요함 | 담당 주체와 재개 조건 기록 |
| 수정 완료 | 수정과 관련 검증이 완료됨 | 실행 명령과 결과 연결 |
## 4. 검토한 근거
### 문서와 코드
- 요구사항: `<예: AUTH-001~013>`
- API Contract: `<예: §3 인증>`
- 계획: `<예: P1-T2, P1-T3, P1-GATE>`
- 코드: `<파일 경로와 line>`
- 테스트: `<테스트 파일과 test name>`
### 실행 환경
```text
OS: <값>
Node: <값>
npm: <값>
Browser/viewport: <값>
환경 변수: 민감정보를 제외한 이름과 사용 mode만 기록
```
### 실행한 검증
| 명령 또는 수동 검증 | 결과 | 핵심 증거 |
|---|---|---|
| `<실제 실행 명령>` | 성공 / 실패 / 불가 | `<exit code, test 수, 오류 또는 불가 사유>` |
| `<수동 검증 절차>` | 성공 / 실패 / 불가 | `<관찰 결과>` |
## 5. 발견 사항 요약
| ID | 심각도 | 상태 | 제목 | 소유 Task | 후속 goal |
|---|---|---|---|---|---|
| `REV-P1-001` | `<심각도>` | 후보 | `<한 문장 제목>` | `<예: P1-T3>` | 판정 전 |
발견 사항이 없으면 “확정 발견 사항 없음”이라고 명시하고, 검토 범위와 실행 증거는 그대로 남긴다.
## 6. 발견 사항 상세
### REV-P1-001 — `<한 문장 제목>`
- **심각도:** `<Blocker | High | Medium | Low>`
- **상태:** `<후보 | 확정 | 오탐 | 보류 | 수정 완료>`
- **관련 요구사항:** `<요구사항 ID 또는 없음>`
- **관련 계약:** `<api-contract.md section 또는 없음>`
- **소유 Task:** `<기존 Goal ID 또는 신규 회귀 Task>`
**관찰 내용**
`<실제로 관찰한 동작을 추정 없이 작성한다.>`
**근거**
- 코드: `<파일 경로:line과 관련 동작>`
- 테스트: `<테스트 파일:test name 또는 누락 사실>`
- 문서: `<문서 경로와 요구사항/계약/계획 항목>`
**재현 또는 검증 절차**
1. `<사전 조건>`
2. `<실행 명령 또는 사용자 동작>`
3. `<실제 결과>`
4. `<요구되는 결과>`
**영향**
`<사용자, 데이터, 보안, 접근성, 회귀 범위를 구체적으로 작성한다.>`
**권장 조치**
`<최소 수정 방향과 추가해야 할 회귀 test를 작성한다. 구현 전 확정되지 않은 endpoint·DTO·오류 값은 추정하지 않는다.>`
**판정 기록**
- `YYYY-MM-DD` — `<확정/오탐/보류 판정과 근거>`
- `YYYY-MM-DD` — `<후속 정정이 있으면 기존 기록을 지우지 않고 추가>`
## 7. 확정 항목의 plan·goal 전환
확정 발견 사항이 없으면 이 절에 “전환 항목 없음”을 기록한다. 확정 항목이 있으면 구현 전에 `plan-task.md`에 아래 내용을 반영한다.
### 신규 회귀 수정 Task 초안
```markdown
### Task R<번호>.<번호> <수정할 결과>
**Goal 실행 `P<Phase>-R<번호>`:** <확정된 문제를 수정하고 회귀를 방지하는 한 문장 objective>
- **시작 조건:** <관련 review ID, 기존 Task/Gate, 필요한 계약>
- **완료 증거:** <실패 재현 test → 수정 후 focused test → Phase Gate → 검증 기록>
- **범위 밖:** <이번 수정에서 건드리지 않을 기능>
- [ ] `<재현 가능한 실패 test를 먼저 추가하고 의도한 assertion 실패를 확인한다.>`
- [ ] `<최소 수정으로 test를 통과시킨다.>`
- [ ] `<관련 focused test와 Phase Gate를 실행한다.>`
- [ ] `<plan-task.md 하단에 무엇을/왜/어떻게를 누적한다.>`
```
### create_goal objective 초안
```text
[P<Phase>-R<번호>]의 확정 review 항목 <REV-ID 목록>을 수정하고 회귀를 방지한다.
plan-task.md에 추가된 회귀 수정 Task만 수행한다.
실패 재현, 최소 수정, focused test, Phase Gate와 검증 기록이 모두 끝나기 전에는 complete로 표시하지 않는다.
관련 없는 리팩터링과 계약 추정은 범위 밖이다.
```
## 8. 리뷰 종료 판정
| 판정 항목 | 결과 | 근거 |
|---|---|---|
| 리뷰 범위 전체 확인 | 충족 / 미충족 | `<근거>` |
| 후보 항목 판정 완료 | 충족 / 미충족 | `<근거>` |
| 확정 항목 plan 반영 | 충족 / 해당 없음 / 미충족 | `<Task 또는 사유>` |
| 보류 항목의 담당·재개 조건 기록 | 충족 / 해당 없음 / 미충족 | `<근거>` |
| 검증 명령과 결과 기록 | 충족 / 미충족 | `<근거>` |
**최종 결론:** `<확정 발견 사항 없음 | 수정 goal 필요 | 외부 조건 대기 | 수정 검증 완료>`
**남은 항목:** `<없음 또는 review ID와 다음 행동>`
## 9. 수정 후 검증 기록
기존 기록을 삭제하거나 덮어쓰지 않고 차수별로 누적한다.
### N차 수정 검증 — YYYY-MM-DD
- 무엇을: `<수정한 review ID와 결과>`
- 왜: `<요구사항·계약 위반 또는 회귀 위험>`
- 어떻게:
- `<실행 명령>` — `<성공/실패와 핵심 수치>`
- `<수동 검증>` — `<성공/실패/불가 사유>`
- 남은 항목: `<없음, 보류 또는 후속 review ID>`