The Engineering of Intent 第3章:コンテキスト・モメンタムと経路依存

本記事は、私の著書The Engineering of Intent(英語版)を1章ずつ読み解くシリーズの第3回です。前回の記事では、物質的離脱──エージェントが書いているものに、エンジニアが意味のある形で関与しなくなってしまう静かな失敗モード──を見てきました。この章では焦点を人間からコードベースへと移します。なぜ初期の決定がこれほど長い影を落とすのか、そしてプロジェクトが成長しても舵を取れる状態をどう保つのか、です。


勢いはひとつの力です。エージェントはそれを増幅します。

どのプロジェクトも、成長するにつれて勢いがついていきます。まだ進むことのできる方向は狭まっていきます。これは昔からそうでしたが、AIエージェントはそれを増幅します──エージェントは既存のコードを読み、スタイルの面でも構造の面でもそれに似たコードを生み出すからです。良いパターンは広がります。悪いパターンも、同じ忠実さで広がります。

第3章は、その勢いの力学についての章です──初日にそれを正しく設定する方法、それがずれ始めたときに測る方法、そして書き直しをせずにそれを反転させる方法です。


最初のプロンプトの罠(First Prompt Trap)

新しいプロジェクトにおける最初の本格的なプロンプトは、不釣り合いなほど重要です。エージェントが最初に生み出したものが、その後に続くすべてのスタイル上の錨になります。最初のプロンプトが曖昧なら? 曖昧なコードが返ってきて、その後のすべてのプロンプトがその曖昧さを引き継ぎます。最初のプロンプトが正確なら──スタック、スタイル、ドメインの語彙、エラーハンドリングの哲学──その正確さは何か月にもわたって複利で効いてきます。

大半のエンジニアは、この重みを認識していません。「ユーザーを管理するREST APIをセットアップして」と打ち込み、返ってきたものをそのまま受け入れます。その返ってきたものが、その後の3か月を決めるのです。

💡 ポイント: うまく運営されているプロジェクトでは、最初のプロンプトのためのドキュメントが2〜3ページに及ぶことがよくあります。それで構いません。プロジェクト憲章と同じように扱ってください──フレームワーク、デプロイ先、テストの哲学、コーディング規約、アンチパターン。最初の1週間で元が取れます。

エントロピーとコンテキスト腐食

うまく運営されているプロジェクトでさえ、コンテキストは腐食します。1週目に下された決定は、8週目には見えなくなります。最初のプロンプトを見ていない新しいメンバーが加わります。会話が積み重なるにつれて、エージェントがプロジェクトについて持っている作業モデルはドリフトしていきます。物理学者が好んで言うように、エントロピーが勝つのです。

防御策は、優れたエンジニアリングチームが昔から使ってきたものと同じです──リポジトリの中に置かれ、コードと一緒にバージョン管理され、ツールが自動的に読み込むドキュメントです。今との違いは、そのドキュメントが人間のためだけのものではないということです。エージェントのためのものなのです。それこそが、AGENTS.mdをREADMEとは質的に異なるものにしています。READMEは売り込みです。AGENTS.mdは、エージェントがすべてのターンで従うことを求められる、拘束力のあるリファレンスです。

「考えうる最悪のコンテキストファイルとは、最初の月には正確だったが、その後ひそかにドリフトしてしまったものだ。エージェントはそれでもそれを読む。エージェントはそれでもそれに従う。そしてエージェントは、もはや存在しないバージョンのプロジェクトと整合したコードを生み出すのだ。」


ドリフトを測る

この章では、プロジェクトのドリフトを定量的に測る3つの指標を紹介しています。どれもまだ定番と呼べるものではありませんが、3つとも十分に役に立つので、今週から見始めるべきです。

  1. イディオムの分散(idiom variance)。表面的なスタイル上の特徴──インデント、命名規則、エラーハンドリングのパターン──の、ファイル間での標準偏差です。健全なプロジェクトはイディオムの分散が低く、ドリフトしているプロジェクトではイディオムの分散が上昇していきます。
  2. テストと振る舞いの結合度(test-to-behavior coupling)。振る舞いを変える差分と、テストを変える差分の比率です。比率が1に近ければ、振る舞いの変更のたびにテストの変更が伴っているということです。1を大きく上回っていれば、振る舞いがテストを追い越しているということであり──将来の障害の先行指標です。
  3. 不要な新規性(unnecessary novelty)。それに見合う外部からの必然性がないのに、エージェントが新しい依存関係、パターン、抽象を持ち込む頻度です。ある程度の新規性は必要です。けれども監督されないエージェントは、コードベースにすでにあるものを喜んで再発明します。そのコストを示すのはエンジニアの役目です。

規約は力場です。維持するにはエネルギーが要ります。

プロジェクトが採用するあらゆる規約は、エントロピーに逆らって引っ張っています。コードは発散したがります。新しいエンジニアは、お気に入りのパターンを持ち込みたがります。エージェントは、膨大な学習コーパスをもとに、広い世界で統計的に支配的なものを生み出したがります──そしてそれが、あなたのチームのスタイルと同じであることはめったにありません。

この力学を理解すると、投資の仕方が変わります。私の経験則はこうです。この章ではその根拠を詳しく述べています。

  • コードベースの上位5つの規約は積極的に強制すべきです──リンターでチェックし、CIで拒否し、レビューで指摘します。
  • 次の15個は、規約ファイルに受動的に文書化しておきます。
  • それより先は、規約がその場その場に特化しすぎている領域です。成文化するのではなく、変更ごとに議論すべきです。

50もの規約を積極的に強制しようとするプロジェクトは、いつまでも出荷できないか、ツールに費用をかけすぎてビジネスが傷つくかのどちらかです。ひとつも積極的に強制しないプロジェクトは、1年以内に混沌へとドリフトしていきます。

この章のケーススタディのひとつでは、シリーズCのスタートアップのプラットフォームチームが、2年分のドリフトを6か月で反転させた事例を取り上げています。やったことは、全社のあらゆるエージェントのセッションにひとつの規約ドキュメントを差し込み、上位5つの違反に対する小さなSemgrepのルールセットを追加したことだけでした。新規コミットの準拠率は、推定30%から94%に跳ね上がりました。総コストは、エンジニアリング能力のおよそ5%。代わりの案──CTOが当初望んでいた「大修正」計画──は、2四半期にわたってエンジニアリング能力の40%を費やし、しかもより悪い結果を生んでいたはずです。


規約は人間のためではなく、エージェントのために書く

私が目にする規約ドキュメントの大半は、人間のために書かれています。「読みやすさを優先する」「不必要な複雑さを避ける」といったことが書いてあります。こうした言葉はエージェントにとっては無意味です──正直に言えば、人間にとっても少しましな程度にしか意味がありません。

エージェントのための規約は、運用可能で具体的であるべきです。「読みやすさを優先する」ではなく、「40行を超える関数はリファクタリングしなければならない」。「不必要な複雑さを避ける」ではなく、「少なくとも3か所で使われるのでない限り、新しい抽象を導入しない」。「エラーを適切に扱う」ではなく、「外部呼び出しはResult型でラップする。内部のユーティリティ関数からは決して例外を投げない」。

ある規約を機械的なものにできないなら、それがそもそもドキュメントに載せるべきものなのかを考え直してください。センスに依存する規約は、文書化するのではなく、人間に訓練として身につけさせるべきものです。


すべての決定が同じ意思決定プロセスに値するわけではありません

初期の決定の中には、覆すのが安価なものもあります。変数の命名、ファイルの配置、テストフレームワーク──エージェントなら午後のうちに移行できます。一方で高くつくものもあります。データモデルの形、認証モデル、デプロイのトポロジー、トランザクショナルか結果整合性か──いったん決めてしまえば、これらはその後のあらゆる決定を形づくります。それを覆すのは何か月もかかる大仕事です。

AIネイティブの速度のもとでは、すべての決定を同じ速いリズムで下したくなるものです。これは間違いです。AIは安価な決定を加速します。高くつく決定を自動的に加速してくれるわけではありません。

⚠ 注意: この章の最後では、エージェントに勧められたという理由で、午後のうちにドキュメントストアを選んだアナリティクス企業を取り上げています。2年後、彼らはそれを回避するためにエンジニアリング能力の4分の1を費やしていました。彼らのデータは、実は深くリレーショナルなものだったのです。何を変えればよかったと思うかとCTOに尋ねると、彼は多くの創業者が振り返って口にすることを言いました。「あの決定に、あと1日かければよかった。」たった1日です。その1日が、2年を救っていたはずなのです。

私は個人的な経験則をひとつ持っていて、この章ではそれを詳しく説明しています──1万ドルルール(ten-thousand-dollar rule)です。2年後にこの決定を覆すのに1万ドルを超えるエンジニアリングの時間がかかるなら、決める前にいったん立ち止まります。10万ドルを超えるなら、立ち止まり、2人の同僚に相談し、一晩寝かせます。数字は恣意的なものです。けれども原則はそうではありません。すべての決定が同じ意思決定プロセスに値するわけではないのです。


次回 ── 第4章「Model Context Protocol(MCP)」 三者関係のうち人間の側(関与)とコードベースの側(規約)がそろったところで、第4章は本書の第II部:エージェントのエコシステムとインフラの幕開けとして、三者関係のエージェントの側──エージェントを現実世界のシステムにつなぐインフラ──へと目を向けます。MCPは、エージェント型開発をデモの小技から本格的な分野へと変えた標準です。


📖 さらに詳しく知りたい方へ

この章では、規約のドリフトの力学の全体像、18ページのCONVENTIONS.mdによってコードベースの一貫性を3年以上保ち続けているB2B SaaSスタートアップの事例、3つの演習からなるコンテキスト衛生監査、書き直しの誘惑を見極める診断(実際に正当化される提案は10件に1件だけ)、そして意思決定の厳密さを決定の重大さに合わせて調整するための1万ドルルールの全体を解説しています。

The Engineering of Intent をAmazonで購入する →(英語版)

2026-04-19

下田 昌平

開発に関するインプットをアウトプットしています。