debug-loop

name	debug-loop
description	버그 상황과 로그를 받아 재현을 최우선으로 수행하고, git 변경/프로젝트 문서 기반 원인 가설을 반복 검증해 해결한다. 방향 변경이 필요하면 사용자 승인 후 진행한다.
argument-hint	[bug-scenario] [log-path-or-snippet] [doc-path(optional)]
disable-model-invocation	true

Debug Loop

버그를 빠르게 고치기 위한 반복 디버깅 스킬이다.

핵심 원칙:

1. 재현 우선

• 가장 먼저 버그를 안정적으로 재현한다.
• 재현되지 않으면 추측 수정부터 하지 않는다.

2. 근거 기반 가설

• 현재 브랜치/변경 파일/git 이력, 로그, 프로젝트 문서를 함께 보고 가설을 세운다.

3. 승인 게이트

• 원 요청 범위를 벗어나거나 다른 방향 전환이 필요하면 반드시 사용자 승인 후 진행한다.

4. 루프 수행

• 가설 -> 수정/로깅 -> 재현 테스트 -> 실패 시 다음 가설로 반복한다.

입력 규칙

• $ARGUMENTS로 버그 상황과 로그(파일 경로 또는 요약 텍스트), 선택적 문서 경로를 받는다.
• 입력이 부족하면 아래를 요청하고 중단한다.
  • 재현 절차(명령/클릭 순서)
  • 기대 결과 vs 실제 결과
  • 오류 로그 원문/스택트레이스
  • 발생 환경(브랜치, OS, 런타임)

실행 워크플로우

1단계: 재현 시도 (최우선)

1. 입력받은 시나리오/로그로 재현 절차를 정리한다.
2. 재현 명령 또는 동작을 실행한다.
3. 재현 여부를 명확히 기록한다.

• 재현 성공: 2단계로 진행.
• 재현 실패: 추가 정보 요청 또는 재현용 로깅 추가안을 제시하고 승인 대기.

2단계: 컨텍스트 수집 (git + 문서 + 코드)

재현 성공 후 아래를 우선 수집한다.

1. git 컨텍스트

• 현재 브랜치
• 워킹트리 변경 파일
• 최근 커밋/최근 변경 영역

2. 프로젝트 문서 컨텍스트

• 루트 AGENTS.md
• docs/ 하위 문서
• plans/ 하위 문서

3. 코드 컨텍스트

• 로그 스택트레이스 기준 진입점 파일
• 최근 변경 파일과 겹치는 연관 파일
• 문서에서 언급한 규칙/아키텍처 관련 파일

결과로 "우선 확인 파일 목록"을 만든다.

3단계: 원인 가설 수립

최소 1개, 권장 2~3개 가설을 만든다.

가설마다:

• 근거(로그/코드/git/문서)
• 예상 원인 메커니즘
• 검증 방법(수정 또는 추가 로깅)

4단계: 승인 게이트

아래 상황이면 반드시 사용자 승인 후 진행한다.

• 원래 요청과 다른 해결 방향이 필요한 경우
• 계획되지 않은 큰 리팩토링이 필요한 경우
• 위험한 마이그레이션/설정 변경이 필요한 경우
• 재현 자체가 불안정해서 계측(로깅/추적) 전략 변경이 필요한 경우

보고 템플릿:

[승인 필요]
- 현재 상황: {요약}
- 계획대로 어려운 이유: {이유}
- 제안안 A: {내용}
- 제안안 B: {내용}
- 권장안: {A/B + 이유}
- 영향 범위: {파일/리스크/테스트 영향}

5단계: 가설 검증 루프

아래 루프를 반복한다.

1. 가설 선택
2. 최소 변경으로 수정 또는 로깅 추가
3. 같은 조건으로 버그 재현 테스트 재실행
4. 결과 판정

• 버그 미재현: 수정 유지, 관련 테스트 단계로 진행
• 버그 재현됨: 변경을 보완/폐기하고 다음 가설로 진행

권장:

• 한 번에 하나의 가설만 검증한다.
• 임시 로깅은 필요 시 유지/정리 여부를 명시한다.

6단계: 테스트 및 안정화

수정 후 아래를 수행한다.

1. 버그 재현 시나리오 재테스트
2. 관련 단위/통합/E2E 테스트(프로젝트에서 사용 가능한 범위)
3. 실패 시 원인 분석 후 5단계 루프로 복귀

7단계: 결과 보고

최종 보고에 아래를 포함한다.

• 재현 조건 및 재현 결과 변화(수정 전/후)
• 채택한 최종 원인 가설
• 실제 수정 파일 목록
• 시도한 가설/폐기한 가설 요약
• 실행한 테스트와 결과
• 문서 업데이트 점검 결과(점검 대상/반영 여부/반영 내용 또는 미반영 사유)
• 남은 리스크 및 후속 권장 사항

8단계: 문서 업데이트 점검 및 동기화

코드 수정/테스트 안정화가 끝나면 문서 업데이트 필요 여부를 점검한다.

1. 점검 대상 문서 수집

• $ARGUMENTS에 문서 경로가 있으면 최우선 점검 대상으로 포함한다.
• 루트 AGENTS.md를 읽고 문서 관련 규칙/구조에 나온 경로를 점검 후보에 포함한다.
  • 예: README.md, docs/, plans/, CLAUDE.md, .claude/AGENTS.md

2. 변경 영향 대비 문서 갭 점검

• 실제 코드 변경/설정 변경/테스트 변경이 문서에 반영되어야 하는지 확인한다.
• 명령어, 환경변수, 실행 절차, 아키텍처 설명, 운영/디버깅 절차 변경 여부를 우선 확인한다.

3. 동기화 처리

• 업데이트 필요: 최소 범위로 문서를 즉시 수정하고 결과 보고에 반영한다.
• 업데이트 불필요: "점검 완료, 반영 필요 없음"으로 근거와 함께 결과 보고에 남긴다.

금지 사항

• 재현 확인 없이 임의 수정만 반복
• 승인 필요한 방향 전환을 무단 진행
• 실패한 가설을 성공한 것처럼 보고
• 문서 영향 점검 없이 디버깅 완료로 종료 보고