新しい不具合の報告が来たときに、過去の不具合チケット・修正のプルリクエスト・原因分析の記録から症状の近いものを探し、原因と修正箇所の候補をチケット番号付きで開発担当へ返す

処理の起点を決める

不具合のチケットに bug のラベルが付いたことを起点にします。 起票そのものを起点にすると、要望や質問のチケットまで探しに行きます。ラベルはサポート部門と開発者が起票のときに付ける運用なので、付いた時点で1件ずつ動かします。

本文が書き換えられたときにも、もう一度動かします。 起票の直後は「再現手順は追って書く」という本文のことが多く、エラーの全文が貼られるのは数時間後です。2回目以降は、前回のコメントを書き換える形にして、コメントが増えすぎないようにします。

索引の更新は別に動かします。 チケットが閉じられたとき、プルリクエストがマージされたとき、原因分析の記録が承認されたときに、その1件だけを索引に入れ直します。 夜にまとめて入れ直すと、昼に直した不具合が翌朝まで見えません。

入力データを集める

質を決めるのは、過去のチケットの「閉じた理由」です。 重複として閉じたものや、再現しなかったものまで候補に出すと、原因も修正箇所も無い候補が上位を占めます。 重複として閉じたものは、重複先のチケットに寄せてから索引に入れます。

原因分析の記録には、関係するチケット番号を必ず持たせます。 番号が無い記録は、症状の文章で見つかっても、どの修正に対応するかを辿れません。 書かれていない過去の記録は、最初の準備として番号を書き足します。

データの取得方法を決める

チケットとプルリクエストの対応は、まず GitHub の「リンク」で取ります。 プルリクエストの説明に Fixes #123 のようなキーワードを書くと、チケットとプルリクエストが結び付き、マージされるとチケットが自動で閉じます。 使えるキーワードは close／closes／closed、fix／fixes／fixed、resolve／resolves／resolved で、大文字小文字は区別されません。

ただし、リンクが作られるのはデフォルトブランチ向けのプルリクエストだけです。 公式の説明では、それ以外のブランチ向けではキーワードは無視され、リンクは作られず、マージしてもチケットに影響しません。 オンプレミス版のための修正を保守用のブランチに入れているなら、その修正はリンクから辿れません。

保守用ブランチの修正は、チケット番号を題名に入れる決まりで補います。 「題名の先頭に [#123] を書く」と決め、それを読み取って対応を作ります。決まりができる前の修正は、最初に一度だけ手で対応を付けます。

変更されたファイルの API には、上限があります。 返るのは最大3,000ファイルで、1ページの既定は30件、最大100件です。大きなリファクタリングを含むプルリクエストは上限に当たることがあり、その場合は修正箇所の候補から外します。

AIへ渡す前に整形する

1. エラーの型を取り出す … 本文から例外の種類、エラーコード、スタックトレースの上から数段の関数名を取り出します
2. 行番号とアドレスを消す … スタックトレースの行番号、メモリのアドレス、日時、利用者のIDを消します。版が違うと行番号は変わるので、残すと一致しません
3. 定型の見出しを除く … 「再現手順」「期待される結果」「実際の結果」など、起票のひな形の見出しを本文から外します
4. 版をそろえる … 「v5.2」「5.2.0」「ver5.2」を同じ書き方にそろえます
5. 部品を決める … 部品のラベルが付いていなければ、落ちた関数のファイルの場所から部品を推定します
6. 個人の情報を外す … 顧客の名前、メールアドレス、画面の写しに写った顧客のデータは、索引に入れる前に消します

2番目を軽く見ないでください。 同じ不具合でも、版が一つ違えばスタックトレースの行番号はずれます。行番号を残したまま完全一致で探すと、同じ不具合の過去のチケットが一件も当たりません。 残すのは例外の種類と関数名の並びだけです。

3番目は、more_like_this のためです。 ひな形の見出しはすべてのチケットに出てくるので、残すとどのチケットも似ているように見えます。 more_like_this には、無視する語を並べる stop_words と、多くの文書に出る語を無視する max_doc_freq があり、どちらでも外せます。

AIに処理させる

検索は、二つの道を別々に走らせ、結果を合わせます。

more_like_this の既定値は、短いチケットに向いていません。 公式の既定では、入力の中で2回未満しか出ない語は無視され（min_term_freq が2）、5件未満の文書にしか出ない語も無視されます（min_doc_freq が5）。数行のチケットでは、ほとんどの語が1回しか出ないので、min_term_freq を1に下げます。語の数の上限 max_query_terms は既定で25、一致させる語の割合 minimum_should_match は既定で30％です。

生成AIにさせるのは、候補を並べ、それぞれの原因と修正箇所を根拠付きで書き出すことだけです。

4行目を守らせるのが、この構成の線引きです。 修正の案まで出すと、担当者は候補の確認を飛ばして案を試し始めます。探すことと直すことを分けておくほうが、誤った候補で時間を失わずに済みます。

指示内容を固定する

あなたは製品開発部で、新しい不具合のチケットに関係する過去の不具合を
整理する立場です。渡した検索結果だけを根拠にしてください。

【新しいチケット】{new_issue}
【報告された版】{reported_version}
【版の関係】候補ごとに、機械で比べた結果を渡します。
  fixed_before ... 報告された版より前の版で修正済み
  fixed_after .... 報告された版より後の版で修正（その版ではまだ直っていない）
  no_fix ......... 修正の記録が無い

【やること】
1. 候補ごとに、症状・原因・修正の内容を1〜2文で書く
2. 新しいチケットと似ている点、違う点を書く
3. 修正のプルリクエストで変更されたファイルのうち、
   原因に関係しそうなものを挙げる
4. 担当者が再現のときに最初に確かめるべき点を書く

【厳守事項】
- 検索結果に書かれていないことを書かないでください。
  原因が書かれていない候補は、cause を「記載なし」としてください。
- 修正箇所は、変更されたファイルの一覧にあるものだけを挙げてください。
  一覧に無いファイルを推測で挙げないでください。
- 版の関係は、渡した値をそのまま使ってください。
  あなたが版番号を比べ直さないでください。
- 今回の原因がどれかを断定しないでください。
  「同じ原因の可能性がある」までにしてください。
- 似ていない候補は、無理に関連付けず除外してください。
  除外した候補は excluded に番号と理由を書いてください。
- 修正のコードや修正の方法は書かないでください。
- チケットを重複として閉じるべきかは書かないでください。

「変更されたファイルの一覧にあるものだけ」を明記しないと、それらしいファイル名が出ます。 症状の説明に「保存の処理」と書かれていれば、save_handler のようなありそうな名前を作って挙げます。担当者がそのファイルを探して時間を使うので、一覧の外を挙げることを禁じます。

「版番号を比べ直さない」も同じ理由です。 「5.10」と「5.9」を文字として比べると、5.10 のほうが古いと読むことがあります。比べた結果を渡し、使わせるだけにします。

検索結果は、Claude の検索結果のブロックで渡します。 公式の説明では、source・title・content を持つブロックで渡すと、自社の文書を引用付きで答えられ、Amazon Bedrock でも使えます。source にはチケット番号を入れます。引用はテキストのブロックが単位なので、症状・原因・修正を別のブロックに分けて入れておくと、どの部分を根拠にしたかが細かく分かります。

出力形式を固定する

次の形のJSONで受け取ります。

{
  "new_issue": "#9812",
  "reported_version": "5.9.2",
  "candidates": [
    {
      "issue": "#7420",
      "route": "error_signature | symptom_text",
      "version_relation": "fixed_before | fixed_after | no_fix",
      "fixed_in": "5.8.0",
      "fix_pr": "#7433",
      "summary": "",
      "similar_points": "",
      "different_points": "",
      "cause": "",
      "fix_files": ["src/export/csv_writer.py"],
      "check_first": "",
      "citations": ["#7420", "PR#7433", "RCA-2024-11"]
    }
  ],
  "excluded": [{ "issue": "#5102", "reason": "" }]
}

1つ目の理由は、route で探し方を残せることです。 エラーの型で当たった候補と、症状の言葉で当たった候補は、信用の度合いが違います。 前者は同じ例外で落ちている事実があり、後者は言葉が近いだけです。コメントでは前者を上に並べます。

2つ目は、version_relation で担当者の次の作業が決まることです。

1行目は、再発の疑いも含みます。 直した版より新しい版で同じ症状が出ているなら、修正が後の変更で壊れた可能性があります。 担当者はこの行を見て、修正のプルリクエスト以降の変更を確かめます。

3つ目は、excluded で外した理由が残ることです。 検索で出たのに外した候補が見えないと、担当者は「探し漏れがあるのでは」と自分で探し直します。外した理由が書いてあれば、探し直す必要がありません。

システムへ連携する

GitHub への書き込みは、新しいチケットへのコメントだけにします。 そのための権限は、コメントを書ける最小のものにします。過去のチケットを閉じる・ラベルを変える権限は持たせません。 誤った候補が出ても、コメントを消せば元に戻ります。

検索の索引には、非公開のリポジトリのチケットも入ります。 社内の開発者なら誰でも検索できる作りにすると、セキュリティの脆弱性のチケットのように、一部の人だけが見るべきものまで候補に出ます。 脆弱性のラベルが付いたチケットは索引に入れないか、別の索引に分けます。

人が確認する

候補は、すべて担当の開発者が確かめます。 コメントは調査の出発点で、原因の結論ではありません。

1. error_signature の候補から見る … 同じ例外で落ちている事実があるので、当たる見込みが高いほうから開きます
2. version_relation を見る … fixed_before なら、まず顧客の環境の版を確かめます
3. 根拠を開く … 過去のチケットと修正のプルリクエストを開き、原因の説明が今回の症状と合うかを読みます
4. 結果を記録する … 当たった候補はチケットに「関連」として残し、外れた候補には外れた理由を一言書きます

4番目を省かないでください。 外れた理由が残ると、同じ組み合わせの候補が次に出たとき、すぐに外せます。 また、外れが続く部品があれば、索引の分け方か前処理を見直す材料になります。

目標は、1件10分です。 候補のコメントを読み、上位の2〜3件の根拠を開いて確かめるまでの時間です。候補が無かったときも、「無い」と分かるまでの時間が10分になります。 これまでは、無いと分かるまでに30分以上かかっていました。

例外に対処する

上から2行目を、きちんと結果にしてください。 「見つからなかった」が書かれていないと、担当者は仕組みが動かなかったのか、本当に無いのかを区別できず、結局自分で探します。

記録を残す

• 新しいチケットの番号と、取り出したエラーの型・部品・版
• 二つの道それぞれの検索の条件と、返ってきた上位の候補
• 生成AIに渡した検索結果のブロックと、返ってきたJSONの全文
• 書き込んだコメントと、その日時
• 担当者が付けた「関連」と、外れた理由
• 最終的に原因となったチケット（後から分かったもの）

最後の行が、仕組みを良くする材料になります。 最終的な原因が候補の中にあったか、何番目にあったかを数えれば、探し方が効いているかが分かります。 候補に無かったのに過去に記録があった不具合は、言葉が合わなかった例として前処理と stop_words を見直す材料にします。