# Goal 실행형 구현 계획 샘플

> 이 문서는 goal 기능으로 구현 계획을 실행하기 위한 템플릿이다. 실제 `plan-task.md`를 만들 때 `<...>` placeholder를 모두 구체적인 값으로 교체한다. Phase는 결과와 의존성을 묶고, `create_goal`에는 Task 또는 Phase Gate 하나만 등록한다.

| 문서 항목 | 내용 |
|---|---|
| 상태 | 계획 작성 중 / 구현 중 / 외부 조건 대기 / 구현 완료 |
| 작성일 | `YYYY-MM-DD` |
| 요구사항 기준 | `<대상 prd.md 경로>` |
| API 기준 | `<대상 api-contract.md 경로>` |
| 현재 Phase | `<Phase 번호와 이름>` |
| 현재 활성 Goal | `<없음 또는 Goal ID>` |

## 목표

`<사용자가 얻는 최종 결과를 한 문장으로 작성한다. 구현 수단보다 완결된 사용자 흐름을 먼저 쓴다.>`

## 현재 상태

| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 대기 / 진행 중 / 완료 / 제외 | `0/N` | `P1-T1` | `<없음 또는 조건>` |
| 2 | 대기 / 진행 중 / 완료 / 제외 | `0/N` | `P2-T1` | `<없음 또는 조건>` |

- 동시에 하나의 미완료 goal만 운용한다.
- 완료된 Task와 검증 기록은 되돌리거나 삭제하지 않는다. 후속 수정은 회귀 수정 Task와 새 goal ID를 추가한다.
- 사용자가 명시적으로 요청하지 않으면 goal에 token budget을 설정하지 않는다.

## 범위

### 포함

- `<구현할 사용자 흐름>`
- `<구현할 route/API/UI 범위>`
- `<필수 오류·반응형·접근성·test 범위>`

### 제외

- `<이번 릴리스에서 만들지 않을 기능>`
- `<외부 시스템 또는 다음 Phase 소유 범위>`
- `<복원, hard delete처럼 명시적으로 금지한 기능>`

## 기술적 제약

- 기술 스택: `<언어, framework, 주요 library와 version 기준>`
- 아키텍처: `<상태·API·UI·파일 책임 경계>`
- 데이터·보안: `<저장 위치, 인증, 민감정보 비기록 규칙>`
- 호환성: `<지원 browser, viewport, runtime>`
- 의존성: 실제 소비 Task에서 필요한 최소 dependency만 추가한다.
- 계약: 제공되지 않은 endpoint, DTO, enum, 오류 status/key와 validation 상한을 추정하지 않는다.
- backend 구현 전 UI 확인이 필요하면 제공 계약 기반 explicit mock mode를 사용하고 실제 404 자동 fallback·production mock을 금지하며 mock/server 완료 증거를 분리한다.
- 구현: 모든 구현 Task는 아래 `RED → GREEN → REFACTOR` 순서를 체크박스에 명시하고, 가장 작은 실패 test에서 시작해 최소 구현으로 통과시킨다.
- 검증: focused test에서 시작해 영향받는 package/feature 회귀로 확장한다. 전체 회귀는 공통 경계 변경, 여러 domain/phase 변경,
  release/final Gate에서 전체 상태 증거를 별도로 요구하는 경우, targeted test만으로 영향 범위를 판단할 수 없는 실패 또는 사용자
  명시 요청이 있을 때만 실행한다.
- 전체 회귀를 생략하면 생략 사실·근거와 대신 실행한 focused/영향 범위 회귀 명령을 Progress에 기록한다.

## Task TDD 작성 규칙

구현 Task의 실행 체크박스는 아래 순서와 표제어를 그대로 사용한다. 각 단계에는 대상 test, 실행 명령과 관찰할 실패·성공 결과를
구체적으로 적고, `RED` 확인 없이 production 구현을 시작하거나 `GREEN` 확인 없이 `REFACTOR`로 넘어가지 않는다.

- [ ] **RED:** 가장 작은 실패 test를 작성한다.
- [ ] **RED 확인:** focused test를 실행해 요구 동작이 없어서 발생한 의도한 assertion 실패를 확인한다.
- [ ] **GREEN:** RED를 통과시키는 최소 구현을 작성한다.
- [ ] **GREEN 확인:** 같은 focused test를 다시 실행해 성공을 확인한다.
- [ ] **REFACTOR:** 새 동작을 바꾸지 않는 범위에서 이번 Task가 만든 중복만 정리하고, focused test·직접 영향 회귀·lint를 다시 실행해 실제 결과를 Progress에 기록한다.

test 작성이 현실적으로 불가능한 read-only 리뷰·문서·외부 확인 Task는 TDD 단계를 형식적으로 만들지 않는다. 대신 Task 본문에
`TDD 예외 사유`와 실행 명령·대조표·수동 확인을 포함한 `대체 검증 방법`을 명시한다.

## Phase 1

**Phase 결과:** `<이 Phase가 끝나면 사용자가 완료할 수 있는 흐름>`

**선행조건:** `<없음 또는 선행 Goal/Gate ID>`

**Phase 완료 조건:** `P1-T1`~`P1-TN`과 `P1-GATE` 완료, 검증 기록 누적.

### 구현 항목

#### Task 1.1 `<독립적으로 검토 가능한 결과>`

**Goal 실행 `P1-T1`:** `<이 Task가 만드는 결과를 한 문장으로 작성한다.>`

- **시작 조건:** `<선행 Goal, 요구사항 ID, API Contract section>`
- **완료 증거:** `<체크박스 전체, focused test, 산출물, 문서 기록>`
- **범위 밖:** `<다음 Task 또는 다른 Phase가 소유하는 항목>`

**Files:**

- Create: `<정확한 파일 경로>`
- Modify: `<정확한 파일 경로>`
- Test: `<정확한 test 파일 경로>`

**Interfaces:**

- Consumes: `<선행 Task가 제공하는 type/function/component contract>`
- Produces: `<후속 Task가 사용할 정확한 type/function/component contract>`

- [ ] **RED:** `<요구 동작>`을 재현하는 가장 작은 실패 test를 작성한다.
- [ ] **RED 확인:** `<focused test 명령>`을 실행해 `<요구 동작 미구현 때문에 발생할 assertion 실패>`를 확인한다.
- [ ] **GREEN:** RED를 통과시키는 최소 구현을 작성한다.
- [ ] **GREEN 확인:** `<focused test 명령>`을 다시 실행해 성공을 확인한다.
- [ ] **REFACTOR:** 이번 Task가 만든 중복만 정리하고 focused test·직접 영향 회귀·typecheck·lint 결과를 Progress에 기록한다.

#### Task 1.2 `<두 번째 독립 결과>`

**Goal 실행 `P1-T2`:** `<이 Task가 만드는 결과를 한 문장으로 작성한다.>`

- **시작 조건:** `P1-T1` 완료와 `<필요한 계약>`.
- **완료 증거:** `<체크박스 전체, test와 문서 기록>`
- **범위 밖:** `<이 Task에서 다루지 않는 항목>`

**Files:**

- Create: `<정확한 파일 경로>`
- Modify: `<정확한 파일 경로>`
- Test: `<정확한 test 파일 경로>`

**Interfaces:**

- Consumes: `<P1-T1이 제공한 정확한 contract>`
- Produces: `<Phase 2 또는 Gate가 사용할 정확한 contract>`

- [ ] **RED:** `<두 번째 요구 동작>`의 실패 test를 작성한다.
- [ ] **RED 확인:** `<focused test 명령>`으로 의도한 assertion 실패를 확인한다.
- [ ] **GREEN:** 최소 구현으로 focused test를 통과시킨다.
- [ ] **GREEN 확인:** 오류·loading·empty·success와 접근성 상태를 포함한 focused test 성공을 확인한다.
- [ ] **REFACTOR:** 이번 Task가 만든 중복만 정리하고 관련 test·typecheck·lint 결과를 Progress에 기록한다.

### 완료 조건

- [ ] `P1-T1`, `P1-T2`의 체크박스와 완료 증거가 모두 충족됐다.
- [ ] Phase 1의 확정 요구사항이 구현·명시적 제외·후속 결정 중 하나로 추적된다.
- [ ] 알려진 문서와 구현의 차이가 없다.

### 검증 방법

#### Phase 1 Gate

**Goal 실행 `P1-GATE`:** Phase 1의 사용자 흐름과 공통 품질 기준을 최종 판정한다.

- **시작 조건:** Phase 1의 모든 활성 Task goal 완료.
- **완료 증거:** 아래 자동·수동 검증 통과와 Progress 기록.
- **범위 밖:** Gate 통과를 위한 test 삭제·완화와 관련 없는 기능 수정.

```bash
<focused unit/integration test 명령>
<Phase 전용 E2E 명령>
<typecheck 명령>
<lint 명령>
<build 명령>
```

**Expected:** `<0 exit code, test 수, 사용자가 완료할 흐름, 금지 요청 0회 등 관찰 가능한 결과>`

수동 검증:

- [ ] `<viewport와 사용자 흐름>`
- [ ] `<keyboard·focus·zoom·접근성 검사>`
- [ ] `<민감정보·network request 검증>`

## Phase 2

**Phase 결과:** `<Phase 1 결과를 소비해 완성하는 다음 사용자 흐름>`

**선행조건:** `P1-GATE` 또는 `<Phase 1의 부분 contract Goal ID>` 완료.

**Phase 완료 조건:** `P2-T1`~`P2-TN`과 `P2-GATE` 완료, 검증 기록 누적.

### 구현 항목

#### Task 2.1 계약·상태 확인

**Goal 실행 `P2-T1`:** Phase 2 구현에 필요한 계약, 상태/action inventory와 component/file map을 확정한다.

- **시작 조건:** `<선행 Goal>` 완료, 관련 PRD/API Contract 확인.
- **완료 증거:** 계약 제공 또는 제외 결정이 기준 문서에 일치하고 구현 map이 기록됨.
- **범위 밖:** 계약을 추정한 production adapter와 실제 기능 구현.
- **TDD 예외 사유:** production 동작을 변경하지 않는 read-only 계약·상태 확인 Task다.
- **대체 검증 방법:** PRD/API Contract/현재 구현의 field·상태·파일 대조표와 누락·결정 기록을 작성하고 문서 검증 명령 결과를 Progress에 남긴다.

- [ ] 필요한 endpoint·DTO·오류·pagination 계약을 확인한다.
- [ ] loading·empty·error·success·read-only·viewport 상태와 action을 inventory한다.
- [ ] 계약이 없으면 담당 주체·영향·재개 조건과 제외/후속 결정을 문서화한다.
- [ ] Page·feature·shared component와 test file 책임을 확정한다.

#### Task 2.2 `<Phase 2의 독립 구현 결과>`

**Goal 실행 `P2-T2`:** `<사용자가 직접 확인할 수 있는 흐름을 한 문장으로 작성한다.>`

- **시작 조건:** `P2-T1` 완료.
- **완료 증거:** `<contract/UI/E2E test와 문서 기록>`
- **범위 밖:** `<다음 Task 또는 후속 Phase>`

**Files:**

- Create: `<정확한 파일 경로>`
- Modify: `<정확한 파일 경로>`
- Test: `<정확한 test 파일 경로>`

- [ ] **RED:** contract·serializer와 사용자 action의 가장 작은 실패 test를 작성한다.
- [ ] **RED 확인:** `<focused test 명령>`을 실행해 각 요구 동작이 없어 발생한 assertion 실패를 확인한다.
- [ ] **GREEN:** RED를 통과시키는 최소 구현을 작성한다.
- [ ] **GREEN 확인:** 같은 focused test를 다시 실행해 contract와 사용자 흐름의 성공을 확인한다.
- [ ] **REFACTOR:** 이번 Task가 만든 중복만 정리하고 관련 integration/E2E·공통 품질 명령의 실제 결과와 남은 항목을 Progress에 기록한다.

### 완료 조건

- [ ] `P2-T1`, `P2-T2`의 체크박스와 완료 증거가 모두 충족됐다.
- [ ] 외부 의존은 제공 계약 구현 또는 명시적 제외/후속 결정으로 종결됐다.
- [ ] Phase 2의 사용자 흐름과 오류·반응형·접근성 상태가 검증됐다.

### 검증 방법

#### Phase 2 Gate

**Goal 실행 `P2-GATE`:** Phase 2의 contract, 사용자 흐름과 회귀 방지를 최종 판정한다.

- **시작 조건:** Phase 2의 모든 활성 Task goal 완료.
- **완료 증거:** 아래 명령과 Expected 통과, Progress에 실제 결과 누적.
- **범위 밖:** 실패와 무관한 다음 Phase 구현.

```bash
<Phase 2 focused test 명령>
<Phase 2 E2E 명령>
<typecheck·lint·build 명령>
```

**Expected:** `<사용자 journey, 오류 처리, request payload와 금지 동작을 포함한 최종 결과>`

## 실행 순서와 의존성

| 순서 | Goal | 선행조건 | 병행 가능 | 차단 시 다음 행동 |
|---:|---|---|---|---|
| 1 | `P1-T1` | 없음 | 아니요 | 근거 문서 보정 |
| 2 | `P1-T2` | `P1-T1` | 아니요 | 독립 검증 계속 |
| 3 | `P1-GATE` | Phase 1 Task 전체 | 아니요 | 실패 소유 Task의 회귀 수정 goal 생성 |
| 4 | `P2-T1` | `P1-GATE` | 아니요 | 외부 계약 담당·재개 조건 기록 |
| 5 | `P2-T2` | `P2-T1` | `<예/아니요>` | 독립 범위만 계속 수행 |
| 6 | `P2-GATE` | Phase 2 Task 전체 | 아니요 | 실패 소유 Task로 되돌림 |

```text
P1-T1 → P1-T2 → P1-GATE → P2-T1 → P2-T2 → P2-GATE
```

## 변경 금지 항목

- 확정된 요구사항·API Contract를 근거 없이 변경하지 않는다.
- 기존 완료 체크박스와 Progress·Decision Log·검증 기록을 삭제하거나 덮어쓰지 않는다.
- 제공되지 않은 endpoint·DTO·enum·오류 값과 validation 상한을 만들지 않는다.
- 요청 범위 밖의 리팩터링, dependency 추가와 공통 abstraction을 확장하지 않는다.
- test를 삭제·skip·완화하거나 타입 오류를 우회해 Gate를 통과시키지 않는다.
- JWT, password, signed URL, 파일 본문 같은 민감정보를 log·fixture·문서에 기록하지 않는다.

## 의사결정 및 중단 규칙

- PRD와 API Contract가 충돌하면 프로젝트가 정한 우선순위에 따라 결정하고 Decision Log에 근거를 남긴다.
- 구현 범위가 바뀌면 `plan-task.md` 체크박스와 범위를 먼저 갱신한 뒤 코드를 수정한다.
- 안전한 최소 기본값이 문서에 있으면 그 값만 구현한다. 안전하게 구현할 수 없으면 추정하지 않는다.
- 계약 미제공 기능을 제외할 때는 PRD 결정 기록 → API Contract → 이 계획 순서로 갱신한다.
- 같은 차단 사유가 최초 시도와 자동 후속을 포함해 3회 연속 반복되고, 문서화나 독립 작업도 불가능할 때만 goal을 `blocked`로 갱신한다.
- 체크박스 일부, test 일부 또는 코드 작성만 끝난 상태에서는 goal을 `complete`로 갱신하지 않는다.
- 완료 증거와 Progress 기록까지 충족한 뒤에만 goal을 `complete`로 갱신한다.

## Progress

기존 기록을 삭제하거나 덮어쓰지 않고 실제 실행 결과를 차수별로 누적한다.

### `<Goal ID>` N차 실행 — YYYY-MM-DD

- 상태: 진행 중 / 완료 / 차단 감사 중 / 차단
- 무엇을: `<이번 실행에서 완료한 체크박스와 산출물>`
- 왜: `<Task objective와 요구사항 근거>`
- 어떻게:
  - `<실행 명령>` — `<성공/실패, exit code, test 수와 핵심 결과>`
  - `<수동 검증>` — `<성공/실패/불가 사유>`
- 남은 항목: `<체크박스, 외부 조건 또는 없음>`
- 다음 행동: `<같은 goal에서 이어서 할 가장 작은 단계>`

## Decision Log

| 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 |
|---|---|---|---|---|---|
| `YYYY-MM-DD` | `DEC-001` | 제안 / 확정 / 정정 | `<결정 내용>` | `<요구사항, 계약, 검증 근거>` | `<Goal ID와 문서>` |

- 기존 결정을 정정할 때 원문을 지우지 않고 새 `정정` 행을 추가한다.
- 외부 의존 제외, 새로운 dependency, 범위 변경, 안전한 기본값 선택은 반드시 기록한다.

## 발견된 문제

| ID | 심각도 | 상태 | 발견 내용 | 영향 Goal | 처리 계획 |
|---|---|---|---|---|---|
| `ISSUE-001` | Blocker / High / Medium / Low | 후보 / 확정 / 보류 / 해결 | `<관찰 사실>` | `<Goal ID>` | `<수정 Task, 외부 담당 또는 없음>` |

- 구현 중 발견한 범위 내 문제는 근거와 재현 방법을 기록하고 해당 Task에서 처리한다.
- 완료된 범위의 회귀는 기존 Task를 다시 열지 않고 별도 회귀 수정 Task와 goal을 만든다.
- 범위 밖 문제는 임의로 수정하지 않고 사용자에게 보고하거나 후속 Task로 결정한다.
- 상세 코드 리뷰 결과가 필요하면 `docs/sample/sample-review.md` 형식으로
  `docs/[날짜]_구현할내용한글/reviews/[리뷰범위]-review.md`에 별도 문서를 만든다.

## 최종 보고 형식

```markdown
구현 결과: <완료한 Phase와 사용자 흐름>

- 변경: <주요 파일과 동작>
- 결정: <중요한 Decision Log ID와 내용>
- 검증:
  - `<실행 명령>` — <성공/실패와 핵심 수치>
  - `<수동 검증>` — <성공/실패/불가 사유>
- 남은 항목: <외부 의존, 후속 범위 또는 없음>
- 문서: <갱신한 PRD/API Contract/plan/review 링크>
```

최종 보고는 성공을 추정하지 않는다. 실제 실행한 최신 검증 결과와 완료되지 않은 범위를 함께 전달한다.