Draft plan

Draft Plan 스킬

GitHub 이슈 또는 자연어 주제를 기반으로 논의·QA 자료를 준비한 뒤, Claude Code 내장 Plan Mode(EnterPlanMode)에서 상세한 리빙 문서 계획서 포맷을 적용하는 스킬이다.

Plan Mode 애드온이다 — 대체가 아니다. 이전 버전은 계획과 구현을 세션 단위로 분리했다(계획서를 private/에 저장하고 /clear 후 새 세션에서 구현 시작). 하지만 실제로는 세션 분리가 거의 일어나지 않고, 이슈 → 작은 PR로 바로 이어가는 워크플로우에선 한 세션에서 몰아서 진행하는 쪽이 더 직관적이다. 그래서 지금은 EnterPlanMode로 들어가 하네스가 제공하는 탐색 → 설계 → 검토 흐름을 그대로 쓰고, 최종 계획 작성 단계(Phase 4)에서만 이 스킬의 상세 템플릿을 적용한다. ExitPlanMode 승인을 받으면 같은 세션에서 곧바로 구현으로 넘어간다.

핵심 원칙:

• 세션을 분리하지 않는다. /clear나 "구현은 다음 세션에서" 안내를 하지 않는다.
• 계획 파일은 Plan Mode가 하네스에서 지정한 경로(~/.claude/plans/<name>.md)에 그대로 작성한다. 별도로 프로젝트 private/에 복사해 저장하지 않는다 — "나중에 검색할 수도 있으니" 같은 가정성 니즈로 미리 대비하지 않는다. 실제로 그 니즈가 커지면 그때 별도로 다룬다.
• 모든 계획서는 목표 → 추적 매트릭스 → 진행 현황 → 변경·결정 로그의 리빙 문서 구조를 갖춘다. 목표·달성기준·성공기준·검증의 네 구분은 유지하되, 달성기준·성공기준·검증은 별도 섹션으로 반복 나열하지 않고 하나의 추적 매트릭스 표의 열로 묶는다 (Step 3 참고).
• 리빙 문서로 만든다. 계획(목표값)과 진행 현황(실측값)을 갈라, 계획 본문엔 목표값만 두고 변동 값(진행도·개수·버전)은 진행 현황/로그 한 곳에만 둔다(단일 출처). 무엇이 언제 왜 바뀌었는지는 ## 변경·결정 로그에 누적한다. 이 구조는 세션 분리가 아니라 긴 단일 세션이 컨텍스트 압축(compaction)을 겪어도 상태를 잃지 않기 위한 것이라, 구현 중에도 체크포인트(커밋 단위 등)마다 갱신한다.
• 계획이 실험으로만 판정 가능한 미검증 기술 전제(외부 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로 읽은 뒤 아래 항목을 점검하고, 누락된 항목을 사용자에게 알린 다음 보강 여부를 확인한다.

• ## 목표 + ## 추적 매트릭스(달성기준·성공기준·검증·현황 열) 존재 여부
• 매트릭스의 각 행이 달성기준↔성공기준↔검증으로 이어지는지(빈 칸=끊긴 고리), 성공 기준 칸과 검증 칸이 섞이지 않았는지 (성공 기준=무엇이 참이어야 하나 / 검증=어떻게 확인하나), 검증 칸에 자동/수동이 구분돼 있는지
• ## 진행 현황 + ## 변경·결정 로그 스캐폴드 존재 여부 (없으면 리빙 문서 구조가 아님)
• ## 커밋 계획 섹션 존재 여부
• ## 코드 리뷰 섹션 존재 여부 (/simplify + 위험 지적만 수정 + 커스텀 리뷰 조건부/명시 + hunk-pr-review 조건부 제안) 보강이 필요하면 Step 2로 진입하고, 이미 완비되어 있으면 그대로 논의를 이어간다.

---

Step 2: EnterPlanMode 진입 + 탐색·논의

아직 Plan Mode가 아니면 이 시점에 EnterPlanMode를 호출한다. 이후 하네스가 제공하는 Phase 1(탐색)·Phase 2(설계)·Phase 3(검토) 절차를 그대로 따른다 — Explore/Plan 서브에이전트 활용 등 하네스 지시가 이 스킬의 절차보다 우선한다.

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

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

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

• 가장 근본적인 결정 사안이 우리 손 밖의 의존성(백엔드 팀 확인, 외부 응답 대기 등)으로 막혀 논의를 더 진행할 수 없으면, 그때까지 모은 조사·검증 결과(코드 발췌·가정 검증·발견한 사실)를 잃지 말고 Plan Mode의 plan 파일에 초안(status: 보류)으로 먼저 적어둔다.
• 미해결 사안은 ## 결정 사항 / 미해결 질문에 ⬜로, 무엇을 기다리는지는 ## 변경·결정 로그에 '보류'로 남긴다.
• 왜: 근본 사안에서 조기에 이탈하면 그때까지의 양질의 조사가 휘발된다. 부분 기록이 그 재작업을 막는다.
• 이 경우 ExitPlanMode는 아직 호출하지 않는다 — 승인받을 완결된 계획이 없기 때문이다.

이슈가 있는 경우: 이슈 본문의 "문제 / 작업 범위 / 완료 기준" 섹션을 계획서 골격으로 활용한다. 특히 이슈의 "완료 기준"은 추적 매트릭스 달성 기준 열의 1차 재료로 쓴다.

---

Step 3: 계획서 본문 작성 (Plan Mode Phase 4)

탐색·논의가 정리되면, 하네스의 Phase 4("최종 계획 작성")에서 아래 골격으로 계획서 본문을 채워 Plan Mode의 plan 파일에 그대로 Write한다. 골격은 가이드이므로 상황에 맞게 섹션을 추가·생략한다. 구조는 계획(목표값) → --- → 진행 현황·로그(변동값) 두 묶음으로 가른다.

# <한 줄 제목>

> 📌 **요약** — 1~2문장, 배경지식 없는 독자도 무엇을 하는 작업인지 잡을 수 있게.

## Context
- 이슈: #<n> / <url> (있으면)
- 브랜치: `feat/...`
  ```bash
  git checkout -b feat/...

• 변경의 이유 / 배경

목표

• 이 작업이 궁극적으로 달성하려는 것 1~2문장. "왜 하는가"의 종착점. (예: "신규 앱이 Play 스토어 심사를 통과해 배포 가능한 상태가 된다")

추적 매트릭스

달성 기준(무엇이 참이어야) ↔ 성공 기준(구현이 무엇을 만족) ↔ 검증(어떻게 확인) ↔ 현황을 한 행으로 묶는다. 셋을 따로 나열하지 않고 한 표로 — 같은 항목을 세 번 다시 쓰는 중복이 사라지고, 행 단위로 보면 끊긴 고리(매핑 안 된 성공 기준, 확인 방법 없는 기준)가 즉시 드러난다.

#	달성 기준 (무엇이 참이어야)	성공 기준 (구현이 무엇을 만족)	검증 (어떻게 확인 · 자동/수동)	현황
1	구체·측정 가능한 결과 조건 (예: "첫 업로드가 거부 없이 심사 큐에 등록")	그를 충족할 구현 조건 (예: "업로드 API가 신규 앱 첫 요청에 200 반환")	자동: 명령/테스트 · 수동: 실기기·눈 (예: "스테이징에 첫 AAB 업로드 후 응답코드 확인")	⬜
2	...	...	...	⬜

작성 규칙: 달성 기준은 추상 표현("개선된다", "안정화된다") 금지 — 수치·상태·관찰 가능한 사실로. 성공 기준은 무엇이 참이어야 하는가(도달 상태)이고 검증은 어떻게 확인하는가(방법)다 — 옆 칸으로 분리돼 섞일 일이 없다. 자동화 가능한 검증은 자동으로 분류, 수동은 실기기·시각 확인이 꼭 필요한 것만. 생성 시점엔 **현황 열을 전부 ⬜**로 둔다(구현 전). 구현이 진행되며 ✅/🔶로 갱신한다.

현황 분석 (핵심 발견만)

• Phase 1~2 탐색 단계에서 이미 코드를 다 읽었으므로 전체 재현이 아니라 결론을 뒷받침하는 핵심 발견만 짧게 남긴다 — 특히 조사 비용이 컸던 사실(예: 이미지·데이터 직접 검증, 외부 API 동작 확인)은 잃지 않도록 반드시 기록한다.
• 재사용 후보 (기존 함수·유틸)가 있으면 간단히 언급

결정 사항 / 미해결 질문

• 사용자와 합의된 선택 (✅)
• 대안 비교: 구현 방식에 갈림길이 있으면 방안을 표(방안 / 장점 / 단점 / 영향)로 비교하고, 선택한 안과 근거를 남긴다
• TBD 항목 (⬜로 명시)

여기서 확정된 결정(✅)은 맨 끝 ## 변경·결정 로그에 한 줄씩 시드한다.

기술 리스크 / 선행 검증 (해당 시에만)

계획이 실험으로만 판정 가능한 미검증 전제 위에 설 때만 둔다. 그런 전제가 없으면 이 섹션을 생략한다.

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

구현 계획

1. ...
2. ...

영향 범위

• 변경 파일 목록
• 잠재 리스크

예상 결과 (산출물 미리보기) (해당 시 권장)

결정·구현이 실물로 어떻게 떨어지는지 미리 보여, 구현 전에 눈으로 확인·판단하게 한다. 산출물이 파일·구조·정형 출력을 갖는 작업(스킬·도구·리포트·API·화면 등)에 권장하고, 미리보기가 얇은 작업(소규모 리팩터·조사)에선 생략한다. 채운 값은 대표 예시임을 밝힌다(실측 아님).

• 산출물 구조 — 만들어질 파일/폴더 트리. 신규·변경·삭제, 커밋 대상 vs 로컬/무시(gitignore)를 구분
• 산출물 형식 예시 — 리포트·API 응답·설정·화면 목업 등 대표 출력의 실제 형태(코드블록·표·ASCII)
• 기대효과 — as-is → 이후 (무엇이 좋아지나)
• 리스크(산출물·운영 관점) — 산출물이 낳는 운영 리스크. 구현·정확성 리스크는 ## 영향 범위로 크로스레퍼런스해 중복 회피

커밋 계획

• 커밋 단위별로 나열 (각 커밋은 컴파일 가능 상태 유지)
• 위 ## 기술 리스크 / 선행 검증이 있으면 그 검증은 커밋에 넣지 않는다 — 검증 코드는 버리고, 결과로 계획을 고친 뒤 본 작업 첫 커밋부터 시작한다. 커밋 계획은 선행 검증 통과를 전제로 쓴다
• 실제 커밋 메시지 작성은 프로젝트 커밋 스킬을 쓴다 — 전역 ~/.claude/CLAUDE.md나 이 프로젝트 CLAUDE.md가 커밋 스킬을 명시하면 그걸 따르고, 없으면 범용 common:commit을 쓴다. 특정 환경 전용 스킬(syai-commit, plugin-commit 등)을 다른 프로젝트에 있다고 가정하지 않는다

코드 리뷰

모든 작업·커밋을 마친 뒤, 같은 세션에서 최종 게이트로 코드 품질 정리와 리뷰를 수행한다.

• /simplify 실행 — 변경 코드를 재사용·단순화·효율·altitude 관점에서 정리하고 수정을 적용한다 (품질 전용, 버그는 잡지 않음)
• 프로젝트에 커스텀 코드 리뷰 스킬이 있으면 함께 실행 (탐지되면 스킬명 명시)
• 지적사항 중 위험한 것만 수정 — 정확성 버그·보안·데이터 손상·크래시 유발 등. 단순 정리·스타일·효율은 앞서 /simplify가 처리했으므로 중복 반영하지 않는다
• 위 리뷰 과정에서 사용자의 결정·확인이 필요한 지점(트레이드오프, 애매한 판단, 위험 감수 여부)이 남았다면 그 지점에 코멘트를 남기고 hunk-pr-review로 diff 동반 검토를 제안한다 — 그런 지점이 없으면 제안하지 않고 바로 PR로 넘어간다

---

진행 현황 (컨텍스트 압축 대비 — 생성 시 빈 스캐폴드)

구현 시작 전이라 비어 있다. 이 세션이 길어져 컨텍스트가 압축되더라도 이 섹션만 보면 재개할 수 있도록, 구현 중 체크포인트(커밋 단위 등)마다 이 섹션과 위 추적 매트릭스 '현황' 열을 갱신한다. 단일 출처 규칙: 변동 값(진행도·개수·버전·실측)은 여기와 아래 로그에만 둔다. 위 계획 본문은 목표값만 유지한다 — 같은 수치를 두 곳에 적으면 갱신 시 어긋난다.

• 진행 요약: 구현 전 — 없음
• 빌드 순서 — 계획 대비 실제: (구현 시작 후 ✅/🔶/⬜로 채움)
• 주요 발견(데이터): 없음
• 계획에 없던 추가: 없음
• 남은 일: 계획 전체 (아직 미착수)

변경·결정 로그 (이력 — 최신 위로, append-only)

계획·현황을 최신값으로 덮어쓸 때, 무엇이 언제 왜 바뀌었는지는 여기에만 쌓는다. 생성 시점 결정들로 시드한다.

날짜	종류	내용	영향
<오늘>	결정	(결정 사항에서 시드한 핵심 결정)	<섹션/기준 N>
<오늘>	생성	계획 수립	—

종류 enum: 결정 / 범위조정 / 순서조정 / 보정 / 추가 / 보류 / 생성

**계획서 작성 원칙 — 추적 매트릭스 (목표·달성기준·성공기준·검증)**

이 네 가지는 서로 다른 질문에 답한다. 한 덩어리로 뭉치면 "무엇을 위해 하는지"도, "됐는지 어떻게 아는지"도 흐려진다. 그래서 구분은 유지하되, **달성기준·성공기준·검증 셋은 별도 섹션으로 반복 나열하지 않고 한 표(추적 매트릭스)의 열로 묶는다.** 같은 항목을 세 번 다시 쓰는 중복이 사라지고, 행 단위로 보면 끊긴 고리가 즉시 드러난다. 목표만 1~2문장으로 매트릭스 위에 따로 둔다 — 방향은 표로 적기엔 너무 짧고 추상적이기 때문이다.

| 구분 | 답하는 질문 | 위치 |
|------|-------------|------|
| **목표** | 왜 하는가 / 무엇을 이루려는가 | `## 목표` (1~2문장, 추상적이어도 됨) |
| **달성 기준** | 목표가 "달성됐다"를 어떻게 판별하는가 | 매트릭스 `달성 기준` 열 (구체·측정 가능) |
| **성공 기준** | 그 달성 기준을 충족시키려면 구현이 무엇을 만족해야 하는가 | 매트릭스 `성공 기준` 열 |
| **검증** | 위 조건들이 실제로 충족됐는지 어떻게 확인하는가 | 매트릭스 `검증` 열 (자동·수동) |

핵심 규칙:

1. **목표는 반드시 명시한다.** 목표 없는 계획서는 "왜 하는지" 합의 없이 작업만 나열한 것이다. 이슈가 있으면 이슈의 목적을, 없으면 사용자와의 논의에서 목표를 끌어내 한 줄로 박는다.
2. **달성 기준은 구체적이어야 한다.** "개선된다"가 아니라 "X가 Y 상태가 된다", "Z 수치가 N 이하가 된다"처럼 관찰·측정 가능해야 한다. 모호하면 충족 여부를 누구도 판정할 수 없다.
3. **성공 기준은 검증이 아니다.** 가장 흔한 실수다. 성공 기준은 *무엇이 참이어야 하는가*(도달 상태)이고, 검증은 *그것을 어떻게 확인하는가*(방법)다. 매트릭스에서 둘은 옆 칸으로 분리돼 한 칸에 섞일 일이 없다.
4. **한 행이 곧 고리다.** 같은 행의 달성 기준 ↔ 성공 기준 ↔ 검증이 이어진다. 빈 칸이 있으면 — 충족할 구현이 없는 달성 기준, 확인 방법 없는 성공 기준 — 그 자리에서 끊긴 고리로 드러난다.

**계획서 작성 원칙 — 리빙 문서 (계획 / 진행 현황 / 로그)**

계획서는 한 번 쓰고 끝이 아니라 구현이 진행되며 갱신되는 **리빙 문서**다. 진행 상황이 계획 본문에 덕지덕지 덧붙으면(예: "원랜 N개였는데 지금 M개", 본문과 모순되는 수치) 문서가 중구난방이 된다. 그래서 처음부터 세 묶음으로 가른다:

- **계획**(목표·매트릭스·결정·구현계획 등) — 항상 *목표값*만. 잘 안 바뀐다.
- **진행 현황** — 지금 어디까지 됐나. *실측값*만. 구현하며 갱신한다.
- **변경·결정 로그** — 무엇이 언제 왜 바뀌었나. append-only, 최신 위로.

생성 시점엔 진행 현황은 빈 스캐폴드(매트릭스 현황 열 전부 ⬜), 로그는 생성 결정으로 시드한다. **변동 값(진행도·개수·버전)은 현황/로그 한 곳에만** 둔다(단일 출처) — 계획 본문과 현황에 같은 수치가 따로 적히면 갱신할 때 어긋난다. 이 구조 덕에 이 세션이 길어지다 컨텍스트가 압축되더라도, 진행 현황이 들어갈 **지정된 자리**가 있어 재개가 쉽다.

**계획서 작성 원칙 — 예상 결과 미리보기 (해당 시 권장)**

산출물이 파일·구조·정형 출력을 갖는 작업(스킬·도구·리포트·API·화면 등)은, 결정·구현이 실물로 어떻게 떨어지는지 **미리보기**로 보이면 구현 전에 눈으로 방향을 확정하기 쉽다. 폴더 트리·출력 형식 예시·기대효과·리스크를 담되:

- **권장이지 필수가 아니다.** 미리보기가 얇은 작업(소규모 리팩터·단순 조사)에선 생략한다 — `## 기술 리스크 / 선행 검증`과 같은 "해당 시" 섹션이다.
- **예시임을 밝힌다.** 채운 수치·값은 대표 예시이지 실측이 아니다("값은 run-X 기준 예시" 식). 미리보기를 확정 결과로 오독하지 않게 한다.
- **리스크는 산출물·운영 관점만.** 구현·정확성 리스크는 `## 영향 범위`에 두고 크로스레퍼런스해 중복을 피한다.

**계획서 작성 원칙 — 현황 분석은 요약이지 재현이 아니다**

Phase 1~2 탐색은 이미 같은 세션 안에서 이뤄졌으므로, `## 현황 분석`에 코드를 통째로
옮겨 적는 건 중복 작업이다. 대신:

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

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

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

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

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

빌트인 /code-review는 체크리스트에 넣지 않는다. 일부 모델·환경에서 Skill 도구로 호출되지 않는 문제("cannot be used with Skill tool due to disable-model-invocation")가 반복 확인됐고, 그때마다 사용자에게 직접 터미널 실행을 요청하거나 생략을 확인해야 해서 체크리스트 항목으로서 신뢰할 수 없다. 아래 1번(커스텀 리뷰 스킬)과 hunk-pr-review(조건부)로 대체한다.

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

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

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

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

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

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

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

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

3. hunk-pr-review — 조건부, 코멘트 달 지점이 있을 때만

   - [ ] 위 리뷰 과정에서 사용자의 결정·확인이 필요한 지점이 남았다면 `hunk-pr-review`로 diff 동반 검토를 제안한다 — 없으면 생략
   

   매번 무조건 제안하지 않는다. 판단 기준은 "구현자(Claude)가 그 diff에 코멘트를 달고 싶은 지점이 있는가"다 — 코멘트를 달고 싶다는 것 자체가 트레이드오프·애매한 판단·위험 감수처럼 사용자 확인이 필요한 사안이 남았다는 신호이기 때문이다. /simplify·커스텀 리뷰가 커스텀 리뷰가 전부 깨끗하게 끝나 코멘트할 지점이 없으면 hunk-pr-review를 건너뛰고 바로 PR 스킬로 넘어간다.

---

Step 4: 브랜치명 결정

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

브랜치명 생성 규칙 (git-convention 스킬 컨벤션 준수):

상황	형식	예시
이슈 있음 + 레이블 fix/bug	fix/<number>-<title-slug>	fix/35-measure-screen-back-press
이슈 있음 + 그 외 레이블	feat/<number>-<title-slug>	feat/36-ecg-offline-queue
자연어 주제	feat/<topic-slug>	feat/login-screen-improvement

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

결정된 브랜치명을 계획서 Context 섹션에 위 Step 3 골격대로 명시한다.

---

Step 5: ExitPlanMode 승인 → 같은 세션에서 구현

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

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

• ## 목표가 한 줄 이상 박혀 있는가
• ## 추적 매트릭스의 달성 기준이 구체적·측정 가능한가(추상 표현 아님), 각 행이 달성 기준 ↔ 성공 기준 ↔ 검증으로 이어지는가(빈 칸 없음), 성공 기준 칸과 검증 칸이 섞이지 않았는가, 현황 열이 생성 시 전부 ⬜인가
• ## 진행 현황(빈 스캐폴드) + ## 변경·결정 로그(생성 결정 시드)가 들어 있는가
• 웹 검색으로 가져온 외부 주장에 출처(URL)가 달려 있는가

점검을 마쳤으면 ExitPlanMode를 호출해 사용자 승인을 받는다. 승인되면 같은 세션에서 곧바로 구현으로 들어간다 — 세션을 끊거나 /clear하지 않는다.

구현 중에는 커밋 단위 등 자연스러운 체크포인트마다 ## 진행 현황과 추적 매트릭스 '현황' 열을 갱신한다. 무엇이 왜 바뀌었는지는 ## 변경·결정 로그에 append한다 — 이 갱신이 컨텍스트 압축 이후 재개를 가능하게 하는 핵심이다.

---

주의사항

• Plan Mode를 대체하지 않는다. EnterPlanMode/ExitPlanMode 흐름 위에서 계획서 포맷만 담당한다. 세션 분리·/clear 안내를 하지 않는다.
• 목표를 명시한다. 목표·추적 매트릭스(달성기준·성공기준·검증)가 없는 계획서는 쓰지 않는다. 매트릭스에서 성공 기준 열과 검증 열은 별도 칸이다 — 섞지 않는다.
• 리빙 문서 구조를 포함한다. 생성 시 진행 현황은 빈 스캐폴드(매트릭스 현황 열 ⬜), 변경·결정 로그는 생성 시점 결정으로 시드한다. 변동 값은 진행 현황/로그 한 곳에만 둔다(단일 출처). 구현 중 체크포인트마다 갱신한다 — 컨텍스트 압축 대비가 이 구조의 존재 이유다.
• 이슈 본문에 모호한 부분이 있으면 임의 결정하지 않고 반드시 사용자에게 확인한다.
• 코드베이스 분석 중 이슈 내용과 괴리(없는 파일·심볼 등)가 발견되면 즉시 피드백한다.
• 외부 근거가 필요하면 WebSearch/WebFetch를 적극 쓰되, 그 근거에 기댄 주장 옆에 출처(URL)를 반드시 남긴다. 출처 없는 외부 주장은 쓰지 않는다.
• 브랜치명은 git-convention 스킬 컨벤션을 따른다.
• 커밋 메시지 작성은 프로젝트에 명시된 커밋 스킬을 쓰고, 없으면 common:commit을 쓴다. 특정 환경 전용 스킬(syai-commit, plugin-commit 등)을 다른 프로젝트에도 있다고 가정하지 않는다.
• 계획서 끝에 ## 코드 리뷰 섹션을 넣어 "모든 작업·커밋 완료 후 /simplify(및 커스텀 리뷰 스킬)를 실행"하도록 지시만 적는다. 실제 실행은 구현 단계(같은 세션)에서 한다.
• 계획 파일은 Plan Mode 기본 저장 위치(~/.claude/plans/)에만 둔다 — 프로젝트 private/로 복사하지 않는다.