3bb2f8f1c5
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
179 lines
6.7 KiB
Markdown
179 lines
6.7 KiB
Markdown
# 실패한 실행을 디버그하는 방법
|
|
|
|
**목표:** 페이즈 실행이 실패하거나, 멈추거나, 불완전한 결과를 생성했을 때 — 이미 성공한 작업을 잃거나 반복하지 않고 깔끔하게 복구하고 재개합니다.
|
|
|
|
**사전 조건:** `/gsd-execute-phase N`을 실행했는데 `VERIFICATION.md` 작성 전에 실행이 중단된 경우, 또는 예상치 못한 출력, 누락된 파일, 멈춘 스피너가 보이는 경우.
|
|
|
|
---
|
|
|
|
## 실행이 멈췄는지 실패했는지 감지
|
|
|
|
복구 조치를 취하기 전에 실제로 무슨 일이 일어났는지 파악합니다.
|
|
|
|
### "Spawning…"만 표시되고 1~5분 후에도 출력이 없는 경우
|
|
|
|
이것은 정상 동작이며 멈춤이 아닙니다. GSD 서브에이전트는 격리된 컨텍스트 창에서 실행됩니다. 스폰 라인의 활성 상태 메모가 이를 확인해 줍니다. 세션을 중단하지 마세요.
|
|
|
|
10분 이상 결과가 없다면 Claude Code 사이드바를 확인하세요. 에이전트 작업이 완료된 것으로 표시되지만 출력이 나타나지 않았다면 컨텍스트 전환에서 결과가 손실되었을 수 있습니다 — 동일한 명령을 다시 실행합니다:
|
|
|
|
```bash
|
|
/gsd-execute-phase 1
|
|
```
|
|
|
|
GSD는 실행자를 디스패치하기 전에 `SUMMARY.md` 파일이 있는지 확인합니다. 이미 `SUMMARY.md`가 있는 플랜은 자동으로 건너뜁니다.
|
|
|
|
### 실행이 오류 메시지와 함께 파동 중간에 중단된 경우
|
|
|
|
git 히스토리를 확인하여 어떤 플랜이 성공적으로 커밋되었는지 확인합니다:
|
|
|
|
```bash
|
|
git log --oneline -20
|
|
```
|
|
|
|
작업을 커밋한 플랜은 `feat(01-02): …`와 같은 항목을 가집니다. 커밋이 없는 플랜은 불완전하며 재실행 시 다시 실행됩니다.
|
|
|
|
### 실행자가 코드를 커밋했지만 SUMMARY.md를 작성하지 않은 경우
|
|
|
|
GSD는 다음 실행 시 이를 감지하고 세 가지 옵션이 있는 안전 재개 게이트를 표시합니다:
|
|
|
|
- **수동으로 마무리** — 커밋을 직접 검사하고 `SUMMARY.md`를 작성한 후 재실행합니다.
|
|
- **처음부터 재실행** — 새 실행자를 디스패치하기 전에 부분 커밋을 되돌리거나 대체합니다.
|
|
- **표시 후 건너뜀** — 이상 현상을 기록하고 계속 진행하되 명시적인 확인이 필요합니다.
|
|
|
|
---
|
|
|
|
## 근본 원인 진단
|
|
|
|
### `/gsd-debug --diagnose` 실행
|
|
|
|
실행이 잘못된 출력, 스텁 코드, 또는 검증 실패를 생성한 경우 수정을 적용하지 않고 조사만 하는 진단 모드를 사용합니다:
|
|
|
|
```bash
|
|
/gsd-debug --diagnose "Phase 2 executor produced stubs instead of real code"
|
|
```
|
|
|
|
`--diagnose`는 파일을 건드리지 않고 근본 원인에서 멈춥니다. 나중에 조사를 이어갈 수 있도록 `.planning/debug/<slug>.md`에 세션 파일을 생성합니다.
|
|
|
|
수정도 적용하는 전체 디버그 세션을 시작하려면:
|
|
|
|
```bash
|
|
/gsd-debug "Login middleware not handling 401 correctly after phase 3"
|
|
```
|
|
|
|
GSD는 증상을 수집하고, 과학적 방법을 사용한 구조화된 조사를 실행하며, 수정안을 제안합니다. 설정에서 `tdd_mode: true`가 지정된 경우 수정을 적용하기 전에 실패하는 테스트를 요구합니다.
|
|
|
|
### 활성 디버그 세션 확인
|
|
|
|
```bash
|
|
/gsd-debug list
|
|
```
|
|
|
|
현재 가설과 다음 조치를 포함한 모든 열린 세션을 표시합니다. 특정 세션을 재개하려면:
|
|
|
|
```bash
|
|
/gsd-debug continue <slug>
|
|
```
|
|
|
|
---
|
|
|
|
## `/gsd-forensics`로 사후 분석 실행
|
|
|
|
오류 출력에서 원인이 명확하지 않은 경우 — 예를 들어, 플랜이 존재하지 않는 파일을 참조하거나, 실행이 예상치 못한 결과를 생성하거나, 상태가 손상된 것 같은 경우 — 포렌식 조사를 실행합니다:
|
|
|
|
```bash
|
|
/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가 실행 중간 상태를 표시하고 마지막 커밋이 두 시간 이상 지남
|
|
- **충돌 또는 중단** — 커밋되지 않은 변경과 활성 실행 상태 및 고아 워크트리가 결합됨
|
|
- **범위 이탈** — 최근 커밋이 현재 페이즈의 예상 파일 집합 밖의 파일을 수정함
|
|
|
|
---
|
|
|
|
## 복구 후 실행 재개
|
|
|
|
근본적인 문제가 해결되면 실행 명령을 다시 실행합니다:
|
|
|
|
```bash
|
|
/gsd-execute-phase 1
|
|
```
|
|
|
|
GSD는 이미 `SUMMARY.md`가 존재하는 플랜을 건너뛰고 나머지 플랜에 대해서만 실행자를 디스패치합니다.
|
|
|
|
특정 파동만 재실행해야 하는 경우:
|
|
|
|
```bash
|
|
/gsd-execute-phase 1 --wave 2
|
|
```
|
|
|
|
디스패치하기 전에 `.planning/` 무결성을 검증하려면:
|
|
|
|
```bash
|
|
/gsd-execute-phase 1 --validate
|
|
```
|
|
|
|
---
|
|
|
|
## `/gsd-undo`로 롤백
|
|
|
|
실행이 전적으로 버리고 싶은 코드를 생성한 경우, 수동 `git revert` 대신 플랜 매니페스트를 사용하여 롤백합니다:
|
|
|
|
### 단일 플랜 롤백
|
|
|
|
```bash
|
|
/gsd-undo --plan 03-02
|
|
```
|
|
|
|
페이즈 `3`의 플랜 `02`에 대한 모든 커밋을 되돌립니다. GSD는 변경 사항을 작성하기 전에 확인 게이트를 표시합니다.
|
|
|
|
### 전체 페이즈 롤백
|
|
|
|
```bash
|
|
/gsd-undo --phase 03
|
|
```
|
|
|
|
페이즈 `3`의 모든 커밋을 되돌립니다. GSD는 이후 페이즈가 이 페이즈에 의존하는지 확인하고 진행 전에 경고합니다.
|
|
|
|
### 최근 커밋에서 대화식으로 선택
|
|
|
|
```bash
|
|
/gsd-undo --last 5
|
|
```
|
|
|
|
가장 최근 GSD 커밋 다섯 개를 표시하고 어떤 것을 되돌릴지 선택할 수 있게 합니다.
|
|
|
|
---
|
|
|
|
## 중단 후 세션 컨텍스트 복원
|
|
|
|
컨텍스트 초기화나 새 세션 후 프로젝트로 돌아온 경우:
|
|
|
|
```bash
|
|
/gsd-resume-work
|
|
```
|
|
|
|
마지막 핸드오프의 전체 세션 컨텍스트(현재 페이즈, 블로커, 실행이 중단된 위치)를 복원합니다.
|
|
|
|
또는 현재 위치를 확인하고 다음 올바른 단계로 자동 진행하려면:
|
|
|
|
```bash
|
|
/gsd-progress --next
|
|
```
|
|
|
|
---
|
|
|
|
## 관련 문서
|
|
|
|
- [페이즈 실행](execute-a-phase.md)
|
|
- [복구 및 문제 해결](recover-and-troubleshoot.md)
|
|
- [명령 참조](../COMMANDS.md)
|
|
- [문서 인덱스](../README.md)
|