a9a7a328e6
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD across contents and paths, upstream package/repo coordinates -> @golem15/msd-core and golem15com/msd-core. Deep links into upstream history, sibling upstream packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is. Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line, package/plugin identity, regenerated lockfile, install-tree fixtures, derived registries and benchmark baseline; migration checksum baseline re-locked (MSD keeps its own install state, so no install had applied the old sums); sort-order and regex-escaped expectations in tests adjusted.
13 KiB
回復とトラブルシューティングの方法
目標: コンテキストの喪失や状態の破損からインストール失敗やパーミッションエラーまで、条件分岐レシピ構造を使って一般的な問題を特定して修正する。
前提条件: MSD Core がインストール済みであること。インストールの問題については、ランタイムへのインストールを参照してください。
コンテキストとセッションの問題
現在の位置を見失った場合
/msd-progress
すべての状態ファイルを読み込み、現在地と次にすべきことを正確に教えてくれます。
正しい次のステップに自動的に進むには：
/msd-progress --next
新しいセッションを開始してコンテキストを復元する必要がある場合
/msd-resume-work
最後のハンドオフから、現在のフェーズ・計画上の決定・作業が停止した場所を含む完全なセッションコンテキストを復元します。
長いセッションで品質が低下している場合
主要なコマンド間でコンテキストウィンドウをクリアします。
/clear
その後、状態を復元します。
/msd-resume-work
MSD は新鮮なコンテキストを前提に設計されています。すべてのサブエージェントはすでにクリーンな 200k ウィンドウを取得します。メインセッションは時間とともに劣化します。プッシュし続けるのではなく、クリアして再開することが正しい対処法です。
停止前にコンテキストを保存したい場合
/msd-pause-work
現在の位置を含む .planning/HANDOFF.json を作成します。セッション後のサマリーを .planning/reports/ にも書き込む場合は --report を追加します。
/msd-pause-work --report
計画整合性の問題
.planning/ の整合性が不確かな場合
/msd-health
エラー、警告、情報ノートにわたるステータスを報告します。
| ステータス | 意味 |
|---|---|
HEALTHY |
期待される成果物がすべて存在し、正しい形式である |
DEGRADED |
対処すべき警告があるが作業は続行できる |
BROKEN |
実行をブロックする重大なエラーがある |
自動修復可能な一般的な問題（エラー E004、E005；警告 W003、W008）：
/msd-health --repair
これにより不足している STATE.md が再作成され、破損した config.json がデフォルトにリセットされ、不足している設定キーが追加されます。PROJECT.md や ROADMAP.md は上書きされません。
STATE.md が存在しないフェーズを参照している場合
これは警告 W002 を生成します。状態 CLI を使って診断と修復を行います。
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state validate
書き込まずに同期で何が変わるかをプレビューします。
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync --verify
同期を適用します。
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync
これらのコマンドはディスク上の実際のプロジェクト状態から STATE.md を再構築します。手動での STATE.md 編集に代わるものです。
「Project already initialised」と表示される場合
.planning/PROJECT.md がすでに存在します。/msd-new-project は安全チェックです。本当に最初からやり直したい場合は、まず .planning/ ディレクトリを削除します。
rm -rf .planning/
その後 /msd-new-project を再実行します。
コンテキストウィンドウの使用率が高い場合
/msd-health --context
コンテキストウィンドウ使用率ガードを調査します。60% で警告、70% でクリティカル。警告閾値を超えている場合は、次の主要なコマンドを開始する前に /clear を実行してから /msd-resume-work を実行してください。
実行の問題
エグゼキューターが Bash コマンドで「Permission denied」になる場合
MSD の msd-executor サブエージェントには書き込み可能な Bash アクセスが必要です。~/.claude/settings.json の permissions.allow に必要なパターンを追加します。最低限：
"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 に同じブロックを追加する。
実行が失敗するか、スタブが生成される場合
プランが過度に野心的でないか確認してください。プランには最大でも 2〜3 個のタスクを含めるべきです。タスクが大きすぎると、単一のコンテキストウィンドウが確実に生成できる範囲を超えます。より小さいスコープでフェーズを再計画します。
/msd-plan-phase 1
何が起きたかを体系的に診断するには、フェーズ実行の失敗をデバッグするを参照してください。
並行実行がビルドロックエラーやプリコミットフック失敗を引き起こす場合
これは複数のエージェントが同時にビルドツールをトリガーすることで発生します。MSD は v1.26 以降、これを自動的に処理します。古いバージョンを使用している場合、またはまだ競合が見られる場合は、並行実行を無効にします。
/msd-settings
parallelization.enabled を false に設定します。
サブエージェントが失敗しているように見えるがコミットが行われている場合
何かが壊れていると判断する前に git ログを確認します。
git log --oneline -10
Claude Code の既知の分類バグで、作業が成功したのに失敗と報告される場合があります。MSD のオーケストレーターは実際の出力をスポットチェックしますが、不一致が見られる場合はコミットが真実です。
プランとフェーズの問題
プランが意図と異なる、または整合していない場合
計画前に /msd-discuss-phase N を実行します。プランの品質問題のほとんどは、CONTEXT.md があれば防げた前提から生じます。
/msd-discuss-phase 1
完全なセッションを開始せずに MSD が現在行っている前提を確認するには：
/msd-discuss-phase 3 --assumptions
実行後に何かを変更する必要がある場合
/msd-execute-phase を再実行しないでください。対象を絞った修正には /msd-quick を使用します。
/msd-quick "Fix the login button not responding on mobile Safari"
または /msd-verify-work N を使って UAT を通じて体系的に問題を特定・修正します。
コマンドが「Spawning…」でフリーズしているように見える場合
待ってください。MSD サブエージェントは別のコンテキストウィンドウで動作します。その作業は進行中の間、親セッションからは見えません。スポーン行の liveness ノートがこれが期待される動作であることを確認しています。リサーチと計画エージェントは通常 1〜5 分かかります。大きなフェーズでは検証エージェントがさらに時間がかかる場合があります。
セッションを中断しないでください。セッションを終了すると進行中のサブエージェント作業が破棄されます。
10 分以上経過した場合は、Claude Code のサイドバーでエージェントタスクがまだアクティブと表示されているか確認してください。
ワークフロー状態の問題
ワークフローが破損しているか、状態が一貫していない場合
/msd-forensics
または説明を添えて：
/msd-forensics "Phase 3 execution stalled after wave 1"
/msd-forensics はポストモーテム調査を実行します：git 履歴の異常、成果物の整合性、STATE.md の一貫性、未コミットの作業、孤立したワークツリー。レポートを .planning/forensics/ に書き込み、推奨される修復手順を提示します。読み取り専用であり、プロジェクトファイルを変更することはありません。
フェーズまたはプランをロールバックする必要がある場合
/msd-undo --phase 03 # フェーズ 3 のすべてのコミットをロールバックする
/msd-undo --plan 03-02 # フェーズ 3 のプラン 02 のコミットをロールバックする
/msd-undo --last 5 # 最近の 5 件の MSD コミットからインタラクティブに選ぶ
/msd-undo はロールバック前に依存するフェーズを確認し、常に確認ゲートを表示します。
インストールとアップデートの問題
インストール後に MSD が認識されない場合
ランタイムを再起動してください。MSD はランタイムのコマンドディレクトリ（例：~/.claude/commands/msd/）にスラッシュコマンドをインストールします。ほとんどのランタイムは起動時にのみ新しいコマンドを検出します。
問題が続く場合はインストールを確認します。
npx @golem15/msd-core@latest --claude --local
ランタイム固有のインストールパスとトラブルシューティングについては、ランタイムへのインストールを参照してください。
アップデートがローカルの変更を上書きした場合
v1.17 以降、インストーラはローカルで変更されたファイルを msd-local-patches/ にバックアップします。変更を再適用します。
/msd-update --reapply
npm 経由でアップデートできない場合
npm の障害やネットワーク制限のために npx @golem15/msd-core が失敗する場合は、docs/manual-update.md に npm アクセスなしで動作するステップバイステップの手動アップデート手順があります。
定期的なアップデートについては、MSD のアップデートを参照してください。
コストの問題
モデルのコストが高すぎる場合
バジェットプロファイルに切り替えます。
/msd-config --profile budget
ドメインが慣れ親しんだものであれば、設定でリサーチとプランチェックのエージェントを無効にします。
/msd-settings
また、有効になっている MCP サーバーを監査してください。有効な MCP サーバーはそれぞれのツールスキーマをすべてのターンに注入します。ブラウザとプラットフォーム固有のツールはそれぞれ 20,000 トークン以上かかる場合があります。現在のフェーズに不要なものは .claude/settings.json で無効にしてください。
{
"disabledMcpjsonServers": ["playwright", "mac-tools"]
}
回復クイックリファレンス
| 問題 | 解決策 |
|---|---|
| コンテキストを失った、または新しいセッション | /msd-resume-work または /msd-progress |
| 次のステップがわからない | /msd-progress --next |
| フェーズがうまくいかなかった | /msd-undo --phase NN、その後再計画する |
| 何かが壊れた | /msd-debug "description"（修正なしの分析は --diagnose を追加） |
| STATE.md が同期していない | state validate その後 state sync |
.planning/ の整合性が不確か |
/msd-health、その後 /msd-health --repair |
| ワークフロー状態が破損しているように見える | /msd-forensics |
| 対象を絞った素早い修正 | /msd-quick |
| プランがビジョンと一致しない | /msd-discuss-phase N その後再計画する |
| コストが高くなっている | /msd-config --profile budget と /msd-settings でエージェントをオフにする |
| アップデートがローカルの変更を壊した | /msd-update --reapply |
| セッションのサマリーが必要 | /msd-pause-work --report |
| 並行実行のビルドエラー | MSD をアップデートするか parallelization.enabled: false を設定する |