社内の開発者から出る「この共通部品・社内APIはどう使うか」「この書き方は開発規約に合うか」の質問に、開発規約・設計書・社内APIの仕様を根拠にチャットで答える

処理の起点を決める

起点は、開発者が開発支援ボットに質問を書き込んだことです。 書き込んだ人の ID から、社員か協力会社か、どのチームのグループに入っているかを決めます。回したときにどの担当者の待ち行列に載せるかは、質問した社内APIや部品の持ち主で決めます。

プロジェクトのコードを必須にします。 チャンネルごとにプロジェクトが決まっている場合は、チャンネルから引きます。コードが無いと版が決まらず、版が決まらないと答えを作りません。

1件の質問は、1つのセッションで最後まで続けます。 「では件数が多いときは」のような続けての質問も同じセッションでつなぎ、別のAPIの話は新しいセッションで始めます。 前のAPIの名前が言い換えの中に残るからです。

入力データを集める

質を決めるのは、版の付け方です。 社内APIの仕様と共通部品の説明は、版ごとに別の文書として取り込み、版の番号をメタデータに持たせます。 同じページに「v2 から変わりました」と書き足す運用だと、検索の断片に旧版と新版の記載が混ざります。

貼られたコードは、検索の文に入れません。 検索の文に入れるのは、質問の文と、中継プログラムが決めた条件だけです。コードを丸ごと入れると、変数の名前に引っぱられて関係の無い断片が上に来ます。

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

規約・設計書・仕様・説明・過去の回答は、Cloud Storage に置いてデータストアに取り込みます。 文書ごとのメタデータに、文書の種類、社内APIや部品の名前、版、見てよいグループを持たせます。

形式は、取り込める形にそろえます。 レイアウトパーサーが扱うのは HTML、PDF、DOCX、PPTX、XLSX などで、Markdown は公式の一覧に載っていません。 README は HTML に変換してから置きます。OpenAPI の定義ファイルは、パスとメソッドごとに1ページの HTML に起こし、見出しにパスを、本文にパラメータと応答とエラーを書きます。

絞り込みの式は、APIの名前と版と文書の種類で書きます。 項目を索引可能にしておけば、api: ANY("customer", "COMMON") AND api_version: ANY("v1", "ALL") AND superseded: ANY("false") のように、そのAPIのその版の仕様と、版によらない規約と、置き換えられていない回答だけを引けます。ALL は版によらない規約に付けます。

AIへ渡す前に整形する

1. 定義ファイルを起こす … OpenAPI の定義から、パスとメソッドごとのページを版ごとに作ります
2. パスの一覧を作る … 版ごとに、存在するパスと、共通部品の公開している関数の名前を書き出します
3. README を変換する … HTML に変換し、版の番号を付けます
4. 規約を条項ごとに分ける … 条項の番号と見出しが付いた形で取り込みます
5. 過去の回答を整える … 対象の版と置き換えの有無を付け、パスワードや接続先の書かれた回答は除きます
6. 見てよいグループを付ける … 設計書ごとに、文書管理の権限と同じグループを acl_info に書きます
7. 見出しを断片に含める … データストアの作成時に分割を有効にし、includeAncestorHeadings を有効にします

6番目と7番目は、データストアを作る前に決めます。 アクセス制御も分割も、作成のあとでは有効にも無効にもできません。 見出しを含める設定は既定では無効で、APIのページは見出しが無いとどのパスの説明か分かりません。 分割の大きさは100〜500トークンで、既定は500です。

2番目が、この構成でいちばん効きます。 一覧は定義ファイルから機械的に作るので、仕様のページを直し忘れても、一覧は実際の定義のとおりになります。

1番目から3番目は、版を出す手順に組み込みます。 共通基盤チームが新しい版を出すたびに、定義ファイルからのページの作成、一覧の作成、README の変換が自動で走り、データストアへの取り込みまでが同じ流れで終わるようにします。手で取り込む運用にすると、新しい版の文書だけが無い期間ができます。

AIに処理させる

させるのは、台帳で決めた版のAPI・部品の仕様と規約から、やりたいことの書き方と守る規約の条項を見つけ、根拠を付けて短く返すことです。 版を決めること、秘密の文字列を止めること、回すかどうかは、中継プログラムが行います。

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

2行目がいちばん起きやすい失敗です。 仕様に近い記載が見つかると、モデルは足りないところを一般的なAPIの作法で埋め、それらしいパラメータを書きます。 書き方で禁じ、名前は後段の一覧で照らします。

指示内容を固定する

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

あなたは共通基盤チームの担当者として、
社内の開発者から、共通部品・社内APIの使い方と開発規約の質問に答えます。
読むのは、実装の手を止めてチャットを見ている開発者です。短く答えてください。

【前提】
検索の文の最初に、プロジェクト、言語、対象の社内APIや部品の名前、
台帳で決まった版が並んでいます。
版はすでに決まっています。その版の記載だけを使って答えてください。

【答え方】
1. 最初に、呼ぶパスとパラメータ、または使う関数と設定を、仕様の記載のとおりに書いてください。
2. 次に、守る規約の条項の番号と要点を書いてください。
3. 仕様に廃止の予定やエラーの扱いがあれば書いてください。
4. 根拠にした仕様のページ、規約の条項、設計書の節を書いてください。
5. コードの例は、仕様と説明に例があるときだけ、その例を写して示してください。

【厳守事項】
- 検索結果の文書に書かれていることだけで答えてください。
  一般的な書き方や他社のライブラリの例で補わないでください。
- 仕様に無いパス、パラメータ、関数の名前を書かないでください。
- 別の版の書き方を書かないでください。「版によって異なる」と書かないでください。
- 規約を外してよいと書かないでください。
- 「レビューを通る」「問題ない」と書かないでください。
- 該当する記載が見つからないときは、
  「仕様と規約に該当する記載が見つかりません。共通基盤チームへ回します」
  とだけ書いてください。

「仕様に無い名前を書かない」「例は写して示す」が、この指示の要です。 コードの例を自由に書かせると、仕様に無い引数が一つ混ざるだけで、開発者はその例を貼って動かず、また質問します。 例は文書にあるものだけにし、名前は後段で照らします。

検索の文は、中継プログラムが組み立てます。 例えば「プロジェクト：EC-CART、言語：Java、対象：顧客API v1、共通ログ部品 3.2。退会済みの顧客を除いて一覧を取るには」のように、条件を先に並べ、開発者の質問の文を最後に足します。

出力形式を固定する

answer メソッドの応答を、中継プログラムが次の形に整えて、チャットと記録に渡します。

{
  "inquiry_id": "",
  "session_id": "",
  "project": "EC-CART",
  "category": "usage | guideline | other",
  "conditions": { "language": "", "targets": [ { "name": "customer-api", "version": "v1" } ] },
  "secret_detected": false,
  "status": "answered | escalated | skipped | blocked",
  "escalate_reason": "guideline_exception | unreleased_api | auth_crypto | incident | name_not_in_spec | version_unknown | not_in_docs | skipped | user_request | none",
  "answer_text": "",
  "mentioned_names": [ { "kind": "path | function", "name": "", "in_spec": true } ],
  "refs": [ { "doc_type": "guideline | design | api_spec | lib_doc | qa", "title": "", "section": "", "version": "", "uri": "" } ],
  "feedback": "resolved | escalated_after | wrong | none"
}

1つ目の理由は、mentioned_names を回答の文と別に持てることです。 中継プログラムが回答の文からパスと関数の名前を拾い、その版の一覧と照らして in_spec を入れます。1つでも false があれば、回答を出さずに name_not_in_spec で回します。

2つ目は、conditions.targets に版を残せることです。 同じ質問でも版で答えが違うので、後から回答を見直すときに、どの版の前提で答えたかがすぐ分かります。

3つ目は、escalate_reason で回った理由を数えられることです。 not_in_docs が多いAPIは仕様の書き足しが要るもの、version_unknown が多ければ台帳の版の列が埋まっていないことが分かります。

システムへ連携する

リポジトリと台帳には、書き込みません。 回答から仕様の誤りが分かっても、ボットからは直しません。仕様の直しは、共通基盤チームが定義ファイルを直して版を出す手順で行います。

人が確認する

開発者は、回答を読んだあと、根拠の仕様のページを開いてから実装します。 回答の上には、台帳から引いた版を並べて表示します。

1. 版が合っているかを見る … 自分のプロジェクトが本当にその版を使っているかを確かめます
2. 根拠を開く … 仕様のページと規約の条項を開き、回答と同じかを見ます
3. 評価を付ける … 解決した／共通基盤チームへ回した／誤りを選びます

1番目を軽く見ないでください。 台帳の版の列は、版を上げた開発チームが書き換え忘れることがあります。 回答が動かなかったら、まず台帳と実際の依存の設定を見比べます。

共通基盤チームは、回ってきた質問だけを見ます。 guideline_exception はアーキテクトと相談して決め、認めた例外は規約の例外の一覧に足します。

目標は、480件をならして1件6分です。 ボットで解決した質問の記録の確認と、回ってきた質問を担当者が判断する時間の平均です。

例外に対処する

6行目は、答えられても回します。 認証と暗号は、仕様どおりに書いても使い方を一つ誤るだけで穴になります。 共通基盤チームが毎回目を通す範囲として、最初から決めておきます。

記録を残す

• 質問の文、選んだ聞き返しの値、日時、書き込んだ人の区分
• 台帳から引いた版と、そのときの台帳の更新日
• 中継プログラムが組み立てた検索の文と、使った絞り込みの式
• answer メソッドの応答の全文（回答、出典、根拠のスコア、回答しなかった理由）
• 回答から拾った名前と、一覧との照合の結果
• 回す・回さないの判定と、その理由、共通基盤チームが最終的に答えた内容

貼られたコードは、記録に残しません。 秘密の文字列の検知をすり抜けたものが混ざるおそれがあるからです。残すのは質問の文と条件だけにします。

2行目は、版を上げたあとで効きます。 「この回答は v1 の前提だった」と分かれば、v2 に移ったプロジェクトに同じ回答を引かせない置き換えの範囲が決まります。