受託開発の保守担当が、過去の設計書と変更管理の記録から改修する機能の記載と変更の経緯を探し、影響調査に根拠付きで使う

処理の起点を決める

検索は、担当者が検索画面にチケット番号を入れたときに動きます。 改修依頼のすべてに自動で走らせると、見積の対象にならない問い合わせにも検索がかかり、結果を誰も見ません。影響調査を始めると決めた人が、始めたときに動かします。

インデックスの更新は別の流れで、定期的に動かします。

インデクサーはスケジュールで動かすことが推奨されています。 変更されたドキュメントや、スロットリングで取りこぼしたドキュメントを拾うためです。埋め込みモデルの呼び出しが上限に達したときの再試行も、スケジュール実行に任せます。

入力データを集める

質を決めるのは、いちばん下の文書の台帳です。 ファイル名の「最終」「修正」からは最新版を決められません。案件ごとに、どのファイルが今の正本かを一覧にします。 全案件を一度に整える必要はなく、改修依頼の多い案件から始めます。

チケットは本文だけでなく、コメントと関連コミットまで取ります。 経緯の多くはコメントの議論に残り、「この条件を足したのは〇〇の障害のため」という一文が、本文ではなく途中のコメントにあります。

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

Redmine のチケットは、2段階で取ります。 一覧の取得（GET /issues.json）で、updated_on に前回の取得日時以降を指定し、status_id=* で完了したものも含めて取ります。一覧の取得で include に指定できるのは attachments と relations で、コメントと変更の履歴（journals）や関連コミット（changesets）は1件ずつの取得（GET /issues/[id].json）で指定します。 ページ送りは offset と limit で行います。認証はAPIキーです。

設計書は、レイアウトモデルで構造化してからインデックスに入れます。 レイアウトモデルはPDF、画像、Word、Excel、PowerPoint、HTMLに対応し、抽出したテキストを Markdown で出力できます。見出しや表の構造が残るので、章や節の単位で分割しやすくなります。

Excel の注意が、この題材でいちばん大事です。 レイアウトモデルは、入力ファイルがXLSXの場合、テーブルの分析をサポートしないとされています。テキストは取れますが、表の行と列の構造は返りません。 項目一覧の表が主体のテーブル定義書は、1行を「項目名：型：桁：説明」の1文に組み直してから登録します。 列の見出しと値の対応が切れると、検索で当たっても読めない断片になります。

分割と埋め込みは、統合ベクトル化で行います。 インデクサーが Blob Storage から取り、Text Split スキルで分割し、AzureOpenAIEmbedding スキルでベクトルにします。クエリ時は、同じ埋め込みモデルのベクトライザーで検索語をベクトルにします。Redmine のチケットはインデクサーの対象ではないので、取り込みの処理がベクトルまで作って、プッシュで登録します。

AIへ渡す前に整形する

1. 案件と顧客の付与 … すべてのチャンクに、案件ID、顧客のグループID、文書種別を付けます。付かないチャンクは登録しません
2. 版の付与 … 文書の台帳から版と「最新版かどうか」を付けます。台帳に無いファイルは「版不明」とします
3. 出典の付与 … ファイル名、シート名または章・節の見出し、ページを付けます
4. Excel の表の組み直し … テーブル定義書などの表は、1行を1文に組み直します
5. チケットの整形 … 本文とコメントを日付順に並べ、コメントごとに番号と日付を付けて分割します。関連コミットの番号と、関連チケットの番号も持たせます
6. 定型文の除去 … 設計書の表紙、改訂履歴の空欄、チケットの自動通知の文言を除きます
7. 重複の扱い … 同じ内容のファイルが複数の版で残っていても消さず、版の情報で区別します

1番目を省かないでください。 案件IDの付かないチャンクは、どの案件の検索にも出てこないか、すべての案件の検索に出てくるかのどちらかになります。後者は顧客の情報が混ざる事故です。

7番目で古い版を消さないのは、経緯のためです。 「v2.0 まではこの条件が無かった」ことは、古い版を見ないと分かりません。最新版を優先して返し、古い版は経緯の材料として別に返します。

AIに処理させる

生成AIにさせるのは2つです。 改修依頼から検索語を取り出すことと、検索結果だけを根拠に出典付きの一覧と時系列をまとめることです。

表の右下が、いちばん起きやすい失敗です。 「〇〇テーブルへの影響」について何も見つからないと、生成AIは「影響はないと考えられます」と書きたがります。見つからなかったのは、書かれていないからか、探し方が足りないからかのどちらかで、どちらも影響が無いことを意味しません。

指示内容を固定する

あなたは受託開発の保守担当の調査を手伝う立場です。
次の【検索結果】だけを根拠に、改修依頼の対象機能について、
設計書の記載箇所と、過去の変更の経緯をまとめてください。

【改修依頼の要点】{request_points}
  例: ["請求明細の締め日を月末以外にも設定できるようにしたい"]
【検索結果】{search_results}
  各要素に chunk_id、文書名、版、最新版かどうか、シート名または章・節、本文がある

【厳守事項】
- 検索結果に書かれていないことを書かないでください。
  一般的な設計の知識で補わないでください。
- すべての記載に、根拠にした chunk_id を付けてください。
  chunk_id を付けられない記載は書かないでください。
- 引用は検索結果の本文から、そのまま写してください。言い換えないでください。
- 最新版でない文書の記載は、current_spec ではなく history に入れてください。
- 最新版と古い版で記載が食い違っていても、どちらが正しいかを判断しないでください。
  conflicts に両方の chunk_id を並べてください。
- 変更の理由は、チケットやコメントに書かれている場合だけ書いてください。
  書かれていなければ reason は「記載なし」としてください。
- 改修依頼の要点のうち、記載が見つからなかったものは not_found に入れてください。
  「影響なし」「関係ない」と書かないでください。
- 影響範囲の結論、工数、難易度を書かないでください。

「chunk_id を付けられない記載は書かない」が、この指示の要です。 出典の無い一文は、担当者が確かめようがありません。確かめられない記載を混ぜるくらいなら、書かせないほうが安全です。

「引用を言い換えない」も同じ理由です。 言い換えた瞬間に、設計書の原文との照合ができなくなります。設計書の言い回しは、そのまま検索語として次の検索にも使えます。

出力形式を固定する

次の形のJSONで受け取ります。 Azure OpenAI の構造化出力で、このスキーマに従わせます。すべてのフィールドを必須にし、省略可能な値は null との共用体型で表し、オブジェクトには additionalProperties: false を設定します。

{
  "ticket_id": "",
  "project_id": "",
  "current_spec": [
    { "point": "", "summary": "", "quote": "", "chunk_id": "",
      "doc": "", "version": "", "location": "" }
  ],
  "history": [
    { "date": "", "what_changed": "", "reason": "", "source_ticket": "",
      "journal_no": null, "chunk_id": "" }
  ],
  "conflicts": [ { "point": "", "chunk_ids": [] } ],
  "not_found": [ { "point": "", "queries_tried": [] } ]
}

1つ目の理由は、出典を機械的に検証できることです。 chunk_id が検索結果に含まれていたかを、受け取った側で突き合わせます。検索結果に無い chunk_id が1つでもあれば、その回答は捨てて出し直させます。

2つ目は、not_found に試した検索語を残せることです。 担当者は、AIが何で探して見つからなかったのかを見て、別の言い方で探し直すか、本当に書かれていないと判断するかを決められます。

3つ目は、history の journal_no で、チケットのどのコメントかまで戻れることです。

システムへ連携する

Redmine への書き込みは、担当者が仕上げたメモの添付だけです。 AIのまとめをそのままチケットに書き込みません。顧客が見るチケットに、確かめていない記載が残ります。

検索は、セキュリティ フィルターで絞ります。 インデックスに顧客のグループIDを持つ Collection(Edm.String) のフィールドを作って filterable にし、retrievable は false にします。検索のたびに group_ids/any(g:search.in(g, '...')) のフィルターを付け、 担当者が属するグループの文書だけを返します。

ただし、Azure AI Search はこのパターンでユーザーを認証しません。 セキュリティ プリンシパルは単なる文字列で、フィルターを付けるのは検索画面の側の責任です。 検索画面は、利用者の Microsoft Entra のグループを取り、案件の台帳と突き合わせてからフィルターを組み立てます。フィルターを付けない検索の経路を作らないことを、設計の決まりにします。

人が確認する

担当者が確かめるのは、出典です。 まとめの文章ではなく、current_spec と history の各行の出典を開き、引用が本当にそこにあるかを見ます。

1. current_spec の出典を開く … 引用がその文書・その版・その場所にあるかを見ます
2. conflicts を確かめる … 古い版と最新版の食い違いは、実装を見て決めます
3. not_found を見て探し直す … 別の言い方で検索するか、書かれていないと判断します
4. ソースコードを確かめる … 設計書に無い実装の都合は、コードで確かめます
5. 影響調査メモを仕上げる … 採用した出典を残して、チケットに添付します

3番目が、いちばん人の力の要るところです。 「書かれていない」と判断するには設計書の癖を知る必要があり、新しい担当者はここだけベテランに見てもらいます。

目標は、1件あたり35分です。 出典の確認に15分、not_found の探し直しに10分、コードの確認とメモの仕上げに10分という想定です。コードの確認に時間がかかる改修では35分を超えます。

例外に対処する

上の2行が、この構成でいちばん重い例外です。 どちらも、案件の範囲が決まらないまま検索が走ることを止めるためのものです。範囲が決まらないときは、結果を出さないのが正しい動作です。

記録を残す

• 検索した日時、担当者、チケット番号、案件ID、付けたセキュリティ フィルター
• 取り出した検索語と、検索結果の chunk_id の一覧
• 生成AIが返したJSONの全文と、chunk_id の検証の結果
• 担当者が採用した出典と、採用しなかった出典
• 仕上がった影響調査メモと、チケットに添付した日時
• インデクサーの実行の記録と、取り込みに失敗したファイル

1行目でフィルターを残すのは、後から確かめるためです。 顧客から「当社の情報が他社の調査に使われていないか」と問われたとき、どの検索がどの範囲で行われたかを示せるようにしておきます。

4行目は、検索の質を上げる材料です。 採用されなかった出典が多い文書は、分割の仕方か、文書の台帳の版の付け方に問題があります。