debugger

debugger 스킬 개요

debugger 스킬이 하는 일

debugger 스킬은 AI 에이전트가 바로 추측성 해결책으로 뛰어들지 않고, 소프트웨어 문제를 구조적으로 진단하도록 돕습니다. 이 debugger 스킬은 깨진 코드, stack trace, crash, 예상과 다른 동작, 간헐적 장애, 운영 환경에 가까운 트러블슈팅처럼 빠른 임시 패치보다 근본 원인 파악이 더 중요한 디버깅 작업에 맞춰 설계되었습니다.

debugger 스킬을 설치하면 좋은 사용자

이 debugger 스킬은 특히 다음과 같은 경우에 잘 맞습니다:

• 반복 가능한 디버깅 워크플로를 원하는 개발자
• AI를 코드 작성용이 아니라 버그 조사에 활용하는 팀
• 로그, 에러 메시지, 재현 절차, 코드 맥락을 제공할 수 있는 사용자
• “일단 재설치해 보세요” 같은 뭉뚱그린 답변보다 가설 기반 분석을 원하는 사람

주된 목적이 처음부터 새 코드를 생성하는 것이라면 최적의 선택은 아닙니다. 이미 무언가가 존재하고, 그게 실패하고 있을 때 훨씬 강합니다.

실제로 해결해 주는 핵심 문제

대부분의 사용자는 “디버깅 팁”이 필요한 것이 아닙니다. 실제로는 다음 질문에 답이 필요합니다:

• 정확히 무엇이 망가졌는가
• 실패가 어디서 시작됐을 가능성이 큰가
• 그 결론을 뒷받침하는 증거는 무엇인가
• 다음에 무엇을 테스트해야 하는가
• 실제 문제를 가리지 않으면서 어떻게 고칠 수 있는가

debugger 스킬이 유용한 이유는 에이전트를 다음 순서로 밀어주기 때문입니다: 문제 이해 → 증거 수집 → 가설 수립 → 가설 검증 → 근본 원인 식별 → 수정 → 검증.

일반 프롬프트와 다른 점

일반 프롬프트는 피상적인 트러블슈팅 체크리스트나 근거가 약한 수정안을 내놓는 경우가 많습니다. 이 debugger for Debugging은 다음이 필요할 때 더 강합니다:

• 빠진 증거를 먼저 요청하기
• 증상과 원인을 구분하기
• 가능성 높은 설명부터 우선순위 매기기
• 표적화된 테스트 제안하기
• 수정안을 낸 뒤 검증까지 하기

이런 구조 덕분에 가능한 원인이 여러 개인 복잡한 문제에서 불필요한 시행착오를 줄일 수 있습니다.

설치 전에 가장 중요하게 볼 점

이 스킬은 가볍습니다. 저장소는 주로 디버깅 프로세스와 사용 시점을 설명하는 단일 SKILL.md로 구성되어 있습니다. 먼저 익혀야 할 추가 스크립트, 참고 자료, rules 폴더는 없습니다. 도입 자체는 쉽지만, 그만큼 결과 품질은 사용자가 제공하는 맥락의 질에 크게 좌우됩니다.

가장 큰 도입 장벽은 설치 복잡도가 아닙니다. 재현 절차 없음, 로그 없음, 환경 정보 없음, 기대 동작 설명 없음 같은 약한 입력이 더 큰 문제입니다.

debugger 스킬 사용 방법

debugger 스킬 설치 방법

에이전트 환경이 GitHub 기반 Skills 설치를 지원한다면, awesome_agent_skills/debugger가 포함된 저장소 경로에서 debugger 스킬을 설치하면 됩니다. 일반적인 패턴은 다음과 같습니다:

npx skills add Shubhamsaboo/awesome-llm-apps --skill debugger

다른 skill loader를 쓰는 환경이라면, 저장소 안의 debugger 스킬 디렉터리를 가리키세요:
awesome_agent_skills/debugger

저장소에서 먼저 읽어야 할 파일

가장 먼저 볼 파일은 다음입니다:

• SKILL.md

이 파일에 실질적으로 필요한 동작 로직이 거의 다 들어 있습니다:

• 어떤 상황에서 스킬을 적용할지
• 디버깅 프로세스
• 에이전트가 요청해야 할 증거 유형
• 진단에서 검증까지의 기대 흐름

보조 파일이 없기 때문에 SKILL.md만 빠르게 읽어도 이 스킬이 어떤 방식으로 사고하는지 파악할 수 있습니다.

일반 코딩 에이전트 대신 debugger를 호출해야 하는 때

다음처럼 이미 실패 신호가 있을 때는 debugger usage가 적합합니다:

• exception 또는 stack trace가 있음
• 잘 되던 테스트가 깨지기 시작함
• crash 또는 hang 발생
• 회귀가 의심되는 성능 저하
• deploy, dependency 업데이트, config 변경 이후 동작이 달라짐
• 범위를 좁혀야 하는 간헐적 버그

반대로 기능 설계나 광범위한 리팩터링의 첫 도구로 쓰지는 마세요. 이 스킬은 장애 격리에 최적화되어 있습니다.

debugger가 최소한으로 필요로 하는 입력

debugger guide로 유의미한 결과를 얻으려면 다음을 제공하세요:

• 기대 동작
• 실제 동작
• 정확한 에러 메시지 또는 증상
• 재현 절차
• 관련 코드 스니펫 또는 파일 경로
• 환경 정보: OS, runtime, framework 버전, config 차이
• 최근 변경 사항: deploy, dependency 버전 상승, feature flag, schema 변경

이 정보가 없더라도 도움은 받을 수 있지만, 에이전트는 대부분의 시간을 추가 질문에 쓰게 됩니다.

허술한 버그 리포트를 강한 debugger 프롬프트로 바꾸는 법

약한 프롬프트:

My app is not working. Can you debug it?

더 나은 프롬프트:

Use the debugger skill. Expected behavior: POST /checkout returns 200. Actual behavior: returns 500 for carts with discount codes. Started after upgrading stripe from 12.x to 13.x. Repro: apply code SAVE10, submit payment. Error log: TypeError: cannot read properties of undefined (reading 'amount_total') in payments/checkout.ts:84. Environment: Node 20, Next.js 14, production only. Please rank likely causes, identify the most probable root cause, and suggest the smallest safe fix plus validation steps.

두 번째 버전은 에이전트가 추측이 아니라 증거 기반으로 추론할 수 있을 만큼 충분한 정보를 제공합니다.

실제로 잘 먹히는 debugger 워크플로

신뢰할 수 있는 debugger usage 흐름은 다음과 같습니다:

1. 기대 동작과 실제 동작을 분명히 적는다.
2. 재현 절차와 실패 증거를 제공한다.
3. 에이전트에게 가능성 순으로 가설을 정리해 달라고 한다.
4. 상위 2~3개 가설을 가르는 가장 빠른 판별 테스트를 요청한다.
5. 그 테스트 결과만 다시 공유한다.
6. 근본 원인 후보가 좁혀진 뒤에만 수정안을 요청한다.
7. 검증 절차와 회귀 체크까지 요청한다.

이 흐름은 스킬의 핵심 설계와 맞고, 처음부터 패치를 요구하는 것보다 보통 더 좋은 판단으로 이어집니다.

debugger 스킬이 보통 추가로 요청하는 것

이 스킬의 자체 프로세스는 다음 수집에 초점이 맞춰져 있습니다:

• stack trace와 에러 메시지
• 로그
• 환경 및 설정 정보
• 문제를 유발하는 입력 데이터
• 실패 전, 중, 후의 시스템 상태

이런 자료를 처음부터 포함하면 상호작용이 훨씬 빠르고 구체적으로 진행됩니다.

간헐적 이슈에서 debugger를 쓰는 방법

flaky하거나 비결정적으로 발생하는 버그라면 에이전트에게 다음을 알려주세요:

• 문제가 얼마나 자주 나타나는지
• 부하, 타이밍, 동시성, 특정 데이터셋과 상관관계가 있는지
• 이미 배제한 원인이 무엇인지
• 로컬 전용인지, 운영 전용인지, 특정 환경에서만 발생하는지

그다음 이렇게 요청하면 좋습니다:

• 범주별로 묶은 후보 원인
• 필요한 instrumentation 아이디어
• 이진 탐색식으로 범위를 좁히는 계획
• 가설을 구분하는 데 필요한 최소 추가 로그

이런 상황이야말로 debugger 스킬이 일회성 수정 프롬프트보다 더 빛나는 지점입니다.

stack trace와 로그 분석에 debugger를 쓰는 방법

stack trace를 공유할 때는 마지막 exception 한 줄만 붙여넣지 마세요. 다음까지 포함해야 합니다:

• 최상단 에러 라인
• 내 코드 주변의 관련 frame
• 문제를 유발한 입력 또는 요청
• 여러 시스템이 얽혀 있다면 timestamp
• 실패 직전에 함께 나온 경고 로그

그리고 스킬에게 다음을 설명해 달라고 요청하세요:

• 증상이 어디에서 나타나는지
• 어떤 상위 조건이 원인일 가능성이 큰지
• 어떤 frame이 가장 액션하기 좋은지
• 아직 부족한 증거가 무엇인지

진단을 놓치지 않으면서 수정안을 요청하는 법

흔한 실수는 에이전트에게 너무 이른 시점에 패치를 강요하는 것입니다. 더 좋은 표현은 다음과 같습니다:

Use the debugger skill. First identify the most likely root cause and the evidence for it. Then propose the smallest fix. Finally give me validation steps and one regression test to add.

이 프롬프트는 증거 우선 워크플로를 유지하면서도 해결로 자연스럽게 이어지게 해줍니다.

debugger 스킬 FAQ

debugger 스킬은 초보자도 쓰기 쉬운가?

네, 구체적인 증거를 제공할 수 있다면 초보자에게도 유용합니다. 이 스킬은 조사 과정을 이해 가능한 단계로 정리해 주기 때문에 입문자도 도움을 받기 쉽습니다. 다만 만능은 아닙니다. 무엇이 바뀌었는지, 어떻게 재현되는지, 에러가 정확히 무엇인지 설명하지 못하면 결과 품질은 떨어집니다.

debugger가 가장 잘 다루는 문제는 무엇인가?

debugger가 특히 강한 영역은 다음과 같습니다:

• runtime 에러
• 깨진 테스트
• crash
• 변경 이후 발생한 회귀
• 수상한 로그
• 운영 장애 초기 분류와 대응
• “로컬에서는 되는데 운영에서는 안 됨” 유형의 조사

반대로 “내 전체 아키텍처를 리뷰해 줄래?”처럼 범위가 넓고 모호한 요청에는 덜 적합합니다.

일반 프롬프트와 debugger는 어떻게 다른가?

일반 프롬프트는 증상에서 곧바로 수정안으로 점프하는 경우가 많습니다. 반면 debugger 스킬은 증거 수집, 가설 우선순위화, 근본 원인 분석, 검증에 맞춰져 있습니다. 그래서 추측성 답변은 줄고, 다음 액션에 대한 안내는 더 좋아지는 편입니다.

debugger 설치에 도구나 스크립트도 포함되나?

아니요. 이 스킬 디렉터리에서 별도의 주요 지원 도구는 드러나지 않습니다. 핵심은 패키지형 debugger 바이너리나 스크립트 묶음이 아니라 SKILL.md에 담긴 지시형 워크플로입니다. AI 보조 디버깅을 위한 추론 프레임워크에 가깝다고 보면 됩니다.

언제는 debugger를 쓰지 않는 편이 좋은가?

다음 상황이라면 이 스킬은 건너뛰는 편이 낫습니다:

• 진단이 아니라 기능 구현이 필요할 때
• 문제가 이미 완전히 격리되어 있고 코드 생성만 원할 때
• 의미 있는 맥락을 전혀 공유할 수 없을 때
• 실제 문제는 소프트웨어 장애가 아니라 제품 요구사항의 모호함일 때

이 경우에는 coding, architecture, planning 계열 스킬이 더 잘 맞을 수 있습니다.

debugger는 성능 문제에도 도움이 되나?

네. 다만 측정값이나 증상이 있어야 합니다. 예를 들면 느린 endpoint, 지연 시간 급증, CPU 사용량, 메모리 증가, 최근 변경 사항, 재현 조건 같은 정보입니다. 이런 자료가 있으면 이 스킬은 막연한 최적화 조언 대신 가설을 세우고 표적화된 테스트를 제안할 수 있습니다.

debugger 스킬 개선 방법

결론만 주지 말고 debugger에 증거를 줘라

나쁜 입력:

The database is probably the problem.

더 나은 입력:

API latency increased from 120ms to 2.4s after adding a join. EXPLAIN ANALYZE shows a sequential scan on orders. CPU is stable, DB IOPS spiked, and the slowdown happens only for accounts with more than 50k rows.

두 번째 방식은 debugger가 사용자의 가정을 그대로 받아들이는 대신 사실에서 출발해 추론하게 만듭니다.

모든 요청을 기대 동작 vs 실제 동작으로 고정하라

이건 가장 효과가 큰 개선 포인트입니다. 항상 다음을 명시하세요:

• 무엇이 일어나야 하는지
• 실제로는 무엇이 일어나는지
• 그 사실을 어떻게 확인했는지
• 얼마나 자주 발생하는지

이렇게 해야 에이전트가 엉뚱한 목표를 최적화하는 일을 막을 수 있습니다.

단일 정답보다 우선순위가 매겨진 가설을 요구하라

debugger for Debugging에 강한 프롬프트 예시는 다음과 같습니다:

Rank the top 3 likely causes from most to least probable, explain the evidence for each, and give one test that would eliminate each hypothesis.

이 방식은 “뭐가 문제야?”라고 묻는 것보다 훨씬 더 좋은 디버깅 루프를 만듭니다.

변경 이력은 초반에 바로 제공하라

많은 버그의 원인은 다음과 같습니다:

• dependency 업데이트
• config 변경
• 환경 드리프트
• deploy
• schema 또는 API 계약 변경

최근 무엇이 바뀌었는지 스킬에 먼저 알려주세요. 추가 코드 스니펫을 더 붙이는 것보다 이것이 근본 원인에 빨리 도달하게 해주는 경우가 많습니다.

표적화된 아티팩트로 debugger 출력을 개선하라

가장 유용한 아티팩트는 다음입니다:

• 실패한 테스트 출력
• 주변 frame이 포함된 stack trace
• 실패 시간대 전후의 로그
• 정확한 요청 payload 또는 입력 데이터
• 최근 변경 diff
• 관련 config 파일

하나만 제공할 수 있다면, 가장 작은 재현 가능한 실패 예제부터 시작하세요.

흔한 실패 패턴: 너무 빨리 수정안을 요구함

첫 답변이 너무 일반적이라면 “좀 더 자세히”라고 하지 마세요. 대신 이렇게 물으세요:

What evidence is missing?
What is the fastest test to separate the top two hypotheses?
What would make you change your current diagnosis?

이 질문들은 디버깅 경로를 더 날카롭게 만들어 줍니다.

흔한 실패 패턴: 과도하게 큰 컨텍스트 덤프

저장소 전체를 한 번에 던지면 오히려 신호 대 잡음비가 떨어지는 경우가 많습니다. 먼저 다음만 주세요:

• 실패한 파일 또는 함수
• 정확한 에러
• 재현 절차
• 최근 변경
• 관련 파일 한두 개

그다음 에이전트가 더 많은 맥락이 필요한 의존 경로를 짚었을 때만 범위를 넓히세요.

첫 debugger 응답 뒤에 어떻게 이어갈까

첫 라운드 이후에는 이렇게 진행하세요:

1. 제안된 판별 테스트를 실행한다
2. 결과만 다시 전달한다
3. 에이전트에게 가설 순위를 업데이트해 달라고 한다
4. 가장 작고 안전한 수정안을 요청한다
5. 검증 절차와 회귀 커버리지까지 요청한다

이렇게 하면 debugger guide가 처음부터 다시 재분석하는 쪽으로 새지 않고, 핵심에 계속 집중할 수 있습니다.

debugger에서 더 나은 수정안을 끌어내는 방법

실제 패치를 요청할 준비가 됐다면 다음을 요구하세요:

• 한 문장짜리 근본 원인 요약
• 최소한의 코드 변경
• 왜 그 변경이 증상만이 아니라 원인을 해결하는지
• 가능한 부작용
• 검증 절차
• 재발 방지를 위한 회귀 테스트 1개

이 마지막 단계가 있어야 괜찮은 진단이 실제 워크플로에서 신뢰할 수 있는 debugger usage로 이어집니다.