社内システム間の連携の設計書・項目定義書・改修記録を横断して、ある項目がどこから来てどこへ渡るかを根拠付きで答える

処理の起点を決める

問い合わせ画面への入力を起点にします。 入れるのは、項目名、分かればシステム名、調べたい向き（上流へ・下流へ・両方）の3つです。向きを入れてもらうのは、両方向に広げると区間が増えすぎて確認が終わらないからです。

文書の取り込みは、問い合わせとは別に定期で動かします。 Cloud Storage からのデータの同期は、1日・3日・5日ごとから選べます。改修の多い時期は1日ごとにします。 設計書の更新から検索に載るまでの遅れは、問い合わせ画面に「最終の同期日」として出しておきます。

入力データを集める

質を決めるのは、項目名の対応表です。 第3章の（b）のとおり、同じ項目がシステムごとに違う名前で書かれています。検索の仕組みは意味の近い語もある程度拾いますが、「納品先コード」と「届先CD」が同じものだという社内の取り決めまでは知りません。 最初は、問い合わせの多い項目から50語程度で始めます。

メタデータの「状態」が、版の新旧を分ける唯一の手がかりです。 同じインターフェースの古い版を残しておくのはかまいませんが、状態を「廃止」にして、検索の対象から外します。

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

文書は、Cloud Storage に置き、メタデータを書いたJSONLファイルとあわせて取り込みます。JSONLの1行が1文書で、id、メタデータを入れる structData、文書の content（mimeType と uri）を持ちます。

JSONLの1行は、たとえば次のようになります。

{"id": "IF-0123-def-v3-2", "structData": {"source_system": "販売管理", "target_system": "倉庫管理", "if_id": "IF-0123", "doc_type": "項目定義書", "version": "3.2", "status": "有効"}, "content": {"mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "uri": "gs://<bucket>/if/IF-0123_項目定義書_v3.2.xlsx"}}

id に版を含めておくと、同じインターフェースの版の入れ替えが追いやすくなります。 新しい版を入れるときは、古い版の行の status を「廃止」にするか、Cloud Storage から外します。

絞り込みに使うには、メタデータの項目をスキーマで「インデックス可能」にしておく必要があります。 そのうえで、問い合わせのときに status: ANY("有効") のような条件を付けます。下流へたどるときは source_system、上流へたどるときは target_system の条件を足すと、関係の無いシステムの同じ名前の項目を拾いにくくなります。

同期の方式は、差分を足す方式（INCREMENTAL）と、Cloud Storage の中身に合わせて丸ごとそろえる方式（FULL）があります。FULL では、Cloud Storage から消した文書が検索からも消えます。 廃止した版を Cloud Storage から外す運用にするなら、FULL を選びます。

AIへ渡す前に整形する

1. 有効な版だけを複製する … 共有フォルダから、状態が「有効」の版だけを Cloud Storage へ写します。ファイル名の「最新」「改」は信用せず、台帳で有効と決めた版を写します
2. 項目定義書の1行目を見出しにそろえる … 列の見出しが2段になっている表は1段に直します。見出しが崩れると、どの列が「送り側の項目」かが分からなくなります
3. 改修記録を文書にする … 課題管理のチケットを、改修の番号・対象のIF番号・変えた項目・反映日を見出しにしたHTMLに書き出します
4. 項目名の対応表も文書として取り込む … 検索の根拠として引けるようにします
5. レイアウトパーサーと分割の設定を、データストアを作るときに決める … チャンクの設定は、作った後で入れたり外したりできません。 見出しを各チャンクに含める設定にします
6. 画像だけのPDFを洗い出す … 古い設計書にはスキャンしたPDFがあります。文字の入ったPDFに作り直すか、OCRのパーサーを使います

5番目は、やり直しが効きません。 見出しを含めない設定で作ると、項目定義書の表の途中で切れたチャンクに、どのインターフェースの表なのかが書かれていない状態になります。引用を開いても、どの設計書の話か分かりません。

AIに処理させる

answer メソッドにさせるのは、「ある項目が、どの文書のどこで、どこからどこへ渡されているか」を、引用付きで書き出すことです。 1回の問い合わせで1区間を返させ、区間をつなぐのは画面の側の処理で行います。

画面の側が answer メソッドに投げる問いは、区間ごとに次の形で組み立てます。

【問い】
システム「{system}」の項目「{item}」（別名：{aliases}）を、
送り側の項目として受け取っているインターフェースをすべて挙げ、
受け側のシステムと項目名、変換の規則を答えてください。
【絞り込み】status: ANY("有効") AND source_system: ANY("{system}")

問いの文面を固定するのは、答えの形をそろえるためです。 人が自由に問うと、「どこへ渡る？」と「どこで使われている？」で拾う文書が変わり、区間の並びが組み立てられなくなります。

区間をつなぐのを生成AIに任せないのは、つなぎ目で推測が入るからです。 「受け側の項目」から「次の区間の送り側の項目」へ移るところで、名前が似ているだけの別の項目につなぐことがあります。つなぎ目は、項目名の対応表か、同じ項目名の完全一致に限ります。

answer メソッドには、問いを小さな問いに分けて調べる働き（最大5段まで）があります。 それでも、この構成では1回1区間にします。区間ごとに根拠を確かめられる形のほうが、まとめて答えさせるより確認が速いからです。

指示内容を固定する

answer メソッドの promptSpec.preamble に、次の指示を入れます。

あなたは情報システム部で、社内システム間の連携を調べる係です。
検索結果として与えられた文書だけを根拠に答えてください。

【答えること】
問われた項目について、次の1区間だけを答えてください。
- 送り側のシステムと項目名（論理名・物理名）
- 受け側のシステムと項目名（論理名・物理名）
- インターフェースの番号と、連携の方式（ファイル・API など）
- 変換の規則が書かれていれば、その内容をそのまま

【守ること】
- 文書に書かれていない区間は答えないでください。
  見つからなければ「この項目を受け渡すインターフェースは、検索した文書の中に見つかりません」とだけ答えてください。
- 項目名が似ているだけで、同じ項目だと判断しないでください。
  項目名の対応表か、項目定義書の「送り側の項目」の列に書かれている場合だけ、対応しているとしてください。
- 複数のインターフェースが見つかった場合は、すべて並べてください。1つに絞らないでください。
- 変換の規則を要約したり、言い換えたりしないでください。書かれているとおりに写してください。
- 改修の影響があるかどうか、改修してよいかどうかは書かないでください。
- 答えの各文に、根拠にした文書を引用として付けてください。

あわせて、answerGenerationSpec で includeCitations を有効にし、ignoreLowRelevantContent を有効にします。関連の薄い内容しか見つからないときに、無理に答えを作らせないためです。 groundingSpec では filteringLevel を高く設定し、根拠との結び付きが弱い答えを返させないようにします。

「似ているだけで同じ項目と判断しない」を明記しないと、つなげます。 「受注番号」と「受注明細番号」のように一部が同じ項目は、生成AIには同じものに見えやすく、実際には別のインターフェースの別の項目なのに、経路が一本につながって見えます。

「変換の規則を要約しない」も大事です。 「先頭ゼロ埋め8桁」「消費税込みに換算」のような規則は、要約すると落ちる部分にこそ改修の影響があります。

出力形式を固定する

問い合わせ画面は、answer メソッドの応答から次の形を組み立てて表示します。

{
  "query_item": "納品先コード",
  "direction": "downstream",
  "aliases": ["納品先コード", "届先CD"],
  "hops": [
    {
      "from_system": "販売管理",
      "from_item": "納品先コード（DLV_CD）",
      "to_system": "倉庫管理",
      "to_item": "届先CD（TDK_CD）",
      "if_id": "IF-0123",
      "transform_rule": "先頭ゼロ埋め8桁",
      "evidence": [
        { "doc_type": "項目定義書", "uri": "gs://.../IF-0123_項目定義書_v3.2.xlsx", "version": "3.2", "excerpt": "" }
      ],
      "newer_change": { "found": true, "change_id": "CHG-0456", "applied": "" }
    }
  ],
  "stopped_at": { "item": "", "reason": "NO_RELEVANT_CONTENT" },
  "last_sync": ""
}

1つ目の理由は、evidence を区間ごとに持てることです。 answer メソッドは、回答の文と引用元を結ぶ情報（citations）と、引用元の文書のURIとチャンクの中身（references）を返します。画面ではこれを区間ごとに並べ、クリックで文書を開けるようにします。

2つ目は、stopped_at で止まった理由を残せることです。 answer メソッドは、答えを作らなかったときに理由（answerSkippedReasons）を返します。関連する内容が無い、根拠との結び付きが弱い、といった理由です。止まった場所と理由が、第5章の7番目で担当者が調べる対象になります。

3つ目は、newer_change で設計書が古い可能性を示せることです。 区間の根拠は設計書でも、その後に改修の記録があれば、変換の規則が変わっているかもしれません。

システムへ連携する

検索の側から共有フォルダや課題管理へは書き込みません。 「不明」で止まった区間を調べた結果は、担当者が設計書か項目名の対応表を直し、次の同期で載ります。

社内の権限に合わせて、見せる文書を分けることも考えます。 人事や給与の連携の設計書には、項目の名前だけでも知られたくないものがあります。そうした文書は別のデータストアに分け、問い合わせ画面の側で使える人を絞ります。

人が確認する

人が見るのは、すべての答えです。 この構成は下調べの時間を減らすもので、答えを確定させるものではありません。

1. 区間ごとに根拠の文書を開く … 引用の箇所が、本当にその項目の受け渡しを書いているかを見ます
2. newer_change がある区間は改修記録を読む … 変換の規則が変わっていないかを確かめます
3. stopped_at の区間を調べる … プログラムの中を見る、詳しい担当者に聞く、などで調べます
4. 分かったことを文書に足す … 設計書を直すか、項目名の対応表に足します
5. 問い合わせた人に、確かめた経路と根拠を返す

1番目を省かないでください。 引用が付いていても、その箇所が「別のインターフェースの同じ名前の項目」を書いていることがあります。引用があることと、引用が正しいことは別です。

確かめる人は、問い合わせた人とは別にします。 開発ベンダーが自分で区間の並びを見て改修の範囲を決めると、根拠を開かずに進むことがあります。情報システムの担当が確かめた区間だけを「確認済み」として返します。 目標は、区間がすべてつながった問い合わせで1件数分です。

例外に対処する

区間の上限を5にしているのは、確認の手間に合わせるためです。 5区間を超える経路は、そもそも人が確かめるのに時間がかかります。そこから先は、詳しい担当者と一緒に見る問い合わせとして扱います。

記録を残す

• 問い合わせの内容（項目名、システム名、向き）と、問い合わせた人・日時
• 展開した別名の一覧と、使った項目名の対応表の版
• 区間ごとの answer メソッドの応答（回答、引用、参照した文書、止まった理由）
• 担当者が確かめた結果（区間ごとに、正しい／誤り／確かめられない）
• stopped_at を調べた結果と、直した文書・対応表
• そのときの最終の同期日

4つ目の「区間ごとの正誤」を必ず残します。 誤りの多い文書や、誤ってつながりやすい項目名が分かれば、直すべき設計書と、対応表に足すべき別名が見えてきます。

確かめた経路は、次の問い合わせで再利用できるようにします。 同じ項目の同じ向きの問い合わせは繰り返し来ます。確認済みの経路を問い合わせ画面に残し、次に同じ問いが来たら、確認した日と、その後の改修記録の有無を添えて先に見せます。