gstack-openclaw-investigate について
gstack-openclaw-investigateは、開発者やコーディングエージェント向けの体系的なデバッグスキルです。根本原因を調査して検証してから最小限の修正を行い、結果を確かめてレポートを保存します。
主な機能
- 01症状と最近の変更の追跡
- 02根本原因の仮説検証
- 03仮説が3回失敗したら停止
- 04回帰テストの追加
- 05修正の検証とレポート保存
活用シーン
- 01再現可能なソフトウェア障害の調査
- 02最近の変更から回帰の原因を追跡
- 03検証済み修正を後続セッション向けに記録
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/gstack-openclaw-investigateを入力して読み込まれたか確認します。
詳細
系統的デバッグ
鉄則
根本原因の調査を先に行わずに修正してはいけません。
症状だけを修正すると、いたちごっこのデバッグになります。根本原因に対処しない修正は、次のバグを見つけにくくします。まず根本原因を突き止めてから、修正してください。
フェーズ 1：根本原因の調査
仮説を立てる前に、状況を把握します。
-
症状を収集します： エラーメッセージ、スタックトレース、再現手順を読みます。ユーザーから十分な情報が提供されていない場合は、一度に質問を 1 つだけしてください。5 つまとめて質問してはいけません。
-
コードを読みます： 症状から原因候補まで、コードの実行経路をたどります。すべての参照を検索し、失敗箇所の周辺にあるロジックを読みます。
-
最近の変更を確認します：
git log --oneline -20 -- <affected-files>以前は動作していましたか？ 何が変わりましたか？ リグレッションの場合、根本原因は差分にあります。
-
再現します： バグを確実に発生させられますか？ できない場合は、先に進む前にさらに証拠を集めてください。
-
同じ領域に関する過去のデバッグセッションがないか、メモリを確認します。同じファイルでバグが繰り返し発生するのは、アーキテクチャ上の問題を示しています。
出力：「根本原因の仮説：…」 … 何がなぜ問題なのかを示す、具体的で検証可能な主張。
フェーズ 2：パターン分析
このバグが既知のパターンに当てはまるか確認します。
競合状態 … 間欠的に発生し、タイミングに依存します。共有状態への並行アクセスを調べます。
nil/null の伝播 … NoMethodError、TypeError。オプショナルな値に対するガードが不足しています。
状態の破損 … データの不整合、部分的な更新。トランザクション、コールバック、フックを確認します。
統合の失敗 … タイムアウト、予期しないレスポンス。外部 API 呼び出しやサービス境界を調べます。
設定のずれ … ローカルでは動作するが、ステージング／本番環境では失敗します。環境変数、機能フラグ、DB の状態を確認します。
古いキャッシュ … 古いデータが表示され、キャッシュをクリアすると直ります。Redis、CDN、ブラウザーキャッシュを確認します。
次も確認します：
- 関連する問題について、プロジェクト内の既知の問題
- 同じ領域で過去に修正が行われていないか、Git のログ。同じファイルでバグが繰り返し発生するのは偶然ではなく、アーキテクチャ上の問題です。
外部検索： バグが既知のパターンに当てはまらない場合は、エラーの種類をオンラインで検索します。先にサニタイズします： ホスト名、IP、ファイルパス、SQL、顧客データを削除します。生のメッセージではなく、エラーのカテゴリを検索してください。
フェーズ 3：仮説の検証
修正をひとつでも書く前に、仮説を検証します。
-
仮説を確認します： 根本原因と疑われる箇所に、一時的なログ出力、アサーション、またはデバッグ出力を追加します。再現手順を実行します。証拠は仮説と一致していますか？
-
仮説が間違っている場合： エラーを検索します（先に機密データをサニタイズします）。フェーズ 1 に戻り、さらに証拠を集めます。推測してはいけません。
-
3 回で打ち切るルール： 3 つの仮説が失敗したら、停止してください。ユーザーに次のように伝えます：
「3 つの仮説を検証しましたが、どれも一致しません。単純なバグではなく、アーキテクチャ上の問題である可能性があります。」
選択肢：
- 新しい仮説で調査を続ける（仮説を説明する）
- 人によるレビューにエスカレーションする（システムに詳しい人が必要です）
- ログを追加して待つ（対象領域に計測を追加し、次回発生時に捕捉します）
危険信号 … 次のいずれかを見つけたら、慎重に進めてください：
- 「とりあえずの簡易修正」 … 「とりあえず」はありません。正しく修正するか、エスカレーションしてください。
- データの流れをたどる前に修正を提案する … 推測にすぎません。
- 修正のたびに別の場所で新たな問題が見つかる … コードではなく、レイヤーが間違っています。
フェーズ 4：実装
根本原因が確認できたら：
-
症状ではなく、根本原因を修正します。 実際の問題を解消する、最小限の変更にします。
-
差分を最小限にします： 変更するファイルと行数をできるだけ少なくします。隣接するコードのリファクタリングは控えてください。
-
リグレッションテストを書きます。テストは次の条件を満たす必要があります：
- 修正なしでは失敗する（テストに意味があることを証明します）
- 修正ありでは成功する（修正が機能することを証明します）
-
テストスイート全体を実行します。 リグレッションは許されません。
-
修正が 5 ファイルを超える場合： 先に進む前に、影響範囲が広いことをユーザーに伝えてください。バグ修正としては大規模です。
フェーズ 5：検証とレポート
新たに検証する： 元のバグが発生した状況を再現し、修正されていることを確認してください。これは必須です。
テストスイートを実行してください。
構造化されたデバッグレポートを出力してください。
デバッグレポート
- 症状： ユーザーが確認した現象
- 根本原因： 実際に何が問題だったか
- 修正： ファイルへの参照を含む変更内容
- 証拠： テストの出力、修正が機能することを示す再現結果
- 回帰テスト： 新しいテストの場所
- 関連事項： 同じ領域の過去のバグ、アーキテクチャに関する注記
- ステータス： DONE | DONE_WITH_CONCERNS | BLOCKED
今後のセッションで参照できるよう、今日の日付を付けてレポートを memory/ に保存してください。
重要なルール
- 修正を 3 回以上試みて失敗した場合：作業を止め、アーキテクチャを見直してください。 仮説が間違っていたのではなく、アーキテクチャが間違っています。
- 検証できない修正は適用しないでください。 再現して確認できない場合は、リリースしないでください。
- 「これで修正されるはずです」とは絶対に言わないでください。 検証して証明してください。テストを実行してください。
- 修正対象のファイルが 5 個を超える場合： 作業を進める前にユーザーに伝えてください。
- 完了ステータス：
- DONE ... 根本原因を特定し、修正を適用し、回帰テストを作成し、すべてのテストに合格
- DONE_WITH_CONCERNS ... 修正済みだが、完全には検証できない（例：断続的に発生するバグ、ステージング環境が必要）
- BLOCKED ... 調査しても根本原因が不明で、エスカレーション済み