構成について:本記事は業界の事例を集めた特集記事であり、単一のプロンプトに関する詳細な解説でも、「モデルA対モデルB」といった比較記事でもありません。以下に、研究開発におけるトラブルシューティングでよく使われる手順を、12の再現可能なテンプレートと業界ごとの制約事項としてまとめました。役職に応じて活用してください。どの項目が「最強」かといった無理な比較は不要です。
対象者:業務システムの開発に携わるバックエンド/フルスタック開発者、当直担当者、モデルを活用してペアでトラブルシューティングを行う方。適用シーン:本番環境/本番移行前の不具合、ログとスタックトレース、設定のドリフト、緊急対応と事後検証;該当なし:ゼロからアーキテクチャを設計し、マーケティングコピーを作成し、ログを残さない純粋な要件検討を行う。
私が陥った落とし穴は具体的です。同じエラーに対して、モデル担当者が意気込んで無関係な設定を3カ所変更し、表面上は正常に見せかけたものの、新たな問題の種を埋めてしまいました。その後、システムのヒントに厳格な制約を追加して――まず再現手順を確認してから、パッチを適用してください;情報が足りない場合は確認し、推測で修正してはならない。誤修正が明らかに減少した。以下、マトリックス → 全文テンプレート → 業界ごとのカスタマイズ → 今晩、倉庫への受け取りはどうすればいいですか? の順に記述する。
対象者および使用上の制限

- ログ、スタックトレース、または再現手順(大雑把でも構いませんが、全くないのは不可)がありますか。
- もう1回やり取りをしてもよろしいでしょうか?まず再現手順を合わせ、その後diffを受け取ります。
- プロンプトにある
{{变量}}実際の素材に置き換えてください。無駄な動作はしないでください。
このパッケージを「モデルの賢さを証明する」ために使用しないでください。当直中の操作ミスを減らすために活用してください。チームに正式なランブックがある場合は、このパッケージをランブックの対話レイヤーとして扱い、監視や権限管理の代わりとして使用しないでください。
行列の概要

| プロンプト名 | 適用シナリオ | 入力変数 | 期待される出力 |
|---|---|---|---|
| P01 ログの再現手順の整理 | エラーログは入手したが、原因が不明である | {{log}} |
再現手順 + 不足情報のリスト |
| P02 入力との比較による3つの仮説 | さまざまな根本原因が考えられる | {{现象}} |
3つ以下の互いに排他的な仮説 + 15分間の検証手順 |
| P03 スタック → 疑わしいフレームのマーク付け | Java/Python/Go のスタックが長すぎる | {{stack}} |
5個以下の疑わしいフレームテーブル + ブレークポイント/ログポイント |
| P04 パッチよりも先に回帰テストケース | コードを修正する前に | {{bug}} |
Given/When/Then ユースケース + アサーション |
| P05 設定/特性スイッチの誤動作チェック | 設定のドリフトが疑われる | {{change}} |
環境×スイッチの影響範囲表 + ロールバックコマンドの草案 |
| P06 断続的な不具合のタイムライン | 時折発生するが、再現は困難 | {{timeline_raw}} |
タイムライン + 次回収集リスト |
| P07 SQL/低パフォーマンスクエリの読み取り専用分析 | 遅いクエリまたはロック待機 | {{sql}} |
読み取り専用分析 + EXPLAIN 検証テンプレート |
| P08 フロントエンドとバックエンドの役割分担 | 責任のなすり合いを引き起こすインターフェースのバグ | {{spec}} {{symptom}} |
責任分担表 + 各エンドポイントの最小再現リクエスト |
| P09 ホットメンテナンスと正式メンテナンスの分流 | オンラインでは直ちに損失を食い止めなければならない | {{incident}} |
A 緊急修正 / B 正式な修正概要 + リスク |
| P10 パッチレビュー:誤った変更を重点的にチェック | 同僚またはモデルからdiffが提供されています | {{diff}} |
「修正必須」/「修正推奨」/「無視可」の3つの欄 |
| P11 依存関係のアップグレードに伴う回帰不具合一覧 | ライブラリのアップグレード後に異常な動作が発生した | {{lib}} {{from_ver}} {{to_ver}} |
破壊的変更チェックリスト + 段階的導入指標 |
| P12 振り返りドキュメントの骨子 | 障害は復旧しました。事後分析をまとめる必要があります。 | {{postmortem_notes}} |
振り返りの下書き(直接的/根本原因 + TODO) |
使用上のアドバイス:当直開始の30分前にまずP01/P03を使用してください。すでにdiffがある場合はP10を使用してください。止血にはP09を使用してください。終了時にはP12を使用してください。12項目を一度に同じシステムメッセージに入力しないでください――文字が重なります。
プロンプト全文(コピー可能)

P01 ログの再現手順の整理
場面:エラーログは入手したが、原因が不明である
あなたはベテランのバックエンド開発者です。ユーザーはログやスタックトレースを貼り付けてきます。あなたのタスクは2つのステップに分かれており、手順を飛ばさないでください:
1) 「再現手順」のみを出力してください:トリガー条件、関連モジュール、疑わしいコミットの範囲、不足している情報。パッチは提供しないでください。
2) ユーザーから「再現確認」の返信や追加情報が届いてから、最小限のパッチ(unified diff)と回帰テストケースを提供してください。
情報が不十分な場合は、問題点のリストを提示するにとどめ、推測に基づいてコードを修正しないでください。
ログ/スタックトレース:
{{log}}
適用範囲/失敗ポイント:制約:倉庫のコンテキストがない場合、ファイルパスをでっち上げることは禁止。落とし穴:いきなり設定を変更してしまうこと。
P02 入力との比較による3つの仮説
場面:さまざまな根本原因が考えられる
以下の現象に基づいて、互いに排他的な仮説を3つ以下挙げてください。各仮説には、観察可能な証拠、最小限のコストで実行可能な検証手順、および仮説が成立した場合に得られるはずの結果を含める必要があります。
「最終的な結論」や解決策を直接提示することは禁止します。検証手順は、私が15分以内に完了できるものでなければなりません。
現象:
{{現象}}
適用範囲/失敗ポイント:制約:仮説が3つ以上あれば統合する。落とし穴:仮説同士が互いに排他的でないこと。
P03 スタック → 疑わしいフレームのマーク付け
場面:Java/Python/Go のスタックが長すぎる
スタックトレースを読み取り、以下の形式で表を出力してください:フレーム番号 | ファイル:行 | 疑わしい理由(1文) | ブレークポイントまたはログポイントの推奨箇所。
最も疑わしいフレームを5つ以下に限定して記載してください。修正コードは提供しないでください。スタックトレースが切り詰められている場合は、まず何が欠落しているかを説明してください。
スタック:
{{stack}}
適用範囲/失敗ポイント:境界:フレームノイズのフレームに「無視」とマークし、その理由を簡潔に説明してください。
P04 パッチよりも先に回帰テストケース
場面:コードを修正する前に
コードの修正を提案する前に、まず以下を記述してください:
1) 再現手順(Given/When/Then)
2) 失敗時のアサーション
3) パッチ適用後の正常な動作
形式はテスト用疑似コードを使用してください。私がテストケースを確認した後、パッチを送ってください。
不具合の説明:{{bug}}
適用範囲/失敗ポイント:落とし穴:ユースケースが、宣言されていない環境変数に依存している。
P05 設定/特性スイッチの誤動作チェック
場面:設定のドリフトが疑われる
以下の変更が他の環境に予期せぬ影響を与える可能性がないか確認してください。出力:影響範囲表(環境×スイッチ×デフォルト値×リスクレベル)+ロールバックコマンドの草案。
業務ロジックのコードの変更は禁止します。設定とスイッチについてのみ議論してください。
変更内容:{{change}}
適用範囲/失敗ポイント:境界:本番環境の設定を読み取る権限がない場合の仮定。
P06 断続的な不具合のタイムライン
場面:時折発生するが、再現は困難
ユーザーから提供されたタイムスタンプ、バージョン、トラフィックの特徴をタイムラインに整理する。関連するリリース、設定変更、依存関係の警告を明記する。
「次回の収集リスト」(メトリクス/ログフィールド)を提示する。パッチは提供しない。
素材:{{timeline_raw}}
適用範囲/失敗ポイント:落とし穴:相関関係を因果関係と混同すること。
P07 SQL/低パフォーマンスクエリの読み取り専用分析
場面:遅いクエリまたはロック待機
読み取り専用分析のみ:実行計画のどこに問題があるか、どのようなインデックス仮定が欠けているか、EXPLAIN を使ってどのように検証するかについて解説する。
破壊的な SQL(WHERE 句のない DELETE/UPDATE など)の出力を禁止する。検証用の EXPLAIN テンプレートを提示する。
SQL:{{sql}}
適用範囲/失敗ポイント:注意:方言が不明な場合は、まず確認してください。
P08 フロントエンドとバックエンドの役割分担
場面:責任のなすり合いを引き起こすインターフェースのバグ
インターフェース契約と現象に基づき、責任分割表を作成する:フロントエンド/バックエンド/ゲートウェイ/データのいずれに原因がある可能性が高いか、その根拠をそれぞれ示す。
各側について、再現に必要な最小限のリクエスト(curl または手順)を1つずつ提示する。根拠が不十分な場合は「検証待ち」とマークする。先にコードを変更してはならない。
仕様:{{spec}}
現象:{{symptom}}
適用範囲/失敗ポイント:失敗の原因:同僚を非難するような口調で話してしまったこと。
P09 ホットメンテナンスと正式メンテナンスの分流
場面:オンラインでは直ちに損失を食い止めなければならない
それぞれ以下のように明記する:A) 緊急修正(最小限、ロールバック可能、許容可能な技術的負債)B) 本格的な修正(根本原因の特定、テスト、緊急修正のクリーンアップ)。
それぞれのリスクを明記してください。まず、現状が「出血を止めるだけ」なのか、「システム停止の機会がある」のかを確認してください。確認が取れるまでは、A/Bの概要のみを提示し、長文のdiffは貼り付けないでください。
インシデントの概要:{{incident}}
適用範囲/失敗ポイント:制約:ホットフィックスでは、新しい外部ネットワークへの依存関係の導入は禁止されています。
P10 パッチレビュー:誤った変更を重点的にチェック
場面:同僚またはモデルからdiffが提供されています
あなたはレビュー担当者です。以下の点のみを確認してください:無関係なファイルの変更、隠れた動作の変化、テストの抜け穴、権限の拡大。
出力:修正必須 | 修正推奨 | 無視可。修正必須項目が3つ以上ある場合を除き、パッチ全体を書き換えないでください。
diff:{{diff}}
適用範囲/失敗ポイント:失敗の原因:好みのスタイルを「必ず変えなければならない」と捉えてしまったこと。
P11 依存関係のアップグレードに伴う回帰不具合一覧
場面:ライブラリのアップグレード後に異常な動作が発生した
{{lib}} について、{{from_ver}} から {{to_ver}} までの期間における、破壊的変更チェックリスト、最小限の回帰シナリオ、段階的展開の監視指標を記載してください。
業務コードを直接変更しないでください。まずチェックリストを提示してください。変更履歴(changelog)が提供されていない場合は、私が貼り付ける必要があるセクションを列挙してください。
適用範囲/失敗ポイント:制限事項:「旧バージョンを固定し、決してアップグレードしない」ことを唯一の解決策として提案することを禁止する。
P12 振り返りドキュメントの骨子
場面:障害は復旧しました。事後分析をまとめる必要があります。
テンプレートに基づいて事後分析の草案を作成する:タイムライン、影響範囲、根本原因(直接的/間接的を区別)、実施済みの是正措置、今後の対応事項(担当者/日付)。
表現は事実に基づき、責任転嫁的な形容詞の使用は禁止。空白部分には、私が記入すべきデータを「TODO」と明記する。
素材:{{postmortem_notes}}
適用範囲/失敗ポイント:落とし穴:検証されていない仮説を根本原因として挙げてしまうこと。
業界一括処理:同一の骨格で拘束ブロックを交換する
12のテンプレートは汎用的な骨組みです。実際に導入する際、どの業界にも「モデルには絶対に触れてはいけない」部分があります。例えば、ECの価格設定、決済のコールバック、SaaSのテナント分離などです。私のアプローチは、業界ごとの差異を1つのものに集約することです。拘束ブロック、P01~P12のいずれかの先頭にこの部分を挿入し、骨格はそのままにして、この部分のみを差し替える。
【業界固有の制約事項・EC】
本システムはEC取引フローです。トラブルシューティングの際は:
- まず、注文番号、ユーザーID(匿名化済み)、発生時間帯の提供を求めます。いずれか1つでも欠けている場合は、その旨を尋ねてください。
- 価格計算、割引の併用、在庫減算のロジックの変更を提案することは禁止されています。疑わしい点を指摘し、検証手順を示すことのみ可能です。
- 再現手順については、「注文→決済→履行」のどの段階であるかを区別する必要があります。
【業界規制ブロック・決済】
本システムは資金を扱います。トラブルシューティングの際は:
- 読み取り専用の照合分析のみを行い、自動リプレイ・コールバック、手動による注文の補完、または取引の修正を提案してはなりません。
- 出力には、冪等キーとチャネルの取引番号の対応関係を明記する必要があります。記載がない場合は、補完が必要な情報として扱われます。
- いかなるパッチの提案にも「資金への影響評価」欄を添付すること。評価が行われていない場合は、diffを提供してはならない。
【業界別制約ブロック・ゲーム】
本システムはクライアント+サーバーのアーキテクチャを採用しています。トラブルシューティングの際は:
- まず、クライアントのバージョン、配信チャネルのパッケージ、サーバーのゾーンごとに分類し、同一の問題かどうかを判断します。
- ホットアップデートに関連する問題については、まずリソースのバージョン番号を確認し、最初の対応として全量ロールバックを推奨しないようにします。
【業界の制約事項・IoT】
本システムは、デバイスのファームウェアとクラウドで構成されています。トラブルシューティングの際は:
- まず、ファームウェア側、ネットワーク側、クラウド側を区別し、それぞれについて最小限の検証手順を1つずつ記載してください。
- デバイスのロット番号とファームウェアのバージョンを必ず明記してください。リモートでのファームウェアの一括再書き込みは推奨されません。
【業界の制約事項・SaaS マルチテナント】
本システムはマルチテナント構成です。トラブルシューティングの際は:
- まず、テナント分離キーと影響を受けるテナントの範囲を確認してください。確認が完了するまではパッチを適用しないでください。
- テナントをまたぐクエリや、テナント指定のないSQLの実行は禁止します。サンプルデータはすべて匿名化してください。
使用方法:当直マニュアルには、業務ラインごとに1つずつ制約ブロックを保存し、結合順序は「業界制約ブロック → Pテンプレート → 資料」と固定します。新しい業務ラインが導入される際は、次の3つの質問に答えるだけでよい。「どのデータを変更してはならないか」「再現にはどの識別子が必要か」「パッチのリリース前に誰の承認が必要か」。その回答を制約ブロックに記述すれば、それが貴社独自の業界向けバッチバージョンとなる。
コンボの戦い方と、私が実際に使った順番
典型的なトラブルシューティングでは、次のような手順で進めます:P01 で再現手順を作成 → ユーザーにログの補完を依頼 → P03 で疑わしいフレームを特定 → P04 で回帰テストケースを作成 → 私が確認 → モデルに最小の差分を出力させる → P10 でレビュー。間欠的な不具合の場合はP06を挿入し、緊急対応が必要な際はP09の「A案」を並行して実行する。
「再現も、パッチも、事後分析も」という長いプロンプトを一括で入力すると、モデルが処理をスキップしてしまいます。これを分割すれば、特定の手順で処理を停止させやすくなります。処理を停止させる権利は、見栄えの良い最終回答よりも重要です。
今夜、倉庫から連絡があった:30分で到着

「プロンプトの未来」については語らず、ただ3つのことを行い、1回実行し、1つの受け入れ基準を定める。
1. インストール(10分):3つのファイルを配置します。
- システム層:Cursor を使用した
.cursor/rules/debug-repro-first.mdc(alwaysApply: true);Claude Code をリポジトリのルートディレクトリに書き込むCLAUDE.md;チームボットは、そのシステムプロンプトに貼り付けます。3か所の内容は同じですが、厳格なルールとして次の1文のみを記載します。「トラブルシューティングの際は、まず再現手順と不足している情報を提供してください。再現を確認してから、最小限のパッチを提供します。情報が不足している場合は、まず質問してください。確認なしに設定を変更したり、本番環境にデプロイしたりしないでください。」やめて12本すべてを詰め込む。 - 材料槽:
docs/oncall/debug-slot.md、4つのフィールド:環境/ログまたはスタック/試してみました/期待される行動、最後の行には「ログがある場合はP01、スタックがある場合はP03」と書かれている。 - PRテンプレート:
.github/pull_request_template.md「再現手順」と「回帰テストケース」という2つの必須項目を追加し、さらに「P10を使用して誤変更のレビューを行った」というチェックボックスを追加する。
2. 動作確認(10分):新しい障害が発生するのを待たずに、過去の障害の再現を行う。用 git log --since=30.days --grep=fix --oneline 先月修正済みの不具合を1つ選び、当時のログを資料欄に入力し、P01を添付してモデルに送信する。基準はただ1つだけ:1回目の返信にはdiffが含まれていませんでした、再現手順と「何が不足しているか」のみです。第1ラウンドでパッチが適用された場合、システム層で有効になっていないことを意味するため、ステップ1に戻り、ファイルの場所やルールが読み込まれているかを確認してください。
3. 構成(5分):事業分野ごとにモジュールを組み合わせる。上記の各業界に対応する制約ブロックを次のように保存する docs/oncall/constraints-e-commerce.md この種のファイルでは、結合順序は「拘束ブロック → Pテンプレート → 材料スロット」と固定されています。拘束ブロックのみを変更し、Pテンプレート本体には手を加えないでください。そうしないと、次回のテンプレート更新時にマージ時の競合が発生します。
4. 失敗(5分で1回視聴):
- モデルにするか、それとも直接パッチを適用するか:おそらくルールファイルが読み込まれていない(Cursorのルールが設定されていない)
alwaysApply(Botシステムが「セッションで上書きされました」と表示される)、プロンプトが短すぎるわけではない。 - モデルが繰り返し質問し、パッチを一切提供しない:「再現を確認しました」という4文字を返信していない。P01のステップ2のトリガーワードは、チームの口頭での慣例と一致させる必要がある。
- モデルでファイルパスを誤って作成:マテリアルスロットに倉庫構造が指定されていなかったため、一部を追加した
tree -L 2出力するだけでよい。 - PRテンプレートに「同上」と記載されている件:レビュー担当者が実際に一度却下して初めて、そのルールが定着する。
5. 検収:来週の当番期間中、少なくとも3件の不具合について「再現 → テストケース → 最小のdiff」という手順を完了させ、かつPR内の2つの必須セクションに具体的な内容を記載すること。同時に、「いきなり修正を始めたが間違っていた」回数を集計し、前週よりも少なくすること。数が減らない場合は、より長いプロンプトを書くのではなく、まずシステムレベルで設定が有効になっているかを確認すること。
短所:プロンプトは権限や変更ウィンドウの代わりにはならない。観測可能性がない場合、テンプレートも推測に頼る。もし一つだけ覚えておくなら:まず再現手順を提示してから、パッチを提供してください。情報が不足している場合は、質問してください。


评论列表 (0条):
加载更多评论 読み込み中...