kbits

ナレッジプライミング — AIコーディングアシスタントへの「オンボーディング」

原題: Knowledge Priming
著者: Martin Fowler
公開日: 2026年
ソースURL: https://martinfowler.com/articles/reduce-friction-ai/knowledge-priming.html
アーカイブ日: 2026-02-25

要約

問題：「フラストレーションループ」

AIコーディングアシスタントに文脈なしでコード生成を頼むと「フラストレーションループ」に陥る。コードを生成→コードベースに合わない→修正して再生成→繰り返し。

この摩擦の原因はAIの能力不足ではなく、文脈の欠如だ。

例：「UserServiceを作って」と頼むと、AIは以下のようなコードを生成しやすい：

構文的には正しいが、コードベースにとっては完全に間違っている。

解決策：ナレッジプライミング

「ナレッジプライミング」とは、AIにコード生成を依頼する前に、キュレーションされたプロジェクト固有の文脈を共有するプラクティス。新入社員のオンボーディングと同じ考え方だ。

AIの知識の階層

優先度 種類 内容
低（デフォルト） 学習データ 膨大なリポジトリやチュートリアルの平均値。しばしば古い
中 会話コンテキスト 現セッションで共有されたファイルや議論。長い会話では薄れる
高（最優先） プライミングドキュメント 明示的なプロジェクト固有の文脈。汎用的なデフォルトを上書きする

Transformerモデルはアテンション機構が有限の「予算」で動作する。コンテキストウィンドウをプロジェクト固有の高信号な情報で満たすと、それらのトークンがより大きなアテンションを集め、適切なパターンに向けて生成を誘導する。これは技術的にはマニュアルRAGと言える。

プライミングドキュメントの7つのセクション

著者は、人間の新入社員オンボーディングを模した7つのセクション構成を提案している：

  1. アーキテクチャ概要 — アプリケーション全体像と主要コンポーネントの関係
  2. テックスタックとバージョン — 使用技術とバージョン番号（APIは変わるため具体性が重要）
  3. キュレーションされた知識ソース — 公式ドキュメント、参考にしたブログ記事、内部ドキュメントへの参照
  4. プロジェクト構造 — ファイルの配置場所（ファイルの置き場所は重要）
  5. 命名規則 — ファイル名、関数名、型名などの統一規則
  6. コード例 — 「良いコード」の実例を2〜3個（説明だけでなく実物を見せる）
  7. アンチパターン — やってはいけないことのリスト（教訓を明示する）

ドキュメントは1〜3ページが目標。包括的な仕様書ではなく、AIへの「チートシート」。

習慣ではなくインフラとして

プライミングを最も強力にする方法は「毎回コピペする習慣」ではなく、リポジトリに保存されるインフラとして扱うことだ：

インフラとして扱うメリット：

よくある落とし穴

落とし穴 代替案
情報過多（20ページ超） 本質的な文脈のみ1〜3ページ
曖昧な記述（「モダンなベストプラクティス」） 具体的に（「Fastify 4.x、Prisma 5.x、関数型サービス」）
コード例なし 2〜3個の実コードスニペットを含める
古い内容 月次レビュー、または大きな変更のたびに更新
アンチパターンがない 避けるべきパターンを明示的にリスト化

ドキュメントを最新に保つ

ドキュメントは腐る。これを防ぐためのプラクティス：

論評

「AIにコードを書かせると、なぜか微妙にズレたコードが出てくる」という経験は多くの開発者が持っているが、本記事はその原因と解決策を明確に言語化している。AIは「インターネットの平均値」を生成するのが仕事であり、プロジェクト固有の文脈を与えなければ当然そうなる——という認識を整理するだけでも価値がある。

特に注目すべきは「習慣ではなくインフラ」という視点だ。毎回コンテキストをコピペする個人の習慣は維持できないが、リポジトリに保存してバージョン管理された仕組みならチームとして持続できる。新入社員のオンボーディング資料と同じ扱いをするべき、という発想の転換は実践的だ。

ドキュメントを1〜3ページに絞るという「情報の削ぎ落とし」の主張も重要で、包括的に書こうとすると却って効果が薄れるという逆説は意識しておく価値がある。

タグ: #ai #developer-experience #llm #documentation #engineering-practices