Claude Code의 Plan 모드를 루프 엔지니어링으로 편하게 만들기

"UserPromptSubmit": [
  {
    "hooks": [
      { "type": "command",
        "command": "/Users/you/.claude/hooks/plan-mode-workflow.sh" }
    ]
  }
]

#!/bin/bash
# ~/.claude/hooks/plan-mode-workflow.sh
# UserPromptSubmit hook: permission_mode가 plan일 때만 Plan 모드 운영 지시를 주입한다
input=$(cat)
mode=$(printf '%s' "$input" | jq -r '.permission_mode // empty')
[ "$mode" = "plan" ] || exit 0

context=$(cat <<'EOF'
# Plan 모드 운영 규칙 (이 세션에서 반드시 적용한다)
1. 인터뷰: 첫 프롬프트 이후, 요건의 모호한 점이 없어질 때까지 AskUserQuestion으로 반복해서 질문한다. 1라운드로 끝내지 말고, 답변에서 새로운 모호점이 생기면 추가로 질문한다.
2. plan 확정 시그널: plan 파일이 확정되면, ExitPlanMode를 호출하기 전에 plan md 끝에 마커 행 <!-- render -->를 추가해 저장한다. 그 직후에 도착하는 시스템 알림의 절차를 따르고, 그것이 완료될 때까지 ExitPlanMode를 호출하지 않는다.
3. 실행 위임: ExitPlanMode 승인 후, 메인 세션에서는 파일 편집·구현 커맨드를 직접 실행하지 않는다. 일반 태스크는 Agent 툴(model은 4의 기준으로 다룬다), 장시간·독립성 높음·별도 디렉터리 작업은 claude --bg --model <model>, 단발 비대화 처리는 claude -p --model <model>에 위임한다. 메인 세션의 역할은 태스크 분할·지시·결과 검수·통합·보고뿐이다. 예외: 대화 전체의 컨텍스트를 파악하고 있어야만 수행할 수 있는 태스크(plan 전체와의 정합이 필요한 통합·최종 조정 등)에 한해 메인 세션에서 수행해도 된다. 그 외의 구현 작업을 메인 세션에서 하는 것은 불가.
4. 모델 배분: 범용 에이전트(general-purpose 등)는 model을 명시하고, 기본은 sonnet, 설계 판단·복잡한 디버깅·광범위한 변경 등 고난도 태스크는 opus를 지정한다. plan 수립을 위한 조사·설계 서브에이전트(Explore / Plan)에는 opus를 쓴다. 커스텀 에이전트는 model을 넘기지 말고 frontmatter 정의에 맡긴다. 덮어써도 되는 것은 고난도 태스크에서 opus로 끌어올리는 경우뿐이며, sonnet으로 끌어내리는 덮어쓰기는 하지 않는다.
EOF
)
jq -n --arg ctx "$context" '{hookSpecificOutput: {hookEventName: "UserPromptSubmit", additionalContext: $ctx}}'

"PostToolUse": [
  {
    "matcher": "Write|Edit",
    "hooks": [
      { "type": "command",
        "command": "/Users/you/.claude/hooks/plan-html-render.sh",
        "timeout": 240,
        "statusMessage": "plan HTML 생성 중..." }
    ]
  }
]

#!/bin/bash
# ~/.claude/hooks/plan-html-render.sh
# PostToolUse hook (Write|Edit): Plan 모드 중에 ~/.claude/plans/의 plan md에
# 확정 마커 <!-- render -->가 쓰이면, claude -p로 확인용 HTML을 동기 생성한다
input=$(cat)
mode=$(printf '%s' "$input" | jq -r '.permission_mode // empty')
[ "$mode" = "plan" ] || exit 0

file=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
case "$file" in
  /Users/you/.claude/plans/*.md) ;;
  *) exit 0 ;;
esac
[ -f "$file" ] || exit 0
grep -q '<!-- render -->' "$file" || exit 0

# ~/.claude/ 아래는 설정 디렉터리 보호로 headless의 Write가 기계적으로 차단되므로 밖에 둔다
html_dir="/Users/you/plan-html"
mkdir -p "$html_dir"
base=$(basename "$file" .md)
html="$html_dir/$base.html"

prompt="다음 플랜 md를 리뷰용 self-contained HTML로 변환해 주세요. 이 HTML은 Claude Artifact로 게시하는 페이지이므로, Artifact의 디자인 가이던스(design fundamentals)에 따라 플랜 내용을 도해를 곁들여 시각화할 것.
입력: $file 을 Read 한다 (끝의 마커 행 <!-- render --> 는 출력에 포함하지 않는다).
출력: $html 에 Write 한다.
요건:
- DOCTYPE / html / head / body 태그는 쓰지 않는다. <title> 과 <style> 과 콘텐츠를 직접 쓴다.
- 외부 리소스(CDN·외부 폰트·외부 이미지)는 일절 쓰지 않는다. 인라인 CSS / SVG만.
- 색은 :root 의 CSS 커스텀 프로퍼티로 정의하고, prefers-color-scheme 과 :root[data-theme=\"dark\"] / :root[data-theme=\"light\"] 양쪽에 대응해 라이트/다크 두 테마에서 읽을 수 있게 한다.
- 절차·플로·구성·스케줄 등 순서나 관계가 본질인 내용은 그림(CSS 스텝 플로 / 인라인 SVG 박스+화살표 / CSS 간트)으로 시각화한다. 비교·나열은 표로 만든다. 장식 목적의 그림은 만들지 않는다.
- 제목 계층·여백·타이포그래피를 다듬어 한국어로 읽기 쉽게 한다. 가로로 넓은 요소는 overflow-x: auto 컨테이너에 넣는다.
Artifact 게시는 메인 세션이 한다. 당신은 파일을 Write 하기만 하고, 게시는 하지 말 것.
변환해서 Write 했으면 done 이라고만 출력하고 종료할 것."

if claude -p "$prompt" --model sonnet --allowedTools "Read,Write" --disallowedTools "Artifact" > /dev/null 2>&1 && [ -f "$html" ] && [ "$html" -nt "$file" ]; then
  ctx="plan 확인용 HTML을 자동 생성했다: $html
(1) Artifact 툴로 $html 을 게시하고, 그 URL을 Bash의 「open <URL>」로 브라우저에서 연 다음 ExitPlanMode로 진행한다. AskUserQuestion으로의 확인은 끼우지 않는다 (승인/수정은 사용자가 ExitPlanMode 다이얼로그에서 한다. 같은 경로로 재게시하면 URL은 유지된다. 재게시 시에는 브라우저 쪽 리로드로 반영되므로 다시 open 하지 않아도 된다)
(2) reject로 수정 지시가 돌아오면 plan md를 수정한다. 마커 <!-- render --> 는 남기고, 수정은 가능한 한 1회의 Edit로 모은다 (Edit 할 때마다 재변환이 돌기 때문)
(3) Artifact는 소유자만 볼 수 있는 비공개 상태로 다룰 것. 공유 링크 발행·public 공개·제3자 공유 설정은 툴 사양상 가능하더라도 일절 하지 않는다"
else
  ctx="plan HTML 자동 생성에 실패했다 ($html 이 갱신되지 않음). 사용자에게 그 사실을 전하고, plan md를 그대로 Artifact 툴로 게시해 확인을 받을 것 (Artifact는 비공개 상태로 다루고, 공유 링크 발행이나 public 공개는 하지 않는다)."
fi
jq -n --arg ctx "$ctx" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $ctx}}'

jq -n --arg ctx "$ctx" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $ctx}}'