docs(docs): 문서 샘플과 리뷰 규칙을 갱신한다

This commit is contained in:
2026-07-30 14:18:07 +09:00
parent 3a62ed8463
commit a1aa9c2243
8 changed files with 1107 additions and 113 deletions

View File

@@ -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`로 통과했다.

View File

@@ -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<번호>-<implementation-content-kebab-case>-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` |