From 44b8633e594b971998172901b086c6947829363b Mon Sep 17 00:00:00 2001 From: Yu Sung Date: Fri, 15 May 2026 11:11:52 +0900 Subject: [PATCH] =?UTF-8?q?docs(agent):=20PRD=20=EA=B3=84=ED=9A=8D=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=EA=B7=9C=EC=B9=99=EC=9D=84=20=EB=B3=B4?= =?UTF-8?q?=EA=B0=95=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- docs/agent-guides/documentation-policy.md | 25 ++++- .../20260515_PRD계획TASK문서규칙보강.md | 19 ++++ docs/prd/sample-prd.md | 106 ++++++++++++++++++ 4 files changed, 146 insertions(+), 6 deletions(-) create mode 100644 docs/plan-task/20260515_PRD계획TASK문서규칙보강.md create mode 100644 docs/prd/sample-prd.md diff --git a/AGENTS.md b/AGENTS.md index 5f72e14..61387bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -147,7 +147,7 @@ Strong success criteria let you loop independently. Weak criteria ("make it work - 외부 SDK 키 변경 시 빌드 설정과 런타임 초기화 지점을 함께 검토한다. ## 문서 작성 규칙 -- 작업 계획 문서 작성, 체크리스트 갱신, 검증 기록 누적, 문서 분리 기준은 `docs/agent-guides/documentation-policy.md`를 따른다. +- 구현 전 PRD 작성, 사용자 인터뷰, 계획/TASK 문서 작성, 체크리스트 갱신, 검증 기록 누적, 문서 분리 기준은 `docs/agent-guides/documentation-policy.md`를 따른다. ## 문서 유지보수 규칙 - 상세 문서 유지보수 규칙은 `docs/agent-guides/documentation-policy.md`를 참조한다. diff --git a/docs/agent-guides/documentation-policy.md b/docs/agent-guides/documentation-policy.md index 11b58c7..81235d8 100644 --- a/docs/agent-guides/documentation-policy.md +++ b/docs/agent-guides/documentation-policy.md @@ -1,13 +1,28 @@ # 문서 작성 및 유지보수 정책 -`SodaLive` 저장소에서 에이전트가 작업 계획 문서와 가이드 문서를 작성, 갱신, 검증할 때 따르는 규칙이다. +`SodaLive` 저장소에서 에이전트가 PRD, 작업 계획/TASK 문서, 가이드 문서를 작성, 갱신, 검증할 때 따르는 규칙이다. -## 작업 계획 문서 규칙 -- 모든 작업 시작 전에 `docs` 폴더 아래 계획 문서를 먼저 생성하고, 해당 문서를 기준으로 구현한다. -- 계획 문서 파일명은 `[날짜]_구현할내용한글.md` 형식을 사용한다. +## 구현 전 문서 필수 절차 +- 기능 구현, 버그 수정, 동작 변경은 PRD 문서와 계획/TASK 문서 없이 시작하지 않는다. +- 작업 순서는 `사용자 프롬프트 입력 → PRD 문서 작성 → 애매하거나 더 필요한 내용 또는 결정해야 하는 사항이 없어질 때까지 사용자 인터뷰 → 인터뷰 내용을 바탕으로 PRD 문서 보강 → PRD 문서를 바탕으로 계획/TASK 문서 작성 → 계획/TASK 문서를 바탕으로 필요한 내용 최소 구현`으로 고정한다. +- PRD 작성 후 요구사항, 성공 기준, 제외 범위, 제약, 미결정 사항이 남아 있으면 구현이나 계획/TASK 작성으로 넘어가지 말고 사용자에게 질문한다. +- 사용자 인터뷰로 확인한 결정 사항은 먼저 PRD에 반영한 뒤 계획/TASK 문서에 옮긴다. +- 문서 작성 자체, 커밋, 단순 조회처럼 구현을 수반하지 않는 작업은 필요한 최소 문서만 작성한다. + +## PRD 문서 규칙 +- PRD 문서는 `docs/prd/` 아래에 작성한다. +- PRD 문서 파일명은 기존 계획 문서 파일명 규칙을 따르되 계획/TASK 문서와 구분되도록 `[날짜]_구현할내용한글_PRD.md` 형식을 사용한다. - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다. +- PRD 문서는 `docs/prd/sample-prd.md`에서 필요한 섹션만 발췌해 작성한다. +- PRD에는 최소한 목표, 문제/배경, 성공 기준, 제외 범위, 핵심 요구사항, 기술/운영 제약, 미결정 사항을 포함한다. 해당 없는 항목은 억지로 채우지 않고 제외하거나 `해당 없음`으로 명시한다. + +## 계획/TASK 문서 규칙 +- 계획/TASK 문서는 `docs/plan-task/` 아래에 작성한다. +- 계획/TASK 문서 파일명은 `[날짜]_구현할내용한글.md` 형식을 사용한다. +- 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다. +- 계획/TASK 문서는 보강 완료된 PRD를 기준으로 작성하고, 구현 범위가 PRD의 성공 기준과 제외 범위를 벗어나지 않게 한다. - 구현 항목은 기능/작업 단위 체크박스(`- [ ]`)로 작성하고 완료 즉시 `- [x]`로 갱신한다. -- 작업 도중 범위가 변경되면 계획 문서 체크리스트를 먼저 업데이트한 뒤 구현한다. +- 작업 도중 범위가 변경되면 PRD를 먼저 보강하고 계획/TASK 문서 체크리스트를 업데이트한 뒤 구현한다. - 결과 보고 시 문서 하단에 검증 기록(무엇/왜/어떻게, 실행 명령, 결과)을 한국어로 남긴다. - 후속 수정이 발생해도 기존 검증 기록은 삭제/덮어쓰기 없이 누적한다. diff --git a/docs/plan-task/20260515_PRD계획TASK문서규칙보강.md b/docs/plan-task/20260515_PRD계획TASK문서규칙보강.md new file mode 100644 index 0000000..1eeb4d8 --- /dev/null +++ b/docs/plan-task/20260515_PRD계획TASK문서규칙보강.md @@ -0,0 +1,19 @@ +# PRD/계획/TASK 문서 규칙 보강 계획 + +## 목표 +- 구현 전 PRD와 계획/TASK 문서를 작성하고, 애매한 사항은 사용자 인터뷰로 해소한 뒤 최소 구현하도록 문서 정책을 보강한다. +- 기존 `docs/prd/sample-prd.md`, `docs/prd/`, `docs/plan-task/` 구조를 기준으로 저장 위치와 파일명 규칙을 명확히 한다. + +## 작업 항목 +- [x] 기존 `AGENTS.md`와 `docs/agent-guides/documentation-policy.md` 구조 확인 +- [x] `docs/prd/sample-prd.md`, `docs/prd/`, `docs/plan-task/` 존재 여부 확인 +- [x] `AGENTS.md` 문서 작성 규칙 요약 보강 +- [x] `docs/agent-guides/documentation-policy.md`에 구현 전 PRD/계획/TASK 절차 추가 +- [x] 변경 내용 검증 및 검증 기록 누적 + +## 검증 기록 +- 2026-05-15: `rg --files | rg '(^|/)sample-prd\.md$|(^|/)docs/prd(/|$)|(^|/)docs/plan-task(/|$)'`로 `docs/prd/sample-prd.md`, `docs/prd/`, `docs/plan-task/` 구조를 확인했다. +- 2026-05-15: `rg -n "PRD|sample-prd|plan-task|계획 문서|작업 계획|인터뷰|구현하지 않는다" AGENTS.md docs`로 기존 문서 정책과 관련 문구를 확인했다. +- 2026-05-15: `git diff --check -- AGENTS.md docs/agent-guides/documentation-policy.md docs/plan-task/20260515_PRD계획TASK문서규칙보강.md` 실행 결과 출력 없이 종료되어 공백 오류가 없음을 확인했다. +- 2026-05-15: `rg -n "PRD|계획/TASK|docs/prd|docs/plan-task|sample-prd|사용자 인터뷰|최소 구현" AGENTS.md docs/agent-guides/documentation-policy.md docs/plan-task/20260515_PRD계획TASK문서규칙보강.md`로 필수 정책 문구와 참조 경로가 포함되어 있는지 확인했다. +- 2026-05-15: `lsp_diagnostics`로 `AGENTS.md`, `docs/agent-guides/documentation-policy.md`, `docs/plan-task/20260515_PRD계획TASK문서규칙보강.md`를 확인했고 진단 결과는 모두 `No diagnostics found`였다. diff --git a/docs/prd/sample-prd.md b/docs/prd/sample-prd.md new file mode 100644 index 0000000..3136d74 --- /dev/null +++ b/docs/prd/sample-prd.md @@ -0,0 +1,106 @@ +# 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?