docs(agent): 문서 작업 절차를 보강한다

docs/agent-guides/문서유지보수.md

@@ -4,20 +4,35 @@
 - PRD 문서와 구현 계획/TASK 문서는 `docs/[날짜]_구현할내용한글/` 아래에 함께 둔다.
 - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
 - PRD 문서 파일명은 `prd.md`, 구현 계획/TASK 문서 파일명은 `plan-task.md`를 사용한다.
-- PRD 문서는 `sample-prd.md`에서 필요한 섹션만 발췌해 작성하고, 불필요한 빈 섹션을 기계적으로 복사하지 않는다.
-- `sample-prd.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의 검증 기준에는 단일 테스트 실행 명령과 필요한 경우 전체 회귀 명령을 포함한다.
+- 각 task의 검증 기준에는 focused test와 직접 영향받는 회귀 명령을 우선 명시한다. 전체 회귀는 광범위한 공통 코드 변경,
+  여러 domain/phase 변경, release/final Gate에서 전체 상태 증거를 별도로 요구하는 경우, targeted test만으로 영향 범위를 판단할
+  수 없는 경우 또는 사용자 요청일 때만 포함한다.
+- 계획에서 전체 회귀를 조건부로 두면 실행 조건, 생략 시 기록할 근거와 대체 focused/영향 범위 회귀 명령을 함께 명시한다.
 - 구현 완료 즉시 해당 task 체크박스를 `- [x]`로 갱신한다.
 - 작업 도중 범위가 변경되면 계획 문서 체크리스트를 먼저 업데이트한 뒤 구현한다.
 - 결과 보고 시 개별 task 검증 기록(무엇/왜/어떻게, 실행 명령, 결과)은 해당 task 아래에 한국어로 남긴다.
 - 여러 task/phase에 걸친 회귀 검증, 전체 빌드/포맷 검증, 문서 변경 범위 확인처럼 전체에 해당하는 검증 기록은 문서 하단에 한국어로 남긴다.
 - 후속 수정이 발생해도 기존 검증 기록은 삭제하거나 덮어쓰지 않고 누적한다.
+- 완료된 Task의 후속 리뷰는 기존 체크박스를 되돌리지 않는다. `docs/sample/sample-review.md` 형식으로 후보를 판정하고 확정된
+  항목만 새 회귀 수정 Task/Goal과 Progress 기록으로 누적한다.
+- 기존 리뷰 파일을 삭제하거나 덮어쓰지 않는다. 같은 범위의 후속 검증은 기존 파일에 차수별로 누적하고, 검토 범위가 다르면
+  `reviews/` 아래에 새 파일을 만든다.
 - `build.gradle.kts` 변경 시 실행 명령 섹션을 함께 갱신한다.
 - 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다.
 - `.editorconfig` 변경 시 포맷 규칙 섹션을 동기화한다.

docs/agent-guides/실행명령어.md

@@ -3,8 +3,18 @@
 ## 실행 기준
 - 아래 명령은 저장소 루트(`/Users/klaus/Develop/sodalive/Server/sodalive`)에서 실행한다.
 - 변경 범위에 맞는 최소 명령으로 검증하고, 결과는 계획 문서 하단 검증 기록에 남긴다.
+- 검증은 focused test → 영향받는 package/feature 회귀 → 전체 회귀 순서로 범위를 넓힌다.
+- 전체 회귀 테스트(`./gradlew test`, `./gradlew check`, 전체 `build`)는 실행 시간이 길므로 매 Task나 일반적인 작은 변경에서
+  관성적으로 실행하지 않는다.
+- 공통 인증·보안·예외·설정·serialization처럼 영향 범위가 넓은 코드 변경, 여러 domain/phase에 걸친 변경, release/final Gate에서
+  전체 상태 증거를 별도로 요구하는 경우, targeted test만으로 영향 범위를 판단할 수 없는 실패 또는 사용자 명시 요청일 때만
+  전체 회귀를 실행한다.
+- 전체 회귀를 생략하면 실행하지 않은 사실, 생략 근거와 대신 실행한 focused/영향 범위 회귀 명령을 계획 문서에 기록한다.
 
 ## Build/Lint/Test
+
+아래는 사용 가능한 명령 목록이며 모든 변경에서 전부 실행하라는 의미가 아니다.
+
 ```bash
 ./gradlew tasks --all
 ./gradlew bootRun

docs/agent-guides/작업절차.md

@@ -2,11 +2,20 @@
 
 ## 작업 절차 체크리스트
 - 변경 전: 모든 구현 작업은 PRD 문서와 구현 계획/TASK 문서가 모두 준비된 뒤에 시작한다.
-- 변경 전: 사용자 프롬프트를 받으면 먼저 PRD 문서를 작성한다.
+- 변경 전: 사용자 프롬프트를 받으면 먼저 PRD 문서를 작성한다. 새 요구사항 문서는
+  `docs/sample/sample-prd.md`에서 필요한 섹션을 발췌하고 모든 placeholder와 예시 ID를 실제 값으로 교체한다.
 - 변경 전: PRD 작성 중 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 애매한 사항이 없어질 때까지 사용자와 인터뷰하고 PRD를 보강한다.
-- 변경 전: PRD는 `sample-prd.md`에서 작업에 필요한 부분만 발췌해 작성한다. `sample-prd.md`가 없거나 위치가 불명확하면 추측하지 말고 사용자에게 확인한다.
+- 변경 전: PRD는 `docs/sample/sample-prd.md`에서 작업에 필요한 부분만 발췌해 작성한다. 파일이 없거나 읽을 수 없으면 추측하지
+  말고 사용자에게 확인한다.
 - 변경 전: 문서는 `docs/[날짜]_구현할내용한글/prd.md`, `docs/[날짜]_구현할내용한글/plan-task.md` 형식으로 작성한다.
-- 변경 전: 보강된 PRD를 바탕으로 구현 계획/TASK 문서를 작성한 뒤, 해당 문서를 기준으로 필요한 내용만 최소 구현한다.
+- 변경 전: 보강된 PRD를 바탕으로 `docs/sample/sample-plan-task.md`를 참조해 goal 실행형 구현 계획/TASK 문서를 작성한 뒤,
+  해당 문서를 기준으로 필요한 내용만 최소 구현한다.
+- 변경 전: 구현 계획은 Phase를 결과·의존성 단위로, Task와 Phase Gate를 한 번에 하나씩 실행할 goal 단위로 작성한다. 각 Goal에는
+  고유 ID, 한 문장 objective, 시작 조건, 완료 증거, 범위 밖, 정확한 파일 경로, 실행 체크박스와 검증 명령을 포함한다.
+- 변경 전: 요구사항 또는 구현 완료 상태를 재검토하는 문서는 `docs/sample/sample-review.md`를 참조한다. 리뷰 후보는 재현·판정하고,
+  확정 항목만 기존 계획에 새 회귀 수정 Task와 goal로 추가한다.
+- 변경 전: 리뷰 문서는 PRD·구현 계획과 같은 `docs/[날짜]_구현할내용한글/` 아래의 `reviews/` 폴더에 저장한다. 리뷰가 여러
+  개면 목적과 범위가 드러나는 개별 파일명으로 분리하고 기존 리뷰를 덮어쓰지 않는다.
 - 변경 전: 구현 계획/TASK 문서의 각 task에는 TDD 기준의 실패 테스트 작성, 실패 확인, 최소 구현, 통과 확인, 리팩터링/회귀 확인 단계를 포함한다.
 - 변경 전: 유사 기능 코드를 먼저 찾아 네이밍/예외/응답 패턴을 맞춘다.
 - 변경 전: 신규 API나 하위 코드 작성 시 `docs/agent-guides/코드스타일.md`의 패키지/코드 배치 규칙을 확인한다.
@@ -16,6 +25,12 @@
 - 변경 중: Todo를 사용할 때는 사용자에게 보이는 Todo 내용을 한국어로 작성한다. 경로, 클래스명, 명령어, 코드 식별자는 원문을 유지한다.
 - 변경 중: 공개 API 스키마를 임의 변경하지 말고, 작은 단위로 안전하게 수정한다.
 - 변경 중: 구현 완료 즉시 해당 task 체크박스를 `- [x]`로 갱신한다.
-- 변경 후: 최소 단일 테스트 또는 `./gradlew test`를 실행하고, 필요 시 `./gradlew ktlintCheck`를 수행한다.
+- 변경 중: 동시에 하나의 미완료 goal만 운용한다. Goal의 체크박스, focused test, 완료 증거와 Progress 기록이 모두 충족되기
+  전에는 goal이나 Phase Gate를 완료 처리하지 않는다.
+- 변경 중: 완료된 Task와 기존 검증 기록은 되돌리거나 삭제하지 않는다. 후속 리뷰에서 발견한 회귀는 별도 Task/Goal로 누적한다.
+- 변경 후: 변경 범위의 focused test를 우선 실행하고, 공유 경계와 직접 영향받는 package/feature 회귀까지만 단계적으로 확장한다.
+- 변경 후: 전체 회귀 테스트는 공통 인증·보안·예외·설정 등 광범위한 변경, 여러 domain/phase 변경, release/final Gate에서 전체
+  상태 증거를 별도로 요구하는 경우, targeted test만으로 영향 범위를 판단할 수 없는 실패 또는 사용자 명시 요청일 때만 실행한다.
+- 변경 후: 전체 회귀 테스트를 실행하지 않으면 생략 사실과 근거, 대신 실행한 focused/영향 범위 회귀 명령을 검증 기록에 남긴다.
 - 변경 후: 각 task의 검증 결과는 해당 task 아래에 무엇을, 왜, 어떻게 검증했는지, 실행 명령과 결과를 한국어로 누적 기록한다.
 - 변경 후: 여러 task/phase에 걸친 회귀 검증, 전체 빌드/포맷 검증, 문서 변경 범위 확인처럼 전체에 해당하는 검증은 계획 문서 하단의 검증 기록에 누적한다.