81 lines
5.5 KiB
Markdown
81 lines
5.5 KiB
Markdown
# 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에서 일치한다.
|
|
- 외부 의존과 안전한 기본값이 구분돼 있다.
|
|
- backend 구현 전 UI preview가 필요하면 제공 계약 기반 explicit mock mode와 실제 server integration을 별도 Task·Gate·Progress로 구분하고 404 자동 fallback을 금지한다.
|
|
- 실제 검증 명령과 Expected가 구체적이다.
|
|
- placeholder, 미정 값, 추정 계약이 없다.
|
|
- 변경 금지 항목과 중단 규칙이 명시돼 있다.
|