166 lines
10 KiB
Markdown
166 lines
10 KiB
Markdown
# PRD: 계획 문서 규칙 수정
|
|
|
|
## 1. Overview
|
|
작업 절차와 PRD/계획/TASK 문서 작성 규칙을 새 디렉터리 구조와 유지보수 방식에 맞게 갱신한다.
|
|
|
|
---
|
|
|
|
## 2. Problem
|
|
- 기존 규칙은 PRD 문서와 계획/TASK 문서를 `docs/prd/`, `docs/plan-task/`로 분리해 저장하도록 안내한다.
|
|
- 사용자는 새 작업 문서를 `docs/[날짜]_구현할내용한글/prd.md`, `docs/[날짜]_구현할내용한글/plan-task.md` 형태로 함께 관리하길 원한다.
|
|
- 작업 도중 범위 변경, 완료 체크, 검증 기록 누적 규칙을 작업 절차 문서에도 일관되게 반영해야 한다.
|
|
|
|
---
|
|
|
|
## 3. Goals
|
|
- `AGENTS.md`의 작업 절차 핵심 규칙을 새 문서 위치와 작성 순서 기준으로 갱신한다.
|
|
- `docs/agent-guides/work-plan-docs.md`의 작업 계획 문서 규칙을 사용자 요청 사항과 일치하도록 수정한다.
|
|
- 이번 작업의 PRD와 계획/TASK 문서를 새 구조인 `docs/20260601_계획문서규칙수정/` 아래에 작성한다.
|
|
- 기존에 생성된 `docs/prd/`, `docs/plan-task/` 문서는 유지하고, 신규 생성 문서부터 새 구조를 적용한다고 명시한다.
|
|
|
|
---
|
|
|
|
## 4. Non-Goals
|
|
- 기존 `docs/prd/` 및 `docs/plan-task/` 아래 과거 문서를 이동하거나 이름을 바꾸지 않는다.
|
|
- 기존 `docs/prd/` 및 `docs/plan-task/` 아래 과거 문서 내용을 새 구조로 재작성하지 않는다.
|
|
- 빌드, 테스트, 코드 스타일, 커밋 메시지 규칙은 변경하지 않는다.
|
|
- Android 앱 소스 코드는 수정하지 않는다.
|
|
|
|
---
|
|
|
|
## 5. Target Users
|
|
- 이 저장소에서 작업하는 에이전트와 개발자.
|
|
|
|
---
|
|
|
|
## 6. User Stories
|
|
- 사용자는 구현 전에 PRD와 계획/TASK 문서가 모두 준비되길 원한다.
|
|
- 사용자는 하나의 작업 문서를 한 폴더에서 함께 확인하고 싶다.
|
|
- 사용자는 후속 수정과 검증 기록이 기존 문서에 누적되길 원한다.
|
|
|
|
---
|
|
|
|
## 7. Core Features
|
|
|
|
### 작업 문서 구조 변경
|
|
|
|
#### Requirements
|
|
- 문서는 `docs/[날짜]_구현할내용한글/prd.md`, `docs/[날짜]_구현할내용한글/plan-task.md` 형식으로 만든다.
|
|
- 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
|
|
- PRD 문서는 `sample-prd.md`에서 작업에 필요한 부분만 발췌해 작성한다.
|
|
- `sample-prd.md`가 없거나 위치가 불명확하면 추측하지 말고 사용자에게 확인한다.
|
|
- 연속된 하나의 작업은 새 문서를 만들지 않고 기존 PRD와 계획/TASK 문서에 추가 작업으로 기록한다.
|
|
|
|
#### Edge Cases
|
|
- 과거 문서는 기존 기록으로 유지하고 새 규칙만 앞으로의 작업에 적용한다.
|
|
- 작업 범위가 바뀌면 계획/TASK 문서를 먼저 갱신한 뒤 구현한다.
|
|
|
|
### 계획/TASK 문서 유지보수
|
|
|
|
#### Requirements
|
|
- 계획/TASK 문서는 의미 단위 phase로 나누고 `### Phase 1: ...` 형식의 heading을 사용한다.
|
|
- 각 phase 아래 task는 체크박스(`- [ ] **Task N.N: ...**`)로 작성하고 완료 즉시 `- [x]`로 갱신한다.
|
|
- 각 task에는 생성/수정/확인할 파일 경로를 명시한다.
|
|
- 각 phase 또는 task에는 실행 명령, 기대 결과, 수동 확인 항목 등 검증 기준을 작성한다.
|
|
- 결과 보고 시 문서 하단에 검증 기록을 한국어로 남기고, 후속 수정 시 기존 기록을 삭제하거나 덮어쓰지 않는다.
|
|
|
|
---
|
|
|
|
## 8. UX / UI Expectations
|
|
- 해당 없음.
|
|
|
|
---
|
|
|
|
## 9. Technical Constraints
|
|
- Markdown 문서만 수정한다.
|
|
- 변경 범위는 `AGENTS.md`, `docs/agent-guides/work-plan-docs.md`, `docs/20260601_계획문서규칙수정/`로 제한한다.
|
|
|
|
---
|
|
|
|
## 10. Metrics
|
|
- `AGENTS.md`가 새 문서 구조와 작업 순서를 안내한다.
|
|
- `docs/agent-guides/work-plan-docs.md`가 사용자 요청의 규칙을 빠짐없이 포함한다.
|
|
- 이번 작업 문서가 `docs/20260601_계획문서규칙수정/prd.md`와 `docs/20260601_계획문서규칙수정/plan-task.md`에 존재한다.
|
|
|
|
---
|
|
|
|
## 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` |
|