diagnose
AI에게 "체계적 디버깅"을 시키는 법 — 검증된 skill 하나를 해부한다

"그냥 고쳐줘"가 왜 실패하는가, 그리고 사람이 쓰는 디버깅 방법론을 어떻게 skill로 인코딩했는가

AI에게 "이 버그 고쳐줘" 했을 때

코드 생성은 잘하는 AI가, 어려운 버그 앞에선 자주 헛발질한다. 익숙한 장면:

출처: mattpocock/skills — diagnose SKILL.md 도입부

추측-수정 루프(guess-and-patch)의 함정

기본 상태의 AI는 "증상 → 그럴듯한 원인 → 즉시 수정"으로 달린다. 세 가지가 동시에 무너진다.

출처: mattpocock/skills — diagnose SKILL.md Phase 1

"피드백 루프가 곧 디버깅이다"

diagnose의 1번 원칙: 빠르고·결정적이고·에이전트가 직접 돌릴 수 있는 pass/fail 신호를 먼저 만들어라. 나머지(이분법·가설검증·계측)는 전부 그 신호를 소비할 뿐이다.

왜 이게 비직관적이고 깊은가

• 초보(그리고 기본 AI)는 "원인 찾기"에 시간을 쏟는다 → diagnose는 "신호 만들기"에 불균형하게 투자하라고 한다.
• 한 번 신호가 생기면 bisection·가설검증·계측이 전부 기계적으로 풀린다. 이 관점 전환이 발표의 핵심.

출처: mattpocock/skills — diagnose SKILL.md "Phase 1 — Build a feedback loop"

6단계 규율 — "정당한 이유 없이는 건너뛰지 마라"

핵심은 관문(gate)이 있다는 것 — 추측-수정 루프엔 없는 "다음으로 넘어가도 되나?" 체크.

출처: mattpocock/skills — diagnose SKILL.md Phase 1~6

피드백 루프 만드는 10가지 수 (난이도 순)

"재현이 안 돼요"는 끝이 아니라 시작. diagnose는 10가지를 순서대로 시도하라고 한다.

출처: mattpocock/skills — diagnose SKILL.md "Ways to construct one"

가설 — "느낌"을 "반증 가능한 예측"으로

왜 3~5개를 한꺼번에?

가설을 하나만 만들면 첫 그럴듯한 생각에 앵커링된다. diagnose는 테스트 전에 순위 매긴 3~5개를 강제한다.

각 가설은 반증 가능해야

형식: "만약 <X>가 원인이면, <Y>를 바꾸면 버그가 사라진다 /
                        <Z>를 바꾸면 더 심해진다."

예측을 못 쓰면 그건 "느낌(vibe)" → 버리거나 날카롭게. — 이게 과학적 방법(falsifiability)을 프롬프트에 인코딩한 것.

출처: mattpocock/skills — diagnose SKILL.md Phase 3

계측 — 한 번에 한 변수, 그리고 태그 로그

[DEBUG-a4f2] payload=...

출처: mattpocock/skills — diagnose SKILL.md Phase 4

수정 → 회귀 테스트 → 사후 분석

회귀 테스트를 "수정보다 먼저" — 단, 올바른 seam이 있을 때만

올바른 seam = 테스트가 실제 버그 패턴을 호출 지점 그대로 재현하는 자리. 너무 얕은 seam(단일 호출 테스트로 다중 호출 버그)은 거짓 안심을 준다.

완료 전 체크리스트 (Phase 6)

• ☑ 원래 재현이 더 이상 재현 안 됨 (Phase 1 루프 재실행)
• ☑ 회귀 테스트 통과 (또는 seam 부재를 문서화)
• ☑ 모든 [DEBUG-...] 계측 제거 (grep)
• ☑ 맞았던 가설을 커밋/PR 메시지에 — 다음 디버거가 배우도록

마지막 질문: "무엇이 이 버그를 막았을까?" 구조 문제면 아키텍처 개선으로 핸드오프 — 단 수정 후에(정보가 더 많아진 시점).

출처: mattpocock/skills — diagnose SKILL.md Phase 5~6

실제 케이스: div 균형이 77 / 95로 깨졌다 (+18)

이 스터디 카드 페이지에서 카드를 삭제하는 파이썬 스크립트를 돌린 뒤 HTML이 깨졌다. diagnose 6단계를 그대로 적용한 기록.

① 1초짜리 pass/fail 신호 (Phase 1)

$ grep -c '<div'  week7-topic-candidates.html   77   # 여는 태그
$ grep -c '</div>' week7-topic-candidates.html   95   # 닫는 태그
# 95 - 77 = +18  → 닫는 태그가 18개 많다 (구조 깨짐)

③④ 가설과 확정

카드 삭제기가 <div class="card">부터 "첫 단독 </div>"까지를 한 카드로 봤다. 그런데 카드 안에는 중첩된 <div class="row">…</div>가 있어, 검출기가 그 첫 </div>에서 멈춰 카드를 일부만 지웠다 → 카드마다 트레일링 </div> 1개가 남는다.

출처: 이번 세션 실제 진단 (대상: week7-topic-candidates.html) · diagnose SKILL.md Phase 1~4

정리 · 우리 팀에 적용

한 장 요약 (방법론)

• 피드백 루프가 곧 디버깅. "원인 찾기"보다 "1초 재현 신호 만들기"에 불균형 투자.
• 가설 3~5개 + 반증 예측 → 한 변수씩 계측 → 태그 로그.
• 회귀는 올바른 seam에만. seam 부재 = 그 자체가 발견.
• 이 모든 규율을 SKILL.md 한 장 + bash 템플릿에 인코딩 = "방법론을 재사용 가능한 구조로".

코드를 노려보지 말고, 신호를 먼저 만들어라.

출처: mattpocock/skills — diagnose SKILL.md 종합