Draft Plan

Draft Plan 스킬

GitHub 이슈 또는 자연어 주제를 기반으로 논의·QA 자료를 준비한 뒤, 현재 하네스의 Plan Mode에서 PRD 포맷 계획서를 적용하는 스킬이다.

Plan Mode 애드온이다 — 대체가 아니다. 계획 모드 진입·이탈 도구가 제공되면 그 흐름을 그대로 쓰고, 최종 계획 작성 단계에서만 이 스킬의 PRD 템플릿을 적용한다. 도구가 없는 하네스에서는 references/plan-mode-fallback.md가 승인과 인계를 보완한다.

핵심 원칙:

• 기본은 세션을 분리하지 않는다. 다만 하네스의 계획 승인 자체가 새 컨텍스트로 인계하는 방식이면 그 규칙을 존중하고 완결 계획서 파일을 인계 매체로 쓴다.
• 계획 파일은 Plan Mode가 지정한 경로에 먼저 작성한다. 계획서는 구현 세부만이 아니라 논의·판단 근거·결정 컨텍스트를 담으므로, 프로젝트 지침 파일이 명시하는 계획 저장 관례가 있으면 완결된 계획서를 그 위치에도 저장하는 걸 기본으로 한다(승인 후 또는 보류 시 — Step 2·5 참고). 그런 관례가 없는 프로젝트는 새로 만들지 않고 기존대로 Plan Mode 위치에만 둔다. 하네스가 계획 파일 위치를 주지 않으면 references/plan-mode-fallback.md의 저장 사다리를 따른다.
• 계획서는 실행자가 아니라 의사결정자가 읽는다. 사람은 방향성·설계·리뷰 위주로 계획서를 다루고, 실행 세부(어떤 파일을 어떤 순서로 건드릴지 등)는 구현 단계에서 그때그때 정해진다. 그래서 계획서는 문제 배경 → 목표/비목표 → 요구사항 → 트레이드오프 → 성공 지표를 파악해 승인·수정 판단을 내리는 데 필요한 정보만 담고, 실행 순서표·진행 추적 장치는 담지 않는다. (현재 하네스의 상시 로드 지침에 같은 원칙이 있으면 함께 따른다.)
• 기본 골격은 5개 절이다 — 배경/문제 정의 / 목표(Goals) / 비목표(Non-Goals) / 요구사항 / 성공 지표·검증 방법 / 리스크·오픈 이슈. 번호를 붙여 읽는 순서와 절 순서를 맞춘다 (Step 3 참고).
• 설계 판단은 주제별로 묶어 결정 | 이유 표로 낸다. 나열식 문단으로 이어 쓰면 갈림길이 몇 개인지, 어디까지가 한 판단인지 안 보인다.
• 코드 전문·프롬프트 전문·완성된 diff·파일별 작업 순서표는 넣지 않는다. 그런 디테일은 실행 단계에서 실제로 나오고 PR 리뷰 때 diff로 논의한다. 계획서에 다 담으면 방향이 디테일에 묻힌다. 이 배제 대상은 완성된 코드 본문·내부 호출 순서·file:line 참조이지, 공개 인터페이스 자체가 아니다 — 새로 만들거나 바꾸는 public API(함수/클래스 시그니처, CLI 옵션 등) 는 그 인터페이스가 왜 필요한지 설명하는 ## 3. 요구사항의 결정 문장 안에 자연스럽게 녹여 보여준다. 별도 "핵심 인터페이스" 같은 절로 따로 빼지 않는다 — 의도적으로 분리해 강조하면 오히려 결정의 흐름이 끊긴다.
• 구조·흐름이 복잡한 계획은 시각 자료를 적극 활용한다. 아키텍처 관계, 여러 갈래로 나뉘는 흐름, 기존 방식과의 비교처럼 표·문장만으로는 한눈에 안 잡히는 내용이 있으면, 현재 세션에 다이어그램/시각화 도구가 제공될 때 이를 활용해 대화 응답에 순서도·구조도를 보여준다. 다이어그램은 계획 파일이 아니라 대화 응답에 둔다 — 계획 파일은 다이어그램을 텍스트로 담기 어려운 매체이므로, 파일에는 판단·근거를 남기고 시각 자료로 이해를 보완한다.
• 계획서 자체가 길고 표가 많아 md로는 훑기 어려우면, 최종 저장 형식을 md 대신 HTML로 바꾸는 것도 고려한다 — 사본을 병행하지 않는다. 계획은 논의 중 자주 수정되므로, md와 HTML 두 형식을 동시에 유지하면 고칠 때마다 양쪽을 맞춰야 해서 사본을 두는 이득보다 손해가 크다. Plan Mode가 지정하는 임시 작업 파일은 하네스 관례대로 md로 그대로 두되, 프로젝트 지침 파일이 명시하는 계획 저장 관례에 최종본을 남길 때는 md 또는 HTML 중 하나만 골라 그 형식으로만 이어서 갱신한다. 프로젝트에 이미 정해진 형식이 있으면 그걸 따르고, 없으면 계획의 복잡도를 보고 사용자에게 물어 하나로 정한다.
• 계획이 실험으로만 판정 가능한 미검증 기술 전제(외부 SDK·플랫폼·비동기 동작 등) 위에 서 있으면, 본 작업 전에 그 전제를 버리는 최소 코드로 찌르는 선행 검증 게이트를 계획에 포함한다 (검증 코드는 커밋하지 않는다). 사용자에게 묻거나 문서로 풀리는 불확실성은 대상이 아니다 — 그건 조사·QA로 푼다. (Step 3의 ## 기술 리스크 / 선행 검증 참고)

실행 절차

Step 1: 입력 파싱

인자 형태에 따라 다르게 처리한다.

이슈 번호 (#35, 35, gh-35):

gh issue view <number> --json number,title,body,labels,url

가져온 number, title, body, labels, url 을 이후 분석 컨텍스트로 보유한다.

GitHub URL (https://github.com/.../issues/35): owner/repo/number를 파싱해 위와 동일하게 gh issue view 로 조회한다.

자연어 주제 (예: "로그인 화면 개선"): 그대로 주제 문자열로 사용하고 이슈 메타데이터는 없는 것으로 처리한다.

인자 없음: 사용자에게 무엇에 대한 계획서인지 묻는다.

기존 계획 파일 경로 (@path/to/plan.md 등 이미 작성된 계획서): 파일을 Read로 읽은 뒤 아래 항목을 점검하고, 누락된 항목을 사용자에게 알린 다음 보강 여부를 확인한다.

• 기본 골격 5개 절(배경/문제 정의 / 목표 / 비목표 / 요구사항 / 성공 지표·검증 방법 / 리스크·오픈 이슈)이 있는지
• ## 1. 배경 / 문제 정의에 문제·목표가 박혀 있는지 (목표 없는 계획서는 "왜 하는지" 합의 없이 작업만 나열한 것)
• 설계 판단이 나열식 문단이 아니라 주제별 결정 | 이유 표로 정리돼 있는지
• 리스크·오픈 이슈가 있는지 — 가장 자주 빠진다. 없으면 승인 시점에 트레이드오프를 판단할 수 없다
• 코드 전문·프롬프트 전문·파일별 작업 순서표가 통째로 박혀 있지 않은지 (있으면 덜어내고 구현 단계로 미룬다)
• ## 코드 리뷰 섹션 존재 여부 (/simplify + 위험 지적만 수정 + 커스텀 리뷰 조건부/명시) 보강이 필요하면 Step 2로 진입하고, 이미 완비되어 있으면 그대로 논의를 이어간다.

Step 2: 계획 모드 진입 + 탐색·논의

아직 Plan Mode가 아니고 EnterPlanMode 도구가 제공되면 이 시점에 즉시 호출한다. 이후 하네스가 제공하는 탐색·설계·검토 절차를 그대로 따른다. 서브에이전트 활용 등 하네스 지시가 이 스킬의 절차보다 우선한다.

EnterPlanMode가 제공되지 않으면 진입한 척하거나 이 단계를 생략하지 말고, 현재 SKILL.md 디렉터리의 references/plan-mode-fallback.md를 읽어 조사·파일 저장·승인 절차를 적용한다.

탐색·논의 중 이 스킬이 더하는 것:

• 사용자 질문에 답하고, 방향을 함께 결정한다.
• 이슈 본문에서 언급한 파일·심볼이 실제 코드에 없으면 즉시 피드백한다.
• 외부 근거가 필요하면 웹 검색을 적극 사용한다. 코드베이스·로컬 지식만으로 판단이 서지 않는 경우(라이브러리·프레임워크의 정확한 동작·API 스펙·버전별 변경, 표준/스펙, 에러 메시지의 의미, 베스트 프랙티스 등)에 현재 제공된 웹 검색 도구로 찾고 페이지 읽기 도구로 원문을 확인한다. 단, 출처(URL)를 반드시 남긴다 — 계획서에서 그 근거에 기댄 주장·결정 옆에 인라인으로 출처를 달거나 ## 참고 자료에 모은다. 출처 없는 외부 주장은 계획서에 쓰지 않는다.
• 불명확한 부분은 구조화 질문 도구가 있으면 사용한다. 없으면 추천안을 첫 번째에 둔 번호 목록으로 대화에서 확인한다. 임의 결정하지 않는다.
• 구현 방식에 갈림길이 있으면 한 가지로 단정하지 말고, 선택을 가르는 기준을 세운 뒤 그에 따른 방안을 장단점과 함께 제시해 사용자가 고르게 한다 (추천안을 첫 번째로). 방안 개수는 고정하지 않는다 — 실질적 대안이 없으면 "대안 없음"을 밝힌다.
• 최상위 기술 리스크를 식별한다. 이 계획이 기대는 전제 중 '코드/플랫폼에서 실제로 굴려봐야만 성공·실패를 알 수 있는' 불확실성이 있는지 본다. 있으면 Step 3의 ## 기술 리스크 / 선행 검증으로 분리하고, 본 작업에 들어가기 전 통과해야 할 게이트로 둔다.

외부 블로커로 막히면 부분 저장한다:

• 가장 근본적인 결정 사안이 우리 손 밖의 의존성(백엔드 팀 확인, 외부 응답 대기 등)으로 막혀 논의를 더 진행할 수 없으면, 그때까지 모은 조사·검증 결과(코드 발췌·가정 검증·발견한 사실)를 잃지 말고 Plan Mode의 plan 파일에 초안(status: 보류)으로 먼저 적어둔다.
• 미해결 사안은 ## 1. 배경 / 문제 정의 아래 범위 표에 ⬜로 남기고, 무엇을 기다리는지·왜 막혔는지를 그 옆에 적는다.
• 왜: 근본 사안에서 조기에 이탈하면 그때까지의 양질의 조사가 휘발된다. 부분 기록이 그 재작업을 막는다.
• 이 경우 계획 승인 관문은 아직 열지 않는다 — 승인받을 완결된 계획이 없기 때문이다.
• 프로젝트에 계획 저장 관례가 있으면, 이 보류 기록은 진행 목록이 아니라 그 프로젝트의 보류·아카이브 관례로 바로 저장한다 — 착수 전 보류라 진행 중 목록에 올릴 실체가 없기 때문이다.

이슈가 있는 경우: 이슈 본문의 "문제 / 작업 범위 / 완료 기준" 섹션을 계획서 골격으로 활용한다. 이슈의 "완료 기준"은 ## 4. 성공 지표 / 검증 방법의 1차 재료로 쓴다.

Step 3: 계획서 본문 작성

탐색·논의가 정리되면 아래 골격으로 계획서 본문을 채워 Plan Mode의 plan 파일에 그대로 Write한다. 하네스가 대화의 계획 형식을 더 짧게 제한하면 대화에는 압축 요약을 내되, 5절 완결본은 references/plan-mode-fallback.md가 정한 파일에 보존한다.

# <한 줄 제목>

---

## 1. 배경 / 문제 정의

### 문제
- 지금 무엇이 문제인가. 배경지식 없는 독자도 잡을 수 있게.
- 대조가 필요하면 표를 쓴다 (예: 현재 방식 vs 대안의 강점·약점)

### 컨텍스트
- 이슈: #<n> / <url> (있으면) · 브랜치: `feat/...`
- 확정된 전제가 있으면 표로 못박는다 — 여기 있는 항목은 재논의 대상이 아니다.

| 결정 | 내용 |
|---|---|
| <결정 이름> | <무엇으로 정했는지> |

## 2. 목표 (Goals) / 비목표 (Non-Goals)

### 목표
- 이 작업이 궁극적으로 달성하려는 것. "왜 하는가"의 종착점을 1~2문장 또는 목록으로.

### 비목표
- 이번 작업이 명시적으로 다루지 않는 범위. 없으면 "없음"으로 명시.

## 3. 요구사항

설계·기능 요구사항을 **주제별로 묶어** 각각 `결정 | 이유` 표로 낸다. 주제가 하나뿐이면 소절 없이 표 하나로.
왼쪽 열만 훑어도 무엇을 정했는지 보이고, 오른쪽 열이 그 근거다. 파일별 작업 순서·구현 순서는
여기 담지 않는다 — 그건 구현 단계에서 정해진다. 결정을 이해하는 데 필요한 **공개 인터페이스**
(새로 만들거나 바꾸는 함수/클래스 시그니처, CLI 옵션 등)가 있으면 `결정` 또는 `이유` 칸 안에
그대로 적는다 — 별도 절로 빼지 않고 그 결정을 설명하는 문장의 일부로 자연스럽게 넣는다.

### 3-1. <주제 — 예: 구조 / 무엇을 어디에 두는가>

| 결정 | 이유 |
|---|---|
| <구체적 결정> | <왜 그렇게 정했는지 — 대안 대비 무엇이 나은지> |

### 3-2. <주제 — 예: 신뢰성 / 무엇을 믿는가>

| 결정 | 이유 |
|---|---|

> 초안에서 철회한 판단이 있으면 `### 초안에서 철회한 것`으로 짧게 남긴다 — 왜 그 길로 안 갔는지가 다음 사람의 재발명을 막는다.

**제약사항** — 무엇을 할 수 없는지. 승인 시점에 트레이드오프를 판단하려면 이게 있어야 한다.
항목이 많으면 성격별로 소제목을 단다(비용·의존 / 신뢰 한계 / 입력 한계 / 운영 등).

- **<제약 이름>** — 무엇이 제약이고 그래서 어떻게 되는지

## 4. 성공 지표 / 검증 방법

작업이 끝나면 무엇을 관찰하게 되는지, 그게 무슨 뜻인지.

| 예상되는 관찰 | 그때의 해석 |
|---|---|
| <이런 결과가 나올 것> | <나오면 무슨 뜻인지 — 실패로 읽힐 결과가 실은 유효한 결과인 경우 명시> |

**최소 성공 기준**: <무엇이 되면 이 작업이 성공인가 한 줄>

| 검증 항목 | 무엇을 지키는가 |
|---|---|
| <검증할 것> | <이게 깨지면 무엇이 무너지는지> |

- **테스트 실효성 확인**: 회귀 테스트·구조 가드를 새로 쓰면, 잡으려는 결함을 일부러 주입해 실제로 실패하는지 확인하고 원복한다(원복 후 `git diff`가 비었는지 확인).
- **실제 실행 확인**: 코드를 돌려 눈으로 확인할 것. 무엇을 어떻게 띄워서 무엇을 보는지 구체적으로.

## 5. 리스크 / 오픈 이슈

### 알려진 한계 (고치지 않고 기록)
- **<한계>** — 왜 그대로 두는지. 코드에 주석으로 남길 것이면 그것도 명시.

### 미해결 사안
- <아직 결정되지 않았거나 사용자 확인이 필요한 것 — 없으면 "없음">

### 의도적으로 미루는 것
<지금 안 하는 것들을 한 줄로 나열 — 나중에 "왜 이건 없지"를 막는다>

## 코드 리뷰
모든 작업·커밋을 마친 뒤, 같은 세션에서 최종 게이트로 수행한다.
- [ ] `/simplify` 실행 — 변경 코드를 재사용·단순화·효율 관점에서 정리하고 수정 적용 (품질 전용, 버그는 잡지 않음)
- [ ] 프로젝트에 커스텀 코드 리뷰 스킬이 있으면 함께 실행 (탐지되면 스킬명 명시)
- [ ] 지적사항 중 **위험한 것만** 수정 — 정확성 버그·보안·데이터 손상·크래시 유발 등. 단순 정리·스타일은 앞서 `/simplify`가 처리했으므로 중복 반영하지 않는다

조건부 절 — 해당할 때만 추가한다

## 기술 리스크 / 선행 검증은 계획이 실험으로만 판정 가능한 미검증 전제(외부 SDK·플랫폼·비동기 동작 등) 위에 설 때만 ## 3. 요구사항 뒤에 끼워 넣는다. 사용자에게 묻거나 문서로 풀리는 불확실성은 대상이 아니다 — 그건 조사·QA로 푼다.

## 기술 리스크 / 선행 검증
- **검증할 질문**: 가장 불확실한 전제 1~2개 (예: "외부 SDK 콜백이 우리 플러그인→JS까지 실제로 돌아오는가")
- **검증 방법**: 본 구현이 아닌 **버리는 최소 코드**로 그 한 점만 찌른다 — 무엇을 어디까지 만들지 명시
- **통과 기준**: 무엇을 관찰하면 "성립"인가. ⚠️ **통과 신호가 검증 대상 경로를 실제로 거쳤는지**까지 조건에 박는다 — 검증하려던 비동기·앱스위치 경로를 안 타고 즉시 떨어진 신호를 통과로 오판하지 않도록
- **실패 시 대안**: 막히면 어느 방안으로 트나
- **타임박스**: 검증에 쓸 상한. 그 안에 통과 신호를 못 보면 실패로 간주한다
- **검증 뒤 처리**: 검증 코드는 커밋하지 않는다(본 구현과 설계가 달라 남기면 짐이 된다). 배운 것만 계획에 반영하고 본 구현에 들어간다
- **착수를 다시 판단한다**: 한 점만 찔렀는데 본 구현이 낼 결과의 상당 부분이 이미 나왔으면, 본 구현으로 **새로 얻는 것이 얼마나 남는지** 보고 얇으면 범위를 줄이거나 접는다. 게이트 통과는 "기술적으로 된다"는 뜻이지 "만들 값어치가 있다"는 뜻이 아니다

계획서 작성 원칙 — 가독성이 목적이다

계획서를 읽는 사람은 실행자가 아니라 의사결정자다. 사람은 방향성·설계·리뷰 위주로 이 문서를 다룬다 — 계획서만 보고 문제 배경 → 목표/비목표 → 요구사항 → 트레이드오프 → 성공 지표를 파악해 "이대로 가도 되는가"를 판단할 수 있어야 한다. 아래 규칙은 전부 그 목적에서 나온다.

계획서 작성 원칙 — 실행 디테일은 담지 않는다

이전 버전은 파일별 작업 순서표·추적 매트릭스·진행 현황·변경 로그를 계획서에 담아 "리빙 문서"로 운영했다. 하지만 사람이 계획서에서 보고 싶은 건 방향성·설계·리뷰지 구현 순서가 아니고, 실행 순서는 구현을 시작하는 시점의 코드 상태에 따라 자연스럽게 정해진다. 그래서:

• 파일별 작업 순서표를 만들지 않는다. 무엇을 구현해야 하는지는 ## 3. 요구사항에 담고, 어떤 파일을 어떤 순서로 건드릴지는 구현 단계(같은 세션)에서 정한다.
• 진행 추적 장치(매트릭스·진행 현황·변경 로그)를 만들지 않는다. 컨텍스트 압축 대비가 필요한 여러 세션짜리 큰 작업이면, 하네스의 작업 추적 도구(Task 목록 등)나 커밋 자체를 진행 기록으로 쓴다. 계획서는 목표값만 유지하는 정적 문서로 남긴다.
• 커밋은 각각 컴파일 가능 상태를 유지하고, 커밋 메시지 작성은 프로젝트 커밋 스킬을 쓴다 — 현재 하네스가 읽는 프로젝트·전역 지침이 명시하면 그걸 따르고, 없으면 범용 development:commit. 특정 저장소 전용 커밋 스킬을 다른 프로젝트에 있다고 가정하지 않는다.
• 새 의존성이 필요하면 ## 3. 요구사항에서 밝힌다(버전 고정 규칙 영향 포함).

계획서 작성 원칙 — 배경 조사는 요약이지 재현이 아니다

탐색 단계는 이미 같은 세션 안에서 이뤄졌으므로, 코드를 통째로 옮겨 적는 건 중복 작업이다. 탐색 결과는 별도 절로 빼지 말고 ## 1. 배경 / 문제 정의와 ## 3. 요구사항의 이유 칸에 녹인다 — 근거는 그 근거가 뒷받침하는 결정 옆에 있을 때 가장 잘 읽힌다. 대신:

1. 결론을 뒷받침하는 핵심 근거만 남긴다 — 전체 코드 재현이 아니라, 이 계획이 왜 이 방향인지 판단하는 데 필요한 한두 가지 사실.
2. 조사 비용이 컸던 발견은 반드시 기록한다 — 실기기·외부 API·데이터 파일을 직접 열어보고서야 알게 된 사실처럼, 다시 조사하면 시간이 크게 드는 것들. 컨텍스트가 압축되면 이런 조사 결과부터 사라지므로, 계획서가 유일한 기록이 될 수 있다.
3. 재사용할 기존 패턴이 있으면 무엇을 재사용하는지만 짧게 언급한다.

코드 리뷰 섹션 작성 — 커스텀 스킬 탐지 (하이브리드)

## 코드 리뷰는 모든 작업·커밋을 끝낸 뒤 같은 세션에서 실행할 마지막 단계다. 이 스킬은 리뷰를 직접 실행하지 않고, 아래 항목을 계획서에 적기만 한다.

0. 단순화 먼저 — /simplify

   - [ ] `/simplify` 실행 — 변경 코드를 재사용·단순화·효율·altitude 관점에서 정리하고 수정 적용
   

   /simplify 는 버그를 찾지 않고 코드 품질만 다듬는다(재사용·단순화·효율 cleanup을 working tree 에 적용). 버그 검출은 아래 커스텀 리뷰 스킬(있다면)이 맡는다. 단순화를 먼저 돌려 군더더기를 걷어낸 뒤 리뷰하면, 리뷰가 본질적 위험에 집중된다.

   빌트인 /code-review는 체크리스트에 넣지 않는다. 일부 모델·환경에서 다른 스킬을 이어 부르는 기능으로 호출할 수 없는 문제가 반복 확인됐고, 그때마다 사용자에게 직접 실행을 요청하거나 생략을 확인해야 해서 체크리스트 항목으로서 신뢰할 수 없다. 아래 1번(커스텀 리뷰 스킬)로 대체한다.

1. 커스텀 — "있다면" 조건부 현재 세션에서 사용 가능한 스킬 목록을 살펴, 프로젝트·팀 전용 코드 리뷰 스킬(예: review-code)이 있는지 확인한다. 불확실하면 .agents/skills/·.claude/skills/와 설치된 플러그인을 grep으로 추가 확인한다.

   • 탐지 성공 → 스킬 이름을 그대로 명시한다.

     - [ ] `/review-code` 실행 후 함께 검토
     

   • 탐지 실패/불확실 → 조건부 문구를 남겨 구현 세션이 판단하게 한다.

     - [ ] 프로젝트에 커스텀 코드 리뷰 스킬이 있으면 함께 실행
     

2. 수정 범위 — 위험한 지적만

   - [ ] 지적사항 중 위험한 것만 수정 — 정확성 버그·보안·데이터 손상·크래시 유발 등. 단순 정리·스타일·효율 제안은 반영하지 않거나 별도 이슈로 분리한다
   

   --fix 는 모든 지적을 무차별로 working tree 에 적용하므로 쓰지 않는다. 위험한 지적만 골라 손으로 반영해야 의도치 않은 리팩터링 churn 을 막는다.

Step 4: 브랜치명 결정

계획서 본문 작성 중 또는 직후, 이 작업을 위한 브랜치명을 결정하여 계획서에 포함한다.

브랜치명 생성 규칙 (프로젝트의 브랜치 명명 규칙 준수):

• slug: 영문 소문자 + 하이픈, 40자 이하, 한글은 영문 키워드 추출
• 이슈 레이블에 fix, bug, hotfix 가 있으면 fix/ 접두사 사용
• 프로젝트에 Jira 이슈 키(DEV-123)가 있다면 feat/DEV-123-<slug> 형식 우선

결정된 브랜치명을 계획서 ## 1. 배경 / 문제 정의 > 컨텍스트에 위 Step 3 골격대로 명시한다.

Step 5: 승인 → 구현 또는 인계

Step 3의 골격으로 채운 계획 본문을 Plan Mode가 지정한 plan 파일에 그대로 Write한다 (저장 위치는 하네스가 이미 정해줬으므로 별도 경로 결정이 필요 없다).

저장 전 자체 점검 (Write 직전 한 번 확인):

• 훑기 테스트: 절 제목과 표의 왼쪽 열만 읽어도 "무슨 문제를 어떻게 풀려는지"가 잡히는가. 안 잡히면 구조가 아니라 서술에 정보가 숨어 있는 것이므로, 분량을 줄이지 말고 숨은 정보를 절·표로 끌어올린다 (줄여야 할 것은 실행 단계에서 어차피 나올 디테일이지 판단 근거가 아니다)
• ## 1. 배경 / 문제 정의에 문제와 목표가 박혀 있는가
• 설계 판단이 주제별 결정 | 이유 표로 묶여 있는가 (나열식 문단 아님)
• ## 2. 비목표와 ## 5. 리스크 / 오픈 이슈가 채워져 있는가 — 가장 자주 빠진다
• 코드 전문·프롬프트 전문·파일별 작업 순서표가 박혀 있지 않은가 (단, 결정에 필요한 공개 인터페이스 언급까지 함께 지우지는 않았는가 — 지웠다면 ## 3. 요구사항의 해당 결정 문장에 다시 인라인으로 넣는다)
• 구조·흐름이 복잡한데 시각 자료 없이 표·문장만으로 설명하고 있지 않은가 (다이어그램/시각화 도구가 있으면 대화 응답에서 활용했는가)
• 계획서 분량·표가 많아 훑기 테스트를 통과하기 어려우면, 최종 저장 형식을 md 대신 HTML로 바꿀지 사용자에게 확인했는가 (병행 사본 금지 — md/HTML 중 하나만 골라 그것만 갱신)
• 웹 검색으로 가져온 외부 주장에 출처(URL)가 달려 있는가

점검을 마쳤고 ExitPlanMode 도구가 제공되면 즉시 호출해 사용자 승인을 받는다. 승인되면 같은 세션에서 곧바로 구현으로 들어간다.

ExitPlanMode가 제공되지 않으면 references/plan-mode-fallback.md의 승인 관문을 따른다. 같은 컨텍스트에서 계속할 수 있으면 승인 뒤 구현하고, 계획 모드 종료가 새 컨텍스트로 인계되는 하네스면 계획 파일 경로와 인계 문구를 남기고 멈춘다. /clear 같은 특정 하네스 명령을 임의로 안내하지 않는다.

승인 직후, 프로젝트에 계획 저장 관례가 있으면 같은 내용을 그 위치에도 저장한다 — Plan Mode 파일은 하네스 스크래치 공간이라 세션이 끝나면 찾기 어렵고, 계획서에 담긴 논의·결정 근거는 나중에 다시 참조할 가치가 있다. 그런 관례가 없는 프로젝트는 Plan Mode 위치에만 둔다.

주의사항

• Plan Mode를 대체하지 않는다. 진입·이탈 도구가 있으면 그 흐름 위에서 계획서 포맷만 담당한다. 도구가 없으면 fallback 문서로 같은 승인 관문과 파일 인계를 만든다.
• 가독성이 목적이다. 계획서는 의사결정자가 읽는다 — 계획서만 보고 문제 배경·목표/비목표·요구사항·트레이드오프·성공 지표를 파악해 승인 판단을 내릴 수 있어야 한다. 번호 절 + 주제별 결정 | 이유 표를 쓰고, 코드 전문·프롬프트 전문·파일별 작업 순서표는 넣지 않는다.
• 배제 대상은 완성된 코드·내부 구현이지 공개 인터페이스가 아니다. 새로 만들거나 바꾸는 함수/클래스 시그니처·CLI 옵션 등은 해당 결정을 설명하는 문장 안에 자연스럽게 넣는다 — 별도 절로 분리하지도, 아예 지우지도 않는다.
• 구조·흐름이 복잡하면 시각 자료를 적극 활용한다. 다이어그램/시각화 도구가 제공되면 아키텍처·분기·비교 같은 내용을 대화 응답에서 시각적으로 보여준다. 계획 파일에는 판단·근거만 남긴다.
• 계획서가 md로 훑기 어려울 만큼 길거나 표가 많으면 md 대신 HTML로 형식을 바꾸는 것도 고려한다 — 사본을 병행하지 않는다. 계획은 자주 수정되므로 두 형식을 같이 유지하면 수정 부담이 배가된다. Plan Mode 임시 작업 파일은 md로 두되, 프로젝트 계획 저장 관례에 남기는 최종본은 md/HTML 중 하나만 선택해 그것만 갱신한다.
• 비목표와 리스크/오픈 이슈를 빠뜨리지 않는다. 가장 자주 누락되는 둘이고, 없으면 승인 시점에 트레이드오프를 판단할 수 없다.
• 목표를 명시한다. 목표 없는 계획서는 "왜 하는지" 합의 없이 작업만 나열한 것이다.
• 실행 디테일(파일별 작업 순서표·진행 추적 장치)은 계획서에 담지 않는다. 사람은 계획서를 방향성·설계·리뷰 위주로 다루고, 실행 순서는 구현을 시작하는 시점에 자연스럽게 정해진다.
• 이슈 본문에 모호한 부분이 있으면 임의 결정하지 않고 반드시 사용자에게 확인한다.
• 코드베이스 분석 중 이슈 내용과 괴리(없는 파일·심볼 등)가 발견되면 즉시 피드백한다.
• 외부 근거가 필요하면 현재 제공된 웹 검색·페이지 읽기 도구를 적극 쓰되, 그 근거에 기댄 주장 옆에 출처(URL)를 반드시 남긴다. 출처 없는 외부 주장은 쓰지 않는다.
• 브랜치명은 프로젝트의 브랜치 명명 규칙을 따른다.
• 커밋 메시지 작성은 프로젝트에 명시된 커밋 스킬을 쓰고, 없으면 development:commit을 쓴다. 특정 저장소 전용 커밋 스킬을 다른 프로젝트에도 있다고 가정하지 않는다.
• 계획서에 ## 코드 리뷰 섹션을 넣어 "모든 작업·커밋 완료 후 /simplify(및 커스텀 리뷰 스킬)를 실행"하도록 지시만 적는다. 실제 실행은 구현 단계(같은 세션)에서 한다.
• 계획 파일은 Plan Mode가 지정한 위치에 먼저 두되, 프로젝트에 계획 저장 관례가 있으면 승인 후(또는 보류 시) 그 위치에도 저장한다(Step 2·5 참고). Plan Mode가 경로를 주지 않으면 fallback 문서의 저장 사다리를 따른다.