什么是 系统化调试？

系统化调试技能是专为 AI 编程智能体设计的专业工作流，旨在超越试错式的修复模式。通过实施“重现、隔离、识别、验证”这结构化的四个阶段，它确保每个技术问题都有清晰的证据链。作为 Openclaw Skills 库的核心部分，该工具强制智能体记录错误条件、缩小组件范围，并使用“五个为什么”等技术进行深度根因分析。

该技能对于存在间歇性漏洞或静默失败的复杂环境特别有价值。它将 AI 从简单的代码生成器转变为能够进行日志分析、环境验证和回归测试的高级诊断工程师。通过利用 Openclaw Skills 进行调试，开发人员可以确保更高的代码可靠性并减少重复出现的回归问题。

下载入口:https://github.com/openclaw/skills/tree/main/skills/sa9saq/systematic-debug

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

系统化调试 应用场景

• 当 AI 智能体检测到运行时错误或构建失败时，自动触发诊断会话。
• 进行“五个为什么”分析，以揭示 API 返回不一致的 500 错误的原因。
• 通过对近期提交差异进行二分查找，在大代码库中隔离回归问题。
• 通过运行自动化验证检查，验证漏洞修复是否未引入副作用。

1. 第一阶段（重现）：智能体获取确切的错误消息、堆栈跟踪和环境条件，以创建最小化重现步骤。
2. 第二阶段（隔离）：通过识别相关组件并对比正常与异常状态，缩小问题范围。
3. 第三阶段（识别）：形成假设，并针对空指针、异步竞争条件或类型不匹配等常见模式进行测试。
4. 第四阶段（验证）：智能体应用修复程序，确认原始错误已消除，检查副作用，并添加回归测试。

系统化调试 配置指南

要在您的智能体环境中激活此技能，请将其包含在配置清单中。确保将自动触发关键字映射到您的特定工作流。

# 通过 Openclaw Skills 管理器安装技能
openclaw install systematic-debug

安装后，智能体将监控“调试”、“漏洞”或“无法工作”等关键词，以自动启动四阶段生命周期。

系统化调试 数据架构与分类体系

该技能将调试数据组织为结构化格式，以维持整个生命周期的状态：

name: systematic-debug
description: Evidence-based debugging through 4 phases. Reproduce, isolate, identify root cause, verify fix. Auto-triggers on errors.
auto_trigger: true
trigger:
  keyword: デバッグ|debug|バグ|bug|動かない|not working|エラー解決|fix error

Systematic Debugging Skill

証拠ベースの体系的デバッグ。4フェーズで根本原因を特定し、修正を検証。

デバッグフェーズ

Phase 1: 再現（Reproduce）

目的: 問題を確実に再現する

手順:
  1. エラーメッセージを正確に記録
  2. 発生条件を特定
     - いつ発生するか？
     - どの操作で発生するか？
     - 毎回発生するか、時々か？
  3. 最小再現手順を作成

チェック項目:
  - [ ] エラーメッセージをコピー
  - [ ] スタックトレースを取得
  - [ ] 発生環境を記録（OS、バージョン等）
  - [ ] 再現手順を文書化

Phase 2: 分離（Isolate）

目的: 問題の範囲を絞り込む

手順:
  1. 二分探索で問題箇所を特定
     - 動く状態と動かない状態の差分
     - コミット履歴で変更点を確認
  2. 関連コンポーネントを特定
  3. 依存関係を確認

テクニック:
  - コメントアウトして切り分け
  - ログを追加して実行パスを確認
  - 最小構成で再現を試みる

Phase 3: 特定（Identify）

目的: 根本原因を特定する

手順:
  1. 仮説を立てる
  2. 仮説を検証する
  3. 仮説が外れたら次の仮説へ

よくある原因:
  - 型の不一致
  - null/undefinedアクセス
  - 非同期処理の順序問題
  - 環境変数の未設定
  - 依存関係の不整合
  - 権限の問題
  - ネットワークの問題

Phase 4: 検証（Verify）

目的: 修正が正しいことを確認する

手順:
  1. 修正を適用
  2. 元の再現手順で問題が解決したか確認
  3. 副作用がないか確認
  4. テストを追加（再発防止）

チェック項目:
  - [ ] 元のエラーが解消
  - [ ] 関連機能に影響なし
  - [ ] テストが追加された
  - [ ] ドキュメント更新（必要に応じて）

デバッグツール

ログ分析

コンテナログ:
  command: GET /api/logs
  usage: ゲートウェイの動作確認

プロセス確認:
  command: GET /debug/processes
  usage: 実行中プロセスの確認

環境確認:
  command: GET /api/env-check
  usage: 環境変数の設定状況確認

一般的なデバッグコマンド

TypeScript/JavaScript:
  - console.log() で値を確認
  - debugger ステートメント
  - try-catch でエラーキャッチ

Node.js:
  - NODE_DEBUG=* で詳細ログ
  - --inspect でデバッガ接続

ネットワーク:
  - curl -v でリクエスト詳細
  - fetch + console.log(response)

エラーパターン別対処

認証エラー

症状: 401 Unauthorized, 403 Forbidden
確認事項:
  - APIキー/トークンが設定されているか
  - トークンの有効期限
  - 権限設定
対処:
  - 環境変数を再確認
  - トークンを再生成
  - 権限を確認

接続エラー

症状: ECONNREFUSED, timeout
確認事項:
  - サービスが起動しているか
  - URLが正しいか
  - ファイアウォール設定
対処:
  - プロセス状態を確認
  - URL/ポートを確認
  - ネットワーク設定を確認

型エラー

症状: TypeError, Cannot read property of undefined
確認事項:
  - データの形式
  - null/undefinedチェック
  - 型定義
対処:
  - オプショナルチェーン (?.)
  - デフォルト値 (?? defaultValue)
  - 型ガード

非同期エラー

症状: Promise rejection, async/await問題
確認事項:
  - await の付け忘れ
  - try-catch の範囲
  - 実行順序
対処:
  - すべての Promise に await
  - 適切なエラーハンドリング
  - 実行順序を明示

5 Whys 分析

問題発生時に根本原因を追求:

例:
  問題: APIが500エラーを返す
  Why1: データベースクエリが失敗している
  Why2: クエリのパラメータがnull
  Why3: リクエストボディのパースに失敗
  Why4: Content-Typeヘッダーが設定されていない
  Why5: フロントエンドのfetch呼び出しでheadersを設定し忘れ

  根本原因: fetch呼び出しのheaders設定漏れ
  修正: headers: { 'Content-Type': 'application/json' } を追加

連携スキル

使用例

「このエラーをデバッグして」→ 4フェーズデバッグ開始
「なぜこのバグが起きた？」→ 5 Whys分析
「動かないんだけど」→ 再現から開始
「エラーを解決して」→ 根本原因特定→修正→検証

更新履歴

[2026-02-02] 初期作成

推測ではなく、証拠に基づいてデバッグしましょう。