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>
324 lines
11 KiB
Markdown
324 lines
11 KiB
Markdown
# 복구 및 문제 해결 방법
|
|
|
|
**목표:** 조건부 레시피 구조를 사용하여 컨텍스트 손실과 손상된 상태부터 설치 실패와 권한 오류까지 일반적인 문제를 식별하고 수정합니다.
|
|
|
|
**사전 조건:** GSD Core가 설치되어 있어야 합니다. 설치 문제의 경우 [런타임에 설치](install-on-your-runtime.md)를 참조하세요.
|
|
|
|
---
|
|
|
|
## 컨텍스트 및 세션 문제
|
|
|
|
### 현재 위치를 파악하지 못한 경우
|
|
|
|
```bash
|
|
/gsd-progress
|
|
```
|
|
|
|
모든 상태 파일을 읽고 현재 위치와 다음 할 일을 정확히 알려줍니다.
|
|
|
|
올바른 다음 단계로 자동 진행하려면:
|
|
|
|
```bash
|
|
/gsd-progress --next
|
|
```
|
|
|
|
### 새 세션을 시작하고 컨텍스트를 복원해야 하는 경우
|
|
|
|
```bash
|
|
/gsd-resume-work
|
|
```
|
|
|
|
마지막 핸드오프의 전체 세션 컨텍스트(현재 페이즈, 계획 결정, 작업이 중단된 위치)를 복원합니다.
|
|
|
|
### 긴 세션 중 품질이 저하되는 경우
|
|
|
|
주요 명령 사이에 컨텍스트 창을 초기화합니다:
|
|
|
|
```bash
|
|
/clear
|
|
```
|
|
|
|
그다음 상태를 복원합니다:
|
|
|
|
```bash
|
|
/gsd-resume-work
|
|
```
|
|
|
|
GSD는 새로운 컨텍스트를 중심으로 설계되었습니다. 모든 서브에이전트는 이미 깨끗한 200k 창을 받습니다. 메인 세션은 시간이 지남에 따라 저하됩니다 — 초기화하고 재개하는 것이 올바른 해결책이며 계속 밀어붙이는 것이 아닙니다.
|
|
|
|
### 중단 전에 컨텍스트를 저장하고 싶은 경우
|
|
|
|
```bash
|
|
/gsd-pause-work
|
|
```
|
|
|
|
현재 위치가 있는 `.planning/HANDOFF.json`을 생성합니다. 세션 후 요약도 `.planning/reports/`에 작성하려면 `--report`를 추가합니다:
|
|
|
|
```bash
|
|
/gsd-pause-work --report
|
|
```
|
|
|
|
---
|
|
|
|
## 계획 무결성 문제
|
|
|
|
### `.planning/` 무결성이 불확실한 경우
|
|
|
|
```bash
|
|
/gsd-health
|
|
```
|
|
|
|
오류, 경고, 정보 메모에 걸쳐 상태를 보고합니다:
|
|
|
|
| 상태 | 의미 |
|
|
|--------|---------|
|
|
| `HEALTHY` | 모든 예상 아티팩트가 존재하고 올바른 형식 |
|
|
| `DEGRADED` | 처리해야 하지만 작업을 계속할 수 있는 경고 |
|
|
| `BROKEN` | 실행을 차단하는 심각한 오류 |
|
|
|
|
일반적인 자동 복구 가능한 문제(오류 E004, E005; 경고 W003, W008):
|
|
|
|
```bash
|
|
/gsd-health --repair
|
|
```
|
|
|
|
누락된 `STATE.md`를 재생성하고, 손상된 `config.json`을 기본값으로 재설정하며, 누락된 구성 키를 추가합니다. `PROJECT.md`나 `ROADMAP.md`를 덮어쓰지 않습니다.
|
|
|
|
### STATE.md가 존재하지 않는 페이즈를 참조하는 경우
|
|
|
|
이것은 경고 `W002`를 생성합니다. 상태 CLI를 사용하여 진단하고 복구합니다:
|
|
|
|
```bash
|
|
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate
|
|
```
|
|
|
|
쓰기 없이 동기화가 변경할 내용 미리 보기:
|
|
|
|
```bash
|
|
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify
|
|
```
|
|
|
|
동기화 적용:
|
|
|
|
```bash
|
|
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync
|
|
```
|
|
|
|
이 명령들은 디스크의 실제 프로젝트 상태에서 `STATE.md`를 재구성합니다. 수동 `STATE.md` 편집을 대체합니다.
|
|
|
|
### "Project already initialised"가 표시되는 경우
|
|
|
|
`.planning/PROJECT.md`가 이미 있습니다. `/gsd-new-project`는 안전 확인입니다. 정말로 처음부터 다시 시작하고 싶다면 먼저 `.planning/` 디렉터리를 삭제합니다:
|
|
|
|
```bash
|
|
rm -rf .planning/
|
|
```
|
|
|
|
그다음 `/gsd-new-project`를 다시 실행합니다.
|
|
|
|
### 컨텍스트 창 사용률이 높은 경우
|
|
|
|
```bash
|
|
/gsd-health --context
|
|
```
|
|
|
|
컨텍스트 창 사용률 가드를 프로브합니다. 60%에서 경고, 70%에서 위험. 경고 임계값을 초과한 경우 다음 주요 명령을 시작하기 전에 `/clear`를 실행한 후 `/gsd-resume-work`를 실행합니다.
|
|
|
|
---
|
|
|
|
## 실행 문제
|
|
|
|
### 실행자가 Bash 명령에서 "Permission denied"를 받는 경우
|
|
|
|
GSD의 `gsd-executor` 서브에이전트는 쓰기 가능한 Bash 접근이 필요합니다. `~/.claude/settings.json`의 `permissions.allow` 아래에 필요한 패턴을 추가합니다. 최소한:
|
|
|
|
```json
|
|
"Bash(git add:*)",
|
|
"Bash(git commit:*)",
|
|
"Bash(git merge:*)",
|
|
"Bash(git checkout:*)"
|
|
```
|
|
|
|
스택별 패턴(Rails, Python, Node, Rust)은 `docs/USER-GUIDE.md`의 "Executor Subagent Gets Permission denied" 섹션의 전체 표를 참조하세요.
|
|
|
|
프로젝트별 대안: 프로젝트 루트의 `.claude/settings.local.json`에 동일한 블록을 추가합니다.
|
|
|
|
### 실행이 실패하거나 스텁을 생성하는 경우
|
|
|
|
플랜이 너무 야심찬지 확인합니다. 플랜에는 최대 두세 개의 작업이 있어야 합니다. 작업이 너무 크면 단일 컨텍스트 창이 안정적으로 생성할 수 있는 것을 초과합니다. 더 작은 범위로 페이즈를 다시 계획합니다:
|
|
|
|
```bash
|
|
/gsd-plan-phase 1
|
|
```
|
|
|
|
무엇이 잘못되었는지에 대한 체계적인 진단은 [실패한 실행 디버그](debug-a-failed-execution.md)를 참조하세요.
|
|
|
|
### 병렬 실행이 빌드 잠금 오류 또는 사전 커밋 훅 실패를 일으키는 경우
|
|
|
|
이것은 여러 에이전트가 동시에 빌드 도구를 트리거하여 발생합니다. GSD는 v1.26 이후 이를 자동으로 처리합니다. 오래된 버전이거나 여전히 경합이 보이면 병렬 실행을 비활성화합니다:
|
|
|
|
```bash
|
|
/gsd-settings
|
|
```
|
|
|
|
`parallelization.enabled`를 `false`로 설정합니다.
|
|
|
|
### 서브에이전트가 실패한 것처럼 보이지만 커밋이 만들어진 경우
|
|
|
|
무언가가 고장났다고 결론 내리기 전에 git 로그를 확인합니다:
|
|
|
|
```bash
|
|
git log --oneline -10
|
|
```
|
|
|
|
알려진 Claude Code 분류 버그로 인해 작업이 성공했는데도 실패를 보고할 수 있습니다. GSD의 오케스트레이터는 실제 출력을 점검하지만 불일치가 보이면 커밋이 실제 근거입니다.
|
|
|
|
---
|
|
|
|
## 플랜 및 페이즈 문제
|
|
|
|
### 플랜이 의도와 맞지 않거나 잘못 정렬된 경우
|
|
|
|
계획 전에 `/gsd-discuss-phase N`을 실행합니다. 대부분의 플랜 품질 문제는 `CONTEXT.md`가 방지했을 가정에서 발생합니다:
|
|
|
|
```bash
|
|
/gsd-discuss-phase 1
|
|
```
|
|
|
|
전체 세션을 시작하지 않고 GSD가 현재 어떤 가정을 하는지 보려면:
|
|
|
|
```bash
|
|
/gsd-discuss-phase 3 --assumptions
|
|
```
|
|
|
|
### 실행 후 무언가를 변경해야 하는 경우
|
|
|
|
`/gsd-execute-phase`를 다시 실행하지 마세요. 대상이 되는 수정에는 `/gsd-quick`을 사용합니다:
|
|
|
|
```bash
|
|
/gsd-quick "Fix the login button not responding on mobile Safari"
|
|
```
|
|
|
|
또는 `/gsd-verify-work N`을 사용하여 UAT를 통해 체계적으로 문제를 식별하고 수정합니다.
|
|
|
|
### 명령이 "Spawning…"에서 멈춘 것처럼 보이는 경우
|
|
|
|
기다리세요. GSD 서브에이전트는 별도의 컨텍스트 창에서 실행됩니다. 진행 중일 때는 상위 세션에서 보이지 않습니다. 스폰 라인의 활성 상태 메모가 이것이 예상된 동작임을 확인합니다. 연구 및 계획 에이전트는 일상적으로 1~5분이 걸립니다. 검증 에이전트는 대규모 페이즈에서 더 오래 걸릴 수 있습니다.
|
|
|
|
세션을 중단하지 마세요. 종료하면 진행 중인 서브에이전트 작업이 버려집니다.
|
|
|
|
10분 이상 지난 경우 Claude Code 사이드바에서 에이전트 작업이 여전히 활성으로 표시되는지 확인합니다.
|
|
|
|
---
|
|
|
|
## 워크플로 상태 문제
|
|
|
|
### 워크플로가 손상되거나 상태가 일관성이 없어 보이는 경우
|
|
|
|
```bash
|
|
/gsd-forensics
|
|
```
|
|
|
|
또는 설명과 함께:
|
|
|
|
```bash
|
|
/gsd-forensics "Phase 3 execution stalled after wave 1"
|
|
```
|
|
|
|
`/gsd-forensics`는 사후 분석 조사를 실행합니다: git 히스토리 이상 감지, 아티팩트 무결성, STATE.md 일관성, 커밋되지 않은 작업, 고아 워크트리. `.planning/forensics/`에 보고서를 작성하고 권장 복구 단계를 제시합니다. 읽기 전용이며 프로젝트 파일을 절대 수정하지 않습니다.
|
|
|
|
### 페이즈 또는 플랜을 롤백해야 하는 경우
|
|
|
|
```bash
|
|
/gsd-undo --phase 03 # 페이즈 3의 모든 커밋 롤백
|
|
/gsd-undo --plan 03-02 # 페이즈 3의 플랜 02 커밋 롤백
|
|
/gsd-undo --last 5 # 가장 최근 GSD 커밋 5개에서 대화식으로 선택
|
|
```
|
|
|
|
`/gsd-undo`는 되돌리기 전에 종속 페이즈를 확인하고 항상 확인 게이트를 표시합니다.
|
|
|
|
---
|
|
|
|
## 설치 및 업데이트 문제
|
|
|
|
### 설치 후 GSD가 인식되지 않는 경우
|
|
|
|
런타임을 재시작합니다. GSD는 런타임의 명령 디렉터리(예: `~/.claude/commands/gsd/`)에 슬래시 명령을 설치합니다. 대부분의 런타임은 시작 시에만 새 명령을 발견합니다.
|
|
|
|
문제가 지속되면 설치를 확인합니다:
|
|
|
|
```bash
|
|
npx @opengsd/gsd-core@latest --claude --local
|
|
```
|
|
|
|
런타임별 설치 경로와 문제 해결은 [런타임에 설치](install-on-your-runtime.md)를 참조하세요.
|
|
|
|
### 업데이트가 로컬 변경 사항을 덮어쓴 경우
|
|
|
|
v1.17 이후 인스톨러는 로컬에서 수정된 파일을 `gsd-local-patches/`에 백업합니다. 변경 사항을 재적용합니다:
|
|
|
|
```bash
|
|
/gsd-update --reapply
|
|
```
|
|
|
|
### npm을 통한 업데이트가 불가능한 경우
|
|
|
|
npm 중단이나 네트워크 제한으로 `npx @opengsd/gsd-core`가 실패하는 경우 npm 접근 없이도 작동하는 단계별 수동 업데이트 절차는 `docs/manual-update.md`를 참조하세요.
|
|
|
|
일상적인 업데이트는 [GSD 업데이트](update-gsd.md)를 참조하세요.
|
|
|
|
---
|
|
|
|
## 비용 문제
|
|
|
|
### 모델 비용이 너무 높은 경우
|
|
|
|
예산 프로필로 전환합니다:
|
|
|
|
```bash
|
|
/gsd-config --profile budget
|
|
```
|
|
|
|
도메인이 익숙한 경우 설정에서 연구 및 플랜 체크 에이전트를 비활성화합니다:
|
|
|
|
```bash
|
|
/gsd-settings
|
|
```
|
|
|
|
활성화된 MCP 서버도 감사합니다. 활성화된 모든 MCP 서버는 모든 턴에 도구 스키마를 주입합니다. 브라우저 및 플랫폼별 도구는 각각 20k+ 토큰이 소요될 수 있습니다. 현재 페이즈에 필요하지 않은 것은 `.claude/settings.json`에서 비활성화합니다:
|
|
|
|
```json
|
|
{
|
|
"disabledMcpjsonServers": ["playwright", "mac-tools"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 복구 빠른 참조
|
|
|
|
| 문제 | 해결책 |
|
|
|---------|---------|
|
|
| 컨텍스트 손실 또는 새 세션 | `/gsd-resume-work` 또는 `/gsd-progress` |
|
|
| 다음 단계를 모름 | `/gsd-progress --next` |
|
|
| 페이즈가 잘못됨 | `/gsd-undo --phase NN`, 그다음 다시 계획 |
|
|
| 무언가 고장남 | `/gsd-debug "description"` (수정 없이 분석만 하려면 `--diagnose` 추가) |
|
|
| STATE.md 동기화 오류 | `state validate` 후 `state sync` |
|
|
| `.planning/` 무결성 불확실 | `/gsd-health`, 그다음 `/gsd-health --repair` |
|
|
| 워크플로 상태 손상 | `/gsd-forensics` |
|
|
| 빠른 대상 수정 | `/gsd-quick` |
|
|
| 플랜이 비전과 맞지 않음 | `/gsd-discuss-phase N` 후 다시 계획 |
|
|
| 비용이 높아짐 | `/gsd-config --profile budget` 및 `/gsd-settings`에서 에이전트 끄기 |
|
|
| 업데이트가 로컬 변경 사항 손상 | `/gsd-update --reapply` |
|
|
| 세션 요약 원함 | `/gsd-pause-work --report` |
|
|
| 병렬 실행 빌드 오류 | GSD 업데이트 또는 `parallelization.enabled: false` 설정 |
|
|
|
|
---
|
|
|
|
## 관련 문서
|
|
|
|
- [실패한 실행 디버그](debug-a-failed-execution.md)
|
|
- [런타임에 설치](install-on-your-runtime.md)
|
|
- [명령 참조](../COMMANDS.md)
|
|
- [문서 인덱스](../README.md)
|