Claude Code 프롬프트 작성법: 덜 지시하고 스스로 검증하게 하세요

AI에게 일을 맡길 때 우리는 본능적으로 더 자세히 설명하려고 합니다.

“먼저 이 파일을 읽고, 다음으로 저 함수를 고친 뒤, 이 방식으로 테스트해.”

얼핏 보면 친절하고 정확한 지시입니다. 하지만 최신 AI 모델에는 이런 지시가 오히려 족쇄가 될 수 있습니다.

Claude Code 개발을 이끈 Boris Cherny는 최근 인터뷰에서 놀라운 이야기를 꺼냈습니다. Opus 5에 맞춰 Claude Code의 시스템 프롬프트를 80% 이상 지웠다는 것입니다. 이는 Anthropic의 전체 제품 정책이 아니라 Boris가 인터뷰에서 설명한 Claude Code 팀의 내부 재설계 사례입니다. 과거 모델의 실수를 보완하려고 쌓아둔 지침이 더 똑똑해진 모델에는 방해가 될 수 있었기 때문입니다.

결론부터 말하면, 좋은 Claude Code 프롬프트는 작업 순서를 모두 지정하지 않습니다. 목표, 필요한 맥락, 가드레일, 완료 조건, 검증 수단을 분명하게 전달합니다.

이 글에서는 인터뷰의 핵심을 정리하는 데서 끝나지 않습니다. 내 프로젝트에서 직접 실행할 수 있도록 다음 내용을 단계별로 살펴봅니다.

• 어떤 규칙을 지워도 되는지 확인하는 방법
• 에이전트에게 어려운 과제를 맡기는 프롬프트
• 결과를 스스로 검증하게 만드는 환경
• 반복 작업을 자동 루틴으로 바꾸는 방법

핵심은 더 잘 시키는 것이 아니라 덜 방해하는 것

Claude Code 팀은 모델이 바뀔 때마다 기존 프롬프트와 도구를 그대로 물려주지 않습니다. 먼저 많은 것을 걷어낸 뒤 백지에 가까운 상태에서 모델을 사용합니다.

그다음 실제 실패를 관찰합니다. 모델이 같은 문제에서 반복해서 넘어질 때만 필요한 지침을 한 줄씩 되살립니다. 연구에서 구성 요소를 하나씩 제거하며 영향을 측정하는 어블레이션(Ablation, 요소 제거 실험) 방식입니다.

과거 모델을 위해 만든 규칙은 대부분 당시의 약점을 보완하기 위한 것입니다. 최신 모델은 이미 그 문제를 해결했을 수 있습니다. 그런데도 낡은 규칙을 유지하면 모델은 불필요한 문장을 매번 읽고, 사람이 정한 좁은 경로 안에서만 움직이게 됩니다.

호블링과 프로덕트 오버행

호블링: 모델에 족쇄를 채우는 것

호블링(Hobbling)은 모델이 이미 가진 능력을 제품이나 사용 방식이 가로막는 현상입니다.

예를 들어 모델이 코드베이스를 탐색하고 해결책을 선택할 수 있는데도 사람이 수정할 파일과 함수, 구현 순서까지 모두 지정한다고 해보겠습니다. 모델은 더 나은 방법을 발견해도 지시를 벗어나기 어렵습니다.

프로덕트 오버행: 아직 제품으로 꺼내지 못한 능력

프로덕트 오버행(Product Overhang)은 현재 모델이 이미 할 수 있지만, 그 능력을 충분히 표현할 제품이나 환경이 아직 없는 상태를 뜻합니다.

초기 코딩 AI 제품은 자동 완성과 질의응답에 집중했습니다. 하지만 당시 모델도 적절한 권한과 도구를 제공하면 함수나 파일 단위의 코드를 작성할 수 있었습니다. Claude Code는 모델에 터미널과 파일 수정 권한을 제공하면서 숨겨진 능력을 제품으로 끌어낸 사례입니다.

두 개념은 동전의 양면입니다.

실전 1: 기존 프롬프트를 안전하게 걷어내기

“그렇다면 프로젝트 규칙을 전부 지우면 되나요?”

그렇게 하면 안 됩니다. 보안, 권한, 배포 제한처럼 사고를 막는 규칙까지 지우면 위험합니다. 핵심은 삭제 자체가 아니라 비교 실험입니다.

다음 프롬프트를 사용하면 에이전트가 기존 규칙을 직접 분류하도록 만들 수 있습니다.

이 프로젝트의 에이전트 지침을 검토해줘.

각 지침을 다음 세 종류로 분류해.
1. 안전과 권한을 위해 반드시 유지해야 하는 규칙
2. 결과물의 품질과 완료 조건을 정의하는 규칙
3. 과거 모델의 약점을 보완하려고 작업 방법을 세세하게 지정한 규칙

3번 규칙은 제거 후보로 표시해줘.
아직 파일은 수정하지 말고, 각 판단의 근거와 제거했을 때의 위험만 표로 정리해줘.
확신이 낮은 항목은 별도로 표시해줘.

중요한 부분은 “아직 수정하지 말라”는 조건입니다. 먼저 분석만 받고 사람이 제거 범위를 결정할 수 있습니다.

실전 2: 방법이 아니라 목표를 전달하기

기존 방식은 모델에게 작업 순서를 알려주는 것이었습니다.

components 폴더를 열고 Button.tsx를 수정해.
variant prop을 추가하고 switch 문을 사용해.
그다음 Button.test.tsx에 테스트 세 개를 추가해.

이 프롬프트는 명확하지만 해결 방법을 지나치게 좁힙니다. 실제 원인이 디자인 토큰이나 공통 스타일 구조에 있어도 모델은 지정된 파일만 고칠 가능성이 큽니다.

최신 에이전트에는 목표, 필요한 맥락, 가드레일, 종료 조건을 구체적으로 전달하되 구현 순서까지 미리 고정하지 않는 방식이 잘 맞습니다. Anthropic의 Claude Code 공식 모범 사례도 구체적인 지시와 사전 탐색, 계획, 테스트를 권장합니다. 여기서 줄여야 하는 것은 정보가 아니라 불필요한 마이크로매니징입니다.

이 프로젝트의 버튼 컴포넌트에 primary, secondary, danger 스타일을 지원하는 variant 기능을 추가해줘.

가드레일:
- 기존 버튼 사용 코드를 깨뜨리지 마.
- 새 런타임 의존성을 추가하지 마.
- 프로젝트의 기존 설계와 테스트 패턴을 따라.
- 관련 없는 코드는 수정하지 마.

완료 조건:
- 세 가지 variant가 모두 동작해야 해.
- 타입 검사, 관련 테스트, 린트가 통과해야 해.
- 변경 이유와 검증 결과를 마지막에 요약해.

구현 순서와 수정할 파일은 코드베이스를 살펴보고 스스로 결정해.
막히면 추측하지 말고 확인할 방법부터 찾아.

다른 작업에는 아래 템플릿을 그대로 복사해 사용할 수 있습니다.

목표:
[완성해야 할 결과를 설명]

가드레일:
- [절대 하면 안 되는 일]
- [호환성 또는 보안 조건]
- [변경 범위]

완료 조건:
- [자동으로 확인할 수 있는 조건]
- [사용자가 직접 확인할 조건]
- [보고해야 할 내용]

작업 방식:
코드베이스와 도구를 살펴보고 가장 적절한 방법을 선택해.
작업 중 결과를 계속 검증하고, 완료 조건을 만족할 때까지 수정해.

실전 3: 프롬프트보다 검증 환경을 먼저 만들기

Boris가 강조한 핵심은 **검증(Verification)**입니다.

에이전트가 오래 일하려면 자신이 올바른 방향으로 가는지 확인할 수 있어야 합니다. 사람이 옆에서 매번 맞고 틀림을 알려주는 대신 테스트, 빌드, 스크린샷, 로그처럼 스스로 읽을 수 있는 피드백을 제공해야 합니다. Anthropic의 장기 실행 에이전트 연구에서도 작업 목록, 진행 기록, Git 이력과 브라우저 테스트 같은 외부 상태를 남기는 방법을 강조합니다.

가장 단순한 검증 환경은 프로젝트의 주요 검사를 한 번에 실행하는 명령입니다.

#!/usr/bin/env bash
set -euo pipefail

npm run typecheck
npm run lint
npm test
npm run build

echo "모든 검증을 통과했습니다."

프로젝트 루트에 이 내용을 verify.sh로 저장한 뒤 실행 권한을 줍니다.

chmod +x verify.sh
./verify.sh

그리고 에이전트 프롬프트에 검증 명령을 명시합니다.

회원가입 폼의 오류 처리와 접근성을 개선해줘.

완료 조건:
- 키보드만으로 모든 입력과 제출이 가능해야 해.
- 잘못된 입력에는 필드별 오류 메시지가 표시돼야 해.
- 기존 회원가입 흐름은 깨지면 안 돼.
- ./verify.sh가 끝까지 통과해야 해.

작업을 작은 단위로 나눠 진행해.
각 단위가 끝날 때 관련 테스트를 실행하고, 마지막에는 ./verify.sh를 실행해.
검증이 실패하면 원인을 분석하고 수정한 뒤 다시 실행해.
테스트를 삭제하거나 약화해서 통과시키지 마.

검증 명령이 없으면 모델은 “코드가 그럴듯하다”는 수준에서 멈출 수 있습니다. 검증 명령이 있으면 성공과 실패가 명확해집니다.

화면이 중요한 작업은 스크린샷으로 검증하기

구현 후 앱을 직접 실행해.
데스크톱 1440px와 모바일 390px 화면을 각각 캡처해.
다음 항목을 원본 디자인과 비교해.
- 요소의 위치와 간격
- 글자 크기와 줄바꿈
- 색상과 테두리
- 가로 스크롤 발생 여부
- 로딩, 빈 화면, 오류 상태

차이가 발견되면 수정하고 다시 캡처해.
최종 답변에는 캡처 경로와 남아 있는 차이를 함께 알려줘.

에이전트가 브라우저나 시뮬레이터를 사용할 수 있어야 이 프롬프트가 효과를 냅니다. 검증할 도구 없이 “완벽하게 만들어”라고 요구하는 것은 눈을 가린 채 과녁을 맞히라고 하는 것과 같습니다.

실전 4: 모델에게 조금 더 어려운 문제를 주기

인터뷰에서는 Bun의 핵심 코드를 Zig에서 Rust로 옮긴 사례가 소개됩니다. 동적 워크플로가 많은 에이전트를 조율했고, 작업은 11일 동안 이어졌습니다. 사람의 중간 조정도 있었습니다. 따라서 ‘프롬프트 한 번으로 완전 자동 변환했다’고 이해하면 안 됩니다. Bun 1.4 공식 소개는 약 100만 줄 규모의 핵심 코드가 Rust로 재작성됐고 기존 벤치마크 수준을 유지하거나 넘어섰다고 설명합니다.

또 다른 사례에서는 Electron 기반 데스크톱 앱을 Swift 네이티브 앱으로 옮기는 작업이 2주 넘게 진행됐습니다. 에이전트는 두 앱을 실행하고 화면을 캡처한 뒤 픽셀 수준으로 비교하며 계속 수정했습니다.

여기서 배울 점은 “모든 코드베이스를 당장 통째로 다시 작성하라”가 아닙니다. 예전에 실패했던 과제도 최신 모델에 다시 던져보라는 것입니다. 단, 성공 여부를 판정할 테스트와 중간 결과를 관찰할 장치가 있어야 합니다.

큰 과제를 맡길 때는 다음 프롬프트로 시작할 수 있습니다.

이 작업은 한 번에 끝내기 어려운 장기 과제야.

목표:
[달성하려는 큰 결과]

먼저 다음 내용만 작성해.
1. 현재 코드베이스와 제약 조건 분석
2. 성공 여부를 판단할 수 있는 검증 항목
3. 서로 독립적으로 진행할 수 있는 작업 단위
4. 각 단계의 실패 가능성과 되돌리는 방법
5. 사람이 승인해야 하는 지점

아직 구현하지 마.
계획에서 검증이 불가능한 단계가 있다면 필요한 도구부터 제안해줘.

계획을 검토한 다음 구현 단계에서는 아래처럼 요청합니다.

승인한 계획에 따라 첫 번째 작업 단위부터 진행해.
각 단계마다 테스트 또는 실행 결과로 성공을 확인해.
검증되지 않은 상태에서 다음 단계로 넘어가지 마.
예상과 다른 결과가 나오면 원인을 기록하고 계획을 수정해.
운영 환경과 사용자 데이터에는 접근하지 마.

실전 5: 반복 작업은 루틴으로 바꾸기

동적 워크플로가 하나의 크고 복잡한 과제를 여러 에이전트가 나눠 해결하는 방식이라면, 인터뷰에서 설명한 루프와 루틴은 같은 종류의 작업을 정해진 주기로 반복하는 방식입니다. Anthropic은 동적 워크플로 공식 소개에서 하나의 세션이 수백 개의 병렬 서브에이전트를 실행하고 기존 테스트를 기준으로 결과를 검증할 수 있다고 설명합니다. 다만 기능 제공 범위와 사용 조건은 플랜 및 출시 시점에 따라 달라질 수 있습니다.

예를 들면 사용되지 않는 코드 후보 찾기, 테스트가 부족한 영역 찾기, 오래된 문서 확인하기, 중복 구현 찾기가 루틴에 적합합니다.

처음부터 코드를 자동으로 합치거나 배포하게 하면 위험합니다. 초기에는 분석 보고서 또는 초안 PR만 생성하도록 제한하는 것이 좋습니다.

매주 이 코드베이스에서 사용되지 않는 코드 후보를 찾아줘.

판단 기준:
- 정적 분석 결과
- 실제 import와 호출 여부
- 동적 로딩 또는 설정 기반 사용 가능성
- 관련 테스트와 문서

규칙:
- 코드를 직접 삭제하거나 배포하지 마.
- 확실한 후보와 추가 확인이 필요한 후보를 구분해.
- 각 후보마다 근거, 예상 영향, 확인 방법을 작성해.
- 결과는 검토 가능한 보고서 또는 초안 PR로만 남겨.

실패를 지침으로 바꾸는 기록법

에이전트가 실패할 때마다 긴 규칙을 추가하면 프롬프트는 다시 비대해집니다. 모든 실패가 프롬프트 문제는 아닙니다.

• 정보가 없었다면 문서나 데이터에 접근할 도구가 필요합니다.
• 결과를 확인하지 못했다면 테스트나 브라우저가 필요합니다.
• 권한이 부족했다면 제한된 실행 환경이 필요합니다.
• 같은 판단을 반복해서 놓친다면 짧은 지침이 필요합니다.

다음 프롬프트로 실패 원인을 분리할 수 있습니다.

방금 작업이 실패한 원인을 분석해줘.

다음 중 어디에 해당하는지 구분해.
1. 목표가 불명확했다.
2. 필요한 맥락이나 데이터가 없었다.
3. 실행 또는 검증 도구가 없었다.
4. 권한이 부족했다.
5. 모델이 반복적으로 같은 판단을 놓쳤다.

프롬프트 문장을 추가하는 것은 5번일 때만 제안해.
나머지는 필요한 맥락, 도구 또는 환경의 변화로 해결해줘.

오늘 바로 적용하는 30분 실험

거대한 에이전트 시스템을 만들 필요는 없습니다. 작은 작업 하나로 시작해도 충분합니다.

비교할 때는 완료 시간, 사람의 개입 횟수, 실패한 검증 횟수, 불필요하게 수정한 파일 수, 최종 테스트 통과 여부를 기록하세요.

마무리: 최고의 빌더는 모델을 통제하지 않는다

AI 시대에 프롬프트는 사라지지 않습니다. 다만 역할이 달라집니다.

과거의 프롬프트가 작업 절차를 세세하게 적은 매뉴얼이었다면, 앞으로의 프롬프트는 목표와 경계, 성공 조건을 합의하는 업무 요청서에 가까워집니다.

중요한 것은 세 가지입니다.

1. 모델이 간신히 해낼 만큼 어려운 과제를 줍니다.
2. 해결 방법에는 자율성을 주되 권한의 경계는 분명히 합니다.
3. 스스로 실패를 발견하고 수정할 검증 환경을 제공합니다.

모델이 발전할수록 우리가 쌓아온 지침과 도구는 자산인 동시에 부채가 될 수 있습니다. 새 모델이 나왔다면 기능을 더하기 전에 먼저 물어보세요.

“지금 이 모델을 돕고 있는가, 아니면 방해하고 있는가?”

그 질문에서 언호블링이 시작됩니다.

자주 묻는 질문