Engine 스킬 — 체계적 디버깅 (systematic-debugging)

개요

무작위 픽스는 시간을 낭비하고 새 버그를 만든다. 빠른 패치는 근본 문제를 가린다.

핵심 원칙: 픽스 시도 전에 항상 근본 원인을 찾는다. 증상 픽스는 실패다.

규칙의 문구를 어기는 것은 디버깅의 정신을 어기는 것이다.

철칙

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
근본 원인 조사 없이 픽스 금지

Phase 1을 완료하지 않았다면 픽스 제안 불가.

사용 시점

모든 기술 이슈:

• 테스트 실패
• 프로덕션 버그
• 예상치 못한 동작
• 성능 문제
• 빌드 실패
• 통합 이슈

특히 다음 상황:

• 시간 압박 (긴급 상황이 추측을 유혹함)
• "그냥 빠른 픽스"가 명백해 보임
• 이미 여러 픽스 시도함
• 이전 픽스가 동작 안 함
• 이슈를 완전히 이해 못 함

생략 금지:

• 이슈가 간단해 보임 (간단한 버그도 근본 원인 있음)
• 급함 (서두르면 재작업 보장)
• 매니저가 지금 고치라 함 (체계적이 thrashing보다 빠름)

네 단계

각 단계를 완료한 뒤에만 다음 단계로.

Phase 1 — 근본 원인 조사

어떤 픽스 시도 전에:

1. 에러 메시지 주의 깊게 읽기

• 에러·경고 건너뛰지 말 것
• 종종 정확한 해법을 담음
• 스택 트레이스 완독
• 줄 번호·파일 경로·에러 코드 기록

2. 일관되게 재현

• 안정적으로 트리거 가능?
• 정확한 단계?
• 매번 발생?
• 재현 불가 → 데이터 더 수집, 추측 금지

3. 최근 변경 확인

• 이를 유발할 수 있는 변경은?
• git diff, 최근 커밋
• 새 의존성·설정 변경
• 환경 차이

4. 다중 컴포넌트 시스템의 증거 수집

CI → 빌드 → 서명 / API → 서비스 → DB 같이 여러 컴포넌트가 있는 시스템이면:

픽스 제안 전에 진단용 계측 추가:

각 컴포넌트 경계에서:
  - 컴포넌트에 들어가는 데이터 로깅
  - 컴포넌트에서 나가는 데이터 로깅
  - 환경·설정 전파 검증
  - 각 계층에서 상태 확인

한 번 실행해 어디서 깨지는지 증거 수집
그 뒤 증거를 분석해 실패 컴포넌트 식별
그 뒤 그 특정 컴포넌트를 조사

예시 (다층 시스템):

# Layer 1: Workflow
echo "=== 워크플로 시크릿: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

# Layer 2: Build script
echo "=== 빌드 스크립트 환경변수: ==="
env | grep IDENTITY || echo "IDENTITY 환경에 없음"

# Layer 3: Signing script
echo "=== Keychain 상태: ==="
security list-keychains
security find-identity -v

# Layer 4: Actual signing
codesign --sign "$IDENTITY" --verbose=4 "$APP"

이것이 보여줌: 어느 계층이 실패하는지 (secrets → workflow ✓, workflow → build ✗)

5. 데이터 흐름 추적

에러가 call stack 깊은 곳에 있을 때:

• 나쁜 값이 어디서 발원?
• 무엇이 나쁜 값으로 이것을 호출?
• 소스를 찾을 때까지 위로 추적
• 증상이 아니라 소스에서 수정

Phase 2 — 패턴 분석

픽스 전에 패턴 찾기:

1. 동작하는 예시 찾기

• 같은 코드베이스에서 유사한 동작하는 코드 위치 파악
• 깨진 것과 유사한데 동작하는 것은?

2. 참조와 대조

• 패턴을 구현 중이면 참조 구현을 완전히 읽기
• 훑지 말 것 — 모든 줄 읽기
• 적용 전 패턴 완전 이해

3. 차이 식별

• 동작과 깨진 것 사이 차이?
• 아무리 작아도 모든 차이 나열
• "그건 상관없겠지" 가정 금지

4. 의존성 이해

• 이게 필요한 다른 컴포넌트?
• 어떤 설정·환경?
• 어떤 가정?

Phase 3 — 가설과 테스트

과학적 방법:

1. 단일 가설 형성

• 명확히 진술: "Y 때문에 X가 근본 원인이라고 본다"
• 기록
• 구체적으로, 모호하지 않게

2. 최소 테스트

• 가설 테스트용 가장 작은 변경
• 한 번에 한 변수
• 여러 개 동시 수정 금지

3. 계속 전 검증

• 동작? 예 → Phase 4
• 아님 → 새 가설 형성
• 위에 픽스 더 쌓지 말 것

4. 모를 때

• "X를 이해 못 함" 선언
• 아는 척 금지
• 도움 요청
• 더 조사

Phase 4 — 구현

증상이 아니라 근본 원인 수정:

1. 실패 테스트 케이스 생성

• 가능한 가장 단순한 재현
• 가능하면 자동 테스트
• 프레임워크 없으면 일회성 스크립트
• 픽스 전에 반드시
• specops-ko:tdd-ko로 실패 테스트 작성

2. 단일 픽스 구현

• 식별된 근본 원인 처리
• 한 번에 한 변경
• "겸사겸사" 개선 금지
• 묶음 리팩터링 금지

3. 픽스 검증

• 테스트가 지금 통과?
• 다른 테스트 안 깨짐?
• 이슈 실제 해결?

4. 픽스가 동작 안 하면

• 중단
• 몇 번째 픽스 시도? 세기
• 3회 미만 → Phase 1 복귀, 새 정보로 재분석
• 3회 이상 → 중단하고 아키텍처 의심 (아래 5번)
• 아키텍처 논의 없이 4번째 픽스 시도 금지

5. 3+ 픽스 실패 시 — 아키텍처 의심

아키텍처 문제를 시사하는 패턴:

• 각 픽스가 다른 곳의 새 공유 상태·결합·문제를 드러냄
• 픽스에 "대규모 리팩터링" 필요
• 각 픽스가 다른 곳의 새 증상 생성

중단하고 근본 의심:

• 이 패턴이 근본적으로 건전한가?
• "관성으로 유지"하고 있는가?
• 증상 계속 픽스 vs 아키텍처 리팩터링?

더 이상 픽스 시도 전에 사용자 파트너와 논의

이는 실패한 가설이 아니라 잘못된 아키텍처.

레드 플래그 — 중단하고 프로세스 따름

다음 생각이 떠오르면:

• "지금은 빠른 픽스, 나중에 조사"
• "X 바꿔보고 동작하는지 봐"
• "여러 변경 추가하고 테스트 실행"
• "테스트 생략, 수동 검증"
• "아마 X일 테니 고치자"
• "완전히 이해 못 하지만 이게 될지도"
• "패턴은 X라 하지만 다르게 적응"
• "주요 문제는 [조사 없이 픽스 나열]"
• 데이터 흐름 추적 전 해법 제안
• "한 번만 더 픽스" (이미 2+ 시도)
• 각 픽스가 다른 곳의 새 문제를 드러냄

모두 의미: 중단. Phase 1 복귀.

3+ 픽스 실패: 아키텍처 의심 (Phase 4.5)

사용자 파트너의 "잘못하고 있다" 신호

다음 리다이렉션 주의:

• "그게 일어나고 있지 않나요?" — 검증 없이 가정
• "[X]를 보여줄까요?" — 증거 수집을 추가했어야
• "추측 그만" — 이해 없이 픽스 제안 중
• "Ultrathink 하세요" — 증상이 아니라 근본 의심
• "우리 막혔나요?" (좌절) — 당신 접근이 동작 안 함

이런 신호 보면: 중단. Phase 1 복귀.

합리화 차단표

변명	실제
"이슈 간단, 프로세스 불필요"	간단한 이슈도 근본 원인 있음. 프로세스는 간단한 버그에 빠름
"응급, 프로세스 시간 없음"	체계적이 추측-체크 thrashing보다 빠름
"일단 시도하고 나중에 조사"	첫 픽스가 패턴을 정한다. 처음부터 제대로
"픽스 확인 후 테스트 작성"	테스트 안 한 픽스는 유지 안 됨. 테스트 먼저가 증명
"동시 여러 픽스로 시간 절약"	무엇이 동작했는지 격리 불가. 새 버그 유발
"참조 길어서 패턴 적응"	부분 이해가 버그를 보장. 완독
"문제 보여서 고침"	증상 보기 ≠ 근본 원인 이해
"한 번만 더 픽스" (2+ 실패 후)	3+ 실패 = 아키텍처 문제. 패턴 의심, 다시 픽스 금지

빠른 참조

단계	핵심 활동	성공 기준
1. 근본 원인	에러 읽기, 재현, 변경 확인, 증거 수집	무엇과 왜를 이해
2. 패턴	동작 예시 찾기, 대조	차이 식별
3. 가설	이론 형성, 최소 테스트	확증 또는 새 가설
4. 구현	테스트 생성, 픽스, 검증	버그 해결, 테스트 통과

"근본 원인 없음" 결론 시

체계적 조사가 이슈가 정말 환경적·타이밍 의존·외부라고 드러내면:

1. 프로세스 완료함
2. 조사한 내용 문서화
3. 적절한 처리 구현 (재시도·타임아웃·에러 메시지)
4. 추후 조사용 모니터링·로깅 추가

그러나: "근본 원인 없음" 사례의 95%는 조사 미완료.

5원칙 주입 (specops-ko 고유)

원칙	본 스킬 적용
1 투명성	가설·테스트·결과를 .specops/<FID>/debug-log.md에 전문 기록
2 문지기	"빠른 픽스"·증상 처리 제안은 즉시 거절
3 깊이	Phase 1 완료 전 픽스 제안 금지 — "빨리 해야 해" 허용 안 됨
4 주권 존중	3+ 픽스 실패 시 사용자 파트너 반드시 개입
5 한계 고백	이해 못 한 부분을 명시. "추정" 라벨

지원 기법

지원 기법 (필요 시 SKILL.md 본문 내에서 인라인 적용):

• root-cause-tracing — 콜 스택 역추적 (Phase 1~2 활용)
• defense-in-depth — 근본 원인 발견 후 다층 검증 (Phase 3 활용)
• condition-based-waiting — 임의 타임아웃을 조건 폴링으로 교체 (Phase 4 활용)

관련 스킬:

• specops-ko:tdd-ko — 실패 테스트 작성 (Phase 4, Step 1)
• specops-ko:verifying-evidence-ko — 픽스 동작 검증, 성공 주장 전

실제 영향

디버깅 세션 실적 (원본):

• 체계적 접근: 15~30분 픽스
• 무작위 픽스: 2~3시간 thrashing
• 첫 시도 성공률: 95% vs 40%
• 신규 버그 유발: 거의 0 vs 흔함

참조

• specops-ko 한국어 선례: skills/systematic-debugging-ko/SKILL.md

다음 skill

근본 원인 식별 + 단일 픽스 완료 후:

• Phase 4.1~4.3 완료 (테스트·픽스·검증) → 상위 호출자 복귀
  • specops-ko:implementing-ko에서 분기된 경우 → implementing-ko 복귀 (해당 태스크 재리뷰)
  • specops-ko:tdd-ko Red-Green 사이클 중 호출된 경우 → tdd-ko 복귀
  • specops-ko:verifying-evidence-ko에서 분기된 경우 → verifying-evidence-ko 재실행
  • specops-ko:integration-test-ko에서 FAIL 분기로 호출된 경우 → integration-test-ko 재실행 (수정 후 통합 테스트 재검증)
  • specops-ko:performance-test-ko에서 FAIL 분기로 호출된 경우 → performance-test-ko 재실행 (수정 후 성능 테스트 재검증)
• Phase 4.5 트리거 (3+ 픽스 실패) → 사용자 파트너 에스컬레이션. chain 정지. 새 스펙 결정 필요