Skip to content

Instantly share code, notes, and snippets.

@benelog

benelog/opus-plan-sonnet-execute.md

Created May 13, 2026 12:31
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save benelog/129b379b2ca4a095d84d33cc702465e7 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save benelog/129b379b2ca4a095d84d33cc702465e7 to your computer and use it in GitHub Desktop.
Download ZIP
Opus가 Plan, Sonnet이 Execute — Claude Code에서 캐시 효율을 지키는 패턴
Raw
opus-plan-sonnet-execute.md

Opus가 Plan, Sonnet이 Execute — 캐시 효율을 지키는 패턴

배경: opusplan의 캐시 문제

Claude Code의 /model opus-plan 모드는 Plan 단계는 Opus로, 실행 단계는 Sonnet으로 자동 전환된다. 편하지만 한 세션 안에서 모델이 바뀌는 순간 프롬프트 캐시가 무효화된다. Anthropic 캐시는 모델별로 분리돼 있어 Opus → Sonnet 전환 시 cache hit ratio가 떨어지고, 토큰 비용·지연이 다시 늘어난다.

해결 아이디어: 메인 세션은 Opus 그대로 두고, 실행 작업만 Sonnet 서브에이전트에 위임한다. 서브에이전트는 자체 컨텍스트와 캐시 라이프사이클을 가지므로 메인 캐시가 보존된다.

1. 서브에이전트의 모델 지정

공식 문서에 따르면 서브에이전트는 .claude/agents/<name>.md (프로젝트) 또는 ~/.claude/agents/<name>.md (사용자 전역)에 YAML frontmatter + Markdown 본문 형태로 정의한다.

---
name: executor
description: Implements code changes from explicit, file/line-level specs. Use when the main session has already planned the edit.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
---

당신은 실행 전담 에이전트입니다. 받은 지시(파일 경로·라인·변경 내용)를
self-contained하게 처리하고, 결과만 요약해 반환하세요.
변경 의도를 추측하지 말고, 명시되지 않은 부가 수정은 하지 마세요.

model 필드 해상도 순서 (공식 문서 기준):

  1. CLAUDE_CODE_SUBAGENT_MODEL 환경 변수
  2. 호출 시점에 넘긴 model 파라미터 (Agent 도구의 model: "sonnet")
  3. 서브에이전트 정의의 model frontmatter
  4. 메인 대화의 모델 (기본 inherit)

즉 frontmatter에 model: sonnet을 박아두면 메인이 Opus여도 항상 Sonnet으로 실행된다.

2. 빌트인 서브에이전트는 이미 싼 모델로 자동 위임

Claude Code에는 사용자가 따로 만들지 않아도 동작하는 빌트인 서브에이전트가 있다.

서브에이전트 모델 자동 호출 시점
Explore Haiku 파일 검색, 코드 grep, 코드베이스 탐색
Plan 메인과 동일 (inherit) plan mode에서 컨텍스트 수집 시
general-purpose 메인과 동일 복합·다단계 작업
claude-code-guide Haiku Claude Code 자체에 대한 질문
statusline-setup Sonnet /statusline 실행 시

따라서 탐색·조회 작업은 이미 자동으로 Haiku에 위임된다. 명시적 설정이 필요한 건 편집·실행 영역이다.

3. 실전 적용: 세 가지 레벨

레벨 1 — 일회성 지시 (가장 가볍다)

이번 작업은 네가 직접 코드를 수정하지 말고,
계획은 너(Opus)가 세우고 실제 편집은
Agent 도구에 model="sonnet"으로 위임해줘.

레벨 2 — CLAUDE.md에 영구 규칙

~/.claude/CLAUDE.md 또는 프로젝트 CLAUDE.md에 추가:

## Execution Pattern (Opus 세션)

Opus 세션에서 코드 편집·테스트·빌드 같은 실행 작업은
직접 하지 말고 Agent 도구에 model="sonnet"으로 위임할 것.
메인 세션은 계획·분석·검증에만 사용해서 캐시를 유지한다.

서브에이전트 prompt에는 다음을 self-contained하게 포함:
- 정확한 파일 경로와 라인 번호
- 변경 전/후 코드 또는 구체적 지시
- 검증 방법 (테스트 명령 등)

위임이 부적합한 경우:
- 1~2줄 단순 수정
- 빠른 read-only 조회
- 위임 오버헤드가 작업보다 큰 경우

레벨 3 — 커스텀 서브에이전트 정의

위 1번 섹션의 executor.md를 ~/.claude/agents/에 저장. /agents 명령으로 GUI에서 만들 수도 있다.

4. 위임용 프롬프트의 핵심: self-contained

서브에이전트는 메인 대화 컨텍스트를 보지 못한다. "based on your findings, implement it" 같은 위임은 금물이다. Opus가 이해한 내용을 prompt에 직접 박아넣어야 한다.

나쁜 예

src/auth.ts를 분석해서 에러 핸들링을 개선해줘

좋은 예

파일: src/auth.ts (라인 42-58)

현재 코드:
[코드 블록 그대로 붙여넣기]

변경 사항:
1. try/catch로 감싸기
2. catch 블록에서 logger.error(err, { userId }) 호출
3. AuthError 타입으로 rethrow

검증:
- npm test -- auth.test.ts 통과해야 함
- 기존 호출부 src/api/login.ts:23은 그대로 동작해야 함

5. 플러그인으로 자동화

직접 규칙 쓰기 귀찮으면 커뮤니티 플러그인을 쓴다.

설치 (Claude Code 내부에서):

/plugin marketplace add barkain/claude-code-workflow-orchestration
/plugin install workflow-orchestration

6. 결론: 무엇을 선택할 것인가

상황 추천
한 번만 시도해보고 싶다 레벨 1 — 일회성 지시
평소에 항상 이 패턴으로 일하고 싶다 레벨 2 — CLAUDE.md 규칙
특정 역할의 실행자를 자주 호출한다 레벨 3 — executor.md 서브에이전트
작업 자동 분해·병렬 실행까지 원한다 workflow-orchestration 플러그인

핵심: 메인 Opus 세션의 캐시를 깨지 않는 것이 목적이다. 위임이 잦으면 빠르고 싸지만, 위임 오버헤드(prompt 작성·검증)가 작업보다 클 때는 그냥 직접 처리하는 게 낫다.

참고 자료

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment