48 lines
5.7 KiB
Markdown
48 lines
5.7 KiB
Markdown
# 문서 유지보수
|
|
|
|
## 문서 유지보수 규칙
|
|
- 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`를 남긴다.
|
|
- 불확실한 규칙은 추측으로 채우지 말고 근거 파일 경로를 먼저 확인한다.
|
|
- 에이전트 안내 문구는 한국어 중심으로 유지한다.
|
|
- 커밋 규칙 예시는 팀 컨벤션 변경 시 즉시 업데이트한다.
|