Agent Skills: 🐞 체계적 디버깅 (Dev Coding Debug)

🐞 체계적 디버깅 (Dev Coding Debug)

이 워크플로우는 obra/superpowers의 **"The Iron Law"**를 준수합니다. 근본 원인 규명 없이는 절대 코드를 수정하지 않습니다.

1. 초기화 (Initialization)

1. 원칙 확인: this document를 읽고 Iron Law를 상기합니다.
2. 증상 정의: 사용자로부터 정확한 에러 메시지와 현상을 입력받습니다.

2. 조사 (Phase 1: Root Cause Investigation)

"추측하지 말고 증거를 수집하세요."

1. 에러 분석: 스택 트레이스와 에러 코드를 정밀 분석합니다.
2. 재현 (Reproduction): 버그를 확실하게 발생시키는 최소 단위의 스크립트를 작성합니다. (필수)
3. 기기/로그 추가 (Instrumentation): 데이터가 오염되는 지점을 찾기 위해 로그를 추가하고, 데이터 흐름을 역추적(Trace)합니다.

3. 분석 (Phase 2: Pattern Analysis)

"정상적인 패턴과 무엇이 다른가요?"

1. 정상 사례 찾기: 프로젝트 내에서 잘 동작하는 유사한 코드를 찾습니다.
2. 비교 분석: 정상 코드와 문제가 있는 코드의 차이점을 한 줄 한 줄 비교합니다.
3. 차이점 목록: 사소해 보이는 차이점이라도 모두 나열합니다.

4. 가설 (Phase 3: Hypothesis & Testing)

"과학적 방법론을 적용하세요."

1. 가설 수립: "X 때문에 Y가 발생한다"는 가설을 하나 세웁니다.
2. 최소 검증: 가설을 확인하기 위해 변수 하나만 변경하여 테스트합니다. (수정이 아님)
3. 반복: 가설이 틀렸다면 변경 사항을 되돌리고(Revert), 새로운 가설을 세웁니다. 기존 변경 위에 덧칠 금지.

5. 해결 (Phase 4: Implementation)

"증상이 아닌 원인을 고치세요."

1. 실패 테스트 (Red): 식별된 원인을 타겟으로 하는 실패 테스트 케이스를 확정합니다.
2. 단일 수정 (Green): 근본 원인을 제거하는 최소한의 코드를 작성합니다.
3. 검증 (Verification): 테스트 통과 및 회귀 테스트(Regression Test) 수행.
4. 정리 (Cleanup): 디버깅용 로그와 임시 코드를 깨끗이 삭제합니다.

6. 종료 (Completion)

1. 회고: 어떤 부분이 근본 원인이었는지 사용자에게 설명하고 종료합니다.

Standards & Rules

Systematic Debugging (Dev Coding Debug)

Core Principles (The Iron Law)

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

If you haven't completed Phase 1 (Root Cause) and Phase 2 (Pattern Analysis), you cannot propose fixes. Symptom fixes are failure.

🏗️ The Four Phases

Phase 1: Root Cause Investigation

Goal: Understand WHAT and WHY.

1. Read Errors: sticky to the error message. Don't skip stack traces.
2. Reproduce: Can you trigger it reliably? If not, gather more data.
3. Instrumentation: For multi-component systems, log data flow at boundaries.
4. Trace: Follow the bad value backwards to its source (root-cause-tracing).

Phase 2: Pattern Analysis

Goal: Find the standard before fixing.

1. Find Working Examples: Locate similar code that works.
2. Compare: Read reference implementations completely.
3. Identify Differences: List every difference, however small.

Phase 3: Hypothesis and Testing

Goal: Scientific Method.

1. Single Hypothesis: "I think X is the root cause because Y".
2. Test Minimally: Change ONE variable at a time to test the hypothesis.
3. Verify: If it didn't work, revert and form a NEW hypothesis. NO layering fixes.

Phase 4: Implementation

Goal: Fix the root cause, not the symptom.

1. Failing Test: Create a minimal reproduction test case (Red).
2. Single Fix: Address the identified root cause (Green).
3. Verify: Ensure no regressions.

�️ Supporting Techniques

1. Root Cause Tracing ("Why did this happen?")

Don't just fix the bad value. Find where it came from.

• Technique: Ask "What called this with a bad value?" repeatedly until you find the source.
• Rule: Fix at the source, not at the symptom.

2. Defense-in-Depth ("Make it impossible")

Don't just validate at one place.

• Layer 1 (Entry): Reject invalid input at IDL/API boundary.
• Layer 2 (Logic): Ensure data makes sense for the operation.
• Layer 3 (Guard): Environment checks (e.g., test vs prod).
• Layer 4 (Debug): Logging for forensics.

3. Condition-Based Waiting (No sleep)

Never guess how long something takes.

• Bad: sleep(50)
• Good: waitFor(() => condition)
• Why: Flaky tests often come from arbitrary timeouts.

�🚩 Red Flags (STOP immediately)

• "Quick fix for now"
• "Just try changing X"
• "One more fix attempt" (Limit: 3 attempts. Then question Architecture.)
• Proposing solutions before tracing.

✅ Quality Standards

• Reproduction Script: Must exist before fixing.
• Log Cleanup: All temporary instrumentation removed.
• Safe YAML: Frontmatter descriptions quoted.

Checklist

• [ ] Phase 1: Did you identify the exact line/reason for failure?
• [ ] Phase 2: Did you compare with a working example?
• [ ] Phase 4: Is there a test case that failed before and passes now?
• [ ] Cleanup: Are all print/console.log removed?