클로드 코드(Claude Code) 사용법, 같은 버그 수정을 3가지로 맡겨 보니

장바구니 금액 계산 함수의 버그 5개를 고치는 같은 일을 클로드 코드에 세 가지 요청 문장으로 3번씩 맡기면, 세 방식 모두 3/3 성공합니다. 그런데 걸린 시간 중앙값은 41.0초, 34.3초, 29.4초로 갈렸고 입력 토큰은 260,383에서 96,773까지 차이가 났어요. 요청에 읽을 파일·고칠 파일·건드리면 안 되는 파일·확인 명령을 넣으면 같은 작업이 더 짧게 끝났습니다. 설치가 처음이라면 아래 설치 절부터 보세요.

설치하고 첫 수정을 맡기기까지

처음이라면 순서는 네 단계입니다. 운영체제에 맞는 명령으로 설치하고(macOS·Linux·WSL은 curl -fsSL https://claude.ai/install.sh | bash, Windows PowerShell은 irm https://claude.ai/install.ps1 | iex), 새 터미널에서 claude --version으로 설치를 확인한 뒤, 프로젝트 폴더에서 claude를 실행해 작은 수정을 맡기면 됩니다. 단계별 설명은 아래 '처음이라면 설치부터 첫 수정까지 순서' 절에 있습니다. 이어지는 실험은 그 첫 수정 요청을 어떻게 쓰면 좋은지 판단할 근거를 보여 줍니다.

함께 읽을 글

• 코딩 AI 추천, 클로드 코드·코덱스·안티그래비티에 같은 기능을 맡겨 보니
• 클로드 코드(Claude Code) effort 차이, 단계별 고르는 법
• 클로드 코드(Claude Code) 토큰 절약, 직접 재 보니 먼저 바꿀 3가지

요청 문장에 따라 무엇이 달라졌나요?

요청 문장만 바꾸고 모델(claude-opus-5-5)과 기본 effort는 똑같이 뒀습니다. 성공은 실행 뒤 node --test가 통과하고 테스트 파일이 그대로일 때만 셌고, 아래 표의 값은 3회 중앙값입니다.

원인을 먼저 정리하게 한 요청이 가장 짧았습니다. 한 줄 요청과 견주면 걸린 시간 0.7배, 입력 토큰 0.4배였고, 파일과 확인 방법까지 말한 요청은 걸린 시간 0.8배, 입력 토큰 0.6배였죠.

도식출처: 코딩 작업 실측

반면 출력 토큰은 1.0배, 0.9배로 거의 같았습니다. 입력 토큰은 새 입력·캐시 쓰기·캐시 읽기를 더한 값인데, 캐시 읽기만 249,554, 151,113, 86,759였어요. 비용 표시도 0.18, 0.16, 0.14달러 순으로 낮아졌습니다.

도식출처: 코딩 작업 실측

그렇다면 도구 호출이 줄어서 입력 토큰이 줄어든 걸까요? 도구 호출 수가 7, 5, 4로 함께 줄긴 했지만, 이 측정만으로는 원인을 가를 수 없습니다. 내 프로젝트에서 확인하고 싶다면 같은 요청을 새 폴더에서 여러 번 실행해 결과 JSON의 usage 값과 도구 호출 수를 회차별로 나란히 놓고 보세요.

세 번 돌리면 결과가 얼마나 흔들리나요?

중앙값만 보면 순서가 뚜렷하지만, 회차별 값은 꽤 흔들렸습니다. 예를 들어 한 줄 요청의 3회차는 24.3초였고, 원인 정리 요청의 3회차는 43.2초였어요.

눈에 띄는 점은 원인 정리 요청의 입력 토큰이 97,114, 96,682, 96,773으로 세 번 모두 비슷했다는 것입니다. 이 측정에서는 명령을 node --test만 허용했는데, 권한 거부가 왜 생겼는지는 기록에 나오지 않아요. 그래서 요청 방식을 비교할 때는 한 번 실행한 결과만 보고 판단하지 말고 여러 번 돌려 보는 쪽이 안전합니다.

클로드 코드 활용법, 요청은 어떻게 쓸까요?

측정 결과는 공식 Best practices 문서의 권장과 같은 방향입니다. 문서가 먼저 꼽는 것은 Claude가 직접 돌려 볼 수 있는 확인 수단을 주라는 점이에요. 테스트, 빌드, 비교할 스크린샷처럼 통과와 실패가 갈리는 신호가 있으면 Claude가 작업하고, 확인하고, 결과를 읽고, 통과할 때까지 고치는 흐름이 스스로 닫힙니다.

두 번째 권장은 요청에 구체적인 맥락을 넣으라는 것입니다. 어느 파일인지, 어떤 상황인지, 무엇이 고쳐진 상태인지를 말하라고 하죠. 문서는 제약도 함께 적으라고 권합니다. 이번 측정의 "테스트 파일은 고치지 마세요"가 그런 제약이에요.

• 범위 정하기: 파일, 상황, 테스트 방식 지정
• 증상 설명: 증상, 짐작되는 위치, 고쳐진 상태의 모습
• 근거 가리키기: 답이 있는 파일이나 기록을 직접 지목

그럼 원인 정리 요청은 계획 모드(plan mode)와 같은 걸까요? 아닙니다. 이 측정은 한 요청 안에서 목록부터 정리하라고 했을 뿐이에요. 문서는 범위가 분명하고 수정이 작은 일, 즉 바뀔 내용을 한 문장으로 말할 수 있는 일이라면 계획 단계를 건너뛰고 바로 시키라고 권합니다. 계획 모드는 접근 방법이 불확실하거나, 여러 파일을 바꾸거나, 익숙하지 않은 코드를 다룰 때 쓰라고 하고요.

처음이라면 설치부터 첫 수정까지 순서

아직 설치 전이라면 Quickstart 순서를 그대로 따라가면 됩니다.

1. 준비물을 확인합니다. 터미널, 작업할 코드 프로젝트, 그리고 Claude 구독(Pro, Max, Team, Enterprise)이나 Claude Console 계정, 또는 지원되는 클라우드 제공자 접근 권한이 필요해요.
2. 운영체제에 맞는 명령으로 설치합니다. 권장 방식은 네이티브 설치이고, 백그라운드에서 자동으로 업데이트됩니다.

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

위는 macOS·Linux·WSL용이고, 아래는 Windows PowerShell용입니다. Homebrew를 쓴다면 다음 명령도 있지만, 이 방식은 자동 업데이트가 되지 않아요.

brew install --cask claude-code

3. 새 터미널 창을 열고 설치를 확인합니다. 버전 번호 뒤에 (Claude Code)가 찍히면 정상이에요.

claude --version

4. 프로젝트 폴더에서 첫 세션을 시작합니다. 처음 실행하면 로그인을 요청하는데, 일반적으로 구독이나 Console 계정은 안내에 따라 브라우저에서 인증을 마치면 됩니다. 다만 ANTHROPIC_API_KEY 환경 변수를 설정해 두었고 Claude Code가 그 키를 쓸지 물을 때 승인하면 로그인 요청을 건너뜁니다.

cd /path/to/your/project
claude

5. 첫 질문으로 프로젝트를 파악하게 합니다. 문서는 what does this project do? 같은 질문을 예로 듭니다.
6. 작은 수정을 맡깁니다. 바꾸기 전에 물어보면 Yes를 고르고, Shift+Tab으로 권한 모드를 바꿀 수 있어요.

도식출처: 근거를 바탕으로 코드가 그린 도식

그대로 따라 쓸 요청 문장

버그를 고칠 때는 측정에 쓴 문장을 틀로 삼아, 파일 이름만 내 프로젝트에 맞게 바꿔 보세요. 가장 짧게 끝난 원인 정리 요청은 이렇습니다.

먼저 test/cart.test.js와 src/cart.js를 읽고 무엇이 틀렸는지 목록으로 정리해 주세요. 그다음 테스트가 모두 통과하도록 src/cart.js를 고쳐 주세요. 테스트 파일은 고치지 마세요. 고친 뒤 node --test로 확인해 주세요.

목록 정리를 빼고 싶다면 파일과 확인 방법까지 말하는 문장을 써도 됩니다. 이 요청도 3/3 성공했어요.

test/cart.test.js의 테스트가 모두 통과하도록 src/cart.js를 고쳐 주세요. 테스트 파일은 고치지 마세요. 고친 뒤 node --test로 확인해 주세요.

두 문장에는 공통점이 있습니다. 읽을 파일, 고칠 파일, 건드리면 안 되는 파일, 확인할 명령이 모두 들어 있죠.

요청을 보내기 전 점검 목록

이럴 때는 한 번 더 살펴보세요.

• 증상만 한 줄로 쓰기: 이 측정에서도 성공은 했지만 걸린 시간과 입력 토큰이 가장 컸습니다.
• 확인 방법을 빼먹기: 확인 수단이 없으면 끝나 보이는 것만이 신호라서, 실수를 찾는 일이 사람 몫으로 남습니다.
• 지켜야 할 제약 빼먹기: 이 측정은 테스트 파일이 그대로여야 성공으로 셌어요. 테스트를 고치면 안 된다면 그 말을 요청에 넣어야 합니다.
• 설치 직후 claude를 못 찾는 경우: 설치 폴더가 아직 PATH에 없는 상태이니 공식 문서의 PATH 해결 안내를 따르세요.

요청을 보내기 전 점검 목록입니다.

• 읽을 파일과 고칠 파일을 이름으로 적었나요?
• 통과·실패가 갈리는 확인 명령을 넣었나요?
• 건드리면 안 되는 파일이나 조건을 적었나요?
• 바뀔 내용을 한 문장으로 말할 수 없는 큰 일이라면 계획 모드를 고려했나요?

측정 조건과 한계

측정 환경은 Claude Code 2.1.309, darwin arm64, Node.js v22.23.1입니다. 조건마다 작업 폴더를 새 임시 폴더로 복사한 뒤 claude -p로 비대화형 실행을 했고, 세 조건을 번갈아 3번씩 돌려 중앙값을 썼습니다. 사용자 설정·사용자 스킬·플러그인·훅·MCP 서버는 불러오지 않았어요(--setting-sources project, --strict-mcp-config). 파일 수정은 --permission-mode acceptEdits로 자동 허용했습니다.

한계도 분명합니다. 파일 두 개짜리 작은 작업 하나를 claude-opus-5-5 한 모델로만 잰 결과라서, 큰 작업이나 다른 모델에서는 순서가 달라질 수 있어요. 비용 표시는 결과 JSON의 total_cost_usd 값을 그대로 옮긴 것이라 실제 청구 금액과 다를 수 있습니다. 평소 쓰는 CLAUDE.md나 훅, MCP 설정이 켜진 환경이라면 같은 요청으로 직접 다시 재 보는 것이 가장 정확합니다.