アリババエンジニアリング、AI 知識ベース体系構築の実践を公開

分解一座冰山：后端系统「AI 知识库体系」建设实践

系统化地构建后端架构知识库，让 AI 从理解代码进阶到理解业务与架构。

这是 2026 年第 41 篇文章（阅读时间约 20 分钟）

从「让 AI 看懂代码」到「让 AI 正确行动」

在上一篇讨论《后端系统 AI Friendly 设计》的文章中，我们开篇就强调过一个判断：后端系统要想真正进入 AI Friendly 状态，不能只停留在“代码写得清楚一点”、“README 多补一点”或“接口注释完整一点”这种层面。

这些当然重要，但它们解决的更多是“人和 AI 能不能读懂局部代码”的问题，而不是“AI 能否在一个复杂系统中做出正确的工程判断”。

真正的问题是：当 AI Agent 接到一个需求时，它到底知不知道这个系统的边界在哪里？知不知道哪些接口绝对不能破坏兼容？知不知道这张表的某个字段虽然看起来没人用，但其实是下游离线任务每天凌晨要扫描的？知不知道某个 MQ Topic 的 schema 不能随便改，因为还有三个历史服务在消费老格式？知不知道某个模块虽然代码很旧，但它是交易链路里的关键兜底逻辑，动了之后不是单测过了就能上线？

这就是后端系统 AI Friendly 化真正麻烦的地方。

AI 并非完全看不懂代码。恰恰相反，今天的大模型在读取、解释代码，以及补全测试、进行局部修改等方面的能力已经相当强了。

问题在于，后端系统里的很多关键知识并不直接存在于代码中；或者虽然存在于代码里，却分散在不同的仓库、不同的配置、不同的历史 PR 以及各种口头约定之中。

人类工程师靠长期经验、团队沟通和线上事故记忆来补全这些上下文；而 AI Agent 没有这些“组织记忆”，它只能读取你明确给它的东西。

「知識ベースをどう選ぶか」という問いは、一見するとツールの選定問題に見えますが、実はより根本的な課題です。つまり、「どのシステム知識を明示的に取り出すのか」、そして「それを AI が使える形にどう変換すべきか」が問われています。

新人のオンボーディングだけが目的なら、自動生成された Markdown Wiki で十分かもしれません。しかし、サービス間の影響分析や、特に跨サービスの技術設計を行うのであれば、サービス図譜、依存関係、上下流の呼び出しチェーンといった知識が必要です。

さらに、AI によるコードの安全な修正を実現するためには、明確な制約、レッドライン（絶対禁止事項）、タスクルーティング、検証基準が不可欠です。問題ごとに必要な知識の形態は異なり、混同して議論すべきではありません。「大規模で包括的な知識ベース」があれば全て解決できるという幻想に陥ってはいけません。

この記事で論じる核心は、後端システムを AI フレンドリーにする際、どのように知識ベースを設計し、その巨大な山から水面下の 90% を掘り起こすかです。そうして初めて、AI は単なる同僚（coworker）から、自律的に動作するオペレーター（agentic operator）へと進化します。

知識ベースから技術設計へ——決定的なポイント

2.1 なぜ技術設計がこれほど重要なのか

現場で繰り返し直面する課題です。AI コーディングを同僚として支援する「CoWorker」形式であれ、7x24 時間自律的に計画・実行する「Agentic Operator」形式であれ、開発プロセス全体において最も重要な环节は技術設計です。この設計の質が、その後のコーディング実行と成果物の正確性を直接決定します。

この判断は古風に見えるかもしれません。「AI が登場する以前から技術設計は重要だったのに、何が新しいのか？」と思うでしょう。しかし、AI 時代における真の新しさは、設計品質のレバレッジ効果（増幅効果）が飛躍的に高まっている点にあります。その増幅率は、直感を超えています。

一、AI の実行速度が誤りの伝播速度を加速させる

人間エンジニアが方向を間違えた場合、数時間かけて数百行のコードを書き、プルリクエストでレビューされる際に指摘されれば済みます。被害は限定的です。しかし、誤った設計の指示を受けた AI エージェントは、10 分もあれば 5 つのファイル、3 つの API、2 つのデータベーステーブルにまたがる完全な変更を完了してしまいます。方向が間違っていると気づいた時には、ロールバックにかかるコストは人間によるコーディング時の数倍に膨れ上がっています。

さらに厄介なのは、このようなエラーが単なる構文ミスやユニットテストで検出可能なバグではない点です。「業務理解の誤り」「境界条件の改変ミス」「互換性の破壊」「下流への影響の見落とし」といった、本質的な問題が含まれていることが多いのです。

二、AI のデフォルト動作は「忠実な実行」であって、「設計への疑問提示」ではない

経験豊富なシニアエンジニアに問題のある要件を渡せば、「ここに矛盾がある」「この設計では循環依存が発生する」「並行処理のケースを見落としている」「過去の仕様変更と整合しない」といった指摘が返ってきます。こうした批判的思考は、長年の経験によって培われたものです。

現在の AI も完全に疑問を呈できないわけではありません。形式的な論理矛盾については指摘しますが、「システム全体を理解しないと見抜けない問題」——例えば「この設計では下流サービスがタイムアウトする」「このフィールドは削除可能に見えるがオフライン照合に影響する」「この状態遷移には人手による承認プロセスが必要だ」といった事象——に対しては、多くの場合、AI は自ら停止して疑問を呈することなく、指示されたまま実行してしまいます。

三、AI コーディングの真価は「実行の詳細」を AI に任せることにある

しかし、この価値には重要な前提条件があります。それは「実行の方向性が正しいこと」です。もし、AI によって節約できたコーディング時間を、デバッグやロールバック、手戻り、オンライン上の異常説明に費やすのであれば、純粋な効率向上はゼロに近づいてしまいます。

多くのチームが「AI を使っても劇的に速くなった実感がない」と報告する背景には、AI のコーディング能力そのものの問題ではなく、技術設計の段階で何かが欠落しているケースが多々あります。AI は非常に効率的に「局所的には正しいが、全体としては誤った」コードを大量に生成してしまいます。結局、人間がその残りを片付けるために時間を費やす羽目になるのです。

技術設計は、知識ベースへの依存度が極めて高い

AI コーディングの時代において、技術設計とは単に「ドキュメントを作成する」作業ではありません。まずは AI に正確なシステムコンテキストを提供し、それを支えるための堅牢な知識基盤を構築することが不可欠です。

この知識基盤は、少なくとも以下の問いに答えられるものでなければなりません。

現在のシステムアーキテクチャはどのような構造か？モジュールの分割方法は？各モジュールの責任範囲はどこにあるのか？今回の要件に関連する上流・下流システムはどれか？API の契約仕様はどうなっているか？変更が及ぶ影響範囲は？データベーススキーマは？どのフィールドにビジネス制約があるのか？表間の暗黙的な依存関係は存在するか？類似した過去の事例から学べる点は何か？以前同様の機能を実装する際にどのような課題があったか？システム上の「レッドライン（絶対守るべきルール）」とは何か？いかなる状況下でも実行が禁止される操作は何か。

人間のエンジニアであれば、経験やコミュニケーション、そして過去の記憶を通じてこれらの情報を得ます。しかし AI にとって必要なのは、構造化され、正確で、かつ必要な時に柔軟に読み込める知識源です。

さらに重要なのが、「業務メタファ（ビジネスの概念）」に対応する既存の技術スタックや設計パターンです。これらを把握しておくことは、技術設計の効率と精度を飛躍的に高めます。私たちはこの層を「ビジネスレイヤー」と呼び、ビジネス要件とアーキテクチャの間の橋渡しやマッピングを担当します。

私たちが目指すべきは、単に AI にコードを読ませるだけではありません。「AI が設計を行い、変更を実行する際に、正確で完全かつ検証可能なシステムコンテキストを持っていること」を保障することです。

これにより、明確な 2 つの課題が浮き彫りになります。1. 知識基盤にはどのような要素を含めるべきか？2. その知識基盤をどのように構築し、ロードすべきか？

AI コーディング全体を貫く知識基盤

「知識基盤から技術設計へ」という議論に入る前に、一つ明確にしておく必要があります。知識基盤は、AI がコードを書く前の準備段階だけで使われるものではなく、また単なる検索対象の RAG ドキュメントとして片隅に置かれるべきものでもありません。AI コーディングにおいては、要件理解、現状分析、設計立案、コーディング実行、検証・テスト、そしてレビューと納品に至るまで、プロセス全体を通じて活用されるべきものです。

7x24 時間稼働する AI やエージェントによるコーディングを分解して見てみると、それは単に「AI が自動でコードを書く」という単純な話ではありません。少なくとも以下の連続した一連の動作を含んでいます。

まず要件を理解し、ビジネス概念を特定します。次に、その概念に対応するシステム、モジュール、インターフェース、テーブル、メッセージを探し出します。その後、変更範囲を分析し、上流・下流への影響を判断します。そして技術設計を策定し、「どこをどのように変更し、どこは変更しないか」を決定します。最後にようやくコーディング、テスト、レビュー、納品へと進みます。

このプロセスのどの段階でもコンテキストが欠落すれば、その後の実行は歪んでしまいます。

「AI コーディング」における知識ベースの役割は、単なる検索用データベースではありません。それは、開発プロセス全体を貫くシステムコンテキストとして機能します。

まず、要件理解フェーズでは、知識ベースが AI に「業務のメタ言語」を理解させる手助けをします。「リファウンド体験の最適化」「権限凍結」「履行異常への補償」「注文逆転フロー」といった用語は、ビジネス担当者にとっては自然な言葉ですが、AI にとっては単なる文字列に過ぎません。もし業務知識や業務からシステムへのマッピングがなければ、AI は字面だけで推測するしかありません。例えば「リファウンド（refund）」という言葉の意味は知っていても、そのチームにおける具体的なリファウンドが、注文ステータス、決済明細の状態、履行状態、財務照合、カスタマーサポートのチケット、あるいはリスク管理戦略のどれに関わるのかまでは把握できません。業務層知識の価値とは、こうした業務用語をシステムが認識できる技術オブジェクトやフローに変換することにあります。

次に、現状分析と影響分析フェーズでは、知識ベースが AI に「実際のシステム」への回帰を促します。一つのリクエストに対して、単一サービスを変更するだけで済むのか、それとも複数サービスにまたがるのか？インターフェースの変更か、ステートマシンの変更か？同期フローの修正か、非同期メッセージの調整か？下流のコンシューマーに影響はあるのか？旧バージョンのクライアントとの互換性を損なうリスクはないのか？これらの問いに対して、現在のリポジトリを AI が参照するだけでは不十分です。アーキテクチャ層の知識、サービス間の依存関係、上流・下流の呼び出しグラフ、過去のベストプラクティス、そして「なぜこのシステムは過去にこう設計されたのか」という背景知識が必要です。これらが欠如していると、AI は「単一リポジトリ内では理にかなっているように見えるが、全体的なフローで見れば不合理である」ような提案をしてしまうリスクが高まります。

さらに、技術ソリューション設計フェーズでは、知識ベースの価値はさらに増幅されます。なぜなら、この段階で重要なのはコードファイルを列挙することではなく、変更範囲、データフロー、ステートフロー、互換性戦略、例外処理、グレーリリースの方法、検証範囲を明確に定義することだからです。最も警戒すべきは、AI が「形式上は完璧だが文脈が間違っている」提案を行うことです。ドキュメントの体裁は技術仕様書のようであり、インターフェースやテーブル構造、フローチャート、テスト計画も含まれているのに、肝心のシステムの一部が抜け落ちている、重要な制約条件が言及されていない、下流への影響分析が不足している、過去の互換性対応が考慮されていないといったケースです。こうした提案は、一見すると完成度が高いため、かえって後続のコーディング実行に対して「方向性が確定した」という誤った安心感を与え、危険を招きます。

コーディング実行フェーズでは、知識ベースは AI にシステムを理解させるだけでなく、「どのように行動すべきか」を制約する役割も果たします。どのディレクトリを変更可能で、どのモジュールが層を超えた呼び出しを禁止されているのか。どのフィールドの削除が許されず、どのインターフェースは意味を変えずに追加のみ許可されるのか。どのステート遷移が冪等性を保つ必要があるのか。どのミドルウェアの利用方法がチームの規範に従うべきなのか。これらは事前に明示的に定義しておく必要があります。そうでなければ、機能としては動作するものの、システムルールに違反したコードを AI が生成してしまう恐れがあります。

検証・テストフェーズでは、知識ベースは「どのようにして今回の変更が安全であることを証明するか」を回答します。変更の種類によって、対応する検証方法は異なります。新しい API の追加にはインターフェース契約と互換性の確認が必要ですし、データベースの変更にはマイグレーション、ロールバック、履歴データの扱いに注力する必要があります。MQ メッセージの変更では、プロデューサー、コンシューマー、重複消費のリスクを確認します。ステートマシンの変更では、メインフロー、逆転フロー、例外ブランチの検証が不可欠です。知識ベースにこれらの検証ルールがなければ、AI は実行しやすい単体テストだけを実行し、「テスト通過」という結論を導き出しますが、その結論は実際のリスクをカバーしていない可能性が高いのです。

つまり、AI コーディングにおける知識ベースの役割は、単なる「答えを探す資料庫」ではなく、プロセス全体を貫くシステムコンテキストとして捉えるべきです。それは事実とマッピングを提供し、制約と検証基準を示します。AI が業務やシステムを理解するのを助けるだけでなく、実行時に境界線を越えないよう導くのです。

さらに重要なのは、知識ベースは一度きりの入力ではなく、継続的なクローズドループを形成すべきだという点です。技術ソリューションのレビューで見つかった抜け漏れ、コードレビューで指摘されたリスク、本番環境の問題で露呈した隠れた依存関係、過去の互換性対応による特殊な処理など、これらすべてが知識ベースへと逆方向に蓄積されるべきです。そうでなければ、知識ベースは「一見すると完全だが、実際には古くなった」ドキュメントになってしまいます。AI が最も恐れるのは、コンテキストがないことではなく、「誤ったコンテキスト」を与えられることです。

したがって、AI コーディングの観点からすれば、知識ベースの役割はプロセス全体に及んでいますが、その中で最も重要な増幅点は依然として「技術ソリューション設計」にあります。要件理解、現状分析、影響分析、コーディング実行、検証テストは、すべて最終的に「今回はどのように変更すべきか」という一つの問いに収束するからです。一度でも技術ソリューションが間違っていれば、その後のすべての効率的な実行は、効率的なやり直しへと転じてしまいます。

では、知識ベースを具体的にどう構築し、どのような目標を目指すべきなのでしょうか？

03 知識ベースの建設目標と階層化

3.1 建設目標

AI コーディングの全プロセスにおける「知識ベース（Knowledge Base）」構築の目標は、その核心的価値と影響範囲を踏まえて設定する必要があります。典型的なインターネットアーキテクチャの視点から評価すると、主に以下の指標が重要となります。

まず「内容の網羅性」です。技術設計や AI コーディングを行う際、知識ベースの内容が十分かどうかは極めて重要です。特に後端に数十ものマイクロサービスが存在する場合、知識ベースがシステム全体を正しく反映できているかが問われます。例えば、すでに緯度経度からユーザーの POI（地点情報）を取得できるマイクロサービスが存在しているのに、知識ベースにその情報が欠落していると、AI は同じ機能を持つ API をゼロから再設計・開発しようとしてしまいます。

次に「内容の正確性」です。AI 時代において、知識ベースの精度は飛躍的に向上しました。多くの知識が AI によって生成されており、人間の手作業による整理よりも効率的で正確になっています。しかし、「技術用語の定義が重複する」という課題は依然として残っています。例えば「注文（Order）」という概念一つをとっても、外食システムでは「ユーザーが作成した注文」も「配送担当者が受け取った配送依頼」もどちらも「注文」と呼ばれることがあります。これらは本質的に異なるエンティティですが、文脈によってどちらを指しているのか曖昧になりがちです。こうした誤解を招くシナリオへの対応や、コード変更時に知識ベースが即時に同期更新されるかどうかも、実装において特に注意すべき点です。

そして「検索の効率と品質」です。技術調査や設計段階では、複数のコードリポジトリから情報を引き出す必要があります。この際、検索精度はクエリの最適化や検索エンジン自体の性能に大きく依存します。大規模言語モデルのコンテキストウィンドウサイズが数百 KB、あるいは MB 単位であっても、実際には有効な注意（アテンション）が集中するのは最初の数十 KB に過ぎないことが多いためです。

つまり、知識ベースの構築はこれらの方向性に密接に連動して進める必要があります。

3.2 知識ベースの階層設計

調査とヒアリングを通じて、多くのチームが知識ベースの構築や、それを活用した技術設計において共通する課題を抱えていることがわかりました。

製品要件から技術実装への転換におけるボトルネック

製品の PRD（製品仕様書）は通常「ユーザーインターフェース」を起点に記述されます。しかし、UI から後端 API へ移行するには変換プロセスが必要です。「特定の画面リクエストがどの後端 API を呼び出し、その結果として画面のどの部分が描画されるのか」という知識が欠落していることが、「PRD から技術設計へ」移行する際の大きな障壁となっています。

多層・多システムにわたるシステムの事実と制約

大規模なインターネットプロジェクトでは、一つのユーザーリクエストが複数の後端マイクロサービスを横断し、各サービスで異なるロジックが処理されます。今回の要件において「どのレイヤーのどのマイクロサービスで実装すべきか」を決定するには、膨大なリンク知識やアーキテクチャ制約、システム制約に関する情報が必要です。

検索強化生成（RAG）の活用

大規模言語モデルの会話ウィンドウ（コンテキスト長）は有限です。すべての上流・下流システムの知識を一つのセッションに詰め込むことは不可能であり、「必要な時だけ読み込む」あるいは「最も関連性の高い文脈のみを読み込む」という仕組みが不可欠です。これが検索強化生成（RAG）が解決しようとしている課題であり、知識ベース構築において必須の機能の一つです。

単一システム内における知識の網羅性と抽象度

上記のような業務変換やリンク変換を経た後、実際のコーディング段階では、単一のマイクロサービス内の知識ベースの質がより重要になります。例えば、優れた知識ベースは、業界で標準的な DDD（ドメイン駆動設計）や「三色モデル」などの古典的アプローチに基づいてシステムコードを抽象化できます。これはコードの美しさだけでなく、アーキテクチャや制約、設計思想などを可視化する点でも AI コーディングを強力に支援します。

これらの課題と現状を踏まえ、私たちは知識ベースを以下のような 4 つの層に分割して設計・実践を行いました。

• ビジネス層
• アーキテクチャ層
• システム層
• インフラ層

青い背景枠で囲まれた部分は、投資対効果が高く、早期に導入して即効性を得られるモジュールです。

3.2.1 ビジネス層：AI に「なぜ変更するのか」「業務がどこに属するか」を教える

ビジネス層は、技術チームによって最も過小評価されやすい部分です。多くの人が AI コーディングについて議論する際、すぐにコードリポジトリや API ドキュメント、データベースのテーブルから話を始めがちですが、実際の開発プロセスはコードから始まるのではなく、業務課題から始まります。

ビジネス層には少なくとも 3 つの種類の知識が必要です。それは「业务知识（ビジネス知識）」「业务与架构映射（業務とアーキテクチャのマッピング）」「历史实践（過去の事例）」です。

ビジネス知識：これは「このシステムが実際に何の業務を支えているのか」を解決するものです。例えば、注文、決済、履行、特典管理、在庫、リスク管理、照合といった業務概念が何を意味するのか、その中核となるルールは何か、どのような状態遷移が正常なのか、どの操作が高リスクに分類されるのかを理解させる必要があります。AI がコードだけを見ていれば、「order_status」の列挙値をいくつ持っているかくらいは読み取れるかもしれませんが、「支払い済みだが履行されていない」という状態が業務上何を意味するのかまで理解できるとは限りません。また、なぜ特定の状態で直接遷移できないのかという理由も把握できていない可能性があります。

業務とアーキテクチャのマッピング：これは「業務概念が最終的にどのシステム、モジュール、API、テーブル、メッセージに紐づくか」を解決するものです。この部分は非常に重要であり、多くの知識ベースで欠落しがちな箇所です。「リフト体験の改善」というのは一見すると業務上の要望ですが、システムレベルで見ると、注文サービス、決済サービス、履行サービス、カスタマーサポートシステム、財務照合、通知メッセージ、リスク管理戦略など、リフトに関連する機能を持つシステムが多数関わってきます。リフト操作のビジネスフローを技術システムに落とし込んだ際、最初に呼び出される API は何か？同期 API とは何か？非同期 API とは何か？AI がこれらのマッピング関係を知らなければ、跨システムにまたがる要件を単一サービスの局所的な修正と誤判断してしまう恐れがあります。

過去の事例（歴史实践）：これは「過去になぜそう設計したのか」を解決するものです。例えばプラットフォーム型システムにおいて、新しいカスタム機能を追加する際、開発コードは常に似たような階層構造やモジュール構成になります。こうした過去の事例を蓄積し、AI の学習データとして提供することで、同様の問題に対して効率的な技術ソリューションを導き出し、そのリスクを低減できます。また、多くのバックエンドシステムには一見すると不格好に見える設計が残っているものです。不要なフィールドや、古いロジックとの互換性を保つためのコード、特殊なデフォルト処理、削除できない MQ コンシューマーのブランチなどです。新人エンジニアはこれを「汚い」と感じますが、AI は「リファクタリングすべきだ」と判断しがちです。しかし、これらには過去のインシデント、グレーディング（段階的リリース）での互換性維持、旧バージョンクライアントへの対応、下流システムとの依存関係、コンプライアンス要件、あるいは業務上の妥協といった背景が隠されています。

そのため、「業務とアーキテクチャのマッピング」と「過去の事例」はビジネス層の中でも特に重点的に扱うべきだと私は考えます。これらはコード内にも、自動生成されたドキュメント内にも、API 定義書の中にも存在しません。しかし、技術ソリューションの設計が正しいかどうかを直接左右する要素なのです。

3.2.2 アーキテクチャ層：AI に「システム間での連携方法」を教える

アーキテクチャ層は、システム間の役割分担、呼び出し関係、依存関係、そしてガバナンスの問題を解決するものです。具体的には、「アーキテクチャ・階層・リンケージの事実」「アーキテクチャ制約」「サービスガバナンス」を含みます。

アーキテクチャ・階層・リンケージの事実：これは「システムがどのように組織化されているか」を回答するものです。例えば、ある業務フローがゲートウェイから入った後、どのサービスを経由するのか、各サービスはどのような役割を担っているのか、コアとなるフローとサイドラインのフローはどこで分かれるのか、どのモジュールがドメイン層に属し、どのモジュールがアプリケーション層に属し、どのモジュールがアダプター層に過ぎないのか、また、どの API が同期呼び出しで、どのメッセージが非同期処理なのか、どのデータが強い一貫性を保ち、どのデータが最終的な一貫性で許容されるのか、といった情報を把握する必要があります。

技術設計において、アーキテクチャに関する知識や事実は極めて重要です。AI が単に現在のリポジトリのみを参照すると、「局所的な最適解」に陥るリスクがあります。具体的には、特定のサービス内では実装がスムーズでも、システム全体の連携としては不合理なケースです。

例えば、本来は注文サービスで処理すべきロジックを AI がゲートウェイ層へ移してしまったり、ドメインオブジェクトで保証すべきバリデーションを複数のコントローラーに散在させてしまったり、非同期の MQ による疎結合化が必要なのに、AI が新たな同期 RPC 呼び出しを追加したりする問題です。これらはコード能力の問題ではなく、アーキテクチャの文脈（コンテキスト）が不足していることに起因します。

「アーキテクチャ制約」は、「システム設計上、どのようにしてはいけないか」を定義するものです。例えば、コアな処理フローに新たな依存関係を追加することは禁止されたり、取引フローで不安定な外部サービスを導入してはならなかったりします。また、特定のインターフェースはアグリゲーションサービスからのみ呼び出せるように制限されたり、あるサービスが上位層へ逆方向の依存を持つことは許されません。データ同期もドメインイベントを通じて行うべきであり、跨データベースでの直接照会を避ける必要があります。

アーキテクチャ制約とコード規約は異なります。前者はシステム間の関係や依存の方向性を拘束するものです。

「サービスガバナンス」は、よりランタイム時および組織的なガバナンスに焦点を当てています。ここでは、サービスのレベル（SLA）、タイムアウト設定、リトライ戦略、サーキットブレーカーとフェイルオーバー、レート制限ルール、インターフェースの責任者、依存関係のオーナー、グレーデーション戦略、監視・アラートなどが含まれます。

これらの情報は、コードの実装方法に直接影響を与えるわけではありませんが、提案された方案が実際にリリース可能かどうか、リスクは管理できるか、問題発生時に迅速な特定が可能かなどを決定づけます。

技術選定の観点からは、システム間の関係を理解するアーキテクチャ層が必要です。サービスグラフや上下流の依存関係、インターフェース呼び出し、プロジェクトメタデータなどを活用し、「このサービスを変更すると誰に影響するか」「既存の機能で流用できるものはないか」「このインターフェースをどの上位サービスが利用しているか」といった問いに、AI とエンジニアが答えられるように支援します。

このような知識は、単一リポジトリに限定された一般的な CodeWiki が得意とする領域を超えています。マイクロサービスの生態系全体から関係性を捉える必要があるためです。

したがって、アーキテクチャ層の核心的な価値は、コードを説明することではなく、AI による影響分析とサービス探索（サービスマッピング）を支援することにあります。これは、技術設計の前半部分、すなわち「どのシステムを変更すべきか」「上下流にどのような影響があるか」「境界線をどこで引くべきか」という判断が妥当かどうかを決定づけるものです。

3.2.3 システム層：AI に「このサービス内部をどのように変更すれば安全か」を教える

システム層は、単一サービス内部における最も核心的な AI フレンドリーな知識層です。ここには「システム事実」「システム制約」「検証・テスト」が含まれます。

システム事実は、「このサービス内部に何があるのか」を解決するものです。具体的には、モジュールの分割、主要なドメインオブジェクト、主要な API、データベーステーブル、キャッシュキー、MQ トピック、定期タスク、コアフロー、状態機械（ステートマシン）、設定項目などが該当します。

これらの情報は、AI が単一リポジトリを理解する基礎となります。システム事実が欠如していれば、AI はコード内でその場しのぎの検索を行うことになり、「見つけた箇所を修正する」という断片的な判断しかできず、全体像を把握することが困難になります。

システム制約は、「このサービス内部で、何を安易に変更してはいけないか」を解決するものです。例えば、パブリック API のフィールド削除禁止、データベースフィールドの追加のみ許可（意味の変更禁止）、特定の状態遷移には必ず検証プロセスを経る必要があること、過去の互換性ロジックの削除禁止、大規模なリファクタリングが禁じられたモジュール、特定のディレクトリへのアクセスはアダプター層を介することのみ許可、書き込み操作における冪等性の保証などが含まれます。

システム制約は、AI によるコーディングにおいて最も重要かつ、最も欠落しやすい知識です。

過去の事例（ヒストリー）：単一システム内において、特定の類型の要件に対して過去にどのようなアプローチが採用されたかは、AI が技術設計を行う上で非常に大きな参考になります。事実面での意義は「ビジネス層」の歴史的事例と同じですが、適用範囲（スコープ）が異なります。

検証・テスト：これは、「どのように変更が正しかったことを証明するか」を解決するものです。多くの AI によるコード修正の問題点は、実行不能になることではなく、検証プロセスが脆弱である点にあります。

• 新規インターフェースには契約テストが必要か？
• データベースの変更にはマイグレーション検証が必要か？
• 状態機械の変更にはコアフローのユースケースを実行すべきか？
• MQ スキーマの変更には、プロデューサーとコンシューマーの互換性を検証すべきか？
• キャッシュロジックの変更には、キャッシュミス（パンク・ブラスト）や無効化戦略の検証が必要か？

これらを明確に定義しておく必要があります。そうでなければ、AI は単なるいくつかのユニットテストを実行しただけでタスク完了と誤認する可能性があります。

この層においては、CodeWiki と service-knowledge-generate の両方に価値がありますが、それぞれの側重点は異なります。

CodeWiki は、システム事実の生成と維持に特に適しています。プロジェクトの概要、モジュールの説明、API、データモデル、コアフローなどを低コストで自動的に整理し、人間と AI が素早くシステムを理解できるよう支援します。

システム制約や検証ルールを構造化するには、service-knowledge-generate がより適しています。これは単に AI に「このシステムが何であるか」を伝えるだけでなく、「特定のタスクに対してどの文脈を読み取る必要があるか」「どこを変更してはならないか」「完了後にどのように検証すべきか」といった指示も含まれます。つまり、CodeWiki の単純な代替ではなく、AI による実行段階における制約型知識ベースとして機能するものです。

そのため、図では「システム事実」と「システム制約」が重点的に強調されています。単一サービス内の AI フレンドリー化において最も重要なのは、すべてのコードを説明することではありません。「事実」「制約」「検証」の 3 つを適切に整理することです。AI はシステム事実を知ることで変更方法を理解し、制約を知ることで変更してはいけない範囲を知り、検証方法を知ることで変更が安全であることを証明できます。

3.2.4 インフラ層：AI に「基盤ルールとは何か」を教える

インフラ層は多くの記事で軽く触れられるに留まることが多いですが、バックエンドシステムにおいては非常に重要な役割を果たします。ここではミドルウェアの知識、コード規約、エンジニアリング規範などが含まれます。

ミドルウェアの知識：Redis や Kafka などの一般的なミドルウェアの基礎的な使用方法については、現在の大規模言語モデルがすでに内部化しているため、オープンソースや業界標準レベルの知識を知識ベースに追加する必要はあまりありません。ここで知識ベースに含めるべきなのは、チームやシステム固有の使用規約です。具体的には、データベース、Redis、Kafka、RocketMQ、Elasticsearch、設定管理センター、登録センター、タスクスケジューラー、オブジェクトストレージ、ログ監視などのインフラストラクチャをどう扱うかという点です。「Redis とは何か」「Kafka の使い方は」といった一般的な知識ではなく、「Redis のキー命名規則はどうするか」「キャッシュの有効期限はどのように設定するか」「キャッシュに空値を格納してもよいか」「MQ のトピック命名ルールは何か」「メッセージは冪等性を保証すべきか」「データベースのシャード化・パーティショニングのルールは何か」「大規模なフィールドは主テーブルに含めるべきか」「スロークエリの閾値はいくらか」といった、自チームや自システムでの運用ルールが対象となります。

コード規約：これは「コードをどのような構成で組織すべきか」を解決するものです。例えば、階層構造、命名規則、例外処理の方法、ログの記述方法、DTO/DO/Entity の境界線、依存注入の方式、トランザクションのスコープ、単体テストのディレクトリ構成、Mock の手法などが含まれます。これらの知識は地味に思えるかもしれませんが、AI が生成するコードがチームのスタイルに合致しているかどうかを直接決定づけます。この層での制約がない場合、AI は「機能としては動作するが、まるでこのチームが書いたようには見えない」コードを出力してしまいます。

エンジニアリング規範：内容はさらに広範で、依存関係管理、リリースプロセス、設定変更の扱い、グレーディング（段階的ロールアウト）の要件、セキュリティスキャン、監視ポイントの埋め込み、アラートルール、ロールバック戦略などが含まれます。これらは業務コードには直接現れないものの、コードが安全に本番環境へデプロイできるかどうかを決定づけます。この部分の構築については、企業の規模やソフトウェア開発の特性に応じて独自の適応基準を設定できます。大規模なインターネット企業は安定性と標準化への要求が高く、多少の反復効率の低下も許容できるため、規範に関する要件はより厳格で多くなります。一方、中小規模のインターネット企業では業務のイテレーション速度が最優先される傾向があり、安定性や標準化への要求が相対的に低くなるため、エンジニアリング規範に関する要件も少なくなる可能性があります。自社の状況と業務の複雑さに合った建設基準を選択すればよいのです。

インフラ層の価値は、AI に堅固なエンジニアリング基盤を提供することにあります。AI は単にビジネスロジックを記述すればそれで終わりではなく、生成したコードがチームのエンジニアリング習慣やミドルウェアの使用パターン、リリースおよび運用の要件に合致している必要があります。特に大規模なインターネットシステムでは、多くのオンライン上の問題がビジネスロジックそのものの誤りによるものではなく、タイムアウト、リトライ、キャッシュ、メッセージの冪等性、データベースのパフォーマンス、ログ監視といった基盤ルールの処理不足によって引き起こされています。

04

ソリューション調査

4.1 オントロジー（本体論）

知識ベースの構築方案を調査する際、まず業界で最も先端的な、あるいは AI 分野で先行している企業の事例を把握しました。

Palantir は Ontology（オントロジー／本体論）というアプローチを推奨しています。その概要は以下の図の通りです。

詳細については Palantir 公式サイトでのオントロジーに関する記述をご覧ください：https://www.palantir.com/docs/foundry/ontology/overview

注：此配图来自 Palantir 官网

「Ontology（本体）」这一概念并非新生事物，早在几十年前就已出现。它也不局限于软件工程领域，其核心用途在于对领域知识进行体系化的描述。在软件工程和 AI 领域，它指的是对特定领域的概念、属性及关系进行的“形式化、显式且可共享的规范说明”。这构成了构建知识图谱、实现机器推理与语义互操作的“语义骨架”；而在哲学中，本体论则是研究“存在本质”的分支学科。

核心定义与内涵

本质：共享概念模型的形式化规范说明（Formal explicit specification of a shared conceptualization）。

四大特征：概念化（抽象领域结构）、明确性（消除歧义）、形式化（机器可读）、共享性（群体共识）。

构成要素：类（Class）、属性（Property）、关系（Relation）、公理/约束（Axiom/Constraint）、实例（Instance）。

哲学与计算的区别：大写"Ontology"常指哲学的“本体论”；小写"ontology"在 IT 语境下则特指“知识本体”，更侧重于工程落地。

本体与知识图谱的关键区别

维度 | 本体 (Ontology) | 知识图谱 (Knowledge Graph)

---|---|---

层级 | 模式层 (Schema)，定规则的骨架 | 实例层 (Data)，存事实的血肉

内容 | 定义概念、关系、逻辑约束（不存具体业务数据） | 存储海量具体实体及其关系三元组

核心能力 | 语义消歧、逻辑推理、一致性校验 | 关联查询、路径分析、可视化检索

类比 | 建筑设计图/语法书 | 建成的大楼/词典例句

主要应用场景

• 语义网与数据集成：统一多源异构数据的标准，解决“同名异义”或“同义异名”的问题。
• AI 智能体与决策：为 LLM（大语言模型）提供可解释的业务逻辑框架，支撑从“概率猜测”到“确定性执行”的跨越（例如 Palantir Ontology 可直接连接业务系统并执行动作）。
• 知识工程：作为知识图谱的底层 Schema，指导数据抽取、清洗与推理规则的构建。
• 行业标准：用于自动驾驶（如 OpenX）、医疗、金融等领域的标准化描述与互操作。

主要定义

Ontology 常被描述为「企业数字孪生」，但这个说法过于宏大，也容易引起误解。更准确的理解是：Ontology 定义了一种协议，让系统能够以统一的方式暴露其业务对象、属性、关系、动作和权限。

它的核心要素可以拆分为以下四类。

一、Data（数据）：每个系统贡献自己的数据，并将其映射为 Ontology 中的对象、属性和链接。例如，“订单”是对象，订单金额、支付状态、创建时间是属性，而订单与用户、商家、履约单之间的关系则是链接。

二、Logic（逻辑）：业务规则、模型、算法和计算逻辑可以绑定到对象上。AI 不仅能看到“订单”这个对象，还能了解围绕该订单有哪些计算能力，例如风险评估、库存预测、履约优化等。

三、Action：将决策执行建模为原子化操作，支持模拟、审批和写回。这意味着 Ontology 不仅让 AI 读取系统，更让它知晓业务世界中“可以执行哪些动作”。

四、Security：权限并非事后打补丁，而是与对象、属性及动作紧密绑定。在不同人员、不同 Agent 或不同场景下，能够查看什么、修改什么、执行何种操作，都必须具备动态的权限控制能力。

Ontology 的本体思想十分经典：如果每个系统都按统一结构暴露自身能力，那么跨系统的发现、组合与编排，将从私有 API 适配问题转变为标准化建模问题。

传统 API 文档告诉 AI：“这个接口如何调用”。

而 Ontology 更进一步地告知 AI：“业务世界中存在哪些对象，对象间有何关联，允许对对象执行哪些动作，以及动作执行前需满足何种权限与约束。”这正是它与普通 Wiki 的最大区别。Wiki 侧重于解释系统，Ontology 则侧重于建模系统；Wiki 偏向阅读，而 Ontology 偏向行动。

4.2 KBase（Code Wiki）平台

KBase 是阿里集团内部的中心化代码知识 CodeWiki 平台。经调研，其核心能力在于：输入一个代码仓库，即可利用 AI 自动生成一份全面的 Markdown Wiki，并支持自定义生成时机与内容。

其运作流程大致如下：选择仓库和分支后触发生成，支持 monorepo 子目录；AI 分析代码后输出包含项目概览、模块划分、核心流程、API 说明及数据模型等内容的 Markdown 页面（即 LLM Wiki）；代码推送后可进行增量更新，若变动较大则降级为全量更新；通过 MCP 工具提供 AI 访问能力；同时支持 BM25 和语义向量两种搜索方式。

从存储形态来看，CodeWiki 通常部署于云端平台，与代码仓库解耦。它独立生成、独立更新、独立存储。采用 Markdown 自然语言格式，兼顾人机使用：人类可读，AI 亦可理解利用。

此类工具的现实价值巨大，尤其适用于新人入职培训（onboarding）、跨团队协作、陌生系统理解及快速概念定位等场景。

新人入职首日，若能查看到一份自动生成的系统概览，便无需完全依赖“找人询问”或“翻阅代码猜测”。在跨团队协作中，若需了解陌生服务，也不必先预约对方团队开会，只需搜索 CodeWiki 即可获取基本答案。若要查找某业务概念的具体实现位置，语义搜索的效率通常远高于手动 grep。

CodeWiki 的最大优势在于零成本接入与自动维护。对许多团队而言，只要拥有代码仓库的读取权限，即可生成一份基本可用的系统 Wiki。无需额外组织人力，也无需工程师专门维护文档。对于“希望让系统变得 AI Friendly，但暂无额外人力投入”的团队来说，这是非常务实的第一步。

然而从 AI Coding 的角度审视，CodeWiki 默认的生成策略也存在一些结构性限制。

一、自然语言解析：在 AI 执行过程中，其确定性不如结构化数据。当 AI 需要进行判断而非仅仅理解时，从 Markdown 文本中提取隐含约束的准确率，通常低于直接从 YAML 字段中读取。例如，“该接口不可修改字段语义”若写在 Markdown 中仅是一句话，而写入结构化策略（policy）则可转化为明确的规则。

1. クラウドストレージにおける整合性遅延のリスク

開発者が破壊的変更（breaking change）を直ちに反映させた場合でも、AI が更新ウィンドウ期間中に古い Wiki 情報を基に判断を下すと、問題が発生する可能性があります。通常の理解タスクでは深刻な影響は少ないかもしれませんが、コードの自動修正や生成案の作成においては、この遅延が AI コーディングの全工程を通じて評価される必要があります。もちろん、これはクラウド上のコード知識ベースが直面する現実的な課題の一つです。

1. ビジネスカスタマイズへの対応力不足

現状の分析によると、CodeWiki の核となるコンセプトは「コードこそが事実」にあります。そのためコードの事実性を尊重する設計となっている反面、柔軟な業務カスタマイズ機能には限界があります。

4.3 知識検索プラットフォーム

実際の調査では、複数のチームが独自に「知識検索エンジン」を構築するか、kbase を基盤とした RAG（検索拡張生成）能力を活用したローカルエージェントによる検索強化を進めていました。主な活用事例は以下の通りです。

1. 要件定義と調査：特に大規模なインターネット企業ではシステムアーキテクチャが複雑で、処理の深層も大きいため、「ある一つの要求が実際にどのシステムに関与しているのか」「既存の機能がどのシステムに既に備わっているのか」を把握する必要があります。例えば、配車アプリにおける「ドライバーが注文を受け付ける」という一連の流れにおいて、何層ものシステムやリスク管理（ファントム）を経由し、各レイヤーでどのような機能や戦略、あるいはブロック処理が行われているのかを理解することが重要です。また、新しい戦略を追加する際、どのシステムのどのレイヤーに実装するのが最適かといった判断にも役立ちます。新規採用者のシステム理解を深める上でも非常に価値があります。

1. 技術的設計と工数見積もり：要件調査と同様に、製品要求に対する技術設計や工数見積もりを行う際も、上下流のシステム、処理フロー、パフォーマンスなどの詳細な把握が必要です。ある要求が引き起こすシステム改修の範囲、それに伴うリスク、そして必要な工数を評価するためには、関連する各システムの事実情報をチェーン全体で把握しておくことが不可欠です。

1. 本番環境でのトラブルシューティング：前述の「後端システムにおける AI フレンドリーな設計」でも触れた通り、将来的に厳密な意味での 7x24 時間体制が求められる場面では、オンラインアラートの調査・分析・対応も AI が担うようになります。AI が処理や調査を行う際にも、ゲートウェイのエントリポイントから実際の API レベルのマイクロサービス、下流のドメインサービス、さらにはミドルウェアの応答時間（RT）に至るまで、システム全体を跨ぐ完全なチェーン知識が必要です。エージェントが具体的な問題分析や警告、介入処理を行うためには、包括的なシステムアーキテクチャの事実とランタイム環境の事実を前提としていなければなりません。

知識検索に必要なシステムチェーンやアーキテクチャの事実情報については、グループ内の Aone（CI/CD プラットフォーム）や監視アラートプラットフォームなどが MCP 機能を通じて対応可能です。さらに、「コードを Wiki として」「API を Wiki/SKILL として」「アーキテクチャを Wiki として」という知識体系を補完的に活用することで、明確なシステム現状の整理は比較的容易に実現できます。

より実用的なのは検索能力そのものをプラットフォーム化することです。実際、いくつかのチームが検索機能のカスタマイズに取り組んでおり、後述する aitom などがその一例です。

05

導入実践と選定基準

上記のような体系的な階層設計とソリューション調査を経て、次は各レイヤーにおける知識ベースの実装フェーズに入ります。

5.1 ビジネス層

前節の第 3 章で述べた業務層の主要な役割や設計思想については既にご説明済みです。では、実際の導入実践においては具体的にどのような姿になるのでしょうか？

ここでは参考として、当社の実装例をご紹介します。

業務知識ベースは単なる業務ドキュメントの集積であってはなりません。AI が製品要求やビジネスシナリオから技術チェーンへと変換を支援し、AI に業務メタ語彙を理解させ、ビジネス境界を認識させ、関連システムを特定させることを目指すべきです。さらに、技術設計のプロセスにおいて必要な過去の経験や設計上の制約も提供できる必要があります。

この目標を達成するため、各ビジネス（Business）の知識ベースは主に以下のセクションに分割されます：

ビジネス領域のドキュメント構造

├── index.md（ルート）

├── meta/

│ └── index.md

├── principle/

│ ├── index.md

│ ├── timeout.md

│ ├── idempotency.md

│ ├── consistency.md

│ ├── degradation.md

│ └── compatibility.md

├── scenario/

│ ├── index.md

│ └── scenario-*.md

├── practice/

│ ├── index.md

│ └── practice-*.md

└── history/

└── history-YYYYMMDD.md

ルートディレクトリの index.md は、全領域への入口兼インデックスとして機能します。ここでは全体の概要を説明し、関連コンテンツへの索引を提供します。

meta ディレクトリには、その分野におけるビジネスの元語（メタデータ）、中核となる業務オブジェクト、概念の境界線、そして重要な業務ルールが格納されます。例えば「注文」ドメインにおいて、「取引注文」「決済明細」「配送伝票」といった用語がそれぞれ何を指すのか、相互の関係性は何かを明確にする必要があります。また、日常会話では単に「注文」と呼ばれていても、技術設計の段階で混同してはならない概念についても区別を設けます。

ビジネス元語の数は通常多くないため、初期段階では meta/index.md 1 ファイルに集約して管理するのが現実的です。AI が正確に参照・検索できるよう、各元語には安定した名称または識別子を付与し、定義や別名、同義語ではない用語、業務の境界線、関連概念、そして中核ルールを明記します。ドメインが複雑化し、単一ファイルの容量が大きくなりすぎた段階で初めて、さらに細分化して分割することを検討してください。

principle ディレクトリには、特定のページや API 呼び出しチェーンに限定されず、その分野内で複数の業務シナリオに跨って再利用される中核的な設計原則が格納されます。これはアーキテクトがシステムを設計する際に長期的に堅持すべき重要な考慮事項を記述したものです。具体的には以下のような内容が含まれます。

• 全体的なタイムアウト予算の配分方法
• 複数システム間での整合性確保と補償戦略の選定基準
• どの処理パスでサービス低下（デグレード）を許容し、どこで確実に失敗させるべきか
• API、メッセージ、状態の意味をどのように保ちつつ後方互換性を維持するか
• コアとなる処理パスとバックスラッシュ（非コア）パスの境界線引き
• 状態の集約と表示における原則

例えば、注文一覧ページや注文詳細ページにおいて、商品画像やプロモーションタグなどの情報はサービス低下を許容できる一方、注文本体の情報はいかなる場合も低下させないコアデータです。もしこうした原則を各シナリオごとに個別に記述すると、記述の重複が生じるだけでなく、長期的なメンテナンスの中で内容が矛盾するリスクが高まります。そのため、これらを principle に抽象化して一元管理し、各シナリオ側で参照することで、ドメイン設計全体の一貫性を保つようにします。

ただし、principle ディレクトリに収めるのは「そのビジネス分野特有」かつ「複数シナリオで跨って再利用される」設計原則に限られます。データベース、Redis、メッセージキュー（MQ）、ログ管理、リリースフローなど、社やチームレベルの共通インフラに関する規範は、あくまで基盤層に蓄積すべきです。各ビジネス領域が重複して同じ知識を維持する必要はありません。

scenario ディレクトリは、業務シナリオと技術的な処理パスをつなぐ中核となるフォルダです。ここで扱う「シナリオ」とは、ユーザーや製品担当者、あるいは事業担当者の視点から定義されたものです。具体的には、注文一覧ページ、注文詳細ページ、返金詳細ページ、注文作成ページといった画面ベースのものもあれば、特定の画面に依存しない包括的な業務利用シーンも含まれます。

各シナリオのドキュメントでは、まずその業務目標、利用者、表示内容、そして業務の境界線を説明します。その後、シナリオ内の具体的な機能やユーザー操作へと分解していきます。例えば「注文一覧ページ」には以下のような要素が含まれる可能性があります。

• 注文リストの検索と表示
• 詳細ページへの遷移
• 注文の削除
• 再購入
• 返金申請

これらの各操作に対して、ドキュメントはさらに以下の点を記述する必要があります。

• 業務上の意味（セマンティクス）
• 実行前の前提条件
• クライアント側から送信される API の仕様
• ゲートウェイおよび集約サービスのエントリポイント
• 内部のドメインサービスが呼び出す処理チェーン
• 関与する外部システム
• データの変化内容
• 同期・非同期イベントの発生
• エラー、サービス低下、補償処置の方法
• 関連する meta、principle、および過去の実践事例

例えば、「注文削除」というボタンは製品画面では単なる操作ですが、ビジネスの文脈では注文データを物理的に削除するのではなく、現在のユーザーの注文リストから非表示にする意味を持つ場合があります。そのため、シナリオドキュメントには以下の点を明確に記述する必要があります。

• クライアントがどの API を呼び出すか
• 注文サービスが注文の所有権とステータスをどのように検証するか
• 返金や履行ステータスの照会が必要かどうか
• 最終的に修正するのは注文主テーブルなのか、それともユーザーと注文の表示関係なのか
• カスタマーサポート、精算処理、オフラインデータにおいてその注文を依然として参照できるか

このように整理することで、シナリオは製品画面やユーザー操作からバックエンドの実装に至るまでの変換ルートを構築します。

1. 製品ページまたはビジネスシーン
2. ページ機能とユーザー操作
3. ビジネス意味と事前条件
4. クライアント API
5. ゲートウェイまたは集約サービス
6. 内部ドメインサービス
7. 外部システム、データ、メッセージ

scenario/index.md はシナリオの入口およびルーティングインデックスとして機能します。シナリオ数が少ない（例えば 20 未満）場合や内容が軽量な場合は、複数のシナリオを単一のファイルにまとめて管理できます。一方、シナリオ数が増加した場合や、特定のシナリオで頻繁な更新が必要になったり、独立して参照されたり、明確なオーナーが存在する場合は、個別のファイルに分割し、index.md でその名称、ビジネスキーワード、主要機能、およびドキュメントへのリンクを管理します。

「20 個のシナリオ」という数字は厳密な区分け基準として捉えるべきではありません。これは単なる参考値であり、より重要な判断基準となるのはファイルサイズ、コンテンツの複雑さ、更新頻度、そして独立参照の必要性です。

practice は過去の設計と実践を記録するセクションです。ここで重要なのは「過去に何をしたか」だけでなく、「なぜそのようにしたのか」「どの経験が再利用可能か」「どのような失敗は二度と繰り返してはいけないか」という点にあります。

実践内容には以下のような要素が含まれます：

• 特定タイプの要件に対する標準的な改修パターン
• 重要なアーキテクチャやビジネス上の意思決定の経緯
• 過去の互換性設計
• 本番環境でのインシデントから明らかになった隠れた制約条件
• 特定の要件が影響を及ぼすシステム範囲の傾向
• ある解決策が適用可能・不可能となる条件

例えば、新しい注文ステータスを追加する際、過去の記録は AI に対して「注文サービスの状態マシンを変更するだけでなく、クライアント側の状態マッピング、カスタマーサポートシステム、メッセージコンシューマー、オフラインデータウェアハウス、精算ロジックも確認する必要がある」と警告します。実践知識の価値は単に古い解決策をコピーできることではなく、現在のシナリオにおいて過去のどのアプローチが依然として有効かを AI が判断できるように支援することにあります。

history は、知識ベース自体の生成と変更履歴を記録するためのセクションです。具体的には、「いつ」「誰が」「どのスキルを用いて」「どのような資料に基づいて」特定のファイルを生成または更新したか、誰が承認したか、現在未確認事項が残っていないかなどを記録します。

practice と history は明確に区別する必要があります：

• practice は将来の技術的解決策にも示唆を与えるビジネスおよびアーキテクチャ知識を担う
• history は知識ベース自体がいつ、誰によって、どのような方法で変更されたかを記録するのみである

history に保存すべきは具体的な知識そのものではなく、ログ情報です。

ファイル形式については、インデックス構造を持つ Markdown を採用しています。Markdown は製品担当者、ビジネス関係者、開発者、アーキテクチャのいずれにとっても親和性が高く、人的なレビューや継続的な修正が容易です。また、ファイルの先頭に YAML Front Matter を追加し、ドキュメント ID、タイプ、ドメイン、オーナー、ステータス、更新日時、関連するメタデータなどの構造化情報を記述します。

例：

id: scenario.order-list-page

type: business_scenario

domain: order

owner: order-domain-team

status: verified

related_meta:

• trade_order

related_principles:

• timeout
• degradation

updated_at: 2026-07-15

本文将继续以 Markdown 形式阐述业务背景、流程、调用链及设计考量。这种写法既保留了文档对人类的可读性，也为 AI 的检索、路由、过滤和按需加载提供了必要的结构化信息。

从整体架构来看，可以将上述目录理解为：

meta（元数据）

定义业务世界中存在哪些概念，以及这些概念的具体含义。

scenario（场景）

定义具体业务场景的运行逻辑，以及业务操作如何转化为技术链路。

practice（实践）

记录历史上类似问题的处理方式、决策原因及相关的经验教训。

principle（原则）

定义该领域跨场景需长期遵守的核心设计原则。

history（历史）

记录知识库自身的生成、审核与变更过程。

以上结构是我们结合业务层知识库建设实际提出的一种参考实践。其核心在于对业务知识、业务与架构的映射关系以及历史实践这三类内容的设计思考，但这并非要求所有团队强制遵守的标准。

各团队的业务复杂度、文档体系、系统架构及 AI Coding 工作流均不相同。有的团队可能更适合以页面场景来组织知识，有的则倾向于按用户旅程、业务流程或业务能力划分；有的团队会将 Markdown 文件存放在代码仓库中，而另一些团队则更适合作为集中式知识库管理。

因此，这里的目录结构、文件命名及拆分方式，更多是一种可落地、可讨论且可持续演进的实践示例。团队可直接参考，也可结合自身情况调整，并持续提出改进建议。真正重要的并非目录名称是否完全一致，而是业务层知识能否帮助 AI 准确回答以下问题：

• 需求中提到的业务概念具体指什么？
• 当前需求发生在哪个业务场景下？
• 页面功能和用户操作对应哪些后端 API 与系统链路？
• 技术方案需要遵守哪些跨场景的设计原则？
• 历史上类似问题是如何处理的，曾发生过哪些风险？
• 当前的知识是否经过确认，能否安全地作为 AI 的行动依据？

只要能够持续提升对这些问题的回答质量，业务层知识库的建设就产生了实际价值。

在平台化存储和检索能力的实现层面，我们目前使用 kbase 来承载。这主要是为了方便人工编辑、查看及干预。按照“分领域知识库”的维度进行组织和维护，例如将手车互联、驾车导航、停车推荐等关联度较低的场景分别维护各自的知识库。

5.2 架构层（aitom 平台）

这一层，我们采用的是 aitom 平台：https://aitom.amap-inc.com/

aitom 是高德出行后端团队面向 AI Native 时代打造的 AI 平台型基建。aitom 最关键的价值主要体现在三个方面（更多能力正在持续扩展中）：

一、服务能力的 Skill 化

将每个后端服务的对外接口包装为 AI 技能（Skill）。每个 Skill 包含一组相关 API、接入指南及质检文档。AI Agent 安装技能后，即可通过自然语言调用对应的服务能力。这与 Ontology“将能力结构化暴露”的思路一致，只是粒度更接近于后端服务和接口，而非完整的企业级业务对象体系。

二、服务间调用图谱

通过 aitom graph <项目名> 可以查看任何项目的上下游依赖关系：谁调用了你，你调用了谁，使用的是什么协议（HTTP 还是 HSF），具体是哪个接口，超时时间设定为多久。这一点至关重要。许多技术方案设计中最怕的并非不知道如何修改代码，而是无法预判修改后的影响范围。有了服务图谱，影响分析就不再完全依赖人工询问同事。

三、架构约束

这部分是我们正在