debugger

debugger skill 개요

debugger skill은 어떤 용도에 적합한가

debugger skill은 단순한 “무엇이 문제인가요?”식 프롬프트보다 더 빠르게 근본 원인을 찾도록 설계된 구조화된 디버깅 워크플로입니다. 코드가 에러를 발생시키거나, 예상과 다르게 동작하거나, 변경 이후 회귀가 생기거나, 특정 환경에서만 실패하는 상황에 특히 잘 맞습니다. 바로 수정안부터 내놓기보다, 실제 디버깅에서 중요한 순서인 재현, 범위 축소, 분석, 수정, 검증을 따라가도록 유도하는 것이 이 debugger skill의 핵심입니다.

어떤 사용자가 이 debugger skill을 설치하면 좋은가

이 debugger skill은 즉흥적인 트러블슈팅이 아니라, 반복 가능한 Debugging 프로세스를 갖추고 싶은 개발자, AI coding agent, 기술 조직에 잘 맞습니다. 특히 stack trace, 로그, 불완전한 버그 리포트, 확실하지 않은 재현 절차를 바탕으로 작업하는 일이 잦다면 더 유용합니다. 특정 프레임워크의 깊은 전문성보다는, 프로젝트 전반에서 디버깅의 규율과 일관성을 높이는 데 초점이 맞춰져 있습니다.

이 skill이 실제로 해결해 주는 일

이 skill의 핵심 job-to-be-done은 단순히 “에러 메시지를 설명하는 것”이 아닙니다. 모호한 실패를 조사 가능한 경로로 바꾸는 일에 가깝습니다. 즉, 무엇이 바뀌었는지, 어떻게 재현할지, 어디서 범위를 좁힐지, 어떤 증거를 모아야 할지, 최종 수정이 맞는지 어떻게 검증할지를 정리해 줍니다. 그래서 팀이 추측에 시간을 낭비하거나, 원인 대신 증상만 반복해서 고치고 있을 때 이 debugger 설치 가치는 더 커집니다.

왜 이 debugger skill이 눈에 띄는가

이 skill의 차별점은 “어떻게 운영되느냐”에 있습니다. 저장소에는 다음이 포함되어 있습니다.

• SKILL.md의 단계별 디버깅 워크플로
• references/checklist.md, references/errors.md, references/patterns.md의 빠른 참조용 디버깅 보조 자료
• scripts/debug_report.py의 실무형 리포트 생성기

이 조합 덕분에 debugger skill은 단순 프롬프트 템플릿보다 실시간 장애 대응형 작업에 더 적합합니다. 프로세스, 체크리스트, 흔한 실패 유형, 그리고 인수인계 가능한 결과물까지 함께 제공합니다.

이 skill이 하려고 하지 않는 것

이것은 특정 언어 전용 debugger도, IDE extension도, tracing platform도 아닙니다. runtime tool, profiler, framework 문서를 대체하지도 않습니다. 주된 필요가 interactive stepping, memory inspection, protocol-level tracing이라면 그런 도구를 직접 쓰고, 이 debugger 가이드는 그 주변의 추론 레이어로 활용하는 편이 맞습니다.

debugger skill 사용 방법

설치 맥락과 repo 경로

이 skill은 zhaono1/agent-playbook 내부의 skills/debugger에 있습니다. GitHub 소스를 지원하는 skill loader를 사용한다면, 저장소에서 설치한 뒤 debugger skill을 지정하면 됩니다. 흔한 패턴은 다음과 같습니다.

npx skills add https://github.com/zhaono1/agent-playbook --skill debugger

환경 구성이 다르더라도 핵심은 skills/debugger 디렉터리를 로드해서 agent가 SKILL.md와 보조 references/, scripts/ 파일에 접근할 수 있게 하는 것입니다.

먼저 읽어야 할 파일

빠르게 도입하려면 다음 순서로 읽는 것이 좋습니다.

1. skills/debugger/SKILL.md
2. skills/debugger/references/checklist.md
3. skills/debugger/references/patterns.md
4. skills/debugger/references/errors.md
5. skills/debugger/scripts/debug_report.py

이 순서는 실제 debugger 사용 흐름과도 맞닿아 있습니다. 먼저 워크플로를 파악하고, 그다음 조사 휴리스틱, 에러 분류, 마지막으로 문서화 지원 도구를 보는 방식입니다.

실제로 debugger skill이 발동되는 상황

이 저장소는 사용자가 다음과 같이 보고할 때 활성화되도록 설계되어 있습니다.

• 에러나 예외 발생
• 예상과 다른 동작
• “debug this”
• “why isn’t this working?”

실무에서는 요청을 명확히 디버깅 작업으로 규정하고, 증거를 함께 제공할 때 debugger skill이 가장 잘 작동합니다. 예를 들면 다음과 같습니다.

“Use the debugger skill. This API returns 500 only in staging. Expected 200. Started after yesterday’s deploy. Here is the stack trace, the endpoint, and the last 3 commits.”

이 프롬프트는 단순한 “fix this bug”보다 훨씬 강합니다.

debugger skill이 필요로 하는 입력

좋은 debugger 활용은 구체적인 입력에 달려 있습니다. 가능하면 아래 항목을 많이 제공하세요.

• 정확한 에러 텍스트
• stack trace
• 기대한 동작과 실제 동작
• 재현 절차
• 최근 코드 또는 설정 변경
• 환경 정보
• 관련 로그
• 범위를 좁힌 파일 또는 컴포넌트

이 skill의 워크플로는 증거 수집을 전제로 하므로, 구현 세부 정보가 조금 부족한 것보다 재현 절차나 실제 출력이 없는 쪽이 결과 품질에 더 크게 악영향을 줍니다.

두루뭉술한 요청을 강한 debugger 프롬프트로 바꾸기

약한 프롬프트:
“Why does this fail?”

더 강한 프롬프트:
“Use the debugger skill to diagnose this failure. After upgrading dependencies, npm test fails in auth.spec.ts with TypeError: Cannot read properties of undefined. Expected tests to pass. Actual behavior: 6 failures on CI, 0 locally. Recent changes: lockfile update and config edit. Please help reproduce, isolate likely causes, rank hypotheses, and suggest the smallest safe fix.”

왜 이 방식이 효과적인가:

• 디버깅 목표를 분명히 밝힘
• 기대 동작과 실제 동작을 함께 제시함
• 환경 차이를 포함함
• 최근 변경 사항을 포함함
• 패치 전에 조사부터 하도록 요청함

권장 debugger 워크플로

실제 사용에 맞는 실전형 debugger 가이드는 다음과 같습니다.

1. 문제를 정확히 재현한다.
2. 기대 동작과 실제 동작을 기록한다.
3. git log --oneline -10으로 최근 변경 사항을 확인한다.
4. 로그 또는 trace를 수집한다.
5. minimal repro 또는 binary search로 범위를 좁힌다.
6. 실패를 에러 유형에 매핑한다.
7. 근본 원인 가설을 세운다.
8. 가장 가능성이 높은 최소 수정안을 시험한다.
9. 회귀 방지 검증까지 확인한다.

이 흐름은 대부분 skill에 이미 녹아 있지만, agent가 너무 일찍 수정안을 제시하기 시작할 때는 이 순서를 명시적으로 따라가면 도움이 됩니다.

reference 파일을 판단 보조 도구로 활용하기

보조 파일들은 짧지만, 출력 품질 차이는 꽤 큽니다.

• references/checklist.md는 세션이 핵심을 놓치지 않게 해 줍니다: 재현, 범위 축소, 근본 원인, 수정, 회귀 검증.
• references/patterns.md는 문제가 넓거나 노이즈가 많을 때 유용합니다. binary search, targeted logging, minimal repro 축소 같은 방법을 제안합니다.
• references/errors.md는 null access, race condition, config mismatch, data shape drift 같은 흔한 실패를 분류하는 데 도움이 됩니다.

첫 번째 debugger 결과가 지나치게 뭉뚱그려져 보인다면 이 파일들을 쓰는 것이 좋습니다. 문법을 배우기보다 조사 경로를 날카롭게 다듬는 데 더 적합합니다.

재사용 가능한 debug report 생성하기

조사 결과를 문서화된 산출물로 남기고 싶다면 다음을 사용하세요.

python skills/debugger/scripts/debug_report.py --name "Checkout timeout in staging" --owner payments

이 명령은 summary, environment, repro steps, logs, root cause, fix, regression tests, follow-ups 섹션을 포함한 markdown 리포트 템플릿을 생성합니다. 팀 단위 디버깅에서는 저장소에서 가장 실용적인 부분 중 하나인데, 휘발성 조사 과정을 리뷰 가능한 문서로 바꿔 주기 때문입니다.

Debugging용 debugger skill이 특히 잘 맞는 경우

이 debugger skill은 다음과 같은 상황에서 특히 유용합니다.

• 버그는 재현되지만 원인이 바로 보이지 않을 때
• 로그는 있지만 노이즈가 많을 때
• 변경 이후 실패가 시작됐을 때
• 문제가 코드, 설정, 환경을 함께 걸쳐 있을 때
• 코드를 수정하기 전에 규율 있는 triage 흐름이 필요할 때

반대로, 한눈에 보이는 아주 작은 문법 실수나, agent가 접근할 수 없는 독점적 운영 맥락이 필요한 도메인 특화 장애에는 매력이 덜합니다.

debugger 활용도를 높여 주는 실전 팁

skill에게 다음 항목을 분리해서 답하라고 요청하세요.

• 사실
• 가설
• 다음 점검 항목
• 제안하는 수정
• 검증 단계

이 구조는 너무 이른 확신을 막아 줍니다. 또한 가능한 원인을 가능성 순으로 정렬하고, 각 가설을 반증할 수 있는 증거가 무엇인지도 말해 달라고 요청하세요. 그러면 debugger skill은 “똑똑한 추측기”보다 더 나은 조사 파트너가 됩니다.

debugger skill FAQ

이 debugger skill은 일반 프롬프트보다 더 나은가

대체로 그렇습니다. 특히 이슈가 여러 단계를 거치는 경우에는 더 그렇습니다. 일반 프롬프트는 증상에서 추정 수정안으로 곧바로 뛰어가는 경우가 많습니다. debugger skill은 체계적인 범위 축소, 증거 수집, 검증이 필요할 때 더 강합니다. 다만 버그가 사소하고, 하나의 코드 조각만 봐도 충분히 파악되는 경우라면 일반 프롬프트만으로도 충분할 수 있습니다.

debugger 설치는 초보자에게도 쉬운가

네. 핵심 워크플로가 단순하고 구체적이기 때문입니다. 초보자는 단계별 프로세스와 체크리스트의 도움을 크게 받습니다. 다만 한 가지 전제는 있습니다. 이 skill은 로그, stack trace, 재현 절차 같은 증거를 어느 정도 제공할 수 있다고 가정합니다. 그런 정보가 없으면 어떤 debugger 가이드도 추측 비중이 커질 수밖에 없습니다.

이 debugger skill은 어떤 언어·스택에도 사용할 수 있는가

대체로 그렇습니다. 이 debugger skill은 특정 언어가 아니라 프로세스 중심으로 설계되어 있습니다. 에러 예시도 프레임워크 특화라기보다 범용적인 쪽에 가깝습니다. 그래서 이식성은 좋지만, 최상의 결과를 원한다면 스택별 세부 정보를 사용자가 직접 더해 주는 편이 좋습니다.

언제는 이 debugger skill을 쓰지 않는 것이 좋은가

다음 상황이라면 건너뛰는 편이 낫습니다.

• 추론 도움보다 interactive runtime debugging이 더 필요할 때
• 문제가 순수 운영 이슈인데 agent가 시스템에 접근할 수 없을 때
• 버그가 이미 확인된 한 줄짜리 오타일 때
• 저장소에 없는 vendor-specific 전문성이 필요할 때

이런 경우에는 먼저 직접 도구나 도메인 문서를 사용하는 것이 맞습니다.

팀 인수인계나 장애 후속 조치에도 도움이 되는가

그렇습니다. debug_report.py 스크립트는 이 debugger skill이 일회성 채팅 이상의 용도를 염두에 두고 설계되었다는 가장 강한 신호입니다. 디버깅 세션을 ownership, repro steps, root cause, fix, follow-ups까지 포함한 재사용 가능한 리포트로 바꾸는 데 도움을 줍니다.

debugger skill 개선 방법

증상만이 아니라 증거를 debugger skill에 제공하기

debugger 출력 품질을 가장 빨리 높이는 방법은 원시 증거를 함께 주는 것입니다.

• 실제 실행한 command
• 전체 에러 텍스트
• 실패한 입력값
• 문제가 발생하는 환경
• 최근 commit 범위
• 이미 시도해 본 것

“Here is the stack trace and the last good commit”은 “it’s broken after my changes”보다 훨씬 낫습니다.

초기에 minimal repro를 강제하기

debugger 사용에서 흔한 실패 패턴은 너무 넓은 표면적을 한꺼번에 조사하는 것입니다. 가능한 한 빨리 가장 작은 재현 케이스를 만들도록 skill에 요청하세요. 그러면 framework setup, 무관한 서비스, stale state에서 생기는 노이즈를 제거할 수 있고, 근본 원인이 더 빨리 드러나는 경우가 많습니다.

가설 우선순위 정렬을 요청하기

여러 원인이 모두 그럴듯해 보인다면, debugger skill에게 가능성과 검증 용이성 기준으로 우선순위를 매기라고 하세요. 그러면 조사 순서가 더 좋아집니다. 예:

“List the top 3 root-cause hypotheses, what evidence supports each, and the next cheapest check to confirm or reject them.”

이 방식은 flaky test, integration failure, config drift 같은 문제에서 특히 유용합니다.

근본 원인과 수정 품질을 분리해서 보기

또 다른 흔한 문제는 증상이 사라졌다는 이유만으로 첫 번째 수정안을 그대로 받아들이는 것입니다. debugger 가이드를 활용해 다음을 물어보세요.

• 왜 이런 일이 발생했는지
• 어떤 조건이 이를 가능하게 했는지
• 계속 고쳐진 상태임을 어떤 regression test가 증명해야 하는지

이 점은 null handling, race condition, config mismatch처럼 반복해서 나타나는 문제에서 특히 중요합니다.

저장소 맥락을 주어 첫 응답의 질 높이기

버그가 자신의 코드베이스 안에 있다면 다음 정보를 제공하세요.

• 의심되는 파일
• package 또는 service 경계
• 배포 시점
• 관련된 config 파일
• 문제가 local, CI, staging, production 중 어디에서만 발생하는지

debugger skill은 붙여 넣은 stack trace만 보고 추론할 때보다, 증거를 시스템 경계와 연결할 수 있을 때 훨씬 더 잘 작동합니다.

약한 답변은 reference 파일로 날카롭게 보완하기

첫 답변이 지나치게 일반적이라면, agent에게 다음 파일을 명시적으로 사용하라고 지시하세요.

• 프로세스 완결성을 위한 references/checklist.md
• 범위 축소 방법을 위한 references/patterns.md
• 에러 계열 매칭을 위한 references/errors.md

이 방법은 전체 프롬프트를 다시 쓰지 않고도 debugger 결과를 실질적으로 개선하는 현실적인 방법입니다.

첫 번째 디버깅 패스 이후 반복적으로 갱신하기

좋은 debugger 활용은 반복적입니다. 첫 결과를 받은 뒤에는:

1. 제안된 점검 하나를 실제로 수행하고
2. 그 결과를 다시 가져오고
3. skill에게 가설을 업데이트하라고 요청한 다음
4. 그때 코드를 수정하세요

이 루프가 있어야 debugger skill이 정적인 debugger 가이드보다 더 유용해집니다. 한 번에 크고 추측성 강한 답을 만드는 대신, 점점 수렴하도록 도와줍니다.

종료 전에 회귀 방지 근거 추가하기

저장소 체크리스트에는 회귀 검증이 명시적으로 포함되어 있고, 실제로도 그 지점에서 마무리하는 것이 맞습니다. 다음번에도 같은 문제를 잡아낼 수 있도록, debugger skill에게 가장 작은 테스트, assertion, 또는 monitoring check를 제안해 달라고 하세요. 검증 없는 수정은 대개 불완전한 Debugging입니다. 특히 간헐적이거나 환경 의존적인 버그라면 더 그렇습니다.