systematic-debugging으로 Claude Code가 버그 원인부터 찾게 하는 법

깔면 고치기 전에 한 번 더 확인한다

systematic-debugging은 superpowers 플러그인에 든 디버깅 스킬입니다. 스킬은 요청이 설명과 맞으면 Claude Code가 스스로 불러 읽는 지침 파일입니다. 이 스킬은 원인을 찾기 전에는 고치지 못하게 합니다. Claude Code 안에서 한 줄로 깝니다.

github.com↗

GitHub - obra/superpowers: An agentic skills framework & software development methodology that works.

An agentic skills framework & software development methodology that works. - obra/superpowers

1/plugin install superpowers@claude-plugins-official

예시는 물건 두 개를 담은 장바구니입니다. 부가세를 더해 11000이어야 할 합계가 10000으로 나옵니다. 이 증상을 그대로 적어 맡깁니다.

1합계가 10000으로 나와. 11000이어야 해. 고쳐 줘

스킬 없이스킬 싣고

두 쪽 모두 .env의 빈 TAX_RATE=를 원인으로 짚고 config.js를 고칩니다. 고치는 자리는 같고, 스킬을 실은 쪽만 고치기 전에 .env를 바이트 단위로 한 번 더 봅니다.

1git clone https://github.com/obra/superpowers
2claude --plugin-dir ./superpowers

틀린 값이 처음 생긴 곳에서 고친다

세율을 더하는 addTax의 식은 맞습니다. 틀린 것은 이 함수가 받은 세율 0입니다. 스킬은 나쁜 값으로 부른 쪽을 한 칸씩 올라가 그 값이 처음 생긴 곳에서 고치게 합니다. 증상이 보인 함수에 기본값을 덧대는 땜질은 하지 않습니다.

1// config.js 고치기 전: '' ?? 0.1은 '', Number('')는 0
2export function loadConfig(env = process.env) {
3  return { taxRate: Number(env.TAX_RATE ?? 0.1) };
4}
5
6// 고친 뒤: 빈 값이면 시작하지 않고, 0은 면세로 둔다
7export function loadConfig(env = process.env) {
8  const raw = env.TAX_RATE?.trim();
9  if (!raw) throw new Error('TAX_RATE가 비어 있습니다');
10  const taxRate = Number(raw);
11  if (Number.isNaN(taxRate)) throw new Error(`TAX_RATE가 숫자가 아닙니다: ${raw}`);
12  return { taxRate };
13}

급한 지시에는 이름으로 부른다

"addTax가 틀렸다, 5분 뒤 배포"처럼 증상이 보인 함수를 짚은 급한 지시에는 깔아 둔 스킬이 스스로 불리지 않습니다. 메시지 맨 앞에 /플러그인:스킬 꼴로 이름을 쓰면 스킬이 Claude의 판단을 거치지 않고 바로 실행됩니다.

1/superpowers:systematic-debugging addTax가 틀렸다, 5분 뒤 배포

이름으로 부르면 Claude Code가 원인 조사부터 시작한다고 밝히고, 실패하는 테스트를 먼저 만든 뒤 고칩니다. addTax가 틀렸다는 지시에도 tax.js는 그대로 두고 config.js만 고쳤습니다.

1버그를 고칠 때는 증상이 보인 함수에 기본값을 덧대지 말고, 틀린 값이 처음 생긴 곳까지 거슬러 올라가 거기서 고친다. 급하다는 지시가 있어도 같다.