sodalive-backend-spring-boot/docs/agent-guides/문서유지보수.md

문서 유지보수

문서 유지보수 규칙

• PRD 문서와 구현 계획/TASK 문서는 docs/[날짜]_구현할내용한글/ 아래에 함께 둔다.
• 날짜는 YYYYMMDD 8자리 숫자를 사용한다.
• PRD 문서 파일명은 prd.md, 구현 계획/TASK 문서 파일명은 plan-task.md를 사용한다.
• 리뷰 문서는 같은 작업 디렉터리의 reviews/ 아래에 둔다. 기본 경로는 docs/[날짜]_구현할내용한글/reviews/[리뷰범위]-review.md이며, 여러 리뷰는 범위별 파일로 누적한다.
• 요구사항 문서는 docs/sample/sample-prd.md, 구현 계획/TASK 문서는 docs/sample/sample-plan-task.md, 요구사항·구현·완료 상태 리뷰 문서는 docs/sample/sample-review.md를 기준 템플릿으로 참조한다.
• 샘플의 <...>, 예시 ID, frontend 전용 항목은 실제 작업의 확정 근거와 범위에 맞게 교체·발췌하고 불필요한 빈 섹션을 기계적으로 복사하지 않는다.
• 필요한 샘플이 없거나 위치가 불명확하면 추측하지 말고 사용자에게 확인한다.
• 구현 계획/TASK 문서는 의미 단위 phase로 나누고 ### Phase 1: ..., ### Phase 2: ... 형식의 heading을 사용한다.
• 각 phase 아래에는 단계별 task를 체크박스(- [ ] **Task N.N: ...**) 형태로 작성한다.
• goal 기능으로 실행할 계획은 문서 상단에 현재 상태·활성/다음 Goal을 기록하고, Task 또는 Phase Gate 하나만 단일 goal로 실행할 수 있도록 고유 Goal ID와 실행 순서를 둔다.
• 각 goal에는 objective, 시작 조건, 완료 증거, 범위 밖을 명시하며, Phase마다 모든 Task 완료 후 별도로 판정하는 Gate Goal을 둔다.
• 각 task에는 구현 시 생성/수정/확인할 파일 경로를 명시한다.
• 각 task에는 TDD 절차를 명시한다. 기본 형식은 RED: 실패 테스트 작성/실패 확인, GREEN: 최소 구현/통과 확인, REFACTOR: 정리/회귀 확인을 포함한다.
• 테스트 작성이 현실적으로 불가능한 task는 TDD 예외 사유와 대체 검증 방법을 task에 명시한다.
• 각 phase 또는 task에는 실행 명령, 기대 결과, 수동 확인 항목 등 검증 기준을 함께 작성한다.
• 각 Task와 Gate의 에이전트 검증 명령은 구현 기능의 focused test와 직접 영향받는 기능별 회귀로 한정한다. 전체 테스트는 사용자 실행 항목으로 분리한다.
• 공통 코드·여러 domain/phase 변경·release/final Gate를 자동 전체 테스트 실행 조건으로 작성하지 않는다. check/build/clean build의 간접 전체 테스트도 피하고 필요한 빌드는 bootJar로 명시한다.
• 계획과 결과 보고에 기능별 실행 명령·결과, 전체 테스트 미실행 사실 및 사용자 실행 명령 ./gradlew test를 남긴다. 기능 범위 완료와 사용자 전체 검증 상태를 구분하며 기존 timeout·실패 이력은 보존한다.
• 구현 완료 즉시 해당 task 체크박스를 - [x]로 갱신한다.
• 작업 도중 범위가 변경되면 계획 문서 체크리스트를 먼저 업데이트한 뒤 구현한다.
• 결과 보고 시 개별 task 검증 기록(무엇/왜/어떻게, 실행 명령, 결과)은 해당 task 아래에 한국어로 남긴다.
• 여러 task/phase에 걸친 회귀 검증, 전체 빌드/포맷 검증, 문서 변경 범위 확인처럼 전체에 해당하는 검증 기록은 문서 하단에 한국어로 남긴다.
• 후속 수정이 발생해도 기존 검증 기록은 삭제하거나 덮어쓰지 않고 누적한다.
• 완료된 Task의 후속 리뷰는 기존 체크박스를 되돌리지 않는다. docs/sample/sample-review.md 형식으로 후보를 판정하고 확정된 항목만 새 회귀 수정 Task/Goal과 Progress 기록으로 누적한다.
• 기존 리뷰 파일을 삭제하거나 덮어쓰지 않는다. 같은 범위의 후속 검증은 기존 파일에 차수별로 누적하고, 검토 범위가 다르면 reviews/ 아래에 새 파일을 만든다.
• build.gradle.kts 변경 시 실행 명령 섹션을 함께 갱신한다.
• 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다.
• .editorconfig 변경 시 포맷 규칙 섹션을 동기화한다.
• 연속된 하나의 작업에 대해 PRD 또는 구현 계획/TASK 문서가 여러 개 생기지 않도록 기존 문서 재사용 여부를 먼저 확인한다.
• 문서 전용 변경은 문서 간 정합성 대조와 공백 검사까지만 수행한다. ./gradlew tasks --all, 테스트, 빌드는 실행하지 않는다.
• 코드·빌드 설정·실행 스크립트가 함께 변경되거나 사용자가 실행 검증을 명시적으로 요청한 경우에만 변경 범위에 필요한 명령을 선택해 검증한다. 문서의 명령 예시나 향후 구현 단계의 검증 명령을 추가한 것만으로는 실행 검증을 요구하지 않는다. 생략한 검증과 사유는 작업 기록에 남긴다.
• 운영 DB 반영용 DDL 문서는 MySQL 기준으로 작성한다.
• DDL 작성 시 날짜/시간 표시 컬럼은 TIMESTAMP 타입을 사용하고, created_at은 TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각', updated_at은 TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각' 형식을 기본으로 한다.
• DDL의 모든 컬럼에는 MySQL COMMENT를 추가하고, 테이블에도 가능한 경우 COMMENT를 남긴다.
• 불확실한 규칙은 추측으로 채우지 말고 근거 파일 경로를 먼저 확인한다.
• 에이전트 안내 문구는 한국어 중심으로 유지한다.
• 커밋 규칙 예시는 팀 컨벤션 변경 시 즉시 업데이트한다.