本記事では、2025年5月28日に開催されたオンラインイベント「AIエージェントのオンボーディング-ヒトとAIの協同を支える”役割設計”とは」内のセッション「AIのためのオンボーディングドキュメントを整備する」の内容をお届けします。同セッションでは、株式会社スマートバンクのhirotea（@nifuchi222222）さんに、AIエージェントが参照できる共通基盤としての「AIオンボーディングドキュメント」についてお話いただきました。ぜひ本編のアーカイブ動画とあわせてご覧ください。
hirotea：株式会社スマートバンクでAI家計簿アプリ「ワンバンク」というサービスを開発している、hiroteaといいます。
本日の発表は、3月に弊社ブログで公開した記事の内容をブラッシュアップしたものです。
「AIオンボーディングドキュメント」は、使用者に左右されず同じ品質を再現し、あらゆるAIエージェントが参照できる共通基盤とすることを目的としています。
本日は、このドキュメントを「どこで管理し」「どのようにナレッジを込めて配置し」「どう作成・メンテナンスするか」を、皆さんがすぐ実践できるよう、具体的な事例と共にお話しします。
ドキュメントの構造
スマートバンクで作成したAIオンボーディングドキュメントは、プルリクエストにして約2,200行に及ぶ6本のドキュメントです。内訳は、メインが1本、各レイヤーの資料が4本、メンテナンス用が1本となります。
ドキュメントは、概要説明と目次から始まります。LLMは冒頭の情報を重視するため、最初に目次で全体像を示すことが重要です。
次に、Railsのバージョンといったリポジトリの基本情報や、モデル、コントローラーなど各レイヤーの詳細ガイドへのリンクを記載。さらに、具体的なコードサンプル付きのルールも掲載しており、これ一つでも参考になるようになっています。
AIへの失望を防ぐために――ドキュメント作成の背景
AIが良いコードを書けない大きな理由の一つに「社内コーディングルールを知らない」点が挙げられます。ここで言うコーディングルールとは、プロジェクト固有の規約や暗黙知、利用すべき基底クラス、エラーハンドリング方法などです。
AIがルールを知らないと、既存コンポーネントを使わず「車輪の再発明」をしたり、人間による修正コストが増大したりします。
例えば、Userクラスは社内定義のApplicationRecordを継承すべきところをActiveRecord::Baseを継承したり、APIコントローラーはApi::BaseControllerを継承してエラーハンドリングも組み込むべきところをApplicationControllerを継承したりと、多くの手直しが必要になります。結果として「使えない」「手直しが面倒」といった、AIへの失望に繋がります。
この問題は、CursorのRulesやDevinのKnowledgeといった、各ツールに搭載されたナレッジストアを活用することで解消できます。しかし、社内では当初主流だったCursorに加え、GitHub CopilotやDevin、Claudeなど複数のツールが併用されるようになり、ツールは日々増え続けています。
そこで課題となるのが、ツールごとに分散したナレッジの管理です。ツールが乱立すると、ナレッジのバージョン管理や相互参照が困難になります。各ツールのナレッジを個別に育てることも重要ですが、まずはその基盤となる共通のオンボーディングドキュメントが必要だと考えました。
共通ドキュメントにはナレッジの基礎として、ツールからの参照のしやすさ、メンテナンス性、そして情報の一元管理が求められます。リポジトリでコードと共に管理することでこれを実現し、開発者全員が参照できるようにすれば、習熟度に関わらず一定の品質を担保でき、AIへの失望も防げるはずです。
知識抽出とエージェント活用
次に、ドキュメントにどのようなナレッジを込めるかについてです。実装には、一般的な知識、言語・フレームワークの知識に加え、社内コーディング規約や機能仕様が求められます。しかし、LLMが知っているのは主に一般的な知識で、社内規約は含まれていません。場合によっては他社の規約を参考に、期待しないコードを生成することもあります。
そのため、プロンプトで社内規約と仕様を明示的に与える必要があります。暗黙知も含めて言語化した社内規約をオンボーディングドキュメントとして渡すことで、高品質で再現性のある出力を実現できます。
社内規約を言語化してドキュメント化
言語化されていない規約も、既存の実装から共通点を抽出できます。弊社のリポジトリはコーディング規約が遵守されているため、共通ルールを言語化しやすい状態です。実装に共通するルールを言語化して渡すことで、品質とスタイルに一貫性を持たせられると考えます。
これらのナレッジは、先ほど紹介した通り、全体像をまとめた「コーディングガイド」、レイヤーごとのドキュメント、メンテナンス用ドキュメントという構成で配置しています。
エージェントにナレッジを届けるプロンプト設計
ここからは、AIコーディングエージェントにどうナレッジを届けるかです。例えば、エージェントには「ユーザーの要求を確認後、コーディングガイドラインを開き、Semantic Searchで規約を探索しなさい」といったプロンプトを渡すことを想定します。
この指示を受け、エージェントはまずコーディングルールを開きます。次にモデルを実装する場合、ガイド内のリンクからモデル用のルールを正しく検索・参照してくれるはずです。
実際に、架空のキャラクター「ワンバン君」の着せ替え機能APIをAIに作らせて効果を検証しました。プロンプトに機能要求と「コーディングドキュメントを参照せよ」との指示を含めると、Cursorは期待通りにまずコーディングガイドとルール全体を参照し、次にモデルとコントローラーの各ガイドラインを確認した上で実装を開始しました。
生成されたコードは、以前の失敗例とは異なり、ApplicationRecordを正しく継承しており、コントローラーも適切な形で実装されていました。このように、コーディングドキュメントが正しく参照されていることが確認できます。
ドキュメントをローカルで持つ、もう一つの利点として「AIによる自己修正」が挙げられます。例えば、AIの出力に、本来使うべきBaseSerializerではなくActiveModelSerializerを使ってしまう間違いがあったとします。このような場合も、参照してほしい正しいドキュメント（@）を追加するだけで、AIが自らコードをきれいに修正してくれます。
どう作り・どのようにメンテナンスしていくのか？
最後に、ドキュメントの作成方法です。6つのファイルを手で書くのは大変ですが、暗黙知の言語化は、コードから共通箇所を抽出するタスクと言い換えられます。これはLLMが得意なため、AIに任せることにしました。
まず、推論力が高くコンテキストウィンドウの大きいモデル（当時はo1 Proを使用）に情報収集とドキュメンテーション戦略を立案させ、その戦略を基にエージェントが探索とドキュメント化を行う、というステップで作成します。プロンプトではlsコマンドの結果などを渡し、「Railsコミッターとして推論せよ」とペルソナを指定しました。余談ですが、このようにおまじないのようなペルソナ設定をすると、モデルがより良い働きをする気がします。
出力されたステップに対し、「もう少しきれいにしてほしい」と指示を加え、人間が介入することを前提とした手順を作成させました。この手順をCursorに渡し、探索とドキュメント化を実行させた結果が、冒頭の長文ドキュメントです。プロンプトも共有しますので、ご興味があればお試しください。
railsコミッターとして推論せよ。
以下のようなディレクトリ校正のrails server mode appがある
このアプリケーション全体のコーディングルールを調査したい（例えば共通して利用している基底クラスがあるのか？など）
どのような戦略を取るべきだろうか？
また、この探索をLLMに行わせる際、そのような指示と方針を定義し与えればrails template的な実装との差分、固有実装について調査させられるだろうか？
```
{{ Isの結果を貼り付ける }}
```
メンテナンスもAIエージェントに任せる
メンテナンスも同様にAIエージェントに任せられます。プロンプトはガイドラインとセットで管理しているため、再実行によるドキュメントの再生成や、差分調査も可能です。最近はAPIコールが可能なエージェントも登場しており、定期的な自動更新も実現できるはずです。
まとめ
本日お話した内容の要点は3つです。
- オンボーディングドキュメントはコードと共にリポジトリで集約管理するのが良い
- ドキュメントの内容には、品質と再現性を高める共通ナレッジをエージェントが探索しやすい形で言語化して含める
- 作成とメンテナンスをAIエージェントに任せることで、低コストな維持が可能になる
今後の展望ですが、まだ発展途上なため、引き続き改善に努めます。社内ではAI技術の検証や導入を推進する委員会が発足しており、環境を整備しながら、変化し続けるコーディング環境に対応できる体制を維持していきます。
アーカイブ動画・発表資料
イベント本編は、アーカイブ動画を公開しています。また、当日の発表資料も掲載しています。あわせてご覧ください。
▼動画・資料はこちら
※動画の視聴にはFindyへのログインが必要です。