276 lines
18 KiB
Markdown
276 lines
18 KiB
Markdown
# 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`로 통과했다.
|