msd-core/docs/ko-KR/how-to/debug-a-failed-execution.md

실패한 실행을 디버그하는 방법

목표: 페이즈 실행이 실패하거나, 멈추거나, 불완전한 결과를 생성했을 때 — 이미 성공한 작업을 잃거나 반복하지 않고 깔끔하게 복구하고 재개합니다.

사전 조건: /gsd-execute-phase N을 실행했는데 VERIFICATION.md 작성 전에 실행이 중단된 경우, 또는 예상치 못한 출력, 누락된 파일, 멈춘 스피너가 보이는 경우.

---

실행이 멈췄는지 실패했는지 감지

복구 조치를 취하기 전에 실제로 무슨 일이 일어났는지 파악합니다.

"Spawning…"만 표시되고 1~5분 후에도 출력이 없는 경우

이것은 정상 동작이며 멈춤이 아닙니다. GSD 서브에이전트는 격리된 컨텍스트 창에서 실행됩니다. 스폰 라인의 활성 상태 메모가 이를 확인해 줍니다. 세션을 중단하지 마세요.

10분 이상 결과가 없다면 Claude Code 사이드바를 확인하세요. 에이전트 작업이 완료된 것으로 표시되지만 출력이 나타나지 않았다면 컨텍스트 전환에서 결과가 손실되었을 수 있습니다 — 동일한 명령을 다시 실행합니다:

/gsd-execute-phase 1

GSD는 실행자를 디스패치하기 전에 SUMMARY.md 파일이 있는지 확인합니다. 이미 SUMMARY.md가 있는 플랜은 자동으로 건너뜁니다.

실행이 오류 메시지와 함께 파동 중간에 중단된 경우

git 히스토리를 확인하여 어떤 플랜이 성공적으로 커밋되었는지 확인합니다:

git log --oneline -20

작업을 커밋한 플랜은 feat(01-02): …와 같은 항목을 가집니다. 커밋이 없는 플랜은 불완전하며 재실행 시 다시 실행됩니다.

실행자가 코드를 커밋했지만 SUMMARY.md를 작성하지 않은 경우

GSD는 다음 실행 시 이를 감지하고 세 가지 옵션이 있는 안전 재개 게이트를 표시합니다:

• 수동으로 마무리 — 커밋을 직접 검사하고 SUMMARY.md를 작성한 후 재실행합니다.
• 처음부터 재실행 — 새 실행자를 디스패치하기 전에 부분 커밋을 되돌리거나 대체합니다.
• 표시 후 건너뜀 — 이상 현상을 기록하고 계속 진행하되 명시적인 확인이 필요합니다.

---

근본 원인 진단

/gsd-debug --diagnose 실행

실행이 잘못된 출력, 스텁 코드, 또는 검증 실패를 생성한 경우 수정을 적용하지 않고 조사만 하는 진단 모드를 사용합니다:

/gsd-debug --diagnose "Phase 2 executor produced stubs instead of real code"

--diagnose는 파일을 건드리지 않고 근본 원인에서 멈춥니다. 나중에 조사를 이어갈 수 있도록 .planning/debug/<slug>.md에 세션 파일을 생성합니다.

수정도 적용하는 전체 디버그 세션을 시작하려면:

/gsd-debug "Login middleware not handling 401 correctly after phase 3"

GSD는 증상을 수집하고, 과학적 방법을 사용한 구조화된 조사를 실행하며, 수정안을 제안합니다. 설정에서 tdd_mode: true가 지정된 경우 수정을 적용하기 전에 실패하는 테스트를 요구합니다.

활성 디버그 세션 확인

/gsd-debug list

현재 가설과 다음 조치를 포함한 모든 열린 세션을 표시합니다. 특정 세션을 재개하려면:

/gsd-debug continue <slug>

---

/gsd-forensics로 사후 분석 실행

오류 출력에서 원인이 명확하지 않은 경우 — 예를 들어, 플랜이 존재하지 않는 파일을 참조하거나, 실행이 예상치 못한 결과를 생성하거나, 상태가 손상된 것 같은 경우 — 포렌식 조사를 실행합니다:

/gsd-forensics "Phase 3 execution stalled after wave 1"

GSD는 git 히스토리, .planning/ 아티팩트 완전성, STATE.md 일관성, 커밋되지 않은 작업, 고아 워크트리를 분석합니다. .planning/forensics/report-<timestamp>.md에 구조화된 보고서를 작성하고 권장 복구 단계를 제시합니다.

/gsd-forensics는 읽기 전용으로 프로젝트 파일을 절대 수정하지 않습니다.

감지 항목:

• 반복 루프 — 짧은 시간 내에 연속적으로 세 개 이상의 커밋에 동일한 파일이 나타남(커밋 메시지가 유사하면 HIGH 신뢰도)
• 누락된 아티팩트 — 페이즈에 커밋이 있지만 SUMMARY.md나 VERIFICATION.md가 없음
• 방치된 작업 — 커밋되지 않은 변경과 함께 STATE.md가 실행 중간 상태를 표시하고 마지막 커밋이 두 시간 이상 지남
• 충돌 또는 중단 — 커밋되지 않은 변경과 활성 실행 상태 및 고아 워크트리가 결합됨
• 범위 이탈 — 최근 커밋이 현재 페이즈의 예상 파일 집합 밖의 파일을 수정함

---

복구 후 실행 재개

근본적인 문제가 해결되면 실행 명령을 다시 실행합니다:

/gsd-execute-phase 1

GSD는 이미 SUMMARY.md가 존재하는 플랜을 건너뛰고 나머지 플랜에 대해서만 실행자를 디스패치합니다.

특정 파동만 재실행해야 하는 경우:

/gsd-execute-phase 1 --wave 2

디스패치하기 전에 .planning/ 무결성을 검증하려면:

/gsd-execute-phase 1 --validate

---

/gsd-undo로 롤백

실행이 전적으로 버리고 싶은 코드를 생성한 경우, 수동 git revert 대신 플랜 매니페스트를 사용하여 롤백합니다:

단일 플랜 롤백

/gsd-undo --plan 03-02

페이즈 3의 플랜 02에 대한 모든 커밋을 되돌립니다. GSD는 변경 사항을 작성하기 전에 확인 게이트를 표시합니다.

전체 페이즈 롤백

/gsd-undo --phase 03

페이즈 3의 모든 커밋을 되돌립니다. GSD는 이후 페이즈가 이 페이즈에 의존하는지 확인하고 진행 전에 경고합니다.

최근 커밋에서 대화식으로 선택

/gsd-undo --last 5

가장 최근 GSD 커밋 다섯 개를 표시하고 어떤 것을 되돌릴지 선택할 수 있게 합니다.

---

중단 후 세션 컨텍스트 복원

컨텍스트 초기화나 새 세션 후 프로젝트로 돌아온 경우:

/gsd-resume-work

마지막 핸드오프의 전체 세션 컨텍스트(현재 페이즈, 블로커, 실행이 중단된 위치)를 복원합니다.

또는 현재 위치를 확인하고 다음 올바른 단계로 자동 진행하려면:

/gsd-progress --next

---

관련 문서

• 페이즈 실행
• 복구 및 문제 해결
• 명령 참조
• 문서 인덱스