| name | debug-loop |
| description | 버그 상황과 로그를 받아 재현을 최우선으로 수행하고, git 변경/프로젝트 문서 기반 원인 가설을 반복 검증해 해결한다. 방향 변경이 필요하면 사용자 승인 후 진행한다. |
| argument-hint | [bug-scenario] [log-path-or-snippet] [doc-path(optional)] |
| disable-model-invocation | true |
Debug Loop
버그를 빠르게 고치기 위한 반복 디버깅 스킬이다.
핵심 원칙:
- 재현 우선
- 가장 먼저 버그를 안정적으로 재현한다.
- 재현되지 않으면 추측 수정부터 하지 않는다.
- 근거 기반 가설
- 현재 브랜치/변경 파일/git 이력, 로그, 프로젝트 문서를 함께 보고 가설을 세운다.
- 승인 게이트
- 원 요청 범위를 벗어나거나 다른 방향 전환이 필요하면 반드시 사용자 승인 후 진행한다.
- 루프 수행
- 가설 -> 수정/로깅 -> 재현 테스트 -> 실패 시 다음 가설로 반복한다.
입력 규칙
$ARGUMENTS로 버그 상황과 로그(파일 경로 또는 요약 텍스트), 선택적 문서 경로를 받는다.- 입력이 부족하면 아래를 요청하고 중단한다.
- 재현 절차(명령/클릭 순서)
- 기대 결과 vs 실제 결과
- 오류 로그 원문/스택트레이스
- 발생 환경(브랜치, OS, 런타임)
실행 워크플로우
1단계: 재현 시도 (최우선)
- 입력받은 시나리오/로그로 재현 절차를 정리한다.
- 재현 명령 또는 동작을 실행한다.
- 재현 여부를 명확히 기록한다.
- 재현 성공: 2단계로 진행.
- 재현 실패: 추가 정보 요청 또는 재현용 로깅 추가안을 제시하고 승인 대기.
2단계: 컨텍스트 수집 (git + 문서 + 코드)
재현 성공 후 아래를 우선 수집한다.
- git 컨텍스트
- 현재 브랜치
- 워킹트리 변경 파일
- 최근 커밋/최근 변경 영역
- 프로젝트 문서 컨텍스트
- 루트
AGENTS.md
docs/ 하위 문서plans/ 하위 문서
- 코드 컨텍스트
- 로그 스택트레이스 기준 진입점 파일
- 최근 변경 파일과 겹치는 연관 파일
- 문서에서 언급한 규칙/아키텍처 관련 파일
결과로 "우선 확인 파일 목록"을 만든다.
3단계: 원인 가설 수립
최소 1개, 권장 2~3개 가설을 만든다.
가설마다:
- 근거(로그/코드/git/문서)
- 예상 원인 메커니즘
- 검증 방법(수정 또는 추가 로깅)
4단계: 승인 게이트
아래 상황이면 반드시 사용자 승인 후 진행한다.
- 원래 요청과 다른 해결 방향이 필요한 경우
- 계획되지 않은 큰 리팩토링이 필요한 경우
- 위험한 마이그레이션/설정 변경이 필요한 경우
- 재현 자체가 불안정해서 계측(로깅/추적) 전략 변경이 필요한 경우
보고 템플릿:
[승인 필요]
- 현재 상황: {요약}
- 계획대로 어려운 이유: {이유}
- 제안안 A: {내용}
- 제안안 B: {내용}
- 권장안: {A/B + 이유}
- 영향 범위: {파일/리스크/테스트 영향}
5단계: 가설 검증 루프
아래 루프를 반복한다.
- 가설 선택
- 최소 변경으로 수정 또는 로깅 추가
- 같은 조건으로 버그 재현 테스트 재실행
- 결과 판정
- 버그 미재현: 수정 유지, 관련 테스트 단계로 진행
- 버그 재현됨: 변경을 보완/폐기하고 다음 가설로 진행
권장:
- 한 번에 하나의 가설만 검증한다.
- 임시 로깅은 필요 시 유지/정리 여부를 명시한다.
6단계: 테스트 및 안정화
수정 후 아래를 수행한다.
- 버그 재현 시나리오 재테스트
- 관련 단위/통합/E2E 테스트(프로젝트에서 사용 가능한 범위)
- 실패 시 원인 분석 후 5단계 루프로 복귀
7단계: 결과 보고
최종 보고에 아래를 포함한다.
- 재현 조건 및 재현 결과 변화(수정 전/후)
- 채택한 최종 원인 가설
- 실제 수정 파일 목록
- 시도한 가설/폐기한 가설 요약
- 실행한 테스트와 결과
- 문서 업데이트 점검 결과(점검 대상/반영 여부/반영 내용 또는 미반영 사유)
- 남은 리스크 및 후속 권장 사항
8단계: 문서 업데이트 점검 및 동기화
코드 수정/테스트 안정화가 끝나면 문서 업데이트 필요 여부를 점검한다.
- 점검 대상 문서 수집
$ARGUMENTS에 문서 경로가 있으면 최우선 점검 대상으로 포함한다.- 루트
AGENTS.md를 읽고 문서 관련 규칙/구조에 나온 경로를 점검 후보에 포함한다.
- 예:
README.md, docs/, plans/, CLAUDE.md, .claude/AGENTS.md
- 변경 영향 대비 문서 갭 점검
- 실제 코드 변경/설정 변경/테스트 변경이 문서에 반영되어야 하는지 확인한다.
- 명령어, 환경변수, 실행 절차, 아키텍처 설명, 운영/디버깅 절차 변경 여부를 우선 확인한다.
- 동기화 처리
- 업데이트 필요: 최소 범위로 문서를 즉시 수정하고 결과 보고에 반영한다.
- 업데이트 불필요: "점검 완료, 반영 필요 없음"으로 근거와 함께 결과 보고에 남긴다.
금지 사항
- 재현 확인 없이 임의 수정만 반복
- 승인 필요한 방향 전환을 무단 진행
- 실패한 가설을 성공한 것처럼 보고
- 문서 영향 점검 없이 디버깅 완료로 종료 보고
