프롬프트 엔지니어링 / Claude Code 사용 노하우 정리

1hyung·2026년 5월 21일

Claude Gemini claude code codex 제미나이 코덱스 클로드코드 프롬프트 엔지니어링

개발

목록 보기

7/7

문서 목적

이 문서는 Claude Code, ChatGPT, Codex, Gemini 등을 함께 사용하면서 얻은 프롬프트 엔지니어링 실무 노하우를 정리한 문서다.
핵심 목적은 단순히 AI에게 일을 많이 시키는 것이 아니라, 토큰을 아끼면서도 작업 품질을 높이고, 중간에 모델이나 도구가 멈춰도 작업을 이어갈 수 있는 구조를 만드는 것이다.

특히 Claude Code를 사용할 때는 아래 문제가 자주 발생한다.

바로 구현을 시키면 불필요한 파일 탐색과 재시도가 많아져 토큰이 빠르게 소모됨
대화 context가 길어질수록 이전 지시사항이 흐려지거나 compact 과정에서 일부 정보가 휘발될 수 있음
Claude Code 서버 오류나 사용량 제한으로 작업이 중단될 수 있음
Claude가 직접 구현한 코드를 Claude만 다시 검토하면 같은 관점의 오류를 놓칠 수 있음
현재 사용 중인 모델, 브랜치, context 사용량, 비용 상태를 계속 별도 화면에서 확인하는 것이 번거로움

따라서 실무에서는 Plan mode, statusline, Codex review, subagent, 인수인계 문서화, /clear 전략을 함께 사용하는 것이 좋다.

1. 토큰을 절약하는 핵심 원칙

1.1 바로 구현시키지 말고 먼저 설계한다

Claude Code에서 가장 토큰이 많이 낭비되는 패턴은 “일단 해줘”라고 바로 구현을 맡기는 것이다.
이 방식은 편해 보이지만 실제로는 다음 문제가 생긴다.

Claude가 요구사항을 완전히 이해하지 못한 상태에서 여러 파일을 읽음
잘못된 방향으로 코드를 수정한 뒤 다시 되돌리거나 재수정함
구현 중간에 요구사항을 다시 설명하게 됨
같은 맥락을 여러 번 반복해서 입력하게 됨
테스트 실패 후 원인 파악을 위해 더 많은 context를 읽게 됨

즉, 설계가 부족하면 구현 과정에서 토큰을 더 많이 쓰게 된다.
그래서 큰 작업은 바로 구현하지 말고 먼저 Plan mode로 전환해서 아래 내용을 확인하는 것이 좋다.

현재 코드 구조가 어떻게 되어 있는지
요구사항과 현재 구현의 차이가 무엇인지
어떤 파일이 영향을 받는지
수정 방식이 여러 개라면 각각의 장단점은 무엇인지
어떤 순서로 수정하는 것이 안전한지
검증은 어떤 방식으로 해야 하는지
rollback 가능성은 있는지

우리 협업 기준에서도 Claude는 실제 레포지토리 코드, 파일, 로그, 테스트 결과를 확인하는 실행자이고, ChatGPT는 사용자 의도와 설계 기준을 정리하는 설계 보조자로 분리하는 것이 안전하다고 정리되어 있다.

1.2 Plan mode를 사용해야 하는 이유

Claude Code의 Plan mode는 파일을 바로 수정하지 않고, 먼저 읽기 중심으로 조사한 뒤 계획을 제안하는 방식이다. 공식 문서에서도 큰 변경 전에는 Plan mode로 전환하면 Claude가 파일을 읽고 계획을 제안하지만 승인 전에는 수정하지 않는다고 설명한다.

Plan mode가 중요한 이유는 다음과 같다.

구분	바로 구현	Plan mode 사용
요구사항 이해	구현 중간에 오해가 발견될 수 있음	구현 전 오해를 줄일 수 있음
토큰 사용	잘못된 수정과 재시도로 토큰 증가	설계 단계에서 방향을 고정해 낭비 감소
리스크	영향 범위를 모른 채 수정 가능	영향 범위와 검증 방법을 먼저 확인
사용자 개입	문제가 생긴 뒤 개입	구현 전 방향을 검토
품질	모델이 임의 판단할 가능성 증가	기준을 먼저 합의하고 구현

실무적으로는 아래 흐름이 좋다.
1. 요구사항 설명
1. Plan mode로 현재 코드 구조와 수정 후보 확인
1. 사용자가 방향 검토
1. 필요한 경우 Plan 수정 요청
1. 최종 방향이 맞을 때만 구현 진행
1. 구현 후 테스트 / 리뷰 / 인수인계 문서화

1.3 Opus Plan mode를 활용한다

Claude Code에는 opusplan 모델 설정이 있다. 공식 문서 기준으로 opusplan은 Plan mode에서는 Opus를 사용해 복잡한 추론과 아키텍처 결정을 처리하고, 실행 모드에서는 Sonnet으로 자동 전환해 코드 생성과 구현을 수행하는 하이브리드 방식이다.

사용법은 아래와 같이 입력하면 된다.

/model opusplan

이 방식의 장점은 명확하다.

중요한 설계는 더 똑똑한 Opus가 담당
실제 구현은 빠르고 비용 효율적인 Sonnet이 담당
큰 기능 변경, 구조 변경, 리팩토링 전에 특히 유용
설계 품질과 구현 속도의 균형을 잡을 수 있음

추천 사용 패턴은 다음과 같다.

복잡한 작업: opusplan을 사용해 Plan mode에서 구조, 영향 범위, 위험 요소를 확인하고, 구현은 Sonnet으로 진행
단순 작업: Sonnet을 사용해 작은 수정, 테스트 추가, 문서 수정 진행
매우 단순한 조사: Haiku 또는 subagent 활용 가능

1.4 모델 선택 기준

토큰을 아끼려면 모든 작업을 가장 비싼 모델로 처리하면 안 된다.

작업 유형	추천 모델 / 방식	이유
신규 기능 설계	Opus / opusplan	요구사항 해석과 구조 판단이 중요
아키텍처 변경	Opus / opusplan	잘못 설계하면 수정 비용이 큼
일반 구현	Sonnet	속도와 비용 균형이 좋음
단순 코드 수정	Sonnet	충분한 품질과 효율
코드 검색 / 단순 조사	Haiku 또는 Explore subagent	빠르고 저렴하게 조사 가능
리뷰	Codex review 또는 reviewer subagent	다른 관점의 검증 가능

공식 비용 관리 문서에서도 context 크기가 커질수록 토큰 사용량이 늘고, Sonnet은 대부분의 코딩 작업에 적합하며 Opus는 복잡한 아키텍처 결정이나 다단계 추론에 남겨두는 것을 권장한다.

2. Statusline으로 context와 사용량을 실시간 확인하기

2.1 Statusline이 필요한 이유

Claude Code를 오래 사용하다 보면 매번 웹사이트나 별도 화면에 들어가서 현재 상태를 확인하는 것이 번거롭다.
이때 statusline을 설정하면 터미널 하단에서 다음 정보를 바로 확인할 수 있다.

현재 사용 중인 모델
현재 작업 디렉토리
context window 사용률
비용 또는 사용량
git 브랜치
git 변경 상태
repository 상태
경고성 정보
세션 구분 정보

Claude Code 공식 문서에서도 statusline은 Claude Code 하단의 사용자 정의 가능한 막대이며, context window 사용량, 비용, git 상태 등을 한눈에 볼 수 있게 해준다고 설명한다.

2.2 Statusline을 사용하면 좋은 상황

Statusline은 특히 아래 상황에서 유용하다.

긴 작업을 진행하면서 context 사용률을 계속 보고 싶을 때
현재 Opus인지 Sonnet인지 헷갈릴 때
브랜치를 잘못 잡고 작업하는 실수를 줄이고 싶을 때
repository에 변경사항이 있는지 바로 보고 싶을 때
auto-compact가 다가오는지 미리 감지하고 싶을 때
여러 Claude Code 세션을 동시에 사용할 때

실무에서는 statusline을 켜놓고 작업하면, 작업 중간에 context가 많이 찼는지 바로 알 수 있기 때문에 compact나 /clear 시점을 더 잘 판단할 수 있다.

2.3 Statusline 설정 방법

가장 간단한 방법은 Claude Code에서 /statusline 명령을 실행하고 원하는 내용을 자연어로 설명하는 것이다. 공식 문서에서도 /statusline 명령에 표시하고 싶은 내용을 설명하면 Claude Code가 스크립트 파일을 만들고 설정을 업데이트할 수 있다고 안내한다.

예시:

/statusline show model name, git branch, repo name, context percentage, and warnings

또는:

/statusline show current model, current directory, git branch, context usage percentage, and cost

수동으로 설정하고 싶다면 ~/.claude/settings.json에 statusLine 필드를 추가할 수 있다. 공식 문서 예시는 현재 모델명과 context 사용률을 jq로 출력하는 방식도 제공한다.

예시:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\(.model.display_name)] \(.context_window.used_percentage // 0)% context\"'"
  }
}

2.4 추천 statusline 표시 항목

실무 기준으로는 아래 항목을 표시하는 것이 좋다.
[모델명] [레포지토리명] [브랜치명] [context 사용률] [git 변경 상태] [경고]

예시:

[Sonnet] quote-service | feature/auto-quote | 63% context | 5 files changed

또는:

[Opus Plan] backend-api | main | 42% context | clean

이렇게 구성하면 작업 중 다음을 빠르게 판단할 수 있다.

지금 비싼 모델을 계속 쓰고 있는지
context가 너무 많이 찼는지
작업 브랜치가 맞는지
커밋 전 변경 파일이 남아 있는지
compact 또는 /clear가 필요한 시점인지

3. Codex plugin으로 Claude 구현 결과 교차 검증하기

3.1 Claude만으로 리뷰하면 생기는 문제

Claude가 구현한 코드를 Claude가 다시 리뷰하면 어느 정도 검토는 가능하지만, 같은 모델 계열이기 때문에 비슷한 관점의 실수를 반복할 수 있다.
예를 들어 다음 문제가 생길 수 있다.

Claude가 처음 잘못 가정한 내용을 리뷰 단계에서도 그대로 유지
구현 의도에 맞춰 관대하게 판단
구조적 위험보다 표면적인 코드 스타일만 확인
테스트 케이스 누락을 충분히 공격적으로 찾지 못함

그래서 최근에는 Claude Code에서 OpenAI Codex plugin을 연결해, Claude가 구현한 결과를 Codex가 다른 관점에서 리뷰하게 하는 방식이 유용하다.
OpenAI의 codex-plugin-cc 공식 GitHub README에 따르면 이 플러그인은 Claude Code 안에서 Codex를 사용해 코드 리뷰를 하거나 작업을 위임할 수 있게 해주며, /codex:review, /codex:adversarial-review, /codex:rescue, /codex:status, /codex:result, /codex:cancel 명령을 제공한다.

3.2 Codex review를 사용하는 목적

Codex review의 목적은 “Claude가 틀렸는지 확인”이 아니라, 다른 모델의 시각으로 빠진 부분을 찾는 것이다.
특히 아래 항목을 점검할 때 좋다.

요구사항과 구현 결과가 실제로 일치하는지
예외 케이스가 빠지지 않았는지
보안상 위험한 코드가 없는지
테스트가 충분한지
불필요하게 복잡한 구현은 아닌지
더 단순한 대안이 있는지
Claude가 놓친 API / 타입 / 상태 관리 문제가 있는지

추천 흐름은 다음과 같다.
1. Claude Code로 구현
1. /diff 또는 git diff로 변경사항 확인
1. /codex:review 실행
1. Codex가 지적한 항목을 Claude에게 전달
1. Claude가 실제 코드 기준으로 수정 가능 여부 판단
1. 필요한 항목만 반영
1. 테스트 실행
1. 최종 변경사항 정리

3.3 /codex 연결 방법

Codex plugin을 연결하려면 Claude Code 안에서 아래 순서로 진행한다.
공식 README 기준 요구사항은 ChatGPT 구독 또는 OpenAI API key, 그리고 Node.js 18.18 이상이다.

1단계. Claude Code에서 plugin marketplace 추가

/plugin marketplace add openai/codex-plugin-cc

2단계. Codex plugin 설치

/plugin install codex@openai-codex

3단계. plugin reload

/reload-plugins

4단계. Codex setup 실행

/codex:setup

공식 README에 따르면 /codex:setup은 Codex가 준비됐는지 확인하고, Codex가 없고 npm 사용이 가능하면 설치를 제안할 수 있다. 직접 설치하려면 npm install -g @openai/codex를 사용할 수 있다.

npm install -g @openai/codex

Codex는 설치되어 있지만 로그인되어 있지 않다면 Claude Code 안에서 아래처럼 실행한다. (!는 Claude Code 세션 안에서 shell command를 실행하는 방식이다.)

!codex login

3.4 기본 리뷰 실행 방법

가장 기본적인 리뷰는 아래 명령으로 실행한다.

/codex:review

브랜치 기준으로 리뷰하려면 base branch를 지정한다.

/codex:review --base main

멀티 파일 변경 리뷰는 시간이 걸릴 수 있으므로 background 실행이 권장된다. 공식 README에서도 multi-file change review는 시간이 걸릴 수 있어 background 실행을 권장한다고 설명한다.

/codex:review --background

진행 상태 확인:

/codex:status

결과 확인:

/codex:result

취소:

/codex:cancel

3.5 Adversarial review 사용하기

일반 리뷰보다 더 공격적으로 검토하고 싶을 때는 adversarial review를 사용한다.

/codex:adversarial-review

예시:

/codex:adversarial-review --base main 이 구현이 실제 운영에서 실패할 수 있는 edge case를 중심으로 검토해줘

사용하면 좋은 상황은 다음과 같다.

중요한 API 변경
배포 전 최종 검토
장애 가능성이 있는 수정
fallback / retry / timeout / rate-limit 관련 작업
결제, 예약, 견적, 고객 발송 등 운영 영향이 큰 기능
Claude가 “문제없다”고 했지만 사용자가 찝찝한 경우

3.6 Codex review 결과를 그대로 믿지 말아야 하는 이유

Codex review는 매우 유용하지만, 지적사항을 그대로 다 반영하면 안 된다.
권장 기준은 다음과 같다.

Codex가 지적한 내용을 Claude에게 전달한다.
Claude는 실제 파일, 함수, 테스트 결과를 확인한다.
확인된 문제 / 추정 / 보류 / 사용자 결정 필요로 나눈다.
실제로 반영할 항목만 수정한다.
수정 후 테스트를 다시 실행한다.

이 기준은 기존 협업 원칙과도 일치한다. 기존 기준에서는 ChatGPT나 외부 모델의 의견을 최종 사실로 취급하지 않고, 실제 레포지토리와 실행 결과를 기준으로 확인한 뒤 보고하도록 되어 있다.

4. Claude만 사용할 때는 Agents / Subagents로 리뷰하기

4.1 Codex plugin이 없을 때의 대안

Codex plugin을 사용할 수 없거나, Claude만 사용해야 하는 상황이라면 Claude Code의 agents 또는 subagents 기능을 활용할 수 있다.
Claude Code 공식 문서에 따르면 subagent는 특정 유형의 작업을 처리하는 특화된 AI 어시스턴트이며, 각 subagent는 자신의 context에서 작업하고 요약만 반환한다. 또한 context 보존, 도구 제한, 구성 재사용, 동작 특화, 비용 제어에 도움이 된다.

즉, 메인 Claude 세션에서 모든 파일을 읽게 하지 말고, 리뷰 전용 subagent에게 검토를 맡기면 메인 context를 덜 오염시킬 수 있다.

4.2 Reviewer agent 생성 방법

Claude Code에서 아래 명령을 실행한다.

/agents

공식 문서에서는 /agents 명령을 사용해 subagent 인터페이스를 열고, Library 탭에서 새 agent를 생성할 수 있다고 안내한다.

추천 설정:
| 항목 | 추천값 |
| --- | --- |
| Scope | Project 또는 Personal |
| 역할 | code-reviewer |
| 도구 | Read-only tools 중심 |
| 모델 | Sonnet |
| 목적 | 구현 결과 검토, edge case 탐지, 테스트 누락 확인 |
| 메모리 | 팀 공통이면 Project, 개인용이면 Personal |

읽기 전용 검토자의 경우 Read-only tools만 선택하는 것이 좋다. 공식 문서에서도 read-only reviewer는 Read-only tools를 제외한 다른 항목을 선택 해제하는 방식으로 안내한다.

4.3 Reviewer agent 프롬프트 예시

너는 이 프로젝트의 코드 리뷰 전용 subagent다.

*목표:*
- 최근 변경사항이 요구사항과 일치하는지 확인한다.
- edge case, 예외 처리, 상태 관리, 타입 오류 가능성을 찾는다.
- 테스트 누락을 찾는다.
- 불필요하게 복잡한 구현이나 더 단순한 대안을 제안한다.
- 직접 수정하지 말고 read-only 기준으로 리뷰만 한다.

*보고 형식:*
# 한 줄 결론
# 확인한 변경 범위
# 요구사항 충족 여부
# 발견한 문제
# 위험도 높은 문제
# 테스트 누락
# 수정 제안
# 반드시 수정해야 하는 항목
# 보류해도 되는 항목
# 추가 확인 필요 사항

*주의:*
- 실제 코드에서 확인한 사실과 추정을 구분한다.
- 파일명, 함수명, 테스트 결과 등 근거를 포함한다.
- 확실하지 않은 내용은 확인 불가 또는 추정으로 표시한다.
- 직접 구현하지 않는다.

사용 예시:

Use the code-reviewer agent to review the latest changes for edge cases, test gaps, and requirement mismatches.

또는:

use a subagent to review this code for edge cases

Claude Code 공식 best practice에서도 subagent를 사용해 조사나 검토를 별도 context에서 수행하게 하면 메인 대화를 깨끗하게 유지할 수 있고, 구현 후 edge case 리뷰에도 사용할 수 있다고 설명한다.

5. Auto-compact에 의존하지 말고 인수인계 문서화 후 /clear 사용하기

5.1 Context가 길어질수록 생기는 문제

Claude Code 작업이 길어지면 context window 안에 다음 정보가 계속 쌓인다.

사용자 요구사항
Claude의 답변
읽은 파일 내용
command output
테스트 결과
수정 과정
실패한 접근
다시 설명한 내용
CLAUDE.md
auto memory
loaded skills
system instructions

공식 문서에서도 Claude의 context window에는 대화 기록, 파일 내용, command output, CLAUDE.md, auto memory, loaded skills, system instructions가 포함되며, 작업이 진행될수록 context가 차오른다고 설명한다.

문제는 context가 길어지면 매 요청마다 이전 내용까지 다시 읽어야 한다는 점이다.
예를 들어 context 구조가 아래와 같다고 가정한다.

A: 최초 요구사항
B: 설계 논의
C: 구현 및 테스트

여기까지 작업한 뒤 완전히 다른 작업 D를 요청하면, 모델은 D만 보는 것이 아니라 기존 A, B, C context도 함께 참고하게 된다.

A + B + C + D

이렇게 되면 다음 문제가 생긴다.

D와 관련 없는 A, B, C까지 토큰에 포함됨
모델이 이전 작업 맥락에 끌려갈 수 있음
응답 속도가 느려짐
비용이 증가함
이전 실패나 수정 이력이 판단을 흐릴 수 있음

공식 비용 문서에서도 context 크기가 클수록 Claude가 처리하는 토큰이 늘어나고, stale context는 이후 메시지마다 토큰을 낭비한다고 설명한다.

5.2 Auto-compact의 한계

Auto-compact는 context가 한계에 가까워질 때 대화 기록을 요약해 공간을 확보하는 기능이다. 공식 문서에서도 Claude Code가 context limit에 가까워지면 conversation history를 자동으로 compact하고, 더 많은 제어가 필요하면 /compact <instructions>를 사용할 수 있다고 설명한다.

하지만 auto-compact에만 의존하면 다음 문제가 생길 수 있다.

사용자가 중요하다고 생각한 세부 맥락이 요약에서 빠질 수 있음
초기에 말한 제약조건이 희미해질 수 있음
“왜 이렇게 결정했는지”에 대한 근거가 사라질 수 있음
진행 중인 작업의 의도와 히스토리가 축약되어 품질이 떨어질 수 있음

공식 문서에서도 context가 찰 때 Claude Code는 오래된 tool output을 먼저 정리하고 필요하면 대화를 요약하지만, 초기 대화의 상세 지시사항은 잃을 수 있으므로 지속 규칙은 대화 이력에만 의존하지 말고 CLAUDE.md에 넣으라고 안내한다.

따라서 auto-compact가 자동으로 발생하기를 기다리기보다, 작업 단위가 끝났을 때 인수인계 문서를 남기고 /clear로 새 context를 시작하는 것이 더 안전하다.

5.3 /clear와 /compact의 차이

Claude Code 명령어 기준으로 /clear는 empty context로 새 대화를 시작하고, 이전 대화는 /resume에서 다시 접근할 수 있다. 반면 /compact는 지금까지의 대화를 요약해 context를 확보하는 명령이다.

명령어	의미	언제 사용
/clear	context를 비우고 새 대화 시작	작업이 바뀔 때
/compact	지금까지의 대화를 요약해 이어가기	같은 작업을 계속해야 할 때
/context	현재 context 사용량 확인	context가 왜 찼는지 볼 때
/resume	이전 세션으로 돌아가기	이전 작업을 다시 이어갈 때

추천 기준:

같은 작업을 계속한다 → /compact
완전히 다른 작업으로 넘어간다 → 인수인계 문서 작성 후 /clear
작업이 길어졌고 방향이 꼬였다 → 정리 문서 작성 후 /clear
초기 요구사항이 중요하다 → CLAUDE.md 또는 인수인계 문서에 명시

5.4 인수인계 문서화 템플릿

/clear를 하기 전에 아래 템플릿을 Claude에게 작성하게 하면 좋다.

현재 작업을 다음 세션이나 다른 모델이 이어받을 수 있도록 인수인계 문서를 작성해줘.

아래 형식으로 정리해줘.

# 작업 목표
# 현재까지 완료한 내용
# 수정한 파일 목록
# 주요 결정사항
# 아직 남은 작업
# 확인한 테스트 결과
# 실패했던 접근과 이유
# 주의해야 할 제약조건
# 다음 세션에서 바로 실행할 명령
# 다음 세션에 전달할 첫 프롬프트
# 민감정보가 있다면 마스킹해서 요약

인수인계 문서를 받은 뒤에는 다음처럼 진행한다.
1. 인수인계 문서를 파일로 저장
1. 필요한 경우 CLAUDE.md 또는 별도 handoff 문서에 반영
1. /clear 실행
1. 새 세션에서 인수인계 문서만 전달
1. 불필요한 이전 context 없이 작업 재개

5.5 추천 handoff 파일명

프로젝트 안에 아래처럼 남겨두면 좋다.

docs/handoff/YYYY-MM-DD-task-name.md

예시:

docs/handoff/2026-05-20-auto-quote-provider-fallback.md

내용 예시:

# Handoff - Auto Quote Provider Fallback

## 목표
Gemini → Claude Haiku → Claude Sonnet 순서로 fallback 구조를 구현한다.

## 완료된 내용
- Provider 구조 설계 완료
- fallback 순서 확정
- env 기반 Claude 모델명 주입 방식 확정

## 남은 작업
- 실제 provider interface 구현
- fallback 로깅 추가
- SCHEMA_INVALID 처리
- 테스트 실행

## 주의사항
- 고객 자동 발송은 이번 범위 밖
- Claude 모델명 하드코딩 금지
- PARSE_MAX_RETRIES=0 유지

6. Claude Code 서버 오류나 제한에 대비하기

6.1 Claude Code가 멈췄을 때의 문제

Claude Code는 매우 유용하지만, 실무에서는 다음 상황이 발생할 수 있다.

서버 오류
rate limit
사용량 제한
네트워크 문제
특정 모델 응답 지연
긴 작업 중 session 불안정
compact 이후 품질 저하

문제는 이때 작업 내용이 Claude Code 대화 안에만 있으면 다른 도구로 이어가기 어렵다는 점이다.
따라서 Claude Code를 사용할 때는 항상 다른 모델이 이어받을 수 있는 형태로 작업 상태를 남기는 습관이 중요하다.

6.2 GPT나 Gemini 유료 버전을 백업 모델로 활용하기

Claude가 멈췄을 때 GPT나 Gemini 유료 버전을 활용하면 작업을 이어갈 수 있다.
단, 그냥 “이어서 해줘”라고 하면 안 된다. 다른 모델은 Claude Code의 전체 context를 모르기 때문에 인수인계 문서가 필요하다.

추천 흐름:
1. Claude Code에서 작업 중간중간 handoff 문서 작성
1. Claude Code 장애 또는 제한 발생
1. handoff 문서를 GPT 또는 Gemini에 전달
1. 현재 목표, 완료 사항, 남은 작업, 주의사항을 기준으로 이어서 설계 또는 검토
1. 다시 Claude Code가 가능해지면 결과를 Claude에게 전달해 실제 repo 기준으로 반영

이때 GPT나 Gemini에게 맡기기 좋은 작업은 다음과 같다.

설계 재검토
에러 원인 가설 정리
테스트 케이스 목록 작성
코드 리뷰 관점 정리
Claude에게 다시 전달할 프롬프트 작성
인수인계 문서 보완
변경사항 요약

반대로 다른 모델이 실제 repo를 직접 볼 수 없는 상황이라면 아래는 조심해야 한다.

파일 존재 여부 단정
함수명 단정
실제 테스트 통과 여부 단정
운영 API 동작 단정
DB migration 영향 단정

기존 협업 기준에서도 최종적으로는 실제 레포지토리와 실행 결과를 확인하는 Claude의 근거 기반 보고가 중요하며, 사용자가 최종 결정권자라는 원칙을 두고 있다.

7. 실무 추천 워크플로우

7.1 큰 기능 작업 흐름

요구사항 정리
Claude Code를 opusplan 또는 Plan mode로 실행
현재 코드 구조 / 영향 범위 / 수정 후보 확인
사용자가 Plan 검토
구현 승인 후 Sonnet 중심으로 구현
statusline으로 context 사용량과 모델 확인
구현 완료 후 /diff 확인
/codex:review 또는 reviewer subagent로 교차 검증
필요한 수정 반영
테스트 실행
handoff 문서 작성
/clear로 context 정리

7.2 작은 수정 작업 흐름

Sonnet으로 바로 시작
수정 범위를 명확히 지정
필요 없는 파일 탐색 금지
수정 후 테스트
간단 요약 작성
다음 작업이 다르면 /clear

예시 프롬프트:

이번 작업은 작은 수정이다.
관련 파일만 확인하고, 전체 레포지토리 탐색은 하지 마라.
수정 전 변경 대상과 이유를 짧게 보고하고, 승인 후 구현해라.

7.3 리뷰 전용 흐름

구현 완료
/diff 확인
/codex:review --base main --background
/codex:status
/codex:result
Claude에게 결과 전달
실제 코드 기준으로 반영 여부 판단
필요한 항목만 수정

7.4 Context 관리 흐름

statusline으로 context 사용률 확인
60~70% 이상이면 작업 단위 종료 가능성 판단
같은 작업이면 /compact with instructions
다른 작업이면 handoff 작성
/clear 실행
handoff 문서만 전달해 새 context 시작

8. Claude에게 자주 쓰는 프롬프트 예시

8.1 Plan mode용 프롬프트

아직 구현하지 말고 Plan mode로만 확인해줘.

다음 기준으로 보고해줘.

# 한 줄 결론
# 현재 코드 구조
# 요구사항과 현재 구현의 차이
# 수정 후보
# 각 후보의 장단점
# 추천안
# 영향받는 파일
# 위험 요소
# 테스트 방법
# rollback 가능성
# 사용자 결정 필요 사항

확인한 사실과 추정을 구분하고,
실제 코드에서 확인한 파일/함수/로그/테스트 결과를 근거로 적어줘.

8.2 구현 전 토큰 절약 프롬프트

토큰 절약을 위해 관련 파일만 확인해줘.

불필요한 전체 레포지토리 탐색은 하지 말고,
먼저 어떤 파일을 확인해야 하는지 목록으로 보고해줘.

그 다음 내가 확인하면 필요한 파일만 읽고 Plan을 작성해줘.
아직 구현하지 마라.

8.3 구현 후 리뷰 요청 프롬프트

방금 구현한 변경사항을 검토해줘.

기준:
# 요구사항 충족 여부
# edge case
# 테스트 누락
# 타입/런타임 오류 가능성
# 운영 중 문제 가능성
# 더 단순한 구현 가능성
# 반드시 수정해야 하는 항목
# 보류 가능한 항목

직접 수정하지 말고 리뷰만 해줘.

8.4 Codex 결과를 Claude에게 전달하는 프롬프트

아래는 Codex review 결과다.

이 내용을 그대로 반영하지 말고,
실제 코드 기준으로 확인한 뒤 아래 형식으로 보고해줘.

# 실제 문제로 확인된 항목
# Codex 지적은 맞지만 이번 범위 밖인 항목
# 오탐 또는 반영 불필요 항목
# 추가 확인이 필요한 항목
# 수정 우선순위
# 수정한다면 영향받는 파일
# 테스트 방법

아직 구현하지 말고 판단만 해줘.

8.5 Handoff 작성 프롬프트

현재 세션을 정리하고 /clear 하기 전에,
다음 세션 또는 다른 모델이 이어받을 수 있도록 handoff 문서를 작성해줘.

반드시 포함:
# 목표
# 완료한 작업
# 수정한 파일
# 핵심 결정사항
# 남은 작업
# 테스트 결과
# 실패했던 접근
# 주의사항
# 다음 세션 첫 프롬프트
# 민감정보 마스킹

불필요한 대화 내용은 빼고,
실제로 이어받는 데 필요한 정보만 정리해줘.

9. 핵심 결론

Claude Code를 잘 쓰는 핵심은 “많이 시키는 것”이 아니라 context를 설계하는 것이다.
정리하면 다음 원칙이 중요하다.

큰 작업은 바로 구현하지 말고 Plan mode로 설계한다.
opusplan을 사용해 설계는 Opus, 구현은 Sonnet으로 나눈다.
statusline으로 모델, context, 브랜치, 사용량을 계속 확인한다.
Claude 구현 결과는 Codex review 또는 reviewer subagent로 교차 검증한다.
auto-compact에만 의존하지 말고 handoff 문서를 남긴다.
작업 단위가 바뀌면 /clear로 context를 정리한다.
Claude Code 장애에 대비해 GPT/Gemini가 이어받을 수 있는 문서를 남긴다.
모든 AI의 의견은 최종 사실이 아니라 확인 후보로 본다.
실제 repo, 테스트, 로그, API 결과를 기준으로 최종 판단한다.

가장 중요한 습관은 다음 한 문장으로 정리할 수 있다.
AI에게 일을 맡기기 전에 context를 설계하고, 작업이 끝나면 다음 사람이 이어받을 수 있게 문서화한다.

1hyung

이유가 많은 사람보다 (자기)개발자가 되고싶은 1hyung입니다.

이전 포스트

프롬프트 엔지니어링 / Claude Code 사용 노하우 정리

개발

문서 목적

1. 토큰을 절약하는 핵심 원칙

1.1 바로 구현시키지 말고 먼저 설계한다

1.2 Plan mode를 사용해야 하는 이유

1.3 Opus Plan mode를 활용한다

1.4 모델 선택 기준

2. Statusline으로 context와 사용량을 실시간 확인하기

2.1 Statusline이 필요한 이유

2.2 Statusline을 사용하면 좋은 상황

2.3 Statusline 설정 방법

2.4 추천 statusline 표시 항목

3. Codex plugin으로 Claude 구현 결과 교차 검증하기

3.1 Claude만으로 리뷰하면 생기는 문제

3.2 Codex review를 사용하는 목적

3.3 /codex 연결 방법

3.4 기본 리뷰 실행 방법

3.5 Adversarial review 사용하기

3.6 Codex review 결과를 그대로 믿지 말아야 하는 이유

4. Claude만 사용할 때는 Agents / Subagents로 리뷰하기

4.1 Codex plugin이 없을 때의 대안

4.2 Reviewer agent 생성 방법

4.3 Reviewer agent 프롬프트 예시

5. Auto-compact에 의존하지 말고 인수인계 문서화 후 /clear 사용하기

5.1 Context가 길어질수록 생기는 문제

5.2 Auto-compact의 한계

5.3 /clear와 /compact의 차이

5.4 인수인계 문서화 템플릿

5.5 추천 handoff 파일명

6. Claude Code 서버 오류나 제한에 대비하기

6.1 Claude Code가 멈췄을 때의 문제

6.2 GPT나 Gemini 유료 버전을 백업 모델로 활용하기

7. 실무 추천 워크플로우

7.1 큰 기능 작업 흐름

7.2 작은 수정 작업 흐름

7.3 리뷰 전용 흐름

7.4 Context 관리 흐름

8. Claude에게 자주 쓰는 프롬프트 예시

8.1 Plan mode용 프롬프트

8.2 구현 전 토큰 절약 프롬프트

8.3 구현 후 리뷰 요청 프롬프트

8.4 Codex 결과를 Claude에게 전달하는 프롬프트

8.5 Handoff 작성 프롬프트

9. 핵심 결론

Dependency

0개의 댓글