skillDesk/.trae/skills/systematic-debugging/SKILL.md

name, description

name	description
systematic-debugging	버그, 테스트 실패, 예기치 않은 동작을 체계적으로 진단합니다. 수정안을 제시하기 전에 반드시 근본 원인을 먼저 찾아야 할 때 호출합니다.

체계적 디버깅

무작위 수정은 시간을 낭비하고 새 버그를 만듭니다. 빠른 땜질은 증상만 가릴 뿐입니다. 이 스킬의 핵심은 수정 전에 반드시 근본 원인을 찾는 것입니다.

철칙

근본 원인 조사 없이 수정하지 않습니다.

다시 말해, 1단계를 끝내지 않았다면 수정안 제시는 아직 허용되지 않습니다.

언제 사용할지

다음과 같은 모든 기술 문제에서 사용합니다.

• 테스트 실패
• 운영 중 버그
• 예기치 않은 동작
• 성능 문제
• 빌드 실패
• 통합 문제

특히 아래 상황에서 반드시 사용합니다.

• 시간이 촉박할 때
• "일단 이것만 빨리 고치면 될 것 같을 때"
• 이미 여러 수정안을 시도했을 때
• 이전 수정이 실패했을 때
• 문제를 완전히 이해하지 못한 상태일 때

다음 상황에서도 생략하지 않습니다.

• 문제가 너무 단순해 보일 때
• 급하게 고쳐 달라는 압박이 있을 때
• 지금 보이는 증상만 없애면 될 것처럼 느껴질 때

4단계 프로세스

1단계: 근본 원인 조사

수정 전에 반드시 아래를 수행합니다.

• 오류 메시지, 경고, 스택 트레이스를 끝까지 읽습니다.
• 재현 절차를 명확히 만들고, 반복 재현 가능한지 확인합니다.
• 최근 변경 사항, 설정 차이, 의존성 변경, 환경 차이를 확인합니다.
• 다중 컴포넌트 시스템이라면 경계마다 로그와 계측을 추가해 어디서 깨지는지 증거를 모읍니다.
• 호출 스택이 깊다면 잘못된 값이 어디서 시작됐는지 거꾸로 추적합니다.
• 재현이 안정적이지 않다면, 추측 대신 로그와 관찰 지점을 늘립니다.
• 레이어가 여러 개인 시스템이라면 각 경계에서 입력, 출력, 상태 전파를 확인합니다.

2단계: 패턴 분석

• 같은 코드베이스에서 정상 동작하는 유사 사례를 찾습니다.
• 참조 구현이 있다면 끝까지 읽고 패턴을 정확히 이해합니다.
• 정상 사례와 문제 사례의 차이를 작은 것까지 모두 나열합니다.
• 필요한 설정, 환경, 전제 조건을 파악합니다.
• "이 정도 차이는 중요하지 않겠지"라고 넘기지 않습니다.

3단계: 가설과 검증

• "원인은 X이며 이유는 Y다"라는 단일 가설을 명확히 적습니다.
• 가설을 검증할 수 있는 최소 변경만 적용합니다.
• 한 번에 변수 하나만 바꿉니다.
• 실패하면 수정안을 겹쳐 쌓지 말고 새 가설로 돌아갑니다.
• 모르는 것은 모른다고 인정하고 추가 조사 또는 도움 요청을 합니다.

이 단계의 핵심은 과학적 방법입니다.

• 한 번에 하나의 가설만 세웁니다.
• 한 번에 하나의 변수만 바꿉니다.
• 실패하면 더 많은 수정으로 덮지 않고, 얻은 새 증거를 바탕으로 다시 분석합니다.

4단계: 구현

• 먼저 실패하는 테스트나 최소 재현 케이스를 만듭니다.
• 확인된 근본 원인만 겨냥해 한 번에 한 수정만 적용합니다.
• 테스트가 통과하는지, 다른 것이 깨지지 않았는지 검증합니다.
• 수정이 실패하면 즉시 멈추고 다시 1단계로 돌아갑니다.
• 세 번 이상 실패했다면 개별 버그가 아니라 구조적 문제일 가능성을 의심합니다.

세 번 이상 수정이 연속 실패했다면 아래를 질문합니다.

• 우리가 증상을 계속 쫓고 있지는 않은가
• 현재 구조 자체가 문제를 유발하고 있지는 않은가
• 고칠 문제가 아니라 패턴을 바꿔야 하는 상황은 아닌가

중단 신호

다음 생각이 들면 멈추고 다시 1단계로 돌아갑니다.

• 일단 빨리 고치고 나중에 조사하자
• X를 바꿔보면 될 것 같다
• 여러 개를 같이 바꾸면 빠를 것 같다
• 테스트는 나중에 쓰자
• 완전히 이해는 못 했지만 아마 맞을 것이다
• 한 번만 더 고쳐보자
• 여기 문제들은 대충 이런 것들이다
• 로그 없이 감으로 수정 방향을 정하자
• 여기저기 같이 바꾸면 하나쯤 맞을 것이다

이 신호들은 대부분 조사보다 추측이 앞서고 있다는 뜻입니다.

안티 패턴

• 증상만 감추는 빠른 땜질
• 여러 수정안을 한 번에 넣는 방식
• 재현 없이 감으로 고치는 방식
• 비교 대상 없이 현재 코드만 들여다보는 방식
• 세 번 이상 실패했는데도 구조를 의심하지 않는 방식

핵심 원칙

• 증상이 아니라 원인을 수정합니다.
• 계측과 증거 없이 추측하지 않습니다.
• 한 번에 하나만 바꿉니다.
• 재현, 비교, 검증이 없는 수정은 완료가 아닙니다.
• 여러 번 실패하면 구조 자체를 의심합니다.

기대 결과

이 스킬을 적용한 결과는 다음을 만족해야 합니다.

• 문제의 재현 절차가 설명 가능해야 합니다.
• 근본 원인을 뒷받침하는 증거가 있어야 합니다.
• 수정안은 하나의 원인에 대응해야 합니다.
• 수정 후에는 재현 테스트 또는 검증 절차가 통과해야 합니다.