OpenSkillIndex← back to search
claude-code개발 지원

Optimization systematic-debugging

4단계 체계적 디버깅 방법론. 근본 원인 조사 없이 수정 금지.

install
source · Clone the upstream repo
git clone https://github.com/sunLeee/optimization
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/sunLeee/optimization "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/quality/check/systematic-debugging" ~/.claude/skills/sunleee-optimization-systematic-debugging && rm -rf "$T"
manifest: .claude/skills/quality/check/systematic-debugging/SKILL.md
source content

체계적 디버깅 스킬

핵심 원칙

"근본 원인 조사 없이 수정 금지"

무작위 수정은 시간을 낭비하고 새로운 버그를 만들어냅니다. 모든 수정은 반드시 원인 파악 후에 진행해야 합니다.

4단계 필수 프로세스

1단계: 근본 원인 조사 (Root Cause Investigation)

근본 원인을 이해하기 전에는 어떤 수정도 시도하지 마세요.

필수 체크리스트:

  • 에러 메시지와 스택 트레이스를 주의 깊게 읽기
  • 문제를 일관되게 재현하여 트리거 조건 파악
  • 버전 관리를 통해 최근 변경 사항 검토
  • 멀티 컴포넌트 시스템의 경우 각 경계에 진단 로깅 추가
  • 데이터 흐름을 역추적하여 값의 출처 파악

핵심 질문:

  • 정확히 무엇이 실패하고 있는가?
  • 언제부터 실패하기 시작했는가?
  • 어떤 조건에서 실패하는가?

2단계: 패턴 분석 (Pattern Analysis)

작동하는 코드와 실패하는 코드를 비교하여 차이점을 식별합니다.

필수 체크리스트:

  • 코드베이스에서 유사하게 작동하는 코드 찾기
  • 작동하는 구현과 실패하는 구현을 완전히 비교
  • 두 구현 간의 모든 차이점 문서화
  • 모든 의존성과 가정 이해

핵심 질문:

  • 비슷한 기능이 다른 곳에서는 어떻게 작동하는가?
  • 작동하는 코드와 실패하는 코드의 차이점은 무엇인가?
  • 어떤 암묵적 가정이 깨졌는가?

3단계: 가설 수립 및 테스트 (Hypothesis and Testing)

구체적인 가설을 세우고 최소한의 변경으로 검증합니다.

필수 체크리스트:

  • 근본 원인에 대한 구체적이고 명문화된 가설 수립
  • 최소한의 단일 변수 변경으로 테스트
  • 진행 전 결과 검증
  • 추측하지 말고 지식의 공백 인정

가설 템플릿:

가설: [구체적인 원인 설명]
검증 방법: [테스트 방법]
예상 결과: [성공 시 어떻게 될 것인가]
실패 시: [가설이 틀렸을 경우 다음 단계]

4단계: 구현 (Implementation)

검증된 가설을 바탕으로 타겟팅된 수정을 적용합니다.

필수 체크리스트:

  • 수정 전 실패하는 테스트 케이스 먼저 작성
  • 근본 원인을 해결하는 단일 타겟 변경 구현
  • 수정이 문제를 해결하고 다른 테스트를 깨뜨리지 않는지 검증

구현 원칙:

  • 한 번에 하나의 변경만
  • 각 변경 후 테스트 실행
  • 변경 사항 문서화

위반 징후 (Red Flags)

다음 징후가 나타나면 1단계로 돌아가세요:

징후의미
"일단 이렇게 해볼게요"조사 전 수정 시도
"빠르게 고쳐볼게요"근본 원인 이해 부족
동시에 여러 변경원인 격리 불가
테스트 스킵검증 없는 수정
근본 원인 이해 없이 해결책 제안추측에 의한 수정
"아마 이게 문제일 거예요"가설 없는 추측

자가 점검 질문:

  • 지금 무엇을 수정하려고 하는가?
  • 왜 그것이 원인이라고 확신하는가?
  • 어떻게 검증할 것인가?

3번 실패 규칙 (3-Failure Rule)

규칙

3번 수정 실패 시, 아키텍처 검토 필수

동일한 문제에 대해 3번 이상 수정을 시도했으나 실패했다면, 이는 근본적인 설계 문제를 나타냅니다.

3번 실패 후 프로세스

AskUserQuestion 활용 지점

지점 1: 근본 원인 가설 검증

단계 3에서 가설을 세운 후 사용자에게 확인한다:

AskUserQuestion:
  questions:
    - question: "이것이 근본 원인이라고 확신하나요?"
      header: "가설 검증"
      multiSelect: false
      options:
        - label: "예 - 확신함 (95% 이상)"
          description: "근거가 명확하고 검증 가능함. 수정 진행."
        - label: "아니오 - 불확실함"
          description: "1단계로 돌아가 추가 조사 필요"
        - label: "부분적 확신"
          description: "최소 변경으로 테스트 후 판단"

지점 2: 3번 실패 후 아키텍처 검토

3번 수정 실패 후 방향 전환을 제안한다:

AskUserQuestion:
  questions:
    - question: "3번 수정 실패했습니다. 아키텍처 검토가 필요할까요?"
      header: "방향 전환"
      multiSelect: false
      options:
        - label: "예 - 아키텍처 검토 시작 (권장)"
          description: "근본적인 설계 문제일 가능성. adversarial-review 또는 설계 재검토"
        - label: "아니오 - 추가 시도 (비권장)"
          description: "1단계로 돌아가 다른 가설 탐색"
        - label: "전문가 도움 요청"
          description: "팀원/커뮤니티에 문의"

3번 실패 감지
    |
    v
[STOP] 추가 수정 시도 중단
    |
    v
아키텍처 검토 요청
    |
    +-- 현재 설계의 가정 검토
    +-- 컴포넌트 간 의존성 분석
    +-- 대안적 접근 방식 논의
    |
    v
설계 변경 결정 또는 전문가 상담

아키텍처 검토 시 질문

  1. 이 컴포넌트의 책임이 명확한가?
  2. 의존성이 올바른 방향으로 흐르는가?
  3. 테스트하기 어려운 이유가 무엇인가?
  4. 더 간단한 설계가 가능한가?

디버깅 워크플로우 다이어그램

버그 감지
    |
    v
[1단계] 근본 원인 조사
    |-- 에러 메시지 분석
    |-- 재현 조건 파악
    |-- 최근 변경 검토
    |-- 진단 로깅 추가
    |
    v
[2단계] 패턴 분석
    |-- 유사 작동 코드 찾기
    |-- 차이점 식별
    |-- 의존성 분석
    |
    v
[3단계] 가설 수립 및 테스트
    |-- 가설 문서화
    |-- 최소 변경으로 테스트
    |-- 결과 검증
    |
    v
[4단계] 구현
    |-- 실패 테스트 먼저 작성
    |-- 단일 타겟 수정
    |-- 전체 테스트 실행
    |
    v
성공? --[No]--> 실패 카운트++
    |               |
    |               v
    |          3번 실패?
    |               |
    |        [Yes]  |  [No]
    |          |    +---> 1단계로
    |          v
    |     아키텍처 검토
    |
    v [Yes]
완료

관련 스킬 및 참조

  • [@skills/code-review/SKILL.md]: 코드 리뷰 시 버그 예방
  • [@skills/test-generator/SKILL.md]: 테스트 케이스 생성
  • [@skills/check-anti-patterns/SKILL.md]: 안티패턴 검사

참조

Changelog

날짜버전변경 내용
2026-01-211.1.0전체 한국어화 (Phase → 단계, 섹션명 한글화)
2026-01-211.0.0초기 생성 - 4단계 디버깅 방법론

Gotchas (실패 포인트)

  • 근본 원인 없이 증상만 수정하면 동일 버그 재발 — 반드시 4단계 준수
  • 재현 불가능한 버그: 환경 차이 먼저 확인 (OS, Python 버전, venv)
  • 로그 없이 디버깅 시도 시 추측 기반 → 실패 가능성 높음
  • ADK 버그: tool_context.state 값 타입 불일치가 주요 원인 중 하나