systematic-debugging

systematic-debugging 스킬 개요

systematic-debugging 스킬은 에이전트와 개발자가 감에 의존한 땜질식 수정은 줄이고, 근본 원인은 더 빨리 찾아내도록 돕는 구조화된 디버깅 워크플로입니다. 핵심 원칙은 단순합니다. 코드를 바꾸기 전에 먼저 조사하는 것입니다. 그래서 테스트 실패, flaky 동작, 운영 버그, 빌드 문제, 통합 이슈처럼 “일단 빨리 고치기”가 오히려 진짜 원인을 가릴 수 있는 상황에 특히 잘 맞습니다.

이 스킬이 특히 잘 맞는 사람

다음에 해당하면 systematic-debugging를 쓰는 편이 좋습니다.

• 수정했는데도 계속 실패하거나 반쯤만 해결되는 경우가 많다
• 시간 압박 속에서 디버깅하고 있다
• AI assistant가 증상만 패치하지 말고 속도를 늦추고 조사부터 하게 만들고 싶다
• 버그, flaky 테스트, 예상 밖 동작에 대해 반복 가능한 절차가 필요하다

겉으로는 원인이 뻔해 보여도, 왜 그런 일이 생기는지는 아직 모를 때 특히 유용합니다.

이 스킬이 실제로 해결해 주는 일

이 스킬의 목적은 단순히 “수정안을 만들어내는 것”이 아닙니다. 실제로는 다음 일을 돕습니다.

1. 문제를 재현하고,
2. 원인을 추적하고,
3. 설명 가능한 가설을 한 번에 하나씩 검증한 뒤,
4. 그다음에야 정확히 겨냥한 수정을 적용하는 것

겉보기에는 더 느려 보일 수 있지만, 실제로는 재작업, 실패한 패치, 추측 때문에 새로 생기는 버그를 줄이는 경우가 많습니다.

systematic-debugging이 다른 점

일반적인 프롬프트는 증상에서 바로 해결책으로 뛰어갑니다. 하지만 systematic-debugging skill은 그렇게 하지 않도록 강하게 방향이 잡혀 있습니다. 이 repo는 “Iron Law”에 가까운 워크플로를 강조합니다. 즉, 근본 원인 조사가 끝나기 전에는 수정하지 않는다는 원칙입니다.

주변 파일들도 있어서, 단순한 디버깅 체크리스트보다 훨씬 실전적으로 쓸 수 있습니다.

• root-cause-tracing.md: 눈에 보이는 에러와 실제 원인이 멀리 떨어져 있을 때 도움
• condition-based-waiting.md: 임의 대기 때문에 생기는 flaky async 테스트 문제를 다룰 때 도움
• defense-in-depth.md: 일회성 검증 수정에 그치지 않고 구조적 예방으로 확장할 때 도움
• find-polluter.sh: 파일이나 상태를 오염시키는 테스트를 분리해낼 때 도움

잘 맞는 이슈 유형

systematic-debugging for Debugging은 다음 같은 상황에 특히 잘 맞습니다.

• 아직 이유를 설명할 수 없는 테스트 실패
• CI에서 발생하는 flaky 테스트
• 이전 수정이 오래 버티지 못했던 버그
• 스택 깊숙한 곳에서 터지는 에러
• 잘못된 상태, 유출된 파일, 잘못된 경로, race condition, 타이밍 문제

이 스킬이 약한 경우

다음처럼 애초에 디버깅 과제가 아닌 경우에는 굳이 쓰지 않아도 됩니다.

• 단순한 기능 개발
• 설명해야 할 실패 동작이 없는 일반적인 리팩터링
• purely cosmetic changes

그래도 “예상하지 못한 동작”에 대응하는 상황이라면, systematic-debugging으로 시작하는 쪽이 대체로 더 안전합니다.

systematic-debugging 스킬 사용법

systematic-debugging 설치 맥락

이 생태계 전반에서 쓰는 Skills CLI 패턴을 따른다면, 설치는 다음처럼 하면 됩니다.

npx skills add https://github.com/obra/superpowers --skill systematic-debugging

그다음 에이전트 환경에서 호출하거나, 스킬 폴더 안의 소스 파일을 읽어 수동으로 같은 프로세스를 따라 써도 됩니다.

먼저 읽어야 할 파일

빠르게 핵심을 파악하는 systematic-debugging guide가 필요하다면, 다음 순서로 읽는 것이 좋습니다.

1. skills/systematic-debugging/SKILL.md
2. skills/systematic-debugging/root-cause-tracing.md
3. skills/systematic-debugging/condition-based-waiting.md
4. skills/systematic-debugging/defense-in-depth.md
5. skills/systematic-debugging/find-polluter.sh

이 순서를 권하는 이유:

• SKILL.md는 반드시 따라야 하는 4단계 워크플로를 설명합니다
• root-cause-tracing.md는 증상이 한참 아래쪽에서 보일 때 유용합니다
• condition-based-waiting.md는 flaky async 테스트를 고칠 때 쓸 수 있는 구체적인 패턴을 제공합니다
• defense-in-depth.md는 최종 수정안을 더 단단하게 만드는 데 도움을 줍니다
• find-polluter.sh는 테스트 오염을 분리해내는 실전용 도구입니다

이 스킬이 사용자에게 필요로 하는 입력

systematic-debugging usage의 품질은 사용자가 주는 입력에 크게 좌우됩니다. 가능하면 다음을 함께 제공하세요.

• 정확한 에러 메시지
• stack trace
• 재현 단계
• 기대 동작과 실제 동작의 차이
• OS, runtime, test runner, CI에서만 나는지 로컬에서도 나는지 같은 환경 정보
• 최근 코드 변경 사항
• 문제가 항상 재현되는지, 아니면 flaky한지
• 이미 시도해 본 것

이 정보가 없으면 모델이 추측에 의존할 가능성이 높아집니다.

거친 버그 리포트를 강한 프롬프트로 바꾸는 법

약한 프롬프트:

Test is failing. Help fix it.

더 강한 프롬프트:

Use systematic-debugging on this failing test. Do not propose a fix until root cause investigation is complete. Here is the exact error, stack trace, reproduction command, recent changes, and the one behavior difference between local and CI. Identify likely root causes, suggest the minimum investigation steps, and keep hypotheses separate.

이 프롬프트가 더 잘 먹히는 이유는, 구현보다 조사 결과를 먼저 요구하기 때문입니다.

실전용 프롬프트 템플릿

systematic-debugging usage에는 아래 구조가 잘 맞습니다.

• Issue: 무엇이 실패했는지
• Reproduction: 정확한 명령어나 재현 단계
• Evidence: 로그, trace, 스크린샷, 실패한 assertion
• Scope: 로컬만인지, CI만인지, 특정 머신만인지, 모든 환경인지
• Recent changes: commits, dependency bump, config 수정
• Constraints: API는 못 바꿈, 최소 패치 필요, 마감 있음 등
• Request: 먼저 근본 원인을 조사하고, 그다음 수정안 하나만 제안해 달라

예시:

Use systematic-debugging for this Jest failure. Repro: npm test src/foo.test.ts. Error: Timeout waiting for TOOL_RESULT event after 5000ms. It fails in CI and under parallel runs, not always locally. We recently changed thread event handling. First investigate root cause, then propose one focused fix and one validation plan.

4단계 워크플로를 순서대로 따르기

이 repo는 네 단계에 중심을 둡니다. 실전에서는 이렇게 쓰면 됩니다.

1. Root cause investigation
   에러를 꼼꼼히 읽고, 재현을 안정적으로 만들고, 무엇이 바뀌었는지 확인하고, 증거를 수집합니다.
2. Pattern analysis
   타이밍, 환경, 입력 형태, 상태 누수, 호출 체인 같은 패턴이 있는지 봅니다.
3. Hypothesis testing
   설명 가능한 가설을 한 번에 하나씩 세우고 검증합니다. 여러 변수를 동시에 바꾸지 않습니다.
4. Implementation
   원인에 대한 증거가 충분히 쌓인 뒤에만 수정하고, 수정 후 검증합니다.

1단계가 약하면 그다음 단계는 전부 흔들립니다.

flaky 테스트에서 systematic-debugging을 쓰는 법

이 repo는 이 부분에서 특히 실전성이 높습니다. 테스트가 sleep, setTimeout, 임의의 대기 시간에 의존한다면 condition-based-waiting.md와 condition-based-waiting-example.ts를 꼭 확인해 보세요.

핵심 전환점은 이렇습니다.

• 나쁜 패턴: async 작업이 끝날 시간을 추측해서 기다림
• 더 나은 패턴: 완료를 증명하는 조건이 충족될 때까지 기다림

이 차이가 중요한 이유는, 많은 “랜덤” 실패가 사실은 타이밍 추측에 가려진 race condition이기 때문입니다.

증상이 하류에서 보일 때 쓰는 법

에러가 스택 깊은 곳에서 터지거나, 잘못된 데이터가 처음 생긴 지점과 멀리 떨어진 곳에서 보인다면 root-cause-tracing.md를 활용하세요. 흐름은 다음과 같습니다.

• 당장 실패한 줄을 확인하고
• 호출자를 한 단계 위로 추적하고
• 잘못된 상태가 처음 생긴 지점을 찾을 때까지 계속 올라가고
• 크래시가 난 지점만이 아니라 원천에서 수정합니다

이 부분은 systematic-debugging skill의 가장 가치 있는 구성 요소 중 하나입니다. 많은 버그가 사실은 더 이른 시점의 잘못된 상태가 만든 증상에 불과하기 때문입니다.

polluter finder 사용법

파일, 디렉터리, 상태를 남겨두는 테스트를 찾고 싶다면, 즉흥적으로 루프를 짜기 전에 find-polluter.sh부터 읽어보는 편이 낫습니다.

사용 패턴:
./find-polluter.sh <file_or_dir_to_check> <test_pattern>

스크립트에 나온 예시:
./find-polluter.sh '.git' 'src/**/*.test.ts'

눈에 보이는 실패 테스트가 아니라, 숨어 있는 테스트 오염 때문에 실패가 발생하는 경우 특히 유용합니다.

처음 설치하고 쓸 때 가장 잘 먹히는 워크플로

systematic-debugging install과 첫 사용 시에는 다음 흐름이 안정적입니다.

1. 스킬 설치
2. SKILL.md 읽기
3. 정확한 실패 증거 수집
4. 에이전트에게 수정 없이 조사부터 하라고 요청
5. 증거가 가장 많은 가설 선택
6. 그 가설만 검증
7. 범위를 좁힌 수정 하나만 적용
8. 버그 원인이 잘못된 데이터나 여러 진입 경로에서 왔다면 validation 또는 defense-in-depth 추가

이 흐름은 가장 흔한 실패 패턴, 즉 원인을 이해하기 전에 코드를 바꾸는 실수를 막아줍니다.

이 스킬로 하지 말아야 할 것

systematic-debugging에게 다음을 시키지 마세요.

• 처음부터 여러 수정안을 한꺼번에 브레인스토밍하기
• 버그를 재현하기도 전에 넓은 영역을 갈아엎기
• 설명 없이 “그냥 테스트만 통과시켜 달라”고 하기
• 의심되는 원인을 여러 개 한 번에 패치하기

이런 지름길은 스킬의 설계 의도와 정면으로 충돌하고, 결과 품질도 떨어뜨립니다.

systematic-debugging 스킬 FAQ

systematic-debugging은 복잡한 버그에만 쓰는 건가요?

아닙니다. 이 repo의 관점은 단순한 버그에도 여전히 근본 원인이 있다는 것입니다. 문제를 얼핏 단순해 보여서 빨리 패치하고 싶어질 때 오히려 이 스킬의 가치가 더 커집니다.

일반적인 디버깅 프롬프트와 무엇이 다른가요?

일반 프롬프트는 속도와 추측성 수정을 보상하는 경우가 많습니다. systematic-debugging은 조사, 가설, 구현을 분리하도록 강제합니다. 그래서 틀린 패치가 줄고 설명도 더 나아지는 경우가 많습니다.

systematic-debugging은 초보자도 쓰기 쉬운가요?

네. 구체적인 증거만 제공할 수 있다면 충분히 쓸 수 있습니다. 과정은 엄격하지만 단계 자체는 이해하기 쉽습니다. 재현하고, 살펴보고, 추적하고, 가설 하나를 검증한 뒤, 수정합니다. 무작위 시행착오를 막아 준다는 점에서 오히려 초보자에게 더 도움이 될 수도 있습니다.

언제 systematic-debugging을 쓰지 말아야 하나요?

다음에는 주된 패턴으로 쓰지 않는 편이 낫습니다.

• feature ideation
• architecture brainstorming
• 실패 현상과 무관한 code generation
• 설명해야 할 깨진 동작이 없는 purely visual tweaks

무언가가 잘못되었고, 단순한 패치가 아니라 원인이 필요할 때 쓰세요.

CI에서만 나는 실패에도 도움이 되나요?

네. systematic-debugging은 CI 전용 실패나 부하에 민감한 실패에 잘 맞습니다. 환경 차이를 비교하고, 조건을 재현하고, 타이밍과 상태에 대한 가정을 점검하게 만들기 때문에, 막연한 추측보다 훨씬 낫습니다.

flaky async 테스트에도 도움이 되나요?

네. 그리고 이 repo는 이 점에서 평균 이상으로 강합니다. condition-based-waiting.md와 예시 TypeScript 파일이 임의 대기에서 벗어나 조건 기반 동기화로 옮겨 가는 구체적인 길을 제시합니다.

이 스킬은 도구가 포함되어 있나요, 아니면 조언만 있나요?

대부분은 프로세스 가이드이고, 여기에 몇 가지 구체적인 보조 파일이 더해져 있습니다. 가장 실용적인 헬퍼는 find-polluter.sh이고, condition-based waiting 예제는 일부 TypeScript 테스트 환경에서 그대로 재활용할 수 있습니다.

어떤 스택에서든 systematic-debugging을 쓸 수 있나요?

대체로 그렇습니다. 핵심 방법론은 특정 스택에 묶여 있지 않습니다. 예시는 TypeScript, shell, 테스트 워크플로 쪽에 조금 더 기울어져 있지만, 조사 프로세스 자체는 언어와 프레임워크를 가리지 않고 적용할 수 있습니다.

systematic-debugging 스킬 개선 방법

수정 요청 전에 더 좋은 증거를 제공하기

가장 큰 레버는 입력 품질입니다. 더 나은 systematic-debugging 결과를 원한다면 다음을 포함하세요.

• 정확한 재현 명령 하나
• 정확한 에러 블록 하나
• 최소한의 실패 테스트 또는 파일 하나
• 최근 바뀐 내용
• 문제가 항상 재현되는지 여부

이렇게 해야 추론이 아니라 증거를 바탕으로 동작할 수 있습니다.

구현 전에 조사 결과를 먼저 요구하기

잘 작동하는 프롬프트는 성급한 수정을 명시적으로 막습니다. 예를 들면:

Use systematic-debugging. First produce root-cause investigation findings and the top 2 hypotheses with evidence for each. Do not suggest code changes yet.

이렇게 하면 증상을 읽는 단계와 실제 코드 수정 사이에 체크포인트가 생겨서 답변 품질이 좋아집니다.

한 번에 가설 하나만 다루게 만들기

흔한 실패 패턴은 여러 가능 원인을 한 패치에 뒤섞는 것입니다. 다음을 요청하세요.

• 가장 유력한 가설
• 그 가설을 반증할 수 있는 가장 작은 테스트
• 어떤 결과가 나오면 그 가설을 확인할 수 있는지

이렇게 해야 워크플로가 스킬의 의도에 맞게 유지됩니다.

flaky 테스트 시나리오용 프롬프트 개선하기

flaky 테스트에 systematic-debugging for Debugging을 쓸 때는 다음 정보를 함께 주는 편이 좋습니다.

• pass/fail 빈도
• 병렬 실행이나 CI와 실패가 연관되는지
• sleeps, waits, retries, polling 사용 여부
• 테스트가 관찰하려는 정확한 이벤트 또는 상태

이 정보가 있어야 모델이 condition-based-waiting.md가 관련 있는 보조 패턴이라는 점을 더 쉽게 알아차릴 수 있습니다.

SKILL.md만 보지 말고 소스 인접 파일도 함께 쓰기

첫 출력이 너무 일반적이라면, 모델이 보조 문서까지 보게 하세요.

• 하류 증상에는 root-cause-tracing.md
• 타이밍/race 이슈에는 condition-based-waiting.md
• validation 전략에는 defense-in-depth.md
• 테스트 오염에는 find-polluter.sh

에이전트가 대표 워크플로만이 아니라, 이런 특화된 보조 자료까지 활용할 때 스킬의 성능이 더 좋아집니다.

첫 패스 이후 범위를 더 좁히기

첫 결과가 너무 넓다면 다음 정보로 범위를 다시 조이세요.

• 정확히 봐야 할 subsystem
• 잘못된 데이터가 유입된 것으로 의심되는 경계
• 문제가 처음 나타난 commit
• 가장 작은 실패 재현 케이스

광범위한 디버깅 프롬프트는 대개 광범위한 계획을 낳습니다. 범위를 좁혀야 근본 원인 추적의 질이 올라갑니다.

진단만이 아니라 최종 수정도 개선하기

근본 원인을 찾은 뒤에는 다음을 요청하세요.

• 최소 수정안
• 회귀 테스트 하나
• 재발을 막는 validation layer 하나

이때 defense-in-depth.md가 특히 유용합니다. 버그가 잘못된 입력이나 우회 가능한 가정에서 비롯됐다면, 패치 한 번으로는 충분하지 않을 수 있습니다.

이런 흔한 실패 패턴을 경계하기

부실한 systematic-debugging usage는 보통 다음에서 비롯됩니다.

• 불완전한 에러 텍스트
• 믿을 만한 재현 방법 부재
• 너무 이른 수정 요청
• 테스트 실행 사이에 여러 요소를 동시에 변경함
• 그럴듯한 첫 설명을 곧바로 사실로 취급함

이런 함정만 피하면, 이 스킬은 일반적인 “이거 디버깅해 줘” 프롬프트보다 훨씬 더 큰 가치를 줍니다.