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
7.7 KiB
Markdown
179 lines
7.7 KiB
Markdown
# フェーズ実行の失敗をデバッグする方法
|
|
|
|
**目標:** フェーズ実行が失敗・停止した場合、または不完全な作業が生成された場合に回復し、すでに成功した作業を繰り返すことなく、クリーンな状態で再開する。
|
|
|
|
**前提条件:** `/gsd-execute-phase N` を実行したが、`VERIFICATION.md` が書き込まれる前に実行が停止した、または予期しない出力・ファイル不足・スピナーの停止が確認された状態であること。
|
|
|
|
---
|
|
|
|
## 実行が停止したのか失敗したのかを判断する
|
|
|
|
回復操作を行う前に、実際に何が起きたかを確認してください。
|
|
|
|
### 「Spawning…」のまま 1〜5 分間出力がない場合
|
|
|
|
これはフリーズではなく正常な動作です。GSD のサブエージェントは独立したコンテキストウィンドウで動作します。スポーン行の liveness ノートがこれを確認しています。セッションを中断しないでください。
|
|
|
|
10 分以上経っても結果が得られない場合は、Claude Code のサイドバーを確認してください。エージェントのタスクが完了と表示されているにもかかわらず出力が表示されない場合、コンテキスト切り替え時に結果が失われた可能性があります。同じコマンドを再実行してください。
|
|
|
|
```bash
|
|
/gsd-execute-phase 1
|
|
```
|
|
|
|
GSD はエグゼキューターを dispatching する前に `SUMMARY.md` ファイルを確認します。すでに `SUMMARY.md` があるプランは自動的にスキップされます。
|
|
|
|
### 実行がエラーメッセージとともにウェーブの途中で停止した場合
|
|
|
|
git 履歴を確認して、どのプランが正常にコミットされたかを調べます。
|
|
|
|
```bash
|
|
git log --oneline -20
|
|
```
|
|
|
|
作業をコミットしたプランには `feat(01-02): …` のようなエントリがあります。コミットのないプランは未完了であり、再実行時に再度実行されます。
|
|
|
|
### エグゼキューターがコードをコミットしたが SUMMARY.md を書き込まなかった場合
|
|
|
|
GSD は次回の実行時にこれを検出し、3 つの選択肢を持つ安全な再開ゲートを表示します。
|
|
|
|
- **手動でクローズアウト** — コミットを自分で確認し、`SUMMARY.md` を書いてから再実行する。
|
|
- **最初からやり直し** — 新しいエグゼキューターを dispatching する前に、部分的なコミットを revert または上書きする。
|
|
- **マーク・アンド・スキップ** — 異常を記録して続行する（明示的な確認が必要）。
|
|
|
|
---
|
|
|
|
## 根本原因を診断する
|
|
|
|
### `/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` は読み取り専用です。プロジェクトファイルを変更することはありません。
|
|
|
|
**検出内容：**
|
|
|
|
- **スタックループ** — 短い時間ウィンドウ内に同じファイルが 3 回以上の連続コミットに現れる（コミットメッセージが類似している場合は HIGH 信頼度）
|
|
- **成果物の欠落** — フェーズにコミットはあるが `SUMMARY.md` または `VERIFICATION.md` がない
|
|
- **放棄された作業** — 未コミットの変更があり STATE.md が実行中途を示し、最終コミットが 2 時間以上前
|
|
- **クラッシュまたは中断** — 未コミットの変更とアクティブな実行状態、および孤立したワークツリーの組み合わせ
|
|
- **スコープドリフト** — 直近のコミットが現在のフェーズの想定ファイルセット外のファイルに触れている
|
|
|
|
---
|
|
|
|
## 回復後に実行を再開する
|
|
|
|
根本的な問題が解決したら、実行コマンドを再実行します。
|
|
|
|
```bash
|
|
/gsd-execute-phase 1
|
|
```
|
|
|
|
GSD はすでに `SUMMARY.md` が存在するプランをスキップし、残りのプランのみにエグゼキューターを dispatch します。
|
|
|
|
特定のウェーブだけを再実行する必要がある場合：
|
|
|
|
```bash
|
|
/gsd-execute-phase 1 --wave 2
|
|
```
|
|
|
|
dispatching 前に `.planning/` の整合性を検証したい場合：
|
|
|
|
```bash
|
|
/gsd-execute-phase 1 --validate
|
|
```
|
|
|
|
---
|
|
|
|
## `/gsd-undo` でロールバックする
|
|
|
|
実行が生成したコードを完全に破棄したい場合は、手動の `git revert` ではなくプランマニフェストを使ってロールバックします。
|
|
|
|
### 単一プランをロールバックする
|
|
|
|
```bash
|
|
/gsd-undo --plan 03-02
|
|
```
|
|
|
|
フェーズ `3` のプラン `02` に関するすべてのコミットを revert します。GSD は変更を書き込む前に確認ゲートを表示します。
|
|
|
|
### フェーズ全体をロールバックする
|
|
|
|
```bash
|
|
/gsd-undo --phase 03
|
|
```
|
|
|
|
フェーズ `3` に関するすべてのコミットを revert します。GSD は後続フェーズがこのフェーズに依存しているかどうかを確認し、続行前に警告を表示します。
|
|
|
|
### 直近のコミットからインタラクティブに選ぶ
|
|
|
|
```bash
|
|
/gsd-undo --last 5
|
|
```
|
|
|
|
最近の 5 件の GSD コミットを表示し、revert するものを選択できます。
|
|
|
|
---
|
|
|
|
## 中断後にセッションコンテキストを復元する
|
|
|
|
コンテキストリセットや新しいセッションの後にプロジェクトに戻った場合：
|
|
|
|
```bash
|
|
/gsd-resume-work
|
|
```
|
|
|
|
最後のハンドオフから完全なセッションコンテキスト（現在のフェーズ、ブロッカー、実行が停止した場所を含む）を復元します。
|
|
|
|
または、現在の位置を確認して正しい次のステップに自動的に進むには：
|
|
|
|
```bash
|
|
/gsd-progress --next
|
|
```
|
|
|
|
---
|
|
|
|
## Related
|
|
|
|
- [フェーズを実行する](execute-a-phase.md)
|
|
- [回復とトラブルシューティング](recover-and-troubleshoot.md)
|
|
- [コマンドリファレンス](../COMMANDS.md)
|
|
- [ドキュメント一覧](../README.md)
|