docs(agent-guide): 문서 작성 규칙 정리

docs/agent-guide/documentation.md

@@ -3,6 +3,8 @@
 - PRD 문서와 구현 계획/TASK 문서는 `docs/[날짜]_구현할내용한글/` 아래에 함께 둔다.
 - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
 - PRD 문서 파일명은 `prd.md`, 구현 계획/TASK 문서 파일명은 `plan-task.md`를 사용한다.
+- 공통 샘플 문서는 `docs/sample/`에 두며 기능별 문서 디렉터리에 복제하지 않는다.
+- PRD를 작성·변경할 때는 [PRD 작성 및 유지보수 규칙](./prd.md)과 [PRD 샘플](../sample/sample-prd.md)을 따른다.
 - 구현 항목은 기능/작업 단위로 분리해 체크박스(`- [ ]`) 목록으로 작성한다.
 - 구현 완료 시마다 체크박스를 `- [x]`로 갱신하고, 각 항목이 정상 구현되었는지 확인한다.
 - 작업 도중 범위가 변경되면 계획 문서의 체크박스 항목을 먼저 업데이트한 뒤 구현을 진행한다.
@@ -11,3 +13,5 @@
 - 검증 기록은 단계별로 `무엇을/왜/어떻게`를 유지해 작성하고, 이전 단계와 구분이 되도록 명시한다.
 - 단계별 `어떻게`에는 실제 실행한 검증 명령과 결과(성공/실패/불가 사유)를 함께 기록한다.
 - 기존 기록 정정이 필요하면 원문을 지우지 말고 `정정` 항목을 추가해 사유와 변경 내용을 남긴다.
+- goal 기능으로 실행할 구현 계획은 [Goal 실행형 구현 계획 규칙](./goal-plan.md)과 [Goal 실행형 계획 샘플](../sample/sample-plan-task.md)을 따른다.
+- 완료된 Phase 또는 Task의 코드 리뷰·QA 결과 문서는 해당 `prd.md`와 같은 디렉터리에 두고, 상세 형식과 후속 처리에는 [코드 리뷰 및 QA 기록 규칙](./review.md)을 따른다.

docs/agent-guide/goal-plan.md

@@ -0,0 +1,79 @@
+# Goal 실행형 구현 계획 규칙
+
+## 1. 적용 시점
+
+- 사용자가 goal 기능으로 구현을 진행하거나, goal에 적합한 `plan-task.md` 작성·보완을 요청하면 이 문서를 따른다.
+- 구현 전에 [PRD 작성 및 유지보수 규칙](./prd.md), 대상 기능의 `prd.md`, `api-contract.md`, 기존 `plan-task.md`, 관련 코드·test와 저장소 가이드를 읽는다.
+- 계획 작성 요청은 문서 변경 범위다. 사용자가 구현까지 요청하지 않았다면 애플리케이션 코드와 설정을 변경하지 않는다.
+
+## 2. 기준 템플릿과 위치
+
+- `plan-task.md`는 해당 `prd.md`와 같은 `docs/YYYYMMDD_구현할내용한글/` 디렉터리에 둔다.
+- [Goal 실행형 계획 샘플](../sample/sample-plan-task.md)을 원본 템플릿으로 사용하고 필수 section과 goal 필드를 임의로 생략하지 않는다.
+- 실제 계획에서는 `<...>`, 예시 명령, 선택지와 설명용 placeholder를 모두 정확한 값으로 교체한다. placeholder가 남아 있는 Task는 goal로 시작하지 않는다.
+
+## 3. 필수 문서 구조
+
+`plan-task.md`에는 다음 section을 둔다.
+
+1. 목표
+2. 현재 상태
+3. 범위의 포함·제외
+4. 기술적 제약
+5. 하나 이상의 Phase
+6. 실행 순서와 의존성
+7. 변경 금지 항목
+8. 의사결정 및 중단 규칙
+9. Progress
+10. Decision Log
+11. 발견된 문제
+12. 최종 보고 형식
+
+각 Phase에는 다음 내용을 둔다.
+
+- 사용자가 직접 확인할 수 있는 Phase 결과
+- 선행조건과 Phase 완료 조건
+- 하나 이상의 Task
+- Task 전체 완료 조건
+- 자동·수동 검증 방법과 Phase Gate
+
+## 4. Task와 goal 작성 규칙
+
+- Phase는 실행 흐름과 의존성을 묶는 상위 경계다. `create_goal`에는 Task 또는 Phase Gate 하나만 등록한다.
+- 모든 Task에는 고유 Goal ID, 한 문장 objective, 시작 조건, 완료 증거와 범위 밖을 둔다.
+- Goal ID는 `P<Phase>-T<Task>`를 사용한다. Phase Gate는 `P<Phase>-GATE`, 완료 범위의 회귀 수정은 `P<Phase>-R<번호>`를 사용한다.
+- Task는 독립 reviewer가 이웃 Task와 별도로 승인·거절할 수 있고, 자체 test cycle로 검증할 수 있는 최소 결과 단위로 나눈다.
+- Task마다 생성·수정·test 파일의 정확한 경로를 기록한다. 선행 Task contract를 소비하거나 후속 Task에 제공하면 `Interfaces`에 정확한 type·function·component를 기록한다.
+- 구현 체크박스는 실패 test 작성 → 의도한 실패 확인 → 최소 구현 → focused test 성공 → 관련 품질 검증 → Progress 기록 순서를 포함한다.
+- “적절히 처리”, “나중에 구현”, “위와 동일”처럼 실행자가 다시 추측해야 하는 표현을 사용하지 않는다.
+
+## 5. 완료와 차단 판정
+
+- 동시에 하나의 미완료 goal만 운용한다. 활성 goal이 있으면 새 goal을 만들지 않고 같은 Task를 이어서 수행한다.
+- 사용자가 명시적으로 요청하지 않으면 token budget을 설정하지 않는다.
+- 코드 작성이나 일부 test만 끝난 상태는 완료가 아니다. 체크박스, 완료 증거, 실제 검증과 Progress 기록까지 충족한 뒤에만 goal을 `complete`로 갱신한다.
+- Phase의 모든 활성 Task goal을 완료한 뒤 Phase Gate를 별도 goal로 실행한다.
+- 외부 계약이나 권한 같은 동일 차단 사유가 최초 시도와 자동 후속을 포함해 3회 연속 반복되고, 문서화·독립 작업 등 의미 있는 진전도 불가능할 때만 goal을 `blocked`로 갱신한다.
+- 계약이 없어 안전하게 구현할 수 없으면 추정하지 않는다. 담당 주체·영향·재개 조건을 기록하고 PRD 결정 기록 → API Contract → `plan-task.md` 순서로 제외 또는 후속 결정을 반영한다.
+- 완료된 Task를 묵시적으로 다시 열지 않는다. 후속 수정은 발견된 문제와 별도 회귀 수정 Task·goal로 관리한다.
+
+## 6. 계획 유지보수
+
+- 범위나 구현 방식이 바뀌면 코드를 수정하기 전에 관련 체크박스, Files, Interfaces, 완료 증거와 Decision Log를 갱신한다.
+- Progress와 Decision Log의 기존 기록은 삭제하거나 덮어쓰지 않는다. 정정은 날짜·사유와 함께 새 기록으로 추가한다.
+- 실행한 명령만 기록하고 성공/실패, exit code, test 수 또는 불가 사유를 남긴다.
+- 구현 중 발견한 범위 내 문제는 `발견된 문제`에 기록한다. 완료 범위의 상세 리뷰·QA는 [코드 리뷰 및 QA 기록 규칙](./review.md)에 따라 별도 review 문서로 관리한다.
+- Phase 완료 후 현재 상태 표와 체크박스를 갱신하고 Phase Gate의 최신 증거를 Progress에 누적한다.
+
+## 7. 실행 전 자체 검토
+
+goal을 만들기 전에 다음을 확인한다.
+
+- 목표와 포함·제외 범위가 서로 충돌하지 않는다.
+- 모든 확정 요구사항이 최소 하나의 Task와 완료 증거로 추적된다.
+- 모든 Task의 시작 조건과 선행 Goal ID가 실제로 존재한다.
+- Files와 Interfaces의 이름이 앞뒤 Task에서 일치한다.
+- 외부 의존과 안전한 기본값이 구분돼 있다.
+- 실제 검증 명령과 Expected가 구체적이다.
+- placeholder, 미정 값, 추정 계약이 없다.
+- 변경 금지 항목과 중단 규칙이 명시돼 있다.

docs/agent-guide/prd.md

@@ -0,0 +1,51 @@
+# PRD 작성 및 유지보수 규칙
+
+## 1. 적용 시점
+
+- 사용자가 새 기능의 요구사항 정리, PRD 작성·보완 또는 구현 계획 전 요구사항 명확화를 요청하면 이 문서를 따른다.
+- PRD 작성 전에 관련 사용자 요청, 기존 제품 문서, API Contract, 구현 코드와 알려진 제약을 확인한다.
+- PRD 작업은 요구사항 문서 범위다. 사용자가 구현까지 요청하지 않았다면 애플리케이션 코드와 설정을 변경하지 않는다.
+
+## 2. 기준 템플릿과 위치
+
+- 실제 PRD는 `docs/YYYYMMDD_구현할내용한글/prd.md`에 둔다.
+- [PRD 샘플](../sample/sample-prd.md)을 원본 템플릿으로 사용하고 필수 section과 추적 필드를 임의로 생략하지 않는다.
+- 공통 샘플은 `docs/sample/`에서만 관리하며 기능별 문서 디렉터리에 복제하지 않는다.
+- 실제 PRD에서는 `<...>`, 예시 ID, 선택지와 설명용 placeholder를 모두 구체적인 값으로 교체한다.
+
+## 3. 요구사항 작성 규칙
+
+- 요구사항 ID는 `<DOMAIN>-NNN` 형식을 사용하고 한 행에는 독립적으로 판정 가능한 요구사항 하나만 기록한다.
+- 상태는 `확정`, `미결`, `외부 의존`, `권고`, `제외`만 사용한다.
+- 모든 확정 요구사항에는 사용자가 관찰하거나 test로 판정할 수 있는 수용 기준을 둔다.
+- 미결 항목에는 현재 권고, 결정 주체와 결정 시점 또는 다음 행동을 기록한다.
+- 외부 의존에는 담당 주체, 영향받는 기능과 재개 조건을 기록한다. endpoint·DTO·enum·오류 status/key를 추정하지 않는다.
+- 제외 항목에는 제외 이유, 결정 기록과 다시 포함할 조건을 둔다.
+- Non-Goal, 반응형 capability, 접근성, 보안·데이터 처리, 성능과 지원 환경을 명시한다.
+
+## 4. 문서 간 추적
+
+- 제품 결정과 사용자 요구는 PRD가 소유한다.
+- request/response/error와 endpoint 세부 계약은 `api-contract.md`가 소유한다.
+- 구현 순서, Files, Interfaces, Task/Goal과 완료 증거는 `plan-task.md`가 소유한다.
+- 모든 확정 요구사항을 API Contract section 또는 명시적인 contract 불필요 판정, 하나 이상의 Phase/Goal, 자동·수동 검증으로 연결한다.
+- Open Question과 외부 의존을 혼합하지 않는다. 제품이 결정할 수 없는 backend 계약은 별도 외부 의존 ID로 관리한다.
+
+## 5. 변경과 결정 기록
+
+- 요구사항이 변경되면 PRD Decision Log → 관련 요구사항·수용 기준 → API Contract → `plan-task.md` 순서로 갱신한다.
+- 기존 결정은 삭제하거나 덮어쓰지 않는다. 정정은 날짜·사유·영향 범위와 함께 새 Decision Log 행으로 추가한다.
+- 구현 중 범위가 달라지면 코드 변경 전에 PRD와 `plan-task.md`를 먼저 갱신한다.
+- 완료된 요구사항의 회귀나 위반은 [코드 리뷰 및 QA 기록 규칙](./review.md)에 따라 review 문서에 기록하고, 확정된 문제만 회귀 수정 Task/Goal로 전환한다.
+
+## 6. 계획 작성 전 자체 검토
+
+`plan-task.md`를 만들기 전에 다음을 확인한다.
+
+- 목표, Non-Goal과 포함·제외 범위가 충돌하지 않는다.
+- 사용자·권한·핵심 흐름과 라우팅 경계가 명확하다.
+- 모든 요구사항 ID가 고유하고 상태·수용 기준을 가진다.
+- 미결·외부 의존·제외 항목에 다음 행동과 담당 주체가 있다.
+- API endpoint와 payload 규칙이 `api-contract.md`로 추적된다.
+- 기능·UX·보안·성능 성공 기준이 자동 또는 수동 검증 가능한 표현이다.
+- placeholder, 근거 없는 최대값과 추정 계약이 없다.

docs/agent-guide/review.md

@@ -0,0 +1,50 @@
+# 코드 리뷰 및 QA 기록 규칙
+
+## 1. 적용 시점
+
+- 사용자가 코드 리뷰, QA, 완료된 Phase 검증 또는 요구사항 충족 감사를 요청하면 이 문서를 따른다.
+- 리뷰 요청은 기본적으로 읽기·진단 범위다. 사용자가 수정을 함께 요청하지 않았다면 코드, test, 설정과 구현 계획을 변경하지 않는다.
+- 리뷰 결과를 재현하고 판정하는 데 필요한 test·typecheck·lint·build·E2E 같은 비파괴 검증은 실행할 수 있다.
+
+## 2. 기준 문서와 템플릿
+
+- 리뷰 전에 대상 기능 디렉터리의 `prd.md`, `api-contract.md`, `plan-task.md`와 관련 구현·test를 읽는다.
+- 리뷰 문서는 대상 `prd.md`와 같은 디렉터리에 만든다.
+- [코드 리뷰 보고서 샘플](../sample/sample-review.md)을 원본 템플릿으로 사용하고, section·필드·상태 의미를 임의로 축소하지 않는다.
+- 실제 리뷰 문서 파일명은 범위가 드러나게 작성한다. 예: `review-phase-0-1.md`, `review-auth.md`.
+
+## 3. 리뷰 수행 원칙
+
+- 요구사항과 계약 위반, 버그, 보안·데이터 위험, 회귀, test 누락을 우선 찾는다. 요약이나 칭찬보다 발견 사항을 먼저 보고한다.
+- 모든 발견 후보에는 고유 ID, 심각도, 상태, 관련 요구사항·계약, 소유 Task, 코드/test/문서 근거와 재현 또는 검증 절차를 기록한다.
+- 심각도는 `Blocker`, `High`, `Medium`, `Low`만 사용한다.
+- 상태는 `후보`, `확정`, `오탐`, `보류`, `수정 완료`만 사용한다.
+- 실행하지 않은 명령을 실행한 것처럼 기록하지 않는다. 실제 명령, exit code, test 수, 실패 내용 또는 실행 불가 사유를 남긴다.
+- endpoint, DTO, 오류 status/message key, validation 상한처럼 제공되지 않은 계약을 추정하지 않는다. 외부 계약이 필요한 항목은 `보류`로 판정하고 담당 주체와 재개 조건을 기록한다.
+- 발견 사항이 없더라도 “확정 발견 사항 없음”을 명시하고 검토 범위와 실행 증거를 남긴다.
+
+## 4. 판정과 후속 처리
+
+- 발견 후보는 재현 또는 문서·코드 근거 확인 후 `확정`, `오탐`, `보류` 중 하나로 판정한다.
+- `오탐`과 `보류` 기록도 삭제하지 않는다. 후속 정정은 기존 내용을 덮어쓰지 않고 판정 기록에 날짜와 사유를 추가한다.
+- 확정 발견 사항만 구현 전에 `plan-task.md`의 신규 회귀 수정 Task로 옮긴다. 기존 완료 체크박스와 검증 기록은 되돌리거나 삭제하지 않는다.
+- 신규 회귀 수정 Task에는 review ID, goal ID, 시작 조건, 완료 증거, 범위 밖, 실패 재현 test, 관련 Phase Gate와 검증 기록 항목을 포함한다.
+- 확정 항목의 수정은 review 작업과 분리된 goal로 수행한다. focused test와 관련 Phase Gate, `plan-task.md` 검증 기록이 끝나기 전에는 goal을 완료 처리하지 않는다.
+- 수정 후 review 문서의 상태를 `수정 완료`로 바꾸고 실제 검증 명령과 결과를 “수정 후 검증 기록”에 누적한다.
+
+## 5. 리뷰 종료 조건
+
+다음을 모두 만족해야 리뷰를 종료한다.
+
+- 검토 범위와 제외 범위가 문서에 명시돼 있다.
+- 모든 후보가 `확정`, `오탐`, `보류`, `수정 완료` 중 하나로 판정돼 있다.
+- 확정 항목은 `plan-task.md` 회귀 수정 Task로 전환됐거나, 사용자가 수정하지 않기로 한 결정이 기록돼 있다.
+- 보류 항목에는 담당 주체와 재개 조건이 있다.
+- 실행한 자동·수동 검증과 결과 또는 불가 사유가 기록돼 있다.
+- 최종 결론과 남은 항목이 명시돼 있다.
+
+## 6. 사용자 결과 보고
+
+- 발견 사항이 있으면 심각도 순으로 review ID, 핵심 근거, 영향과 후속 조치를 먼저 전달한다.
+- 발견 사항이 없으면 검토 범위, 실행한 검증과 남은 위험 또는 검증하지 못한 범위를 함께 전달한다.
+- 확정 문제를 아직 수정하지 않았다면 완료·해결됐다고 표현하지 않는다.