디버깅, 테스트는 통과했는데 결제 금액이 틀린 이유

테스트는 전부 통과했는데 손님 결제 금액이 틀리게 나오면 어디부터 봐야 할지 막막합니다. 앤트로픽 공식 플러그인 Engineering(엔지니어링)의 debug 스킬은 디버깅, 곧 버그의 원인을 찾아 고치는 일을 재현·범위 좁히기·진단·수정의 네 단계로 시키는 안내문입니다. 플러그인은 무료이지만 클로드 유료 요금제의 사용량을 씁니다. 2026-11-22 macOS 26.1, 클로드 코드(Claude Code) 2.1.299에서 쿠폰 버그를 심은 가상 빵집 주문 프로그램으로 같은 요청을 스킬 없이 2번, 스킬로 2번 보냈습니다.

세 줄 요약
  1. 4번 모두 1분이 안 걸려 원인을 찾고 코드를 한 곳 고쳤습니다. 원인은 앞 손님의 쿠폰이 다음 손님 주문에 남는 파이썬 기본값 버그였고, 직원이 의심한 배달비 변경은 4번 모두 걸렀습니다.
  2. 스킬을 부른 두 번은 “디버그 보고서” 꼴로 답하고, 테스트 말고도 코드 리뷰 규칙 같은 재발 방지책을 냈습니다. 다만 안내문 1단계인 “먼저 재현”은 스킬 쪽도 고치기 전에 하지 않았습니다.
  3. 스킬 안내문 기준 채점은 스킬 없이 7·6점, 스킬 8·8점이었습니다. 한 번에 API 단가로 0.19~0.22달러어치였고, 플러그인을 깔아 두기만 하고 한 번 돌렸을 때는 스킬이 불리지 않았습니다.

결과부터 보기: 테스트는 통과, 결제 금액은 틀림

실습 자료는 가상의 빵집 “밀밭베이커리”의 예약 주문 프로그램입니다. 가게와 손님, 숫자는 모두 지어낸 것입니다. 사장이 11월 21일 저녁 6시에 첫 주문 10% 쿠폰(WELCOME10)을 넣고 배달비 무료 기준을 25,000원에서 30,000원으로 올린 뒤, 손님 몇 명의 결제 금액이 이상하게 나왔다는 상황입니다.

자료넣어 둔 것
coupons.py · pricing.py · server.py쿠폰 계산, 금액 계산, 주문 처리 코드. 쿠폰 함수에 버그 하나
tests/test_pricing.py테스트 3개. 고치기 전에도 모두 통과
CHANGELOG.md11-21 배포 내용: 쿠폰 추가와 배달비 기준 변경
단톡방_1121.txt“쿠폰 안 쓰신 단골 주문이 10% 싸게”, “배달비 기준 바꾼 거 때문 아닐까요?”, “껐다 켠 뒤 처음 몇 건은 괜찮았는데 또 이상해요”
주문내역_1121.json · 주문기록_1121.log주문 12건과 서버가 남긴 계산 기록. 19:42에 서버 재시작

먼저 고치기 전 코드로 같은 주문 12건을 서버 재시작 없이 다시 계산해 봤습니다. 첫 쿠폰 주문(1042번) 뒤로는 쿠폰을 안 쓴 주문에도 할인이 붙습니다.

고치기 전 주문 프로그램으로 주문 12건을 다시 계산한 터미널 출력. 쿠폰을 안 쓴 주문에도 할인이 찍힘
고치기 전 코드로 계산한 주문 12건. 1043번부터 쿠폰이 없어도 할인이 찍힘

정답은 이렇습니다. 원인은 쿠폰 함수가 쓴 쿠폰 목록을 주문마다 새로 만들지 않고 서버가 켜져 있는 동안 계속 함께 쓰는 것입니다. 주문 기록에서 금액이 틀린 주문은 7건이고, 모두 손님에게 덜 받아 합계 21,300원이 빕니다. 배달비 계산은 맞습니다.

스킬 없이 2회차 → debug 스킬 2회차의 마지막 답 · Claude Code · 소넷 5.5 · 생각 깊이 중간

직접 눌러 보기: 스킬 없이 1 · 스킬 없이 2 · 스킬 1 · 스킬 2. 클로드가 마지막에 남긴 답과 고친 코드를 고치지 않고 웹페이지로만 바꿨습니다.

조건원인배달비 의심 거르기고친 뒤 12건틀린 주문 합계재발 방지책점수
스킬 없이 1맞음함12건 모두 맞음7건 21,300원없음7
스킬 없이 2맞음함12건 모두 맞음표만, 합계 없음없음6
스킬 1맞음함12건 모두 맞음7건 21,300원코드 리뷰 규칙8
스킬 2맞음함12건 모두 맞음7건 21,300원코드 리뷰 규칙8

직접 실행 확인한 날짜 2026-11-22

실행 환경
macOS 26.1 · Claude Code 2.1.299 · 소넷(Sonnet) 5.5 · 생각 깊이 중간 (5번 모두 같은 설정)
설치 난이도
명령 두 줄(공식 README)
비용
플러그인 무료. 한 번에 API 단가로 스킬 없이 0.19~0.20달러, 스킬 0.20~0.22달러어치
라이선스
Apache-2.0 · anthropics/knowledge-work-plugins(별 36,652개, 2026-11-22 기준)

debug 스킬에 들어 있는 것

Engineering 플러그인에는 스킬이 10개 들어 있고, debug는 그중 하나입니다. 안내문은 “오류 메시지나 스택 트레이스를 줄 때, 스테이징에선 되는데 운영에선 안 될 때, 배포 뒤에 뭔가 깨졌을 때” 쓰라고 적고 있습니다. 클로드 코드에서는 /engineering:debug 뒤에 증상을 적어 부릅니다.

단계안내문이 시키는 일
1. 재현(Reproduce)기대한 동작과 실제 동작, 정확한 재현 절차, 언제부터 누구에게 생겼는지
2. 범위 좁히기(Isolate)어느 부분·코드 경로인지, 최근 변경(배포·설정·의존성), 기록과 오류 메시지 확인
3. 진단(Diagnose)가설을 세워 확인하고, 증상이 아닌 근본 원인 찾기
4. 고치기(Fix)설명이 붙은 수정, 부작용과 예외 상황 검토, 회귀 테스트 제안

결과는 “Debug Report” 양식으로 내라고 되어 있습니다. 재현(기대·실제·절차), 근본 원인, 수정, 예방(추가할 테스트·둘 장치) 칸입니다. 플러그인에는 슬랙·깃허브·지라·데이터독 같은 외부 연결 10개도 함께 들어 있습니다. 안내문에는 모니터링이 연결돼 있으면 장애 시점의 기록을, 깃허브가 연결돼 있으면 최근 커밋을 찾아보라고 적혀 있습니다. 이 부분은 써 보지 않았습니다.

4번 모두 해낸 것: 한 줄 버그 찾기

원인은 쿠폰 함수의 첫 줄에 있습니다. def apply_coupons(order, subtotal, applied=[])처럼 기본값으로 빈 목록을 두면, 파이썬은 그 목록을 함수가 처음 만들어질 때 한 번만 만듭니다. 그래서 1042번 손님이 쓴 WELCOME10이 목록에 남아, 뒤에 들어온 쿠폰 없는 주문에도 10%가 붙었습니다. 4번 모두 이 줄을 원인으로 짚었습니다.

단톡의 실마리도 모두 이 원인으로 풀었습니다. 서버를 껐다 켜면 목록이 비어서 잠시 정상이었다가, 쿠폰 주문이 들어오면 다시 쌓입니다. “할인이 두 번 들어간 것 같다”는 말은 BREAD2000과 WELCOME10이 함께 남아 한 주문에 둘 다 붙은 경우였습니다. 직원이 의심한 배달비 기준 변경은 기록의 배달비가 모두 새 기준대로 맞다는 근거로 걸렀습니다.

테스트가 통과한 이유도 같은 답이었습니다. 기존 테스트 3개는 쿠폰 없는 주문 두 개를 먼저 계산하고, 쿠폰 주문을 맨 마지막에 계산합니다. 쿠폰이 다음 주문으로 넘어가는 순서가 테스트 안에 없었습니다.

고치기 전 코드로 테스트 3개를 돌려 모두 통과한 터미널 출력
고치기 전 코드로 돌린 테스트 3개. 모두 통과

고친 방법도 같았습니다. 기본값 applied=[]를 지우고 함수 안에서 주문마다 applied = []로 새로 시작하게 했습니다. 결과를 0원 아래로 못 내려가게 자르는 식의 덧대기는 한 번도 없었습니다. “앞 주문의 쿠폰이 다음 주문에 새지 않는다”는 회귀 테스트도 모두 더했습니다. 회귀 테스트는 고친 버그가 다시 생기지 않는지 지켜보는 테스트입니다.

스킬 없이 2회차에서 클로드가 고친 coupons.py 한 줄과 추가한 테스트 비교 화면
스킬 없이 2회차의 수정. coupons.py 두 줄과 테스트 2개 · Claude Code · 소넷 5.5 · 생각 깊이 중간

고친 코드는 따로 만든 검사로 확인했습니다. 새로 켠 프로그램에서 주문 12건을 연달아 계산해 정답과 비교하고, 원래 테스트 3개를 다시 돌리는 검사입니다. 12건이 모두 정답과 같았고 원래 테스트도 통과했습니다.

debug 스킬로 고친 코드로 같은 주문 12건을 계산한 터미널 출력. 쿠폰 없는 주문의 할인이 0원
debug 스킬 2회차가 고친 코드로 계산한 같은 주문 12건. 쿠폰 없는 주문은 할인 0원

마지막에는 모두 “이미 결제된 7건을 추가로 청구할지는 사장님이 정할 일”이라고 남기고, 고친 코드를 서버에 반영하고 다시 켜야 한다고 적었습니다. WELCOME10이 “첫 주문” 쿠폰인데 코드가 첫 주문인지 확인하지 않는다는 점도 두 번(스킬 없이 1, 스킬 1)이 따로 짚었습니다.

스킬을 불렀을 때 달라진 것

첫 번째 차이는 답의 꼴입니다. 스킬 쪽 두 번은 “디버그 보고서” 제목 아래 원인·수정·영향받은 주문·확인할 것·재발 방지 칸으로 답했습니다. 스킬 1회차는 주문 번호마다 쿠폰 목록이 어떻게 쌓였는지 표로 따라갔습니다. 스킬 없이 받은 두 번도 원인·수정·틀린 주문 표는 있었지만 재발 방지 칸이 없었습니다.

debug 스킬 1회차 보고서의 원인 칸과 주문별 상황 표
debug 스킬 1회차 보고서의 원인 칸. 주문마다 쿠폰이 쌓인 과정 · Claude Code · 소넷 5.5 · 생각 깊이 중간

두 번째 차이는 재발 방지책입니다. 스킬 쪽 두 번은 테스트를 더한 것 말고도 “함수 기본값에 [ ]나 { }를 쓰지 않는 것을 코드 리뷰 기준으로 삼으라”고 적었습니다. 스킬 2회차는 배포 때 쿠폰 쓴 주문 다음에 쿠폰 없는 주문을 직접 확인해 보라고도 했습니다. 스킬 없이 받은 두 번은 테스트를 더한 데서 끝났습니다.

debug 스킬 2회차 보고서의 확인이 필요한 부분과 재발 방지 칸
debug 스킬 2회차 보고서의 확인할 것·재발 방지 칸 · Claude Code · 소넷 5.5 · 생각 깊이 중간

세 번째 차이는 작습니다. 틀린 주문을 7건, 21,300원으로 합계까지 적은 것은 스킬 두 번과 스킬 없이 1회차였습니다. 스킬 없이 2회차는 표는 맞았지만 건수와 합계를 적지 않았습니다.

달라지지 않은 것도 있습니다. 안내문 1단계는 “재현”인데, 스킬 쪽 두 번도 틀린 코드를 먼저 돌려 보지 않았습니다. 다섯 번 모두 파일을 읽고 바로 고친 다음 테스트와 재계산을 돌렸습니다. 이번 버그는 기록만 읽어도 원인이 보였기 때문일 수 있습니다. 원인이 숨어 있는 버그라면 “고치기 전에 먼저 재현해서 보여 줘”라고 요청에 적는 편이 안전합니다.

깔아 두기만 했을 때도 따로 한 번 돌렸습니다. 플러그인을 붙이고 /engineering:debug 없이 같은 요청을 보내자 스킬이 불리지 않았고, 답은 스킬 없이 받은 것과 같은 꼴(7점)이었습니다. 한 번만 돌린 결과라 늘 그렇다고는 할 수 없습니다. 확실히 쓰려면 이름을 앞에 붙입니다.

복사해 쓰는 요청문과 실습 자료

아래 요청문을 그대로 썼습니다. 스킬 조건에서는 맨 앞에 /engineering:debug를 붙였습니다.

우리 빵집 '밀밭베이커리' 예약 주문 프로그램에서 어제(11월 21일 금요일) 저녁 쿠폰이랑 배달비 기준을 바꿔 올린 뒤로 손님 몇 분 결제 금액이 이상하게 나왔어. 이 폴더에 코드, 변경 기록, 단톡방 대화, 주문 내역, 주문 기록이 있어. 원인 찾아서 고쳐 줘. 지금은 더 답해 줄 사람이 없으니 자료만 보고 해 줘.

우리 프로그램에 쓸 때는 코드 폴더에서 증상과 바꾼 내용, 오류 메시지나 기록을 함께 적습니다. 안내문 팁도 “오류 메시지는 바꿔 말하지 말고 그대로”, “최근 무엇을 바꿨는지 적기”입니다.

실습 자료 내려받기(debug-practice.zip): 주문 프로그램 코드, 테스트, 변경 기록, 단톡, 주문 내역과 기록, 요청문, 채점 기준을 넣었습니다. 좋은 답이라면 원인으로 applied=[]를 짚고, 틀린 주문 7건과 합계 21,300원이 나옵니다.

1단계. 플러그인 넣기 (약 1분)

이 단계에서는 클로드 코드가 debug 안내문을 읽을 수 있게 합니다. 플러그인 README에 적힌 설치 명령은 터미널에서 아래 두 줄입니다. 이 설치 명령은 이번에 실행하지 않았고, 이 부분은 공식 문서 기준입니다.

claude plugin marketplace add anthropics/knowledge-work-plugins
claude plugin install engineering@knowledge-work-plugins

설치하지 않고 한 번만 써 보려면 저장소를 내려받아 --plugin-dir로 플러그인 폴더를 가리킵니다. 플러그인이 그 실행에만 붙습니다. 이번 실험은 이 방법으로 했습니다.

git clone https://github.com/anthropics/knowledge-work-plugins
claude --plugin-dir knowledge-work-plugins/engineering

이렇게 나오면 성공 이번 실행에서는 명령 목록에 engineering:debug가 올라왔고, 스킬 두 번 모두 세션 기록에 안내문 내용(REPRODUCE·ISOLATE·DIAGNOSE·FIX)이 들어간 것을 확인했습니다.

  • command not found: claude가 나오면 터미널을 닫았다 다시 열고 claude --version을 먼저 확인합니다.
  • 명령 목록에는 클로드 코드에 원래 있는 /debug도 따로 보입니다. 이 글의 스킬은 앞에 engineering:이 붙은 쪽입니다.
  • 필요 없어지면 claude plugin uninstall engineering@knowledge-work-plugins로 지웁니다.

같은 플러그인의 code-review는 엔지니어링 플러그인 리뷰에서, incident-response는 장애 경위서 글에서 써 봤습니다.

2단계. 증상을 적고 고치게 하기 (약 1분)

이 단계에서는 버그를 찾아 고치게 합니다. 코드 폴더에서 터미널로 claude를 켜고 위 요청문을 붙여 넣습니다. 이번 실험과 걸린 시간은 claude -p로 한 번에 보낸 것입니다. 채점 기준 10개는 실행 전에 스킬 안내문의 네 단계와 보고서 양식에서 뽑아 정해 두었습니다.

이렇게 나오면 성공 coupons.py의 기본값 한 줄이 바뀌고 tests 폴더에 테스트가 1~2개 늘어납니다. 4번 모두 1분이 채 안 걸렸습니다.

  • 고쳤다는 말만 믿지 말고, 고친 코드로 문제가 났던 주문을 다시 계산해 봅니다. 이번에는 4번 모두 스스로 server.py로 다시 계산해 보여 줬습니다.
  • 원본을 남겨 두고 싶다면 요청에 “고치기 전에 원본을 백업해 줘”를 넣습니다. 이번 4번은 백업 없이 바로 고쳤습니다.
  • 금액이 걸린 버그라면 영향받은 주문 목록과 합계를 따로 달라고 요청합니다. 스킬 없이 2회차처럼 합계를 빼먹을 수 있습니다.
채점 항목없이 1없이 2스킬 1스킬 2
기대값과 실제값을 숫자로OOOO
고치기 전에 재현해 보이기XXXX
배달비 변경 의심 거르기OOOO
원인(기본값 목록 공유)과 재시작 효과OOOO
근본 수정(덧대기 아님)OOOO
숨은 검사 12건·원래 테스트 통과OOOO
회귀 테스트 추가OOOO
틀린 주문 7건·21,300원OXOO
재현·원인·수정·예방 칸을 다 갖춘 보고서XXXX
테스트 말고 재발 방지 장치XXOO
합계7688

보고서 항목은 스킬 쪽도 0점입니다. 원인·수정·예방 칸은 있었지만 재현 절차 칸이 없었습니다.

실행 기록 · <작업 폴더>/tools/run.sh, <작업 폴더>/runs.tsv

# 같은 요청문. 스킬 조건은 --plugin-dir·--add-dir과 맨 앞 /engineering:debug, 깔아 두기만은 --plugin-dir만
CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 claude -p "$(cat tools/request.txt)" --model claude-sonnet-5-5 --effort medium \
  --setting-sources project,local --permission-mode acceptEdits [--plugin-dir skill/engineering --add-dir skill/engineering] \
  --allowedTools "Bash(ls:*),Bash(python3:*),Bash(python:*),Bash(cat:*),Bash(find:*),Bash(grep:*),Bash(wc:*),Read,Write,Edit,Skill,Glob,Grep" --disallowedTools "WebSearch,WebFetch" --output-format stream-json --verbose

조건	회차	불린 스킬	걸린 시간	사용량(API 단가)	턴	채점
스킬 없이	1	없음	34초	0.20달러	15	7/10
스킬 없이	2	없음	32초	0.19달러	15	6/10
스킬(/engineering:debug)	1	/engineering:debug	38초	0.22달러	15	8/10
스킬(/engineering:debug)	2	/engineering:debug	37초	0.20달러	14	8/10
깔아 두기만	1	없음(안 불림)	28초	0.19달러	14	7/10

$ python3 tools/verify.py runs/skill-2
12건 일치 12/12, 기존 테스트 통과

이런 사람에게 권합니다

  • ✅ 고친 내용을 팀이나 사장님께 보고해야 하는 개발자. 원인·수정·영향·재발 방지가 한 문서로 나옵니다.
  • ✅ 같은 실수가 되풀이되는 작은 팀. 테스트 말고 코드 리뷰 규칙 같은 장치까지 제안받습니다.
  • ❌ 버그만 빨리 고치면 되는 사람. 원인 찾기와 수정, 테스트 추가는 스킬 없이도 같았습니다.

한계와 주의할 점

  • 조건마다 2번씩, 지어낸 작은 프로그램으로 해 본 결과입니다. 1점 차이가 스킬 때문인지 우연인지는 이 횟수로 가릴 수 없습니다.
  • 채점 기준을 스킬 안내문에서 뽑았기 때문에 스킬 쪽이 유리한 구조입니다.
  • 이번 버그는 파일 몇 개만 읽어도 보이는 크기였습니다. 파일이 수백 개이거나 원인이 기록에 안 남는 버그에서는 결과가 다를 수 있습니다.
  • 처음 돌린 4번에는 이 맥의 전역 지침(디버깅 규칙)이 함께 실려, 스킬 없는 쪽이 그 규칙을 읽었습니다. 조건을 맞추려고 전역 지침을 끄고 다시 돌린 결과만 썼습니다. 그 첫 실행의 스킬 없는 두 번은 고치기 전에 틀린 코드를 먼저 돌려 봤습니다. 평소 지침 파일(CLAUDE.md)에 디버깅 규칙을 적어 두면 결과가 달라질 수 있다는 뜻입니다.

대안

이름다른 점이럴 때 고르세요
클로드 코드에 요청만설치 없음. 원인·수정·회귀 테스트는 같고 보고서·재발 방지 칸은 없음혼자 빨리 고칠 때
debug 스킬(이 글)디버그 보고서 꼴, 코드 리뷰 규칙 같은 재발 방지책고친 내용을 보고할 때
pr-review-toolkit올리기 전에 검토 에이전트 6개가 코드를 봄버그가 생기기 전에 막고 싶을 때
incident-response(장애 경위서)사고 뒤 심각도·타임라인·조치표가 있는 경위서손님 피해가 커서 경위서가 필요할 때

자주 묻는 질문

디버깅이 뭔가요?

프로그램이 기대와 다르게 움직이는 원인, 곧 버그를 찾아 고치는 일입니다. 보통 같은 문제를 다시 일으켜 보고(재현), 원인이 있는 곳을 좁히고, 고친 뒤 다시 확인하는 순서로 합니다.

테스트를 다 통과했는데 왜 버그가 나나요?

테스트가 확인하지 않는 순서나 상황에서 생기는 버그라서입니다. 이번 예에서는 테스트가 주문을 하나씩만 계산해서, 앞 주문의 쿠폰이 다음 주문에 남는 상황이 테스트 안에 없었습니다.

파이썬 함수 기본값에 빈 목록을 쓰면 왜 문제인가요?

기본값은 함수가 만들어질 때 한 번만 만들어지고, 그 뒤 모든 호출이 같은 목록을 씁니다. 그래서 한 번 넣은 값이 다음 호출에도 남습니다. 기본값을 None으로 두고 함수 안에서 새 목록을 만드는 것이 보통의 해결법입니다.

출처

anthropics/knowledge-work-plugins 저장소, Engineering 플러그인, debug SKILL.md (2026-11-22 확인)