65 lines
6.9 KiB
Markdown
65 lines
6.9 KiB
Markdown
# 문서 작성 및 유지보수 정책
|
|
|
|
`SodaLive` 저장소에서 에이전트가 PRD, 작업 계획/TASK 문서, 코드 리뷰 리포트, 가이드 문서를 작성, 갱신, 검증할 때 따르는 규칙이다.
|
|
|
|
## 구현 전 문서 필수 절차
|
|
- 기능 구현, 버그 수정, 동작 변경은 PRD 문서와 계획/TASK 문서 없이 시작하지 않는다.
|
|
- 작업 순서는 `사용자 프롬프트 입력 → PRD 문서 작성 → 애매하거나 더 필요한 내용 또는 결정해야 하는 사항이 없어질 때까지 사용자 인터뷰 → 인터뷰 내용을 바탕으로 PRD 문서 보강 → PRD 문서를 바탕으로 계획/TASK 문서 작성 → 계획/TASK 문서를 바탕으로 필요한 내용 최소 구현`으로 고정한다.
|
|
- 신규 PRD와 계획/TASK 문서를 만들기 전에 `docs/sample/sample-prd.md`와 `docs/sample/sample-plan-task.md`를 각각 확인하고 현재 샘플의 구조와 작성 규칙을 따른다.
|
|
- PRD 작성 후 요구사항, 성공 기준, 제외 범위, 제약, 미결정 사항이 남아 있으면 구현이나 계획/TASK 작성으로 넘어가지 말고 사용자에게 질문한다.
|
|
- 사용자 인터뷰로 확인한 결정 사항은 먼저 PRD에 반영한 뒤 계획/TASK 문서에 옮긴다.
|
|
- 문서 작성 자체, 커밋, 단순 조회처럼 구현을 수반하지 않는 작업은 필요한 최소 문서만 작성한다.
|
|
|
|
## PRD 문서 규칙
|
|
- PRD 문서는 `docs/[날짜]_구현할내용한글/prd.md`로 작성한다.
|
|
- 문서 폴더명은 `[날짜]_구현할내용한글` 형식을 사용한다.
|
|
- 문서 폴더명에서 원래 띄어쓰기가 들어갈 위치는 공백 대신 `_`를 사용한다.
|
|
- 이 경로 규칙은 신규 작성 문서부터 적용하며, 기존 과거 문서는 이동하거나 변경하지 않는다.
|
|
- 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
|
|
- PRD 문서는 `docs/sample/sample-prd.md`를 기준으로 작성하고 실제 요구사항에 맞게 모든 placeholder와 예시 ID를 구체적인 값으로 교체한다.
|
|
- PRD에는 최소한 목표, 문제/배경, 성공 기준, 제외 범위, 핵심 요구사항, 기술/운영 제약, 미결정 사항을 포함한다. 해당 없는 항목은 억지로 채우지 않고 제외하거나 `해당 없음`으로 명시한다.
|
|
|
|
## 계획/TASK 문서 규칙
|
|
- 계획/TASK 문서는 PRD와 같은 문서 폴더 아래에 `plan-task.md`로 작성한다.
|
|
- 계획/TASK 문서 경로는 `docs/[날짜]_구현할내용한글/plan-task.md` 형식을 사용한다.
|
|
- 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
|
|
- 계획/TASK 문서는 `docs/sample/sample-plan-task.md`를 기준으로 작성하고 모든 placeholder를 실제 경로, Goal, 명령, 기대 결과로 교체한다.
|
|
- 계획/TASK 문서는 보강 완료된 PRD를 기준으로 작성하고, 구현 범위가 PRD의 성공 기준과 제외 범위를 벗어나지 않게 한다.
|
|
- 연속된 하나의 작업이라면 별도 새 문서를 만들지 말고 기존 PRD와 계획/TASK 문서에 추가 작업으로 이어서 기록한다.
|
|
- 계획/TASK 문서는 샘플과 같이 의미 단위 Phase로 나누고 각 Phase 아래에 독립적으로 검토 가능한 Task, Goal, 완료 증거, 선행조건을 작성한다.
|
|
- 각 Task의 실행 항목과 완료 조건은 체크박스로 작성하고 완료 즉시 `- [x]`로 갱신한다.
|
|
- 각 task에는 구현 시 생성/수정/확인할 파일 경로를 명시한다.
|
|
- 각 phase 또는 task에는 실행 명령, 기대 결과, 수동 확인 항목 등 검증 기준을 함께 작성한다.
|
|
- 작업 도중 범위가 변경되면 PRD를 먼저 보강하고 계획/TASK 문서 체크리스트를 업데이트한 뒤 구현한다.
|
|
- 결과 보고 시 문서 하단에 검증 기록(무엇/왜/어떻게, 실행 명령, 결과)을 한국어로 남긴다.
|
|
- 후속 수정이 발생해도 기존 검증 기록은 삭제/덮어쓰기 없이 누적한다.
|
|
|
|
## 코드 리뷰 리포트 규칙
|
|
- 코드 리뷰와 점검을 수행하면 발견 사항 유무와 관계없이 `docs/sample/sample-review.md`를 기준으로 결과 리포트를 작성한다.
|
|
- 리뷰 리포트는 대상 PRD와 `plan-task.md`가 있는 작업 디렉터리의 `reviews/` 아래에 둔다.
|
|
- 리뷰 리포트 경로는 `docs/[날짜]_구현할내용한글/reviews/phase<번호>-<implementation-summary>.md` 형식을 사용한다.
|
|
- 파일명의 `phase<번호>`에는 리뷰 대상 Phase 번호를 쓰고, `<implementation-summary>`에는 구현 내용을 나타내는 영문 kebab-case를 쓴다. 예: `phase2-user-profile-loading.md`.
|
|
- 리포트에는 리뷰 대상과 범위, 판정 기준, 검토 근거, 실행한 검증, 발견 사항 및 후속 판정을 기록한다. 발견 사항이 없으면 `확정 발견 사항 없음`을 명시한다.
|
|
- 발견 항목은 근거와 재현 또는 검증 절차를 확인한 뒤 수정 필요 여부를 판정한다.
|
|
- 수정이 필요하다고 확정한 항목은 코드 수정 전에 `plan-task.md`의 해당 Phase에 신규 회귀 수정 Task로 추가한다.
|
|
- 신규 Task에는 리뷰 항목 ID와 리포트 링크, 수정 대상 파일, 실패 재현 또는 대체 검증, 완료 조건과 검증 명령을 포함해 바로 실행할 수 있게 작성한다.
|
|
- 수정과 검증은 추가한 Task를 기준으로 수행하고, 완료 결과는 `plan-task.md`와 리뷰 리포트에 기존 기록을 지우지 않고 누적한다.
|
|
|
|
## 문서 유지보수 규칙
|
|
- 불확실한 규칙은 추측으로 채우지 말고 근거 파일 경로를 먼저 확인한다.
|
|
- 에이전트 안내 문구는 한국어 중심으로 유지한다.
|
|
- `CORE EXECUTION PRINCIPLES (andrej-karpathy-skills)` 섹션은 공식 원문을 영어로 유지한다.
|
|
- 명령/경로/타깃명이 바뀌면 `AGENTS.md`와 `docs/agent-guides/**`를 즉시 업데이트한다.
|
|
- 신규 문서의 형식 기준은 `docs/sample/sample-prd.md`, `docs/sample/sample-plan-task.md`, `docs/sample/sample-review.md`로 통일한다.
|
|
- 샘플의 경로, 구조 또는 작성 규칙이 바뀌면 `AGENTS.md`, 이 문서, 다른 가이드와 샘플 내부의 상호 참조를 같은 변경에서 갱신한다.
|
|
- 새 샘플 규칙은 신규 문서와 진행 중인 작업 문서에 적용한다. 과거 완료 문서는 별도 요청 없이 일괄 이동하거나 재작성하지 않는다.
|
|
- 문서를 갱신할 때 기존 Decision Log, Progress, 리뷰 판정과 검증 기록은 삭제하거나 덮어쓰지 않고 정정 또는 후속 기록을 누적한다.
|
|
|
|
## 문서 분리 기준
|
|
- `AGENTS.md`에는 실행 판단에 필요한 핵심 정책과 참조 경로만 남긴다.
|
|
- 문서 샘플은 `docs/sample/**`에 두고 세부 형식과 placeholder는 각 샘플에서 관리한다.
|
|
- 빌드/테스트/검증 명령은 `docs/agent-guides/build-test-verification.md`에 둔다.
|
|
- 코드 스타일 규칙은 `docs/agent-guides/code-style.md`에 둔다.
|
|
- 에이전트 실행 정책 상세는 `docs/agent-guides/agent-execution-policy.md`에 둔다.
|
|
- 문서 작성 및 유지보수 규칙은 이 문서에 둔다.
|