systematic-debugging으로 버그의 근본 원인을 파악하기
機械翻訳 / Machine-translated
機械翻訳 / Machine-translated
원문: systematic-debugging으로 버그의 근본 원인을 파악하기（cccskills）
스킬 페이지: systematic-debugging
이 글의 결론
systematic-debugging을 넣으면, Claude Code나 Codex는 버그나 테스트 실패의 원인을 확인한 후에 수정하게 됩니다.
재현 절차나 로그, 최근 변경 사항으로부터 가설을 세워 검증하고, 마지막에는 실패 테스트로 수정을 확인하는 데까지 순서대로 진행하는 스킬입니다.
이 글에서는 조사의 4단계와 설치 방법, 요청문 예시, 사용 시 주의점을 소개합니다.
systematic-debugging을 넣으면, 에이전트는 원인을 확인하기 전까지 수정 방안을 제시하지 않습니다.
예를 들어 다음과 같이 부탁했다고 합시다.
이 테스트 실패를 재현하고, 최근 변경 사항과 로그로부터 원인을 조사해 주세요
에이전트는 먼저 에러 메시지와 스택 트레이스를 끝까지 읽고, 행 번호와 파일 경로, 에러 코드를 기록합니다.
다음으로 테스트를 실행하여 매번 재현되는지 확인하는 흐름입니다.
이어서 git diff나 최근 커밋, 의존 관계나 설정 변경을 살펴봅니다.
재현되지 않는 경우에도 추측으로 수정하지 않고, 추가 데이터를 수집하는 순서로 진행됩니다.
원인 후보가 보이면, 같은 코드베이스에서 정상적으로 동작하는 유사 코드와 비교하여 작은 차이를 하나씩 나열합니다.
그 위에서 작성하는 가설은 "원인은 X이고, 이유는 Y다"라는 형태의 하나뿐.
이를 최소한의 변경으로 확인합니다.
가설이 빗나가도 수정을 덧붙이지 않고, 새로운 가설을 다시 세우는 흐름입니다.
가설이 맞아도 바로 코드를 수정하지는 않습니다.
먼저 결함을 재현하는 실패 테스트를 만들고, 근본 원인에 대한 수정을 하나만 적용합니다.
마지막으로 그 테스트가 통과하는지, 다른 테스트가 실패하지 않는지를 확인한 후 결과가 반환됩니다.
systematic-debugging은 디버깅을 4단계로 나누고, 이전 단계를 마치기 전에는 다음으로 넘어가지 못하게 하는 스킬입니다.
핵심은 "근본 원인을 조사하기 전에 수정하지 않는다"는 원칙으로, 증상만 없애는 수정은 실패로 간주합니다.
각 단계의 내용은 다음과 같습니다.
| 단계 | 에이전트가 하는 것 | 다음으로 넘어가는 조건 |
|---|---|---|
| 1. 근본 원인 조사 | 에러 읽기, 재현, 최근 변경 확인, 증거 수집 | 무슨 일이 일어나고 있고, 왜 일어나는지 알 수 있음 |
| 2. 패턴 분석 | 정상 동작하는 예시나 참조 구현을 찾아 비교 | 결함이 있는 코드와의 차이를 특정할 수 있음 |
| 3. 가설과 검증 | 가설을 하나 세우고 최소한의 변경으로 시도 | 가설이 확인됨 (빗나가면 새로운 가설로) |
| 4. 구현 | 실패 테스트 작성, 수정 하나 적용, 확인 | 결함이 해소되고 테스트가 통과 |
여러 처리에 걸친 결함에서는 수정 전에 진단용 로그를 넣습니다.
CI에서 빌드, 서명으로 이어지는 흐름이나 API에서 서비스, 데이터베이스로 연결되는 처리가 대상입니다.
각 처리의 경계에서는 들어오는 데이터와 나가는 데이터, 환경 변수나 설정의 전달을 기록합니다.
그 후 한 번 실행하여 어디서 문제가 발생하는지 확인합니다.
문제가 있는 레이어를 파악한 후에 그 레이어만 자세히 조사하는 절차입니다.
호출의 깊은 곳에서 에러가 발생한 경우에는, 잘못된 값이 어디서 왔는지를 호출 원점으로 역추적합니다.
수정을 적용하는 곳은 증상이 나타난 위치가 아니라 값이 생성된 위치라는 것이 원칙입니다.
이 역방향 추적 절차에는 해설이 붙어 있습니다.
원인을 파악한 후에 여러 레이어에서 입력을 검증하는 방법이나, 고정 대기 시간을 조건 확인으로 대체하는 방법도 같은 해설 대상입니다.
에이전트는 수정을 시도할 때마다 횟수를 세고, 3번 이상 실패하면 4번째 수정으로 넘어가지 않습니다.
수정할 때마다 다른 곳에서 새로운 문제가 발생하는 상태나, 수정에 대규모 재작성이 필요해지는 상태는 설계 자체의 문제로 처리합니다.
이때 에이전트는 추가 수정을 멈추고, 설계를 재검토할지 여부를 사용자와 협의합니다.
충분히 조사한 결과, 환경이나 타이밍, 외부 요인이 원인임을 알게 되는 경우도 있습니다.
그 경우에는 조사 내용을 기록하고, 재시도나 타임아웃, 에러 메시지로 대처합니다.
아울러 다음 조사를 대비하여 모니터링이나 로그를 추가합니다.
systematic-debugging은 GitHub의 obra/superpowers에 포함된 스킬 중 하나입니다.
리포지토리 스타 수는 309,845개.
같은 리포지토리에는 브레인스토밍이나 코드 리뷰 등 개발 흐름에 맞는 스킬들이 나열되어 있습니다.
터미널에서 다음 명령어를 실행하면, obra/superpowers에서 systematic-debugging만 추가할 수 있습니다.
넣을 에이전트는 Claude Code나 Codex 등에서 실행 시 선택하는 방식입니다.
npx skills add https://github.com/obra/superpowers --skill systematic-debugging
에이전트에게 맡기는 경우, 다음 내용을 그대로 보내 주세요.
내용 확인을 먼저 부탁하는 형식이므로, 에이전트는 의심스러운 처리가 없는지 확인한 후 배치까지 진행합니다.
次の Agent Skill をインストールしてください。
https://github.com/obra/superpowers/tree/main/skills/systematic-debugging
まず SKILL.md と付属ファイルの中身を確認し、不審な処理（外部への送信、認証情報の読み取りなど）がないことを確かめてから、Claude Code なら ~/.claude/skills/systematic-debugging/、Codex なら ~/.agents/skills/systematic-debugging/ に配置してください。
배치 위치는 사용하는 에이전트와 적용 범위에 따라 결정됩니다.
| 에이전트 | 모든 프로젝트에서 사용 | 특정 프로젝트에서만 사용 |
|---|---|---|
| Claude Code | ~/.claude/skills/systematic-debugging/ | 프로젝트의 .claude/skills/systematic-debugging/ |
| Codex | ~/.agents/skills/systematic-debugging/ | 프로젝트의 .agents/skills/systematic-debugging/ |
설치 여부를 확인하는 방법은 폴더 안에 SKILL.md가 있는지 보는 것입니다.
Claude Code에 전체용으로 설치한 경우, 다음 명령어로 내용을 확인할 수 있습니다.
ls ~/.claude/skills/systematic-debugging/
SKILL.md 외에 해설용 Markdown 파일, TypeScript 예시, 셸 스크립트가 나열되어 있으면 배치 완료입니다.
이 스킬은 수정을 제안하기 전에 사용하는 것을 전제로 만들어졌습니다.
버그나 테스트 실패, 예기치 않은 동작을 만났을 때가 사용 시점입니다.
요청문에 증상과 조사할 범위를 쓰면 조사의 출발점이 명확해집니다.
어제부터 로그인 처리 테스트가 실패하고 있습니다.
수정하기 전에 재현 절차와 최근 커밋을 확인하여 원인을 특정해 주세요
반환되는 것은 재현 가능 여부, 관련될 것으로 보이는 커밋이나 설정 변경, 근거가 있는 가설입니다.
가설이 확인된 후에 실패 테스트와 하나의 수정이 이어집니다.
API에서 데이터베이스까지의 처리를 추적하여, 어디서 잘못된 값이 들어오는지 확인해 주세요
프로덕션 결함을 추적하는 요청입니다.
에이전트는 각 레이어의 경계에 진단용 로그를 넣고 한 번 실행하여, 어느 레이어에서 값이 이상해졌는지 보여줍니다.
수정은 잘못된 값이 생성된 위치에 대해 제안됩니다.
CI 빌드에서 서명에 실패합니다.
워크플로, 빌드 스크립트, 서명의 각 단계에서 무엇이 전달되는지 확인해 주세요
빌드나 연동 실패에서는 단계별로 확인을 넣어 구분합니다.
시크릿은 값 자체가 아닌 "설정 있음/없음"으로 표시하고, 키체인 상태도 확인합니다.
이렇게 하여 "워크플로까지는 도달하지만, 빌드 스크립트에는 전달되지 않는다"와 같이 문제가 있는 단계를 특정하는 흐름입니다.
조사가 얼마나 진행되는지는 처음에 제공하는 재료에 따라 달라집니다.
이 스킬은 재현할 수 없는 결함을 추측으로 수정하지 않고 데이터 수집으로 돌아가는 절차입니다.
재현 절차나 에러 메시지 전문, 로그, 발생하기 시작한 시기를 처음에 제공할수록 조사는 빨리 원인에 가까워집니다.
수정 내용의 최종 확인은 사람이 합니다.
진단용으로 추가한 로그나 확인 처리가 수정 커밋에 남아 있지 않은지도 확인해 두는 것이 좋습니다.
수정이 3번 이상 실패한 상황에서는 에이전트 쪽에서 설계 논의가 시작됩니다.
계속할지 재작성할지를 판단하는 것은 사용자입니다.
실패 테스트 작성 방법과 완료 전 확인은 같은 superpowers의 다른 스킬(테스트 주도 개발과 완료 전 검증)을 참조하는 절차로 되어 있습니다.
systematic-debugging만 넣은 경우, 그 두 가지 지시는 손에 없습니다.
필요에 따라 리포지토리에서 추가하는 것을 검토해 주세요.
라이선스는 MIT입니다.
SKILL.md는 영어로 작성되어 있으며, 부속 파일에는 셸 스크립트와 TypeScript 예시도 포함됩니다.
넣기 전에 SKILL.md와 부속 파일의 내용을 한 번 읽어보시기 바랍니다.
같은 obra/superpowers에는 디버깅 전후에 사용할 수 있는 스킬이 있습니다.
dispatching-parallel-agents는 서로 의존하지 않는 결함이나 테스트 실패를 별개의 에이전트에 할당하여 병렬로 조사·수정하는 스킬입니다.
여러 곳에서 동시에 실패가 발생하고 있을 때 systematic-debugging의 조사를 분담시키는 방식으로 활용할 수 있습니다.
requesting-code-review는 구현 후 또는 머지 전에 다른 에이전트에게 코드 리뷰를 요청하는 스킬입니다.
근본 원인을 수정한 후, 변경 내용을 제3자의 시각으로 확인하고 싶을 때 적합합니다.
finishing-a-development-branch는 모든 테스트를 확인한 후, 머지나 Pull Request 작성을 선택하여 진행하는 스킬입니다.
수정을 마친 브랜치 정리까지 이어서 맡길 수 있습니다.
네.
단순해 보이는 문제에도 근본 원인이 있다는 입장에서, 급한 상황일수록 절차를 지키는 설계입니다.
단순한 버그라면 각 단계는 짧게 끝난다고 위치 지어져 있습니다.
있습니다.
이미 여러 번 수정을 시도한 상황이나, 이전 수정으로 잘 해결되지 않은 상황은 이 스킬이 특히 사용해야 하는 경우로 꼽고 있습니다.
실패가 3번 이상이라면 추가 수정보다 먼저 설계 재검토를 협의하는 흐름입니다.
환경이나 타이밍, 외부 요인이 원인임을 알게 된 경우에는 조사 내용을 기록하고, 재시도나 타임아웃 등으로 대처합니다.
아울러 다음에 조사하기 위한 모니터링이나 로그를 추가하고 마무리합니다.
다만 "원인 없음"의 대부분은 조사 부족으로 처리하므로, 먼저 의심하는 것은 조사의 누락입니다.
사용할 수 있습니다.
설치 명령어에서 대상을 Codex로 선택하거나, ~/.agents/skills/systematic-debugging/에 배치해 주세요.
프로젝트 단위로 사용하는 경우에는 프로젝트의 .agents/skills/에 놓습니다.
systematic-debugging은 에이전트에게 "근본 원인을 조사하기 전에 수정하지 않는다"는 순서를 지키게 하는 스킬입니다.
에러 읽기, 재현, 변경 이력 확인부터 가설 검증, 실패 테스트를 통한 수정 확인까지를 한 단계씩 진행합니다.
3번 실패하면 설계 논의로 전환되므로 임시방편식 수정의 반복을 멈출 수 있습니다.
AI에게 부탁한 수정이 같은 실패를 반복하고 있다면, 먼저 이 스킬을 넣고 조사부터 맡겨 보세요.
이 글은 cccskills의 읽을거리 「systematic-debugging으로 버그의 근본 원인을 파악하기」의 전재입니다.
스킬의 상세 내용과 설치 방법은 cccskills의 systematic-debugging 페이지에 있습니다.