# 20260601 계획 문서 규칙 수정 ## 개요 - 작업 절차와 PRD/계획/TASK 문서 작성 규칙을 사용자 요청 기준으로 수정한다. - PRD: `docs/20260601_계획문서규칙수정/prd.md` ## 구현 범위 - Create: `docs/20260601_계획문서규칙수정/prd.md` - Create: `docs/20260601_계획문서규칙수정/plan-task.md` - Modify: `AGENTS.md` - Modify: `docs/agent-guides/work-plan-docs.md` ## 작업 체크리스트 ### Phase 1: 작업 문서 준비 - [x] **Task 1.1: PRD 문서 작성** - 파일 경로: `docs/20260601_계획문서규칙수정/prd.md`, `docs/prd/sample-prd.md` - 검증 기준: `sample-prd.md`의 필요한 섹션만 사용하고, 이번 작업의 목표/범위/제약을 명시한다. - [x] **Task 1.2: 계획/TASK 문서 작성** - 파일 경로: `docs/20260601_계획문서규칙수정/plan-task.md` - 검증 기준: phase heading, 체크박스 task, 파일 경로, 검증 기준을 포함한다. ### Phase 2: 규칙 문서 수정 - [x] **Task 2.1: `AGENTS.md` 작업 절차 핵심 규칙 수정** - 파일 경로: `AGENTS.md` - 실행 명령: `sed -n '1,220p' AGENTS.md` - 기대 결과: 작업 시작 전 PRD와 계획/TASK 문서 준비, 새 문서 경로, 인터뷰/연속 작업/검증 기록 누적 규칙이 반영된다. - [x] **Task 2.2: `work-plan-docs.md` 작업 계획 문서 규칙 수정** - 파일 경로: `docs/agent-guides/work-plan-docs.md` - 실행 명령: `sed -n '1,260p' docs/agent-guides/work-plan-docs.md` - 기대 결과: 사용자 요청의 문서 구조, 작성 순서, sample PRD, phase/task, 범위 변경, 검증 기록 규칙이 반영된다. - [x] **Task 2.3: 신규 문서에만 새 규칙 적용 명시** - 파일 경로: `AGENTS.md`, `docs/agent-guides/work-plan-docs.md`, `docs/20260601_계획문서규칙수정/prd.md` - 검증 기준: 기존에 생성된 `docs/prd/`, `docs/plan-task/` 문서는 유지하고, 신규 생성 문서부터 새 `docs/[날짜]_구현할내용한글/` 구조를 적용한다고 명시한다. ### Phase 3: 검증 및 기록 - [x] **Task 3.1: 변경 범위와 규칙 문구 검증** - 파일 경로: `AGENTS.md`, `docs/agent-guides/work-plan-docs.md`, `docs/20260601_계획문서규칙수정/prd.md`, `docs/20260601_계획문서규칙수정/plan-task.md` - 실행 명령: `rg -n "docs/\\[날짜\\]_구현할내용한글|docs/prd/|docs/plan-task/|sample-prd|Phase 1|검증 기록" AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정` - 기대 결과: 새 규칙은 반영되고, canonical 안내에서 기존 `docs/prd/`, `docs/plan-task/` 생성 규칙은 제거된다. - [x] **Task 3.2: 검증 기록 누적** - 파일 경로: `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` 구조를 적용하도록 규칙을 수정했다. - 실행 명령: - `rg --files -g 'AGENTS.md' -g 'sample-prd.md' -g 'docs/**'` - `sed -n '1,240p' AGENTS.md` - `sed -n '1,260p' docs/agent-guides/work-plan-docs.md` - `sed -n '1,240p' docs/prd/sample-prd.md` - 결과: - `sample-prd.md`가 `docs/prd/sample-prd.md`에 있음을 확인했다. - 기존 규칙이 `docs/prd/`, `docs/plan-task/` 분리 저장을 안내하고 있음을 확인했다. - 새 PRD/계획 문서는 `docs/20260601_계획문서규칙수정/` 아래에 생성했다. - 2026-06-01 - 무엇/왜/어떻게: 사용자가 기존에 생성된 문서는 두고 신규 생성 문서만 새 규칙을 적용하면 된다고 정정해, 해당 범위 조건을 PRD와 규칙 문서에 추가로 명시했다. - 실행 명령: - `rg -n "docs/\\[날짜\\]_구현할내용한글|docs/prd/|docs/plan-task/|sample-prd|Phase 1|검증 기록|신규 생성 문서|기존에 생성된" AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정` - `git diff -- AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정/prd.md docs/20260601_계획문서규칙수정/plan-task.md` - `git status --short` - 결과: - `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`로 통과했다.