Agent skill

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. Four-phase framework ensuring understanding before attempting solutions.

Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/doyajin174/systematic-debugging

Metadata

Additional technical details for this skill

author
obra/superpowers
version
1.0

SKILL.md

Systematic Debugging

버그, 테스트 실패, 예상치 못한 동작에 대한 체계적 디버깅 방법론입니다.

Core Principle

"ALWAYS find root cause before attempting fixes. Symptom fixes are failure."

Mandatory Phases

Phase 1: Root Cause Investigation

1. 에러 메시지 정확히 읽기
2. 문제를 일관되게 재현
3. 최근 변경사항 확인
4. 멀티 컴포넌트 시스템에서 진단 증거 수집
5. 데이터 흐름을 역방향으로 추적

Phase 2: Pattern Analysis

1. 작동하는 예시 찾기
2. 레퍼런스와 비교
3. 차이점 식별
4. 의존성 이해

Phase 3: Hypothesis Testing

1. 구체적인 가설 수립
   - "X가 Y 때문에 발생한다고 생각됨"

2. 최소한의 테스트로 검증
   - 한 번에 하나의 변수만 변경

3. 과학적으로 결과 검증
   - 가설이 틀렸다면 다음 가설로

Phase 4: Implementation

1. 실패하는 테스트 케이스 작성
2. 단일 수정 구현
3. 결과 검증
4. 3번 실패 시 중단
   → 아키텍처 문제 가능성 검토

Critical Rules

규칙 설명
순차 진행 단계를 건너뛰지 않음
단일 수정 동시에 여러 수정 금지
3회 실패 시 중단 아키텍처 검토 필요

Red Flags - 프로세스 포기 징후

❌ "일단 빠르게 고치고..."
❌ "아마 여기가 문제인 것 같아서..."
❌ "시간이 없어서 그냥..."
❌ "재현은 안되지만 고쳐봤어요"

Debugging Template

markdown
## 문제
[증상 설명]

## 재현 단계
1. [단계 1]
2. [단계 2]
→ [예상 결과] vs [실제 결과]

## Phase 1: 조사
- 에러 메시지: [정확한 메시지]
- 최근 변경: [관련 커밋/변경]
- 데이터 흐름: [추적 결과]

## Phase 2: 패턴 분석
- 작동 케이스: [예시]
- 차이점: [식별된 차이]

## Phase 3: 가설
1. 가설: [내용]
   테스트: [방법]
   결과: [결과]

## Phase 4: 수정
- 수정 내용: [변경사항]
- 테스트: [검증 방법]
- 결과: ✅/❌

Evidence-Based Results

체계적 디버깅 적용 시:
- 문제 해결 시간: 2-3시간 → 15-30분
- 재발 방지: 근본 원인 해결로 재발 감소
- 학습 효과: 시스템 이해도 향상

Best Practices

  1. 증거 수집: 로그, 스택 트레이스, 재현 단계 문서화
  2. 최소 변경: 한 번에 하나만 변경하고 테스트
  3. 원복 준비: 변경 전 상태로 돌릴 수 있게 준비
  4. 기록 유지: 시도한 것과 결과 문서화

Didn't find tool you were looking for?

Be as detailed as possible for better results