diff --git a/AGENTS.md b/AGENTS.md index 9c2fae1c..292f4f0d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,12 +114,19 @@ Strong success criteria let you loop independently. Weak criteria ("make it work - 예: `docs/20260601_메인_홈_추천_UI와_API_연동/` - 기존에 생성된 `docs/prd/`, `docs/plan-task/` 문서는 유지하고, 신규 생성 문서부터 위 구조를 적용한다. - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다. -- PRD 문서는 `sample-prd.md` 파일에서 작업에 필요한 부분만 발췌해 작성한다. `sample-prd.md`가 없거나 위치가 불명확하면 추측하지 말고 사용자에게 확인한다. +- 문서 샘플의 기준 위치는 `docs/sample/`이다. +- PRD 문서는 `docs/sample/sample-prd.md`, 구현 계획/TASK 문서는 `docs/sample/sample-plan-task.md`를 참조해 작업에 필요한 항목을 구체화한다. +- 샘플의 `<...>` placeholder와 예시 값은 실제 작업 값으로 교체한다. 필요한 샘플이 없거나 위치가 불명확하면 추측하지 말고 사용자에게 확인한다. - 연속된 하나의 작업이라면 별도 새 문서를 만들지 말고 기존 PRD와 계획/TASK 문서에 추가 작업으로 이어서 기록한다. - 작업 도중 범위가 변경되면 계획/TASK 문서 체크리스트를 먼저 업데이트한 뒤 구현한다. - 특정 Phase 또는 Task에 직접 대응되는 검증 기록은 해당 Phase 또는 Task 아래에 한국어로 남긴다. - 여러 Phase에 걸치거나 문서 전체에 해당하는 통합 검증, 회귀 검증, 최종 수동 확인 기록은 문서 최하단 `Verification Log`에 한국어로 남긴다. -- 후속 수정이 발생해도 기존 검증 기록은 삭제하거나 덮어쓰지 않고 위치별로 누적한다. +- 코드 리뷰, 코드 품질 점검, 완료 Phase 재검토를 수행하면 `docs/sample/sample-review.md`를 참조해 `docs/[날짜]_구현할내용한글/reviews/[리뷰범위]-review.md`에 결과를 기록한다. +- 리뷰 보고서명의 `[리뷰범위]`는 `phase<번호>-<구현 내용을 나타내는 영문 kebab-case>` 형식으로 작성한다. 예: `phase2-main-home-recommendation-review.md` +- 일반 빌드, 테스트, 린트 실행 결과는 리뷰 보고서를 만들지 않고 계획/TASK 문서의 Task별 검증 기록 또는 `Verification Log`에 남긴다. +- 리뷰에서 수정 항목이 확정되면 코드를 수정하기 전에 review ID, 대상 파일, 수정 범위, 회귀 테스트, 완료 증거를 포함한 신규 회귀 수정 Task를 `plan-task.md`의 해당 Phase에 추가하고 그 Task에 따라 바로 수정한다. +- 리뷰 후속 수정 시 기존 완료 Task를 다시 열지 않으며, 기존 완료 체크박스와 검증·리뷰 기록은 삭제하거나 덮어쓰지 않고 위치별로 누적한다. +- 샘플의 위치, 문서 구조, 작성·운용 규칙이 변경되면 같은 작업에서 `AGENTS.md`와 관련 가이드 문서를 함께 갱신한다. ## 상세 참조 문서 - 빌드/린트/테스트는 `docs/agent-guides/build-test-style.md`를 참고한다. diff --git a/docs/20260601_계획문서규칙수정/plan-task.md b/docs/20260601_계획문서규칙수정/plan-task.md index 38d72523..c8fb6d1f 100644 --- a/docs/20260601_계획문서규칙수정/plan-task.md +++ b/docs/20260601_계획문서규칙수정/plan-task.md @@ -42,6 +42,192 @@ - 파일 경로: `docs/20260601_계획문서규칙수정/plan-task.md` - 검증 기준: 문서 하단에 무엇/왜/어떻게, 실행 명령, 결과를 한국어로 누적 기록한다. +## 2026-07-30 후속 실행 정보 + +| 문서 항목 | 내용 | +|---|---| +| 상태 | 구현 완료 | +| 요구사항 기준 | `docs/20260601_계획문서규칙수정/prd.md`의 `12. 2026-07-30 후속 변경` | +| 샘플 기준 | `docs/sample/sample-plan-task.md` | +| 현재 Phase | Phase 4: 샘플 문서와 리뷰 보고서 규칙 | +| 현재 활성 Goal | 없음(별도 goal 생성 요청 없음) | + +### 목표 + +PRD·구현 계획/TASK·리뷰 보고서의 기준 샘플과 유지보수 절차를 명확히 하고, 리뷰에서 확정된 수정 항목을 해당 Phase의 신규 Task로 바로 전환할 수 있게 한다. + +### 범위 + +#### 포함 + +- `AGENTS.md`의 작업 절차 핵심 규칙 +- `docs/agent-guides/work-plan-docs.md`의 상세 작성·유지보수·리뷰 후속 규칙 +- 기존 PRD와 계획/TASK 문서의 후속 요구사항·Task·검증 기록 누적 + +#### 제외 + +- 과거 작업 문서의 일괄 변환 +- Android 앱 소스와 빌드 설정 변경 +- 일반 빌드·테스트·린트 결과를 위한 리뷰 보고서 생성 +- 실제 코드 리뷰를 수행하지 않는 이번 문서 정비 작업의 `reviews/` 폴더 생성 + +### 기술적 제약 + +- Markdown 문서만 수정한다. +- 사용자 작업인 `docs/prd/sample-prd.md` 삭제와 `docs/sample/`의 신규 샘플 3종을 변경하지 않는다. +- 기존 완료 Task와 검증 기록을 삭제하거나 미완료로 되돌리지 않는다. +- 제공되지 않은 리뷰 파일 이름이나 범위는 미리 만들지 않는다. +- 문서 Task는 production 동작을 변경하지 않아 TDD를 적용하지 않고 경로·문구 대조와 명령 검증으로 대체한다. + +### Phase 4: 샘플 문서와 리뷰 보고서 규칙 + +**Phase 결과:** 에이전트가 세 샘플의 정확한 위치를 따라 문서를 작성하고, 코드 리뷰 결과와 확정 수정 항목을 일관된 경로와 Task로 추적할 수 있다. + +**선행조건:** Phase 3 완료와 `DEC-001~003` 확정. + +**Phase 완료 조건:** `P4-T1`~`P4-T3`, `P4-T5`, `P4-GATE`, `P4-GATE-2`의 체크리스트와 완료 증거가 모두 충족되고 검증 기록이 누적된다. + +#### Task 4.1 후속 요구사항과 실행 계획 확정 + +**Goal 실행 `P4-T1`:** 새 샘플과 사용자 결정을 기존 PRD·계획/TASK 문서에 추적 가능한 후속 범위로 기록한다. + +- **시작 조건:** `docs/sample/`의 샘플 3종과 사용자 결정 확인. +- **완료 증거:** PRD의 `DOC-001~004`, `REV-001~005`, `DEC-001~003`과 이 Phase의 Task·완료 조건. +- **범위 밖:** 규칙 문서와 샘플 원문 수정. +- **TDD 예외 사유:** production 동작을 변경하지 않는 문서 계획 Task다. +- **대체 검증 방법:** 샘플 경로, 요구사항 ID, Task 연결을 `rg`와 `git diff --check`로 대조한다. + +- [x] `docs/sample/sample-prd.md`, `docs/sample/sample-plan-task.md`, `docs/sample/sample-review.md`의 구조와 경로를 확인한다. +- [x] 사용자 결정과 리뷰 후속 절차를 `prd.md`에 누적한다. +- [x] 기존 완료 Task를 유지하고 Phase 4 실행 계획을 추가한다. + +#### Task 4.2 `AGENTS.md` 핵심 규칙 갱신 + +**Goal 실행 `P4-T2`:** 작업 시작 시 샘플 위치와 리뷰 보고서·후속 수정의 필수 순서를 바로 확인할 수 있게 한다. + +- **시작 조건:** `P4-T1` 완료. +- **완료 증거:** `DOC-001~004`, `REV-001~005`의 핵심 원칙이 `AGENTS.md`에 요약되고 상세 가이드 경로가 유지된다. +- **범위 밖:** 상세 템플릿 전체 복제와 다른 실행 원칙 수정. +- **TDD 예외 사유:** 에이전트 안내 문구만 변경하는 문서 Task다. +- **대체 검증 방법:** 세 샘플 경로, `reviews/` 경로, 해당 Phase 신규 Task 선행 규칙을 검색해 확인한다. + +**Files:** + +- Modify: `AGENTS.md` + +- [x] 기존 `sample-prd.md` 안내를 `docs/sample/sample-prd.md`의 정확한 경로로 바꾼다. +- [x] 구현 계획/TASK 문서가 `docs/sample/sample-plan-task.md`를 참조하도록 명시한다. +- [x] 리뷰 보고서 대상·샘플·저장 경로와 일반 검증 제외 규칙을 요약한다. +- [x] 확정 리뷰 항목은 코드 수정 전에 해당 Phase의 신규 회귀 수정 Task로 추가하도록 명시한다. +- [x] 기존 완료·검증·리뷰 기록 보존 규칙을 유지한다. + +검증 기록(2026-07-30): + +- `rg -n "docs/sample/sample-(prd|plan-task|review)\\.md|reviews/|신규 회귀 수정 Task|기존 완료 Task|빌드.*테스트.*린트|샘플.*변경" AGENTS.md` 실행 결과, 세 샘플 경로와 리뷰 보고서·후속 Task·기록 보존 규칙을 확인했다. +- `git diff --check -- AGENTS.md`는 출력 없이 exit code 0으로 통과했다. + +#### Task 4.3 `work-plan-docs.md` 상세 규칙 갱신 + +**Goal 실행 `P4-T3`:** 문서 작성, 샘플 동기화, 리뷰 보고서 작성, 확정 항목의 수정 전환 절차를 하나의 상세 가이드에서 확인할 수 있게 한다. + +- **시작 조건:** `P4-T2` 완료. +- **완료 증거:** PRD·계획/TASK·리뷰 보고서별 샘플과 작성 절차, 문서 유지보수 규칙, 리뷰 후속 Task 전환 규칙이 구체적으로 기록된다. +- **범위 밖:** 샘플 문서 원문 변경과 코드 리뷰 수행. +- **TDD 예외 사유:** 작업 절차 문구만 변경하는 문서 Task다. +- **대체 검증 방법:** 요구사항별 문구 대조표와 경로 검색, Markdown diff 검증을 사용한다. + +**Files:** + +- Modify: `docs/agent-guides/work-plan-docs.md` + +- [x] PRD와 계획/TASK 문서의 기준 샘플 경로와 placeholder 구체화 규칙을 명시한다. +- [x] 리뷰 보고서 생성 대상, `sample-review.md`, `reviews/[리뷰범위]-review.md` 경로를 명시한다. +- [x] 일반 빌드·테스트·린트 결과는 Task별 검증 기록 또는 `Verification Log`에 남기도록 구분한다. +- [x] 확정 리뷰 항목을 review ID와 연결한 해당 Phase 신규 회귀 수정 Task로 먼저 추가하고 바로 수정하는 순서를 명시한다. +- [x] 샘플 위치·구조·작성 규칙 변경 시 `AGENTS.md`와 관련 가이드를 함께 동기화하도록 유지보수 규칙을 추가한다. + +검증 기록(2026-07-30): + +- `rg -n "docs/sample/sample-(prd|plan-task|review)\\.md|reviews/|신규 회귀 수정 Task|기존 완료 Task|빌드.*테스트.*린트|샘플.*변경" docs/agent-guides/work-plan-docs.md` 실행 결과, 기준 샘플·리뷰 보고서·확정 항목 전환·유지보수 규칙을 확인했다. +- `rg -n '### Phase [0-9]|docs/prd/sample-prd\\.md|체크박스.*Task N\\.N' AGENTS.md docs/agent-guides/work-plan-docs.md`는 결과가 없어 폐기된 경로와 이전 Phase/Task 형식 안내가 남지 않았음을 확인했다. +- `git diff --check -- docs/agent-guides/work-plan-docs.md`는 출력 없이 exit code 0으로 통과했다. + +#### Phase 4 Gate + +**Goal 실행 `P4-GATE`:** 샘플 경로, 리뷰 보고서 범위, 확정 항목 전환 순서, 기존 기록 보존 규칙의 문서 간 정합성을 판정한다. + +- **시작 조건:** `P4-T1`~`P4-T3` 완료. +- **완료 증거:** 아래 명령이 성공하고 실제 결과가 `검증 기록`에 누적된다. +- **범위 밖:** 앱 빌드·테스트와 과거 문서 일괄 정비. + +- [x] **Task 4.4: 문서 정합성 및 명령 유효성 검증** + +```bash +rg -n "docs/sample/sample-(prd|plan-task|review)\\.md|reviews/|신규 회귀 수정 Task|빌드.*테스트.*린트" AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정 +git diff --check +./gradlew tasks --all +``` + +**Expected:** 세 샘플의 정확한 경로와 리뷰 후속 절차가 문서 간 일치하고, whitespace 오류가 없으며 Gradle task 목록 조회가 exit code 0으로 끝난다. + +검증 기록(2026-07-30): + +- 문서 검색은 세 샘플 경로, 리뷰 보고서 대상, 일반 검증 제외, 확정 항목의 신규 회귀 수정 Task 전환 규칙을 모두 찾고 exit code 0으로 끝났다. +- `git diff --check`는 출력 없이 exit code 0으로 통과했다. +- 최초 `./gradlew tasks --all`은 sandbox가 `~/.gradle` lock 파일 접근을 차단해 실패했다. 같은 명령을 승인된 권한 범위에서 재실행해 `BUILD SUCCESSFUL in 24s`, `1 actionable task: 1 executed`를 확인했다. + +#### Task 4.5 리뷰 범위 파일명 형식 추가 + +**Goal 실행 `P4-T5`:** 리뷰 보고서명만으로 대상 Phase와 구현 내용을 식별할 수 있게 `[리뷰범위]` 형식을 고정한다. + +- **시작 조건:** `DEC-004`, `REV-006` 확정. +- **완료 증거:** `AGENTS.md`와 `work-plan-docs.md`에 `phase<번호>-<구현 내용을 나타내는 영문 kebab-case>` 형식과 실제 파일명 예시가 일치하게 기록된다. +- **범위 밖:** 기존 리뷰 보고서 파일의 일괄 이름 변경과 샘플 문서 원문 수정. +- **TDD 예외 사유:** 파일명 작성 규칙만 변경하는 문서 Task다. +- **대체 검증 방법:** 형식·예시 검색, 전체 diff whitespace 검사, Gradle task 목록 조회로 검증한다. + +**Files:** + +- Modify: `AGENTS.md` +- Modify: `docs/agent-guides/work-plan-docs.md` +- Modify: `docs/20260601_계획문서규칙수정/prd.md` +- Modify: `docs/20260601_계획문서규칙수정/plan-task.md` + +- [x] PRD에 `REV-006`, `DEC-004`, 파일명 수용 기준을 추가한다. +- [x] `AGENTS.md`에 `[리뷰범위]` 형식과 예시를 추가한다. +- [x] `work-plan-docs.md`에 `[리뷰범위]` 구성 요소와 예시를 추가한다. +- [x] 문서 간 형식·예시가 일치하는지 검증한다. + +검증 기록(2026-07-30): + +- 형식·예시 검색으로 네 문서가 같은 신규 규칙을 안내함을 확인했다. +- `AGENTS.md`, `work-plan-docs.md`, `prd.md`를 대상으로 `phase-2-review.md`를 검색한 결과가 없어 실제 규칙에는 이전 예시가 남지 않았음을 확인했다. `plan-task.md`에는 검증에 사용한 검색어가 과거 실행 기록으로만 남아 있다. +- `git diff HEAD --check`는 출력 없이 exit code 0으로 통과했다. + +#### Phase 4 재검증 Gate + +**Goal 실행 `P4-GATE-2`:** 후속 파일명 규칙이 기존 리뷰 보고서 경로·후속 수정 절차와 충돌하지 않는지 판정한다. + +- **시작 조건:** `P4-T5` 완료. +- **완료 증거:** 아래 명령이 성공하고 실제 결과가 `검증 기록`에 누적된다. +- **범위 밖:** 기존 리뷰 보고서 파일 이름 변경. + +- [x] **Task 4.6: 리뷰 보고서명 규칙 재검증** + +```bash +rg -n "phase<번호>-<구현 내용을 나타내는 영문 kebab-case>|phase2-main-home-recommendation-review\\.md" AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정 +git diff HEAD --check +./gradlew tasks --all +``` + +**Expected:** 네 문서가 같은 `[리뷰범위]` 형식과 예시를 안내하고, whitespace 오류가 없으며 Gradle task 목록 조회가 exit code 0으로 끝난다. + +검증 기록(2026-07-30): + +- 형식·예시 검색은 네 문서에서 `phase<번호>-<구현 내용을 나타내는 영문 kebab-case>`와 `phase2-main-home-recommendation-review.md`를 확인하고 exit code 0으로 끝났다. +- `git diff HEAD --check`는 출력 없이 exit code 0으로 통과했다. +- `./gradlew tasks --all`은 `BUILD SUCCESSFUL in 4s`, `1 actionable task: 1 executed`로 통과했다. + ## 검증 기록 - 2026-06-01 - 무엇/왜/어떻게: 계획 문서 규칙 수정 요청에 따라 기존 작업 절차 문서와 `sample-prd.md` 위치를 확인하고, 신규 작업 문서부터 `docs/[날짜]_구현할내용한글/prd.md`, `docs/[날짜]_구현할내용한글/plan-task.md` 구조를 적용하도록 규칙을 수정했다. @@ -64,3 +250,26 @@ - 결과: - `AGENTS.md`와 `docs/agent-guides/work-plan-docs.md`에 신규 문서 경로와 기존 문서 유지 조건이 반영됐음을 확인했다. - 변경 범위가 `AGENTS.md`, `docs/agent-guides/work-plan-docs.md`, `docs/20260601_계획문서규칙수정/prd.md`, `docs/20260601_계획문서규칙수정/plan-task.md`로 제한됐음을 확인했다. + +- 2026-07-30 + - 무엇/왜/어떻게: 새 PRD·계획/TASK·리뷰 보고서 샘플과 코드 리뷰 후속 수정 절차를 작업 규칙에 반영했다. 기존 작업의 연속 범위이므로 새 작업 폴더를 만들지 않고 Phase 4와 후속 요구사항을 기존 문서에 누적했다. + - 실행 명령: + - `rg -n "docs/sample/sample-(prd|plan-task|review)\\.md|reviews/|신규 회귀 수정 Task|빌드.*테스트.*린트" AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정` + - `git diff --check` + - `./gradlew tasks --all` + - 결과: + - `AGENTS.md`와 `docs/agent-guides/work-plan-docs.md`에서 세 샘플의 정확한 경로, 리뷰 보고서 저장 위치, 일반 검증 제외, 확정 항목의 해당 Phase 신규 Task 전환 규칙을 확인했다. + - `git diff --check`는 출력 없이 exit code 0으로 통과했다. + - `./gradlew tasks --all`은 최초 sandbox 권한 제한을 확인한 뒤 승인 범위에서 재실행해 `BUILD SUCCESSFUL in 24s`로 통과했다. + - 이번 작업은 코드 리뷰를 수행하지 않은 문서 정비이므로 `reviews/` 폴더와 리뷰 보고서를 생성하지 않았다. + +- 2026-07-30 + - 무엇/왜/어떻게: 사용자 후속 요청에 따라 리뷰 보고서명의 `[리뷰범위]`를 `phase<번호>-<구현 내용을 나타내는 영문 kebab-case>`로 고정하고, `phase2-main-home-recommendation-review.md` 예시를 핵심·상세 규칙과 PRD에 일치하게 반영했다. + - 실행 명령: + - `rg -n "phase<번호>-<구현 내용을 나타내는 영문 kebab-case>|phase2-main-home-recommendation-review\\.md" AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정` + - `git diff HEAD --check` + - `./gradlew tasks --all` + - 결과: + - 네 문서가 같은 `[리뷰범위]` 형식과 실제 파일명 예시를 안내함을 확인했다. + - `git diff HEAD --check`는 출력 없이 exit code 0으로 통과했다. + - `./gradlew tasks --all`은 `BUILD SUCCESSFUL in 4s`로 통과했다. diff --git a/docs/20260601_계획문서규칙수정/prd.md b/docs/20260601_계획문서규칙수정/prd.md index 7164cfc1..6a5566d8 100644 --- a/docs/20260601_계획문서규칙수정/prd.md +++ b/docs/20260601_계획문서규칙수정/prd.md @@ -86,3 +86,80 @@ ## 11. Open Questions - 없음. + +--- + +## 12. 2026-07-30 후속 변경: 샘플 문서와 리뷰 보고서 규칙 + +### 12.1 변경 배경 + +- PRD와 구현 계획/TASK 문서의 샘플이 `docs/sample/` 아래의 새 문서로 교체됐다. +- 기존 작업 절차에는 구현 계획/TASK 문서가 참조해야 할 샘플의 정확한 위치와 문서 유지보수 규칙이 없다. +- 코드 리뷰, 코드 품질 점검, 완료 Phase 재검토 결과를 별도 산출물로 추적할 리뷰 보고서 규칙이 필요하다. +- 리뷰에서 확정된 수정 항목을 기존 완료 기록을 훼손하지 않고 구현 흐름으로 전환해야 한다. + +### 12.2 목표 + +- `docs/sample/sample-prd.md`, `docs/sample/sample-plan-task.md`, `docs/sample/sample-review.md`를 각 문서 유형의 기준 샘플로 명시한다. +- PRD와 구현 계획/TASK 문서를 만들 때 해당 샘플을 참조하고 작업에 필요한 항목을 구체화하도록 규정한다. +- 코드 리뷰, 코드 품질 점검, 완료 Phase 재검토 결과를 대상 작업 디렉터리의 `reviews/` 아래에 리뷰 보고서로 작성하도록 규정한다. +- 리뷰에서 수정 항목이 확정되면 `plan-task.md`의 해당 Phase에 신규 회귀 수정 Task를 먼저 추가한 뒤 즉시 수정할 수 있도록 후속 절차를 명시한다. +- 샘플과 안내 문서가 서로 다른 경로 또는 작성 규칙을 안내하지 않도록 유지보수 규칙을 보강한다. + +### 12.3 제외 범위 + +- 기존 PRD, 계획/TASK 문서, 과거 리뷰 기록을 새 샘플 형식으로 일괄 변환하지 않는다. +- 일반 빌드, 테스트, 린트 실행마다 리뷰 보고서를 만들지 않는다. +- Android 앱 소스 코드와 빌드 설정은 수정하지 않는다. +- 이번 문서 규칙 정비 자체를 코드 리뷰로 간주해 리뷰 보고서를 만들지 않는다. + +### 12.4 기능 요구사항 + +| ID | 상태 | 요구사항 | 수용 기준 | +|---|---|---|---| +| `DOC-001` | 확정 | 문서 샘플의 기준 위치를 `docs/sample/`로 통일한다. | `AGENTS.md`와 `work-plan-docs.md`가 세 샘플의 정확한 경로를 안내한다. | +| `DOC-002` | 확정 | PRD 작성 시 `docs/sample/sample-prd.md`를 참조한다. | 필요한 항목만 사용하고 placeholder와 예시 값은 실제 작업 값으로 교체하도록 명시한다. | +| `DOC-003` | 확정 | 구현 계획/TASK 문서 작성 시 `docs/sample/sample-plan-task.md`를 참조한다. | 작업에 필요한 구조와 실행 규칙을 실제 경로, Task, 검증 기준으로 구체화하도록 명시한다. | +| `DOC-004` | 확정 | 샘플 변경 시 관련 안내 문서를 함께 유지보수한다. | 샘플 위치·문서 구조·작성 규칙이 바뀌면 `AGENTS.md`와 관련 가이드를 같은 작업에서 동기화하도록 명시한다. | +| `REV-001` | 확정 | 코드 리뷰, 코드 품질 점검, 완료 Phase 재검토 결과는 리뷰 보고서로 작성한다. | `docs/sample/sample-review.md`를 참조해 `docs/[날짜]_구현할내용한글/reviews/[리뷰범위]-review.md`에 저장한다. | +| `REV-002` | 확정 | 일반 빌드, 테스트, 린트는 리뷰 보고서 대상에서 제외한다. | 해당 결과는 기존처럼 `plan-task.md`의 Task별 검증 기록 또는 `Verification Log`에 남긴다. | +| `REV-003` | 확정 | 리뷰에서 수정 항목이 확정되면 해당 Phase에 신규 회귀 수정 Task를 추가한다. | 코드 수정 전에 review ID, 대상 파일, 수정 범위, 회귀 테스트, 완료 증거가 포함된 Task가 `plan-task.md`에 추가된다. | +| `REV-004` | 확정 | 확정된 리뷰 Task는 계획 반영 후 바로 수정할 수 있다. | 별도 PRD를 만들거나 기존 완료 Task를 다시 열지 않고 신규 Task의 체크리스트에 따라 수정한다. | +| `REV-005` | 확정 | 기존 완료·검증·리뷰 기록을 보존한다. | 완료 체크박스를 미완료로 되돌리거나 기존 기록을 삭제·덮어쓰지 않고 후속 Task와 기록을 누적한다. | +| `REV-006` | 확정 | 리뷰 보고서명의 `[리뷰범위]`는 `phase<번호>-<구현 내용을 나타내는 영문 kebab-case>` 형식으로 작성한다. | Phase 2 메인 홈 추천 구현 리뷰는 `phase2-main-home-recommendation-review.md`로 저장한다. | + +### 12.5 문서 배치 + +```text +docs/sample/ +├── sample-prd.md +├── sample-plan-task.md +└── sample-review.md + +docs/[날짜]_구현할내용한글/ +├── prd.md +├── plan-task.md +└── reviews/ + └── phase<번호>--review.md +``` + +`reviews/`는 실제 리뷰 보고서가 생길 때 만들며, 리뷰가 없는 작업에는 빈 폴더를 만들지 않는다. +`[리뷰범위]`는 `phase<번호>-<구현 내용을 나타내는 영문 kebab-case>`로 작성하며, `phase`와 번호 사이에는 하이픈을 넣지 않는다. + +### 12.6 성공 기준 + +- [x] `AGENTS.md`가 세 샘플의 정확한 위치와 용도를 안내한다. +- [x] `docs/agent-guides/work-plan-docs.md`가 PRD·계획/TASK·리뷰 보고서의 작성 및 유지보수 절차를 안내한다. +- [x] 리뷰 보고서 대상과 일반 빌드·테스트·린트 검증 기록이 명확히 구분된다. +- [x] 확정된 리뷰 항목을 해당 Phase의 신규 회귀 수정 Task로 전환하는 순서가 명시된다. +- [x] 기존 문서와 기록을 일괄 변경하지 않는 범위가 유지된다. +- [x] 리뷰 보고서명의 `[리뷰범위]` 형식과 실제 파일명 예시가 규칙 문서에 일치하게 반영된다. + +### 12.7 Decision Log + +| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·문서 | +|---|---|---|---|---|---| +| 2026-07-30 | `DEC-001` | 확정 | 핵심 규칙은 `AGENTS.md`에 요약하고 상세 절차는 `docs/agent-guides/work-plan-docs.md`에 기록한다. | 사용자 승인 및 중복 유지보수 최소화 | `DOC-001~004`, `REV-001~005` | +| 2026-07-30 | `DEC-002` | 확정 | 리뷰 보고서는 코드 리뷰, 코드 품질 점검, 완료 Phase 재검토에만 필수로 만들고 일반 빌드·테스트·린트에는 만들지 않는다. | 사용자 답변 | `REV-001`, `REV-002` | +| 2026-07-30 | `DEC-003` | 확정 | 리뷰에서 확정된 수정 항목은 해당 Phase의 신규 회귀 수정 Task로 먼저 등록한 뒤 바로 수정한다. | 사용자 추가 요구사항 | `REV-003~005` | +| 2026-07-30 | `DEC-004` | 확정 | 리뷰 보고서명의 `[리뷰범위]`는 `phase<번호>-<구현 내용을 나타내는 영문 kebab-case>` 형식으로 고정한다. | 사용자 추가 요구사항 | `REV-006` | diff --git a/docs/agent-guides/work-plan-docs.md b/docs/agent-guides/work-plan-docs.md index e0dea38d..71421a94 100644 --- a/docs/agent-guides/work-plan-docs.md +++ b/docs/agent-guides/work-plan-docs.md @@ -13,25 +13,57 @@ - PRD 작성 중 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 애매한 사항이 없어질 때까지 사용자와 인터뷰한다. - 인터뷰로 확정한 내용을 PRD 문서에 보강한 뒤, 해당 PRD를 기준으로 구현 계획/TASK 문서를 작성한다. - 구현은 계획/TASK 문서를 기준으로 필요한 내용만 최소 범위로 진행한다. + +### 기준 샘플 +- 문서 샘플의 기준 위치는 `docs/sample/`이다. +- PRD는 `docs/sample/sample-prd.md`를 참조해 작업에 필요한 항목만 사용한다. +- 구현 계획/TASK 문서는 `docs/sample/sample-plan-task.md`를 참조해 작업에 필요한 구조와 실행 규칙을 구체화한다. +- 리뷰 보고서는 `docs/sample/sample-review.md`를 참조한다. +- 실제 문서를 만들 때 샘플의 `<...>` placeholder와 예시 ID·경로·명령·기대 결과를 해당 작업의 구체적인 값으로 교체한다. +- 필요한 샘플이 없거나 경로가 불명확하면 다른 위치를 추정하거나 임의 형식을 만들지 말고 사용자에게 확인한다. + +### 문서 배치 - 문서는 `docs/[날짜]_구현할내용한글/` 아래에 `prd.md`, `plan-task.md`로 만든다. - `docs/[날짜]_구현할내용한글/prd.md` - `docs/[날짜]_구현할내용한글/plan-task.md` - 문서 폴더명에서 원래 띄어쓰기가 들어갈 위치는 공백 대신 `_`를 사용한다. - 예: `docs/20260601_메인_홈_추천_UI와_API_연동/` - 기존에 생성된 `docs/prd/`, `docs/plan-task/` 문서는 유지하고, 신규 생성 문서부터 위 구조를 적용한다. -- PRD 문서는 `sample-prd.md` 파일에서 작업에 필요한 부분만 발췌해 작성한다. `sample-prd.md`가 없거나 위치가 불명확하면 추측하지 말고 사용자에게 확인한다. - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다. - 연속된 하나의 작업이라면 별도 새 문서를 만들지 말고 기존 PRD와 계획/TASK 문서에 추가 작업으로 이어서 기록한다. -- 계획/TASK 문서는 의미 단위 phase로 나누고 `### Phase 1: ...`, `### Phase 2: ...` 형식의 heading을 사용한다. -- 각 phase 아래에는 단계별 task를 체크박스(`- [ ] **Task N.N: ...**`) 형태로 작성하고 완료 즉시 `- [x]`로 갱신한다. -- 각 task에는 구현 시 생성/수정/확인할 파일 경로를 명시한다. -- 각 phase 또는 task에는 실행 명령, 기대 결과, 수동 확인 항목 등 검증 기준을 함께 작성한다. + +### 계획/TASK 문서 작성과 유지 +- 계획/TASK 문서는 `docs/sample/sample-plan-task.md`의 상태·목표·범위·기술적 제약·Phase·Task·Gate·Progress·Decision Log 구조 중 작업에 필요한 항목을 사용한다. +- 의미 단위 Phase는 `## Phase N`, 구현 항목의 Task는 `#### Task N.N` 형식으로 작성한다. +- 각 Task 또는 Phase Gate에는 독립적으로 실행·판정할 수 있는 목표, 시작 조건, 완료 증거, 범위 밖 항목을 명시한다. +- 각 Task에는 구현 시 생성·수정·확인할 파일 경로와 필요한 인터페이스를 명시한다. +- 구현 Task의 실행 단계는 `RED → RED 확인 → GREEN → GREEN 확인 → REFACTOR` 순서의 체크박스로 작성하고 완료 즉시 `- [x]`로 갱신한다. +- 테스트 작성이 현실적으로 불가능한 read-only 리뷰·문서·외부 확인 Task에는 `TDD 예외 사유`와 실행 명령·대조표·수동 확인을 포함한 `대체 검증 방법`을 명시한다. +- 각 Phase 또는 Task에는 실행 명령, 기대 결과, 수동 확인 항목 등 검증 기준을 함께 작성한다. - 작업 도중 범위가 변경되면 계획 문서 체크리스트를 먼저 업데이트한 뒤 구현한다. +- 실제 실행 결과는 샘플의 `Progress` 형식에 맞춰 무엇을/왜/어떻게 수행했는지와 남은 항목을 한국어로 누적한다. - 특정 phase 또는 task에 직접 대응되는 검증 기록(무엇/왜/어떻게, 실행 명령, 결과)은 해당 phase 또는 task 아래에 `검증 기록`으로 한국어로 남긴다. - 여러 phase에 걸치거나 문서 전체에 해당하는 통합 검증, 회귀 검증, 최종 수동 확인 기록은 문서 최하단 `Verification Log`에 한국어로 남긴다. - 후속 수정이 발생해도 기존 검증 기록은 삭제/덮어쓰기 없이 위치별로 누적한다. +### 코드 리뷰 보고서와 후속 수정 +- 코드 리뷰, 코드 품질 점검, 완료 Phase 재검토를 수행하면 결과를 별도 리뷰 보고서로 작성한다. +- 리뷰 보고서는 `docs/sample/sample-review.md`를 참조해 대상 PRD·`plan-task.md`와 같은 작업 디렉터리의 `reviews/[리뷰범위]-review.md`에 저장한다. +- `[리뷰범위]`는 `phase<번호>-<구현 내용을 나타내는 영문 kebab-case>` 형식으로 작성한다. + - `phase`와 번호 사이에는 하이픈을 넣지 않는다. + - 구현 내용은 소문자 영문 단어를 하이픈으로 연결한다. + - 예: `docs/20260601_메인_홈_추천_UI와_API_연동/reviews/phase2-main-home-recommendation-review.md` +- `reviews/`는 실제 리뷰 보고서가 생길 때 만들며, 리뷰가 없는 작업에는 빈 폴더를 만들지 않는다. +- 확정 발견 사항이 없더라도 리뷰 범위, 검토 근거, 실행한 검증, “확정 발견 사항 없음” 판정을 보고서에 남긴다. +- 일반 빌드, 테스트, 린트 실행은 리뷰 보고서 생성 대상이 아니며 해당 결과는 Task별 검증 기록 또는 `Verification Log`에 남긴다. +- 리뷰에서 발견한 후보는 재현·근거 확인 후 `확정`, `오탐`, `보류`로 판정하고, 확정된 수정 항목만 계획/TASK 문서로 전환한다. +- 수정 항목이 확정되면 코드를 변경하기 전에 `plan-task.md`의 해당 Phase에 review ID, 대상 파일, 수정 범위, 회귀 테스트, 완료 증거를 포함한 신규 회귀 수정 Task를 추가한다. +- 계획/TASK 문서 갱신이 끝나면 신규 회귀 수정 Task의 체크리스트에 따라 바로 수정하며, 기존 완료 Task나 Phase의 체크박스를 미완료로 되돌리지 않는다. +- 수정 후 실행한 검증과 판정은 리뷰 보고서와 계획/TASK 문서의 검증 기록에 삭제·덮어쓰기 없이 누적한다. + ## 문서 유지보수 규칙 +- `docs/sample/` 샘플의 위치, 문서 구조, 작성·운용 규칙이 변경되면 같은 작업에서 `AGENTS.md`와 관련 `docs/agent-guides/` 문서를 함께 갱신한다. +- 샘플과 안내 문서가 서로 다른 경로 또는 작성 규칙을 안내하지 않는지 문서 변경 후 검색해 확인한다. - `build.gradle`/`app/build.gradle`/`settings.gradle` 변경 시 실행 명령 섹션을 함께 갱신한다. - 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다. - `.editorconfig` 변경 시 `docs/agent-guides/code-style.md`의 포맷 규칙 섹션을 동기화한다. diff --git a/docs/prd/sample-prd.md b/docs/prd/sample-prd.md deleted file mode 100644 index 3136d742..00000000 --- a/docs/prd/sample-prd.md +++ /dev/null @@ -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? diff --git a/docs/sample/sample-plan-task.md b/docs/sample/sample-plan-task.md new file mode 100644 index 00000000..4a062dae --- /dev/null +++ b/docs/sample/sample-plan-task.md @@ -0,0 +1,317 @@ +# Goal 실행형 구현 계획 샘플 + +> 이 문서는 goal 기능으로 구현 계획을 실행하기 위한 템플릿이다. 실제 `plan-task.md`를 만들 때 `<...>` placeholder를 모두 구체적인 값으로 교체한다. Phase는 결과와 의존성을 묶고, `create_goal`에는 Task 또는 Phase Gate 하나만 등록한다. + +| 문서 항목 | 내용 | +|---|---| +| 상태 | 계획 작성 중 / 구현 중 / 외부 조건 대기 / 구현 완료 | +| 작성일 | `YYYY-MM-DD` | +| 요구사항 기준 | `<대상 prd.md 경로>` | +| API 기준 | `<대상 api-contract.md 경로>` | +| 현재 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 상한을 추정하지 않는다. +- backend 구현 전 UI 확인이 필요하면 제공 계약 기반 explicit mock mode를 사용하고 실제 404 자동 fallback·production mock을 금지하며 mock/server 완료 증거를 분리한다. +- 구현: 모든 구현 Task는 아래 `RED → GREEN → REFACTOR` 순서를 체크박스에 명시하고, 가장 작은 실패 test에서 시작해 최소 구현으로 통과시킨다. +- 검증: focused test에서 시작해 영향받는 package/feature 회귀로 확장한다. 전체 회귀는 공통 경계 변경, 여러 domain/phase 변경, + release/final Gate에서 전체 상태 증거를 별도로 요구하는 경우, targeted test만으로 영향 범위를 판단할 수 없는 실패 또는 사용자 + 명시 요청이 있을 때만 실행한다. +- 전체 회귀를 생략하면 생략 사실·근거와 대신 실행한 focused/영향 범위 회귀 명령을 Progress에 기록한다. + +## Task TDD 작성 규칙 + +구현 Task의 실행 체크박스는 아래 순서와 표제어를 그대로 사용한다. 각 단계에는 대상 test, 실행 명령과 관찰할 실패·성공 결과를 +구체적으로 적고, `RED` 확인 없이 production 구현을 시작하거나 `GREEN` 확인 없이 `REFACTOR`로 넘어가지 않는다. + +- [ ] **RED:** 가장 작은 실패 test를 작성한다. +- [ ] **RED 확인:** focused test를 실행해 요구 동작이 없어서 발생한 의도한 assertion 실패를 확인한다. +- [ ] **GREEN:** RED를 통과시키는 최소 구현을 작성한다. +- [ ] **GREEN 확인:** 같은 focused test를 다시 실행해 성공을 확인한다. +- [ ] **REFACTOR:** 새 동작을 바꾸지 않는 범위에서 이번 Task가 만든 중복만 정리하고, focused test·직접 영향 회귀·lint를 다시 실행해 실제 결과를 Progress에 기록한다. + +test 작성이 현실적으로 불가능한 read-only 리뷰·문서·외부 확인 Task는 TDD 단계를 형식적으로 만들지 않는다. 대신 Task 본문에 +`TDD 예외 사유`와 실행 명령·대조표·수동 확인을 포함한 `대체 검증 방법`을 명시한다. + +## 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>` + +- [ ] **RED:** `<요구 동작>`을 재현하는 가장 작은 실패 test를 작성한다. +- [ ] **RED 확인:** ``을 실행해 `<요구 동작 미구현 때문에 발생할 assertion 실패>`를 확인한다. +- [ ] **GREEN:** RED를 통과시키는 최소 구현을 작성한다. +- [ ] **GREEN 확인:** ``을 다시 실행해 성공을 확인한다. +- [ ] **REFACTOR:** 이번 Task가 만든 중복만 정리하고 focused test·직접 영향 회귀·typecheck·lint 결과를 Progress에 기록한다. + +#### Task 1.2 `<두 번째 독립 결과>` + +**Goal 실행 `P1-T2`:** `<이 Task가 만드는 결과를 한 문장으로 작성한다.>` + +- **시작 조건:** `P1-T1` 완료와 `<필요한 계약>`. +- **완료 증거:** `<체크박스 전체, test와 문서 기록>` +- **범위 밖:** `<이 Task에서 다루지 않는 항목>` + +**Files:** + +- Create: `<정확한 파일 경로>` +- Modify: `<정확한 파일 경로>` +- Test: `<정확한 test 파일 경로>` + +**Interfaces:** + +- Consumes: `` +- Produces: `` + +- [ ] **RED:** `<두 번째 요구 동작>`의 실패 test를 작성한다. +- [ ] **RED 확인:** ``으로 의도한 assertion 실패를 확인한다. +- [ ] **GREEN:** 최소 구현으로 focused test를 통과시킨다. +- [ ] **GREEN 확인:** 오류·loading·empty·success와 접근성 상태를 포함한 focused test 성공을 확인한다. +- [ ] **REFACTOR:** 이번 Task가 만든 중복만 정리하고 관련 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 + + + + + +``` + +**Expected:** `<0 exit code, test 수, 사용자가 완료할 흐름, 금지 요청 0회 등 관찰 가능한 결과>` + +수동 검증: + +- [ ] `` +- [ ] `` +- [ ] `<민감정보·network request 검증>` + +## Phase 2 + +**Phase 결과:** `` + +**선행조건:** `P1-GATE` 또는 `` 완료. + +**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와 실제 기능 구현. +- **TDD 예외 사유:** production 동작을 변경하지 않는 read-only 계약·상태 확인 Task다. +- **대체 검증 방법:** PRD/API Contract/현재 구현의 field·상태·파일 대조표와 누락·결정 기록을 작성하고 문서 검증 명령 결과를 Progress에 남긴다. + +- [ ] 필요한 endpoint·DTO·오류·pagination 계약을 확인한다. +- [ ] loading·empty·error·success·read-only·viewport 상태와 action을 inventory한다. +- [ ] 계약이 없으면 담당 주체·영향·재개 조건과 제외/후속 결정을 문서화한다. +- [ ] Page·feature·shared component와 test file 책임을 확정한다. + +#### Task 2.2 `` + +**Goal 실행 `P2-T2`:** `<사용자가 직접 확인할 수 있는 흐름을 한 문장으로 작성한다.>` + +- **시작 조건:** `P2-T1` 완료. +- **완료 증거:** `` +- **범위 밖:** `<다음 Task 또는 후속 Phase>` + +**Files:** + +- Create: `<정확한 파일 경로>` +- Modify: `<정확한 파일 경로>` +- Test: `<정확한 test 파일 경로>` + +- [ ] **RED:** contract·serializer와 사용자 action의 가장 작은 실패 test를 작성한다. +- [ ] **RED 확인:** ``을 실행해 각 요구 동작이 없어 발생한 assertion 실패를 확인한다. +- [ ] **GREEN:** RED를 통과시키는 최소 구현을 작성한다. +- [ ] **GREEN 확인:** 같은 focused test를 다시 실행해 contract와 사용자 흐름의 성공을 확인한다. +- [ ] **REFACTOR:** 이번 Task가 만든 중복만 정리하고 관련 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 + + + +``` + +**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 + +기존 기록을 삭제하거나 덮어쓰지 않고 실제 실행 결과를 차수별로 누적한다. + +### `` N차 실행 — YYYY-MM-DD + +- 상태: 진행 중 / 완료 / 차단 감사 중 / 차단 +- 무엇을: `<이번 실행에서 완료한 체크박스와 산출물>` +- 왜: `` +- 어떻게: + - `<실행 명령>` — `<성공/실패, exit code, test 수와 핵심 결과>` + - `<수동 검증>` — `<성공/실패/불가 사유>` +- 남은 항목: `<체크박스, 외부 조건 또는 없음>` +- 다음 행동: `<같은 goal에서 이어서 할 가장 작은 단계>` + +## Decision Log + +| 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 | +|---|---|---|---|---|---| +| `YYYY-MM-DD` | `DEC-001` | 제안 / 확정 / 정정 | `<결정 내용>` | `<요구사항, 계약, 검증 근거>` | `` | + +- 기존 결정을 정정할 때 원문을 지우지 않고 새 `정정` 행을 추가한다. +- 외부 의존 제외, 새로운 dependency, 범위 변경, 안전한 기본값 선택은 반드시 기록한다. + +## 발견된 문제 + +| ID | 심각도 | 상태 | 발견 내용 | 영향 Goal | 처리 계획 | +|---|---|---|---|---|---| +| `ISSUE-001` | Blocker / High / Medium / Low | 후보 / 확정 / 보류 / 해결 | `<관찰 사실>` | `` | `<수정 Task, 외부 담당 또는 없음>` | + +- 구현 중 발견한 범위 내 문제는 근거와 재현 방법을 기록하고 해당 Task에서 처리한다. +- 완료된 범위의 회귀는 기존 Task를 다시 열지 않고 별도 회귀 수정 Task와 goal을 만든다. +- 범위 밖 문제는 임의로 수정하지 않고 사용자에게 보고하거나 후속 Task로 결정한다. +- 상세 코드 리뷰 결과가 필요하면 `docs/sample/sample-review.md` 형식으로 + `docs/[날짜]_구현할내용한글/reviews/[리뷰범위]-review.md`에 별도 문서를 만든다. + +## 최종 보고 형식 + +```markdown +구현 결과: <완료한 Phase와 사용자 흐름> + +- 변경: <주요 파일과 동작> +- 결정: <중요한 Decision Log ID와 내용> +- 검증: + - `<실행 명령>` — <성공/실패와 핵심 수치> + - `<수동 검증>` — <성공/실패/불가 사유> +- 남은 항목: <외부 의존, 후속 범위 또는 없음> +- 문서: <갱신한 PRD/API Contract/plan/review 링크> +``` + +최종 보고는 성공을 추정하지 않는다. 실제 실행한 최신 검증 결과와 완료되지 않은 범위를 함께 전달한다. diff --git a/docs/sample/sample-prd.md b/docs/sample/sample-prd.md new file mode 100644 index 00000000..ec5e3471 --- /dev/null +++ b/docs/sample/sample-prd.md @@ -0,0 +1,271 @@ +# 제품 요구사항 문서(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 | `<없음 또는 같은 작업 디렉터리의 reviews/ 아래 문서 링크>` | + +### 요구사항 상태 + +| 상태 | 의미 | 구현 처리 | +|---|---|---| +| 확정 | 제품·기술 결정이 완료되어 구현 기준으로 사용 | `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 사용자 + +| 사용자 | 목표 | 주요 작업 | 사용 환경 | +|---|---|---|---| +| `<역할>` | `<달성 목표>` | `<조회·생성·수정 등>` | `` | + +### 5.2 권한 + +- 인증 주체: `<사용자 또는 시스템>` +- 허용 역할: `` +- 거부 조건: `<401/403 또는 제품 정책>` +- 리소스 소유권: `` +- read-only 조건: `<비활성·권한 부족·외부 상태 등>` + +## 6. 핵심 사용자 흐름 + +1. `<시작 조건과 진입점>` +2. `<대상 탐색·선택>` +3. `<핵심 생성·조회·수정 동작>` +4. `<성공 feedback과 다음 화면>` +5. `<오류·권한·session 만료 복구>` + +각 흐름은 `plan-task.md`의 최소 하나의 Phase 결과와 E2E 완료 증거로 연결한다. + +## 7. 정보 구조와 라우팅 + +```text +/ +/ +//:resourceId + / +``` + +- 전역 화면과 선택된 리소스 문맥의 경계를 명시한다. +- URL path와 query에 보존할 식별자·검색·filter·page 상태를 명시한다. +- 직접 링크·새로고침이 가능한 화면과 collection modal/Sheet처럼 별도 route가 없는 화면을 구분한다. +- 존재하지 않음, 다른 소유자, 비활성 리소스의 처리는 서버 계약과 공통 오류 정책을 따른다. + +## 8. 기능 요구사항 + +요구사항 ID는 `-NNN` 형식을 사용한다. 하나의 행에는 독립적으로 판정 가능한 요구사항 하나만 작성한다. + +### 8.1 `<도메인 A>` + +| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 | +|---|---|---|---|---| +| `DOMAINA-001` | 확정 | `<사용자가 할 수 있어야 하는 동작>` | `<관찰 가능한 성공·오류 결과>` | `api-contract.md §<번호>`, `P1-T1` | +| `DOMAINA-002` | 확정 | `` | `<보내야/보내지 말아야 할 값과 test>` | `P1-T2` | +| `DOMAINA-003` | 외부 의존 | `<외부 제공이 필요한 계약>` | `<제공 전 network integration 0건>` | `EXT-001`, `P1-T1` | + +### 8.2 `<도메인 B>` + +| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 | +|---|---|---|---|---| +| `DOMAINB-001` | 확정 | `<목록·상세·mutation 흐름>` | `` | `api-contract.md §<번호>`, `P2-T2` | +| `DOMAINB-002` | 미결 | `<제품 결정이 필요한 항목>` | `<확정 전 최대값·동작 추정 금지>` | `OQ-001` | + +### 8.3 공통 파일·데이터 정책 + +| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 | +|---|---|---|---|---| +| `FILE-001` | 확정 | `<허용 확장자·MIME·크기>` | `<정확한 byte 경계 test>` | `api-contract.md §<번호>`, `` | +| `DATA-001` | 확정 | `<날짜·가격·enum·pagination 규칙>` | `` | `` | + +## 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: `` +- 성공 envelope: `` +- 오류 envelope와 status: `` +- pagination: `` +- multipart JSON part: `<이름>` + +### 11.2 Endpoint 추적 + +| 요구사항 | Method | Path | 계약 상태 | API Contract | 소유 Goal | +|---|---|---|---|---|---| +| `DOMAINA-001` | `` | `` | 제공됨 / 보정 필요 / 제공 대기 | `§<번호>` | `` | + +### 11.3 외부 제공 대기 계약 + +| ID | 우선순위 | 제공 필요 계약 | 담당 주체 | 구현 영향 | 재개 조건 | +|---|---:|---|---|---|---| +| `EXT-001` | P0 / P1 | `` | `<팀/역할>` | `<차단되는 흐름>` | `<문서와 fixture 제공>` | + +- P0 계약이 없으면 영향을 받는 network flow를 완료로 표시하지 않는다. +- 계약에 의존하지 않는 UI shell·상태 inventory·문서화는 독립적으로 진행할 수 있다. + +## 12. 보안과 데이터 취급 + +- 인증 정보 저장 위치와 lifecycle: `<정확한 정책>` +- log·분석·오류 리포트 금지 값: `` +- 업로드 파일명·MIME·본문 취급: `<정책>` +- 리소스 격리와 ownership 검증: `<정책>` +- 401·403·동시 실패 처리: `<정책>` +- 감사 로그: `<포함, 외부 의존 또는 후속 범위>` + +## 13. 성능과 품질 요구사항 + +- 목록 pagination과 전체 로드 예외: `<정책>` +- 검색 debounce와 기존 데이터 유지: `<정책>` +- image layout shift와 lazy loading: `<정책>` +- mutation 중복 제출·upload 취소/재시도: `<정책>` +- 지원 runtime·browser: `<정확한 범위>` +- test stack과 필수 Gate: `` +- backend 구현 전 UI 확인: `<불필요 또는 explicit mock mode, production 금지, no-auto-fallback, mock/server 완료 상태 분리>` + +## 14. 성공 기준 + +### 14.1 기능 수용 기준 + +- [ ] `<핵심 사용자 journey가 성공한다.>` (`DOMAINA-001`, `P1-GATE`) +- [ ] `<권한·오류·payload 불변식이 검증된다.>` (`DOMAINA-002`, ``) +- [ ] `<외부 의존의 구현 또는 제외 결정이 문서화된다.>` (`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 작성 후>` | `` | + +- Open Question과 외부 의존을 혼합하지 않는다. 제품이 결정할 수 없는 backend 계약은 `EXT-*`로 관리한다. +- 미결 값을 임의의 상수·enum·endpoint로 구현하지 않는다. + +## 16. 요구사항 추적표 + +| 요구사항 범위 | API Contract | 계획 Phase | Goal | 자동 검증 | 수동 검증 | +|---|---|---:|---|---|---| +| `DOMAINA-001~003` | `§<번호>` | 1 | `P1-T1`, `P1-T2`, `P1-GATE` | `` | `<흐름>` | +| `DOMAINB-001~002` | `§<번호 또는 제공 대기>` | 2 | `P2-T1`, `P2-T2`, `P2-GATE` | `` | `<흐름>` | + +## 17. Decision Log + +| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·계약·Goal | +|---|---|---|---|---|---| +| `YYYY-MM-DD` | `DEC-001` | 확정 / 정정 / 폐기 | `<결정 내용>` | `<인터뷰·계약·검증 근거>` | `` | + +- 기존 결정을 수정할 때 원문을 지우지 않고 `정정` 행을 추가한다. +- 범위 변경, Non-Goal 변경, 외부 의존 제외, 안전한 기본값과 주요 기술 선택을 기록한다. + +## 18. 변경 관리 + +요구사항 변경 시 다음을 확인한다. + +- [ ] Decision Log에 변경 이유와 날짜를 기록했다. +- [ ] 관련 요구사항 상태·본문·수용 기준을 갱신했다. +- [ ] API Contract의 request/response/error와 fixture를 갱신했다. +- [ ] `plan-task.md`의 범위·Files·Interfaces·체크박스·완료 증거를 코드 변경 전에 갱신했다. +- [ ] 기존 Progress·review·검증 기록을 삭제하거나 덮어쓰지 않았다. diff --git a/docs/sample/sample-review.md b/docs/sample/sample-review.md new file mode 100644 index 00000000..6378b595 --- /dev/null +++ b/docs/sample/sample-review.md @@ -0,0 +1,187 @@ +# 코드 리뷰 보고서 샘플 + +> 이 문서는 완료된 Phase를 다시 검토할 때 사용하는 템플릿이다. 리뷰에서 발견한 후보를 먼저 검증하고, **확정**된 항목만 `plan-task.md`의 회귀 수정 Task와 goal로 전환한다. 기존 완료 체크박스와 검증 기록은 삭제하거나 되돌리지 않는다. +> 실제 리뷰 문서는 대상 PRD·`plan-task.md`와 같은 작업 디렉터리의 `reviews/` 아래에 +> `docs/[날짜]_구현할내용한글/reviews/[리뷰범위]-review.md` 형식으로 저장한다. + +## 1. 리뷰 정보 + +| 항목 | 내용 | +|---|---| +| 리뷰 대상 | Phase `<번호>` / Task `<번호 또는 범위>` | +| 기준 commit 또는 working tree | `` | +| 리뷰 일자 | `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만 기록 +``` + +### 실행한 검증 + +| 명령 또는 수동 검증 | 결과 | 핵심 증거 | +|---|---|---| +| `<실제 실행 명령>` | 성공 / 실패 / 불가 | `` | +| `<수동 검증 절차>` | 성공 / 실패 / 불가 | `<관찰 결과>` | + +## 5. 발견 사항 요약 + +| ID | 심각도 | 상태 | 제목 | 소유 Task | 후속 goal | +|---|---|---|---|---|---| +| `REV-P1-001` | `<심각도>` | 후보 | `<한 문장 제목>` | `<예: P1-T3>` | 판정 전 | + +발견 사항이 없으면 “확정 발견 사항 없음”이라고 명시하고, 검토 범위와 실행 증거는 그대로 남긴다. + +## 6. 발견 사항 상세 + +### REV-P1-001 — `<한 문장 제목>` + +- **심각도:** `` +- **상태:** `<후보 | 확정 | 오탐 | 보류 | 수정 완료>` +- **관련 요구사항:** `<요구사항 ID 또는 없음>` +- **관련 계약:** `` +- **소유 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-R<번호>`:** <확정된 문제를 수정하고 회귀를 방지하는 한 문장 objective> + +- **시작 조건:** <관련 review ID, 기존 Task/Gate, 필요한 계약> +- **완료 증거:** <실패 재현 test → 수정 후 focused test → Phase Gate → 검증 기록> +- **범위 밖:** <이번 수정에서 건드리지 않을 기능> + +- [ ] `<재현 가능한 실패 test를 먼저 추가하고 의도한 assertion 실패를 확인한다.>` +- [ ] `<최소 수정으로 test를 통과시킨다.>` +- [ ] `<관련 focused test와 Phase Gate를 실행한다.>` +- [ ] `` +``` + +### create_goal objective 초안 + +```text +[P-R<번호>]의 확정 review 항목 을 수정하고 회귀를 방지한다. +plan-task.md에 추가된 회귀 수정 Task만 수행한다. +실패 재현, 최소 수정, focused test, Phase Gate와 검증 기록이 모두 끝나기 전에는 complete로 표시하지 않는다. +관련 없는 리팩터링과 계약 추정은 범위 밖이다. +``` + +## 8. 리뷰 종료 판정 + +| 판정 항목 | 결과 | 근거 | +|---|---|---| +| 리뷰 범위 전체 확인 | 충족 / 미충족 | `<근거>` | +| 후보 항목 판정 완료 | 충족 / 미충족 | `<근거>` | +| 확정 항목 plan 반영 | 충족 / 해당 없음 / 미충족 | `` | +| 보류 항목의 담당·재개 조건 기록 | 충족 / 해당 없음 / 미충족 | `<근거>` | +| 검증 명령과 결과 기록 | 충족 / 미충족 | `<근거>` | + +**최종 결론:** `<확정 발견 사항 없음 | 수정 goal 필요 | 외부 조건 대기 | 수정 검증 완료>` + +**남은 항목:** `<없음 또는 review ID와 다음 행동>` + +## 9. 수정 후 검증 기록 + +기존 기록을 삭제하거나 덮어쓰지 않고 차수별로 누적한다. + +### N차 수정 검증 — YYYY-MM-DD + +- 무엇을: `<수정한 review ID와 결과>` +- 왜: `<요구사항·계약 위반 또는 회귀 위험>` +- 어떻게: + - `<실행 명령>` — `<성공/실패와 핵심 수치>` + - `<수동 검증>` — `<성공/실패/불가 사유>` +- 남은 항목: `<없음, 보류 또는 후속 review ID>`