SaaSのサポート担当が顧客からのAPIの技術的な質問に、顧客が使っているAPIの版の仕様書・リリースノート・過去の回答を根拠に回答案を作る

処理の起点を決める

起点は、チケットが技術サポートチームに割り当てられたことです。 一次対応の窓口が技術的な質問と見分けた時点で、中継プログラムが動きます。担当者がチケットを開いたときには、内部メモに回答案が入っている状態にします。

顧客から追加の質問が届いたときも、同じチケットで動かし直します。 そのときは前の回答案と顧客への回答も材料に渡し、answer メソッドのセッションで前の質問を踏まえた回答を作ります。

リリースノートが公開されたときは、別の起点として取り込みを動かします。 新しいリリースノートを取り込むと同時に、廃止や変更の告知に出てくる項目名を持つ過去の回答に「要見直し」の印を付けます。 印の付いた過去の回答は、見直されるまで検索の出典から外します。

入力データを集める

質を決めるのは、仕様の定義ファイルです。 仕様書の文は人が読むためのもので、項目名が文中に埋もれています。定義ファイルなら、ある版にある項目名とパスの一覧を機械的に作れます。 第7章「AIに何をさせるのか」の照合は、この一覧で行います。

過去の回答は「検証済み」の印のものだけを入れます。 約1万件をすべて入れると、誤っていた回答や、顧客ごとの事情に合わせた例外の回答まで出典になります。最初は、技術に詳しい2名が「今後も使える」と判断した回答から始めます。

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

仕様書は、エンドポイントごとに1つの文書として Cloud Storage に置き、メタデータ付きで取り込みます。 メタデータに、文書の種類、対象の版、エンドポイントのパス、更新日を持たせます。

過去の回答1件分のメタデータは、例えば次のような形です。

{
  "id": "ANS-2026-08-1123",
  "jsonData": "{\"doc_type\":\"past_answer\",\"api_version\":\"v1\",\"answered_at\":\"2026-08-21T00:00:00Z\",\"verified\":\"true\",\"needs_review\":\"false\",\"endpoints\":[\"/v1/orders\"]}",
  "content": { "mimeType": "text/plain", "uri": "gs://api-support/answers/ANS-2026-08-1123.txt" }
}

顧客の版への絞り込みは、ANY() で書きます。 絞り込みの式は ANY() と AND／OR／NOT を組み合わせられ、使う項目はデータストアのスキーマで索引可能にしておく必要があるとされています。

api_version: ANY("v1","common") AND needs_review: ANY("false")

過去の回答を新しいものに寄せるには、優先度の調整の鮮度の指定を使います。 日付の項目と、検索した日からの経過日数の区切り（例：30D、365D）ごとに−1〜1の値を決めると、その間は直線で補って優先度を変えられるとされています。回答した日から30日以内は少し上げ、1年を超えたものは下げる設定から始めます。 仕様書には鮮度の調整をかけません。仕様書は古くても、その版では正しいからです。

AIへ渡す前に整形する

1. 仕様書をエンドポイントごとに分ける … 版ごと・エンドポイントごとに1文書にし、api_version と endpoints を入れます
2. 定義ファイルから一覧を作る … 版ごとに、項目名・パス・上限の数値の一覧を作り、照合に使います
3. リリースノートを項目に結び付ける … 告知に出てくる項目名とパスを抜き出し、メタデータの endpoints に入れます
4. 過去の回答の顧客の情報を消す … 会社名、担当者名、APIキー、リクエストの本文に入っていた取引の情報を消してから取り込みます
5. 過去の回答に当時の版を入れる … 回答した時点の契約情報から版を引いて入れます
6. 廃止の告知で印を付ける … 廃止・変更の告知の項目名を持つ過去の回答に needs_review: true を入れます

4番目を軽く見ないでください。 過去の回答には、顧客が貼ったリクエストの本文がそのまま残っていることがあり、取引先の名前や金額、時にはAPIキーが入っています。 これが出典として別の顧客への回答案に出れば、情報の漏えいです。APIキーの形の文字列は、取り込む前に機械的に消します。

6番目は、リリースのたびに必ず動かします。 印の付け忘れが、第3章（c）の古い回答の再利用をそのまま再現します。

AIに処理させる

させるのは、顧客の版の仕様書と検証済みの過去の回答から質問に当たる記載を見つけ、仕様書の言葉と項目名のまま回答案を書き、出典を示すことです。

answer メソッドの設定は次のようにします。

1行目が最も起きやすい失敗です。 仕様書に ordered_at とあるのに、回答案に order_date と書く。読んだだけでは自然で、担当者も見落とします。 指示で禁じたうえで、第5章の4番目の照合で機械的に見つけます。

指示内容を固定する

answer メソッドの preamble に、次の指示を入れます。中継プログラムが {api_version} と {plan} を差し込みます。

あなたはSaaSの技術サポートの担当として、顧客の開発担当者からの
APIの質問に答える回答案を作ります。読むのはサポートの担当者で、
確かめて直してから顧客に送ります。

【この顧客の条件】
- 使っているAPIの版：{api_version}
- 契約のプラン：{plan}

【書き方】
1. 結論を最初の1〜2文で書いてください。
2. 項目名・エンドポイントのパス・エラーのコードは、仕様書の表記のまま
   `バッククォート` で囲んで書いてください。
3. 上限やタイムアウトの数値は、この顧客のプランの値だけを書いてください。
4. リクエストの例を書くときは、仕様書にある項目だけを使ってください。
5. 廃止の予告がある項目に触れるときは、廃止の予定日と代わりの項目を書いてください。

【厳守事項】
- 仕様書に無い項目名・パスを書かないでください。似た名前を作らないでください。
- {api_version} 以外の版の仕様を、この顧客の仕様として書かないでください。
- 不具合だと断定しないでください。既知の不具合に似ている場合は、
  「既知の事象に似ています」と書き、一覧の回避策だけを示してください。
- 今後の機能の追加や修正の時期を約束しないでください。
- 当たる記載が見つからないときは、
  「仕様書に該当する記載が見つかりません。開発チームに確認が必要です」とだけ書いてください。

「項目名をバッククォートで囲む」は、照合のための約束です。 囲まれた文字列を中継プログラムが抜き出し、版の一覧と照らします。囲まずに書かれた項目名は照合から漏れるので、照合の結果に「囲まれていない英数字の語」の件数も出し、担当者が見る目安にします。

「既知の事象に似ています」と書かせるのは、症状が似ていても原因が違うことが多いためです。 不具合と書いた回答は、顧客が自社の調査を止めてしまいます。 原因の判断は、開発チームがリクエストのIDでログを見て行います。

出力形式を固定する

answer メソッドの応答と照合の結果を、中継プログラムが次の形に整えて内部メモに書きます。

{
  "ticket_id": "",
  "api_version": "v1",
  "plan": "",
  "status": "draft_ready | needs_dev | not_found",
  "draft_text": "",
  "citations": [ { "doc_id": "", "doc_type": "spec | release_note | past_answer | known_issue", "answered_at": "" } ],
  "identifier_check": [ { "token": "", "kind": "field | path | error_code", "exists_in_version": true } ],
  "unquoted_terms": 0,
  "grounding": { "support_score": 0, "weak_claims": [ { "text": "", "score": 0 } ] }
}

1つ目の理由は、identifier_check で仕様に無い名前を一覧で示せることです。 exists_in_version: false の行は、担当者の画面で赤く表示します。v2 にはあるが v1 には無い名前なら、そのことも並べて示します。 版の取り違えだとすぐに分かります。

2つ目は、status で人の動き方を決められることです。

3つ目は、weak_claims で裏付けの弱い文を示せることです。 check grounding API は文ごとの支持の度合いと出典を返し、出典とみなす境目は指定しなければ0.6とされています。境目を下回った文を weak_claims に並べ、担当者が最初に読む箇所にします。

システムへ連携する

顧客への返信は、チケット管理システムの画面で担当者が行います。 中継プログラムは内部メモにしか書きません。内部メモと顧客への返信を同じ欄にしないよう、書き込み先の種別を設定で固定します。

check grounding API に渡すファクトは、answer メソッドが出典にした断片です。 断片ごとに文書の種類と版を属性として付けて渡し、大きな仕様書を1つのファクトにまとめません。

人が確認する

すべての回答案を、担当者が確かめてから顧客へ返します。

1. 照合の結果を先に見る … exists_in_version: false の名前と、weak_claims の文を確かめます
2. 出典を開く … 結論の根拠になった仕様書のページを開き、顧客の版のものかを確かめます
3. プランの数値を確かめる … 上限の数値が顧客のプランのものかを見ます
4. リクエストの例を試す … 例を書いた場合は、検証用の環境で一度呼んでから返します
5. 「検証済み」の印を付ける … 今後も使える回答に印を付け、過去の回答として取り込ませます

4番目を省かないでください。 例のリクエストは、顧客がそのまま貼り付けて使います。項目名が正しくても、型や必須の項目の抜けで失敗することがあります。

needs_dev のものは、開発チームへの問い合わせの文を回答案から作ります。 顧客の版、エラーの文言、リクエストのID、仕様書で確かめた範囲を並べ、開発チームが最初からやり直さずに済む形にします。

例外に対処する

7行目は、顧客の側の不注意から起きます。 開発担当者はエラーの調査のためにリクエストをそのまま貼ります。APIキーの形の文字列は検索に渡さず、担当者から顧客へ、キーの再発行を勧める一文を添えます。

記録を残す

• チケットのID、顧客の版とプラン、回答案を作った日時
• answer メソッドの応答の全文（回答、出典、回答しなかった理由）
• 照合の結果（identifier_check、unquoted_terms）と check grounding API の結果
• 担当者が直した後の回答と、直す前の回答案との差分
• 開発チームへの問い合わせと、その答え
• 「検証済み」の印を付けた担当者と日時

4つ目は、この構成の弱いところを示します。 担当者が毎回同じ種類の直しをしているなら、仕様書の書き方か、preamble の指示か、取り込んだ過去の回答のどれかに理由があります。 月に一度、直しの多い質問の型を数えます。