AI・API 設定

RAG (Retrieval-Augmented Generation) の導入

RAG とは

• 基本構成: ソース文書 → chunking → embeddings / index → retrieval → prompt composition → 回答 + 引用
• 一次情報は docs/、docs/adr/、用語集、仕様書を優先する
• z_docs/history/ などの個人メモを検索対象に入れるなら、「草稿・履歴を含む」ことを明示する

NOTE: RAG を正式運用するなら、.cursor/rules/60-ai-workflow.mdc と CLAUDE.md にも「出典を添える」「根拠が取れないときは推測で埋めない」を入れておくとブレにくい。

向いているケース / 向いていないケース

向いているケース:

• 社内ドキュメント、運用マニュアル、ADR、仕様書、サポートナレッジのように 文書が正式な記録 の知識を引かせたいとき
• 回答のたびに 出典を添えたい とき
• モデル再学習ではなく、文書更新で知識を更新したい とき

向いていない、または注意が必要なケース:

• 元文書の品質が低い、重複が多い、古い版が混ざるなど、検索前の情報整理ができていない状態
• 更新タイミング、再インデックス条件、失効ルールなどの 鮮度管理 が決まっていない状態
• 出典を返さずに使う運用。誤答時に根拠追跡ができず、利用者も検証しづらい
• 本来は DB クエリや外部 API 呼び出しで確定値を返すべき処理。RAG は検索付き要約であり、システム of record の代替ではない

小さく導入する手順

1. 対象知識を絞る: まずは1領域だけに限定する。例: オンボーディング資料、運用FAQ、1機能分の仕様群
2. source of truth を整理する: docs/、docs/adr/、用語集のどれを正式な記録にするかを決め、重複や古い版を潰す
3. 更新フローを決める: 誰が更新し、いつ再インデックスし、古い文書をどう失効させるかを決める
4. 検索粒度とメタデータを決める: chunk の大きさ、見出し単位、文書ID、版、更新日時、章名を揃える
5. 評価基準を先に決める: 取得精度、引用の正確さ、根拠なし時に回答を控える率、レイテンシを最低限測る
6. ログとフィードバックを残す: 質問、取得文書、回答、ユーザーフィードバックを保存して改善材料にする
7. 小さく公開してから広げる: まずは限定ユーザー・限定ユースケースで運用し、定着したら対象文書を増やす。全体方針になるなら ADR 化も検討する

RAG は 検索基盤の話である前に、文書運用の話。このドキュメントの流れに合わせるなら、docs/ / docs/adr/ / 用語集を整えたうえで、AIワークフローに「出典必須」を組み込む順が安全。Naive RAG で足りない場合（多段推論・検索判断・自己修正）は RAG 参考 — Agentic RAG を参照。

生成AI機能 (OpenAI API) の組み込み

先に決めること

• ユースケース: 要約、抽出、分類、チャット支援、下書き生成など、何をAIに任せるかを先に固定する。確定値を返す処理は通常のDB/APIで解く
• レイテンシ / コスト / モデル: 対話UIなら応答目標時間、バッチなら件数と上限単価を決め、まずは小さめのモデルから評価する
• 同期 / 非同期: 画面で待てるなら同期、時間が読みにくい・再実行が必要・件数が多いならジョブ化する
• 出力形式: 人間向け文章か、JSONなどの機械可読形式かを決める。後者は backend で型・schema を検証する前提で設計する