直接回答
最初から「バグを直して」と依頼せず、失敗入力、環境、リビジョン、期待する挙動を固定します。読み取り専用で経路と仮説を調べ、原因説明を人間が確認してから最小パッチを許可し、元の再現、回帰テスト、関連スイートを実行します。
重要な結論
- 安定した再現が、信頼できる修正の開始条件です。
- 観測事実、仮説、確認済み原因を調査記録で分離します。
- 一度に一つの因果経路を変更し、便乗したリファクタリングを避けます。
- 元の障害と隣接する挙動の両方を修正後に検証します。
重要な事実
このガイドで解決できること
因果関係と検証記録を保ったまま、コーディングエージェントで不具合を診断・修正する。
検証範囲と制約
- 証拠の種類
- 公式ドキュメントローカル検証
- 検証範囲
- 再現、証拠保存、原因の切り分け、最小修正、回帰テスト、リリース後確認を対象とします。
- 制約と失効条件
- - 断続的な本番障害には、ローカルエージェントが利用できないテレメトリや業務文脈が必要な場合があります。
- - 既知の再現が成功しても、関連するすべての障害が解決した証明にはなりません。
安定し、秘匿化された障害を記録する
正確なリビジョン、コマンドまたはリクエスト、秘匿化した入力、実際の出力、期待値、時刻、関連バージョンを記録します。認証情報と不要な顧客データはセッションに入れる前に削除します。
本番権限なしで繰り返せるところまで縮小します。断続的な場合は頻度と関連条件を記録し、決定的な原因を作り上げません。
読み取り専用で失敗経路を追跡する
入口、状態遷移、エラー処理、関連する最近の変更を特定させ、コード位置を示しながら観測と仮説を分けます。正常リビジョンが既知なら、自動判定可能なチェックと履歴探索を利用します。
- 入力と環境を固定し、一度に一つの仮説を検証します。
- ログとエラーチェーンからシークレットを除外します。
- クライアント、ネットワーク、サービス、ストレージ、外部提供者を分けます。
- 証拠で仮説を区別できない場合は推測を止めます。
編集前に原因説明をレビューする
原因説明には、入力がなぜ失敗へ到達するか、期待契約と何が違うか、どの証拠で仮説が否定されるかが必要です。検証、再試行、認可の変更前に、保守担当者が業務前提を確認します。
複数の原因が残る場合は、簡単な変更を選ばせるのではなく、観測または狭いテストを追加します。
最小で元に戻せるパッチだけを許可する
変更を原因経路と回帰テストに限定し、レビュー済み契約変更がない限り公開インターフェースを維持します。整理、依存更新、大規模リファクタリングは別の変更に分けます。
複数の境界で修正を検証する
元の再現を実行し、修正なしでは回帰テストが失敗することを示し、関連パッケージやサービスの検証を行います。ログと副作用を確認し、API 境界を跨ぐ場合は成功とエラー応答の両方を確認します。
- 01元のケース同じ秘匿化入力を再実行します。
- 02回帰証明新しいアサーションが古い挙動を検出することを示します。
- 03隣接ケースパッチの影響を受けやすい境界を確認します。
- 04運用確認ログ、指標、後始末、ロールバックの前提を確認します。
残存リスクを明示してリリースする
原因、パッチ、検証コマンド、影響バージョン、ロールバック、未検証部分をまとめ、リリース後も同じ障害シグネチャを監視します。説明と矛盾する証拠が出たら、推測のパッチを重ねず診断を再開します。
公式情報と検証範囲
本ガイドは公開されている公式ドキュメントを根拠にしています。コマンドや設定はクライアントのバージョンにより変わるため、実行前に参照元も確認してください。
技術検証方法を見る