voiceon-character-admin/docs/agent-guide/documentation.md

문서 유지보수 규칙

• PRD 문서와 구현 계획/TASK 문서는 docs/[날짜]_구현할내용한글/ 아래에 함께 둔다.
• 날짜는 YYYYMMDD 8자리 숫자를 사용한다.
• PRD 문서 파일명은 prd.md, 구현 계획/TASK 문서 파일명은 plan-task.md를 사용한다.
• 기능별 API Contract도 같은 디렉터리에 두고 PRD·계획에서 실제 파일명을 링크한다. 계약 형식은 Markdown에 한정하지 않으며 OpenAPI JSON이면 <이름>.openapi.json처럼 형식이 드러나는 파일명을 사용한다.
• 기능별 설계 결정은 prd.md의 요구사항·결정 기록에, 실행 절차는 plan-task.md의 Task·검증 기록에 통합한다. 같은 기능을 위한 별도 spec/plan 디렉터리를 docs/ 아래에 병렬로 만들지 않는다.
• 공통 샘플 문서는 docs/sample/에 두며 기능별 문서 디렉터리에 복제하지 않는다.
• PRD를 작성·변경할 때는 PRD 작성 및 유지보수 규칙과 PRD 샘플을 따른다.
• 구현 항목은 기능/작업 단위로 분리해 체크박스(- [ ]) 목록으로 작성한다.
• 구현 완료 시마다 체크박스를 - [x]로 갱신하고, 각 항목이 정상 구현되었는지 확인한다.
• plan-task.md의 각 Task는 TDD 적용 여부를 명시한다. 테스트 가능한 구현 Task에는 TDD 절차를 두고 RED: 실패 테스트 작성/실패 확인, GREEN: 최소 구현/통과 확인, REFACTOR: 정리/회귀 확인 순서를 적는다.
• 실패 테스트 작성이 현실적으로 불가능한 Task는 TDD 절차를 아무 표시 없이 생략하지 말고 같은 Task에 TDD 예외 사유와 대체 검증 방법을 구체적으로 기록한다.
• 각 Task에는 실행 명령, 기대 결과, 수동 확인을 포함한 검증 기준을 작성한다. 수동 확인이 불필요하면 없음과 그 사유를 적는다.
• 각 Phase의 Gate에도 통합 검증을 위한 실행 명령, 기대 결과, 수동 확인 항목을 작성한다.
• 작업 도중 범위가 변경되면 계획 문서의 체크박스 항목을 먼저 업데이트한 뒤 구현을 진행한다.
• 모든 구현이 끝난 후 결과 보고 시 계획 문서 맨 아래에 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 기록한다.
• 후속 수정이 발생해도 기존 검증 기록은 삭제/덮어쓰지 않고 누적한다(예: 1차 구현, 2차 수정).
• 검증 기록은 단계별로 무엇을/왜/어떻게를 유지해 작성하고, 이전 단계와 구분이 되도록 명시한다.
• 단계별 어떻게에는 실제 실행한 검증 명령과 결과(성공/실패/불가 사유)를 함께 기록한다.
• 기존 기록 정정이 필요하면 원문을 지우지 말고 정정 항목을 추가해 사유와 변경 내용을 남긴다.
• goal 기능으로 실행할 구현 계획은 Goal 실행형 구현 계획 규칙과 Goal 실행형 계획 샘플을 따른다.
• 완료된 Phase 또는 Task의 코드 리뷰·QA 결과 문서는 해당 prd.md·plan-task.md 디렉터리 아래 reviews/에 모아 둔다. 기능 문서 디렉터리 바로 아래나 단수형 review/에는 두지 않는다.
• 리뷰 문서의 상세 형식, 파일명과 참조 방법은 코드 리뷰 및 QA 기록 규칙을 따른다.