9月14日、Addy Osmaniが「Brownfield Agentic Engineering」と題した記事を公開した。長年運用されてきたレガシーコードベース（ブラウンフィールド）にAIエージェントを安全に導入するための実践的なアプローチについて詳しく論じている。
「エージェントに任せたら動いたが、設計が壊れていた」問題
AIエージェントをレガシーコードベースに投入する際の根本的な問題を、Addy Osmaniは冒頭でこう表現している。
エージェントを古いコードベースに監視なしで投入すると、「動く」けれど設計が間違っていて、テストも脆いものが生まれる
これはグリーンフィールド（新規開発）との本質的な違いだ。長年動き続けてきたシステムでは、リポジトリがシステムの実際の挙動を完全には表していない。制度的な知識、他チームが依存する暗黙の契約、ドキュメント化されていない制約——これらはコードの外に存在する。エージェントはそれを知らない。
コードベースをゾーニングする
この記事で最も実践的なフレームワークが「ゾーン」の概念だ。
- グリーンゾーン：テストカバレッジが充分、モダンな慣習、適切な分離。エージェントが自律的なタイトループ（人間の介入なしにフィードバックを受けて繰り返す作業サイクル）で作業できる
- イエローゾーン：テスト品質が混在、信頼性が不確か。キャラクタリゼーションテストを先に書いてからエージェントを動かす
- レッドゾーン：認証、課金、パーミッション、給与計算など。人間が全ステップでペアを組むか、作業しない
重要なルールが3つある。ゾーンの地図を描くのは人間であり、エージェントではない。エージェントに選ばせると、「最も面白い名前のファイル＝最も恐ろしいファイル」から手をつける。ゾーンのアップグレードは獲得制で、イエローがグリーンになるのはキャラクタリゼーションテストが揃い、モジュールのオーナーがレビューを終えた後だけだ。そしてゾーンが「動詞」を決める——グリーンはタイトループ、イエローはテスト先行、レッドは人間ペアか非実施。
「コードが語れないこと」だけを書く
エージェントへの指示をどう書くか、という観点でOsmaniは明確な方針を示す。
エージェントはリポジトリ自体から多くを読み取れる——モジュール構造、コールグラフ、命名パターン、テストの構成、型の制約、リンターの設定。これらをわざわざドキュメントに書く必要はない。
書くべきは、コードから読み取れないものだけだ。具体的には：
- ビジネスやチーム固有のニュアンス
- なぜそう設計されているかのトレードオフ
- 静的解析ツールが検出できないガイドライン
- ドメイン固有のルール
- 直感に反する実装の背景にある歴史的経緯
そして重要な原則：「エージェントへの自律性の付与は、ブラスト半径（ある変更が誤っていた場合に影響を受ける範囲）・オブザーバビリティ（システム内部の状態を外部から観測・追跡できる度合い）・復旧容易性に比例させるべきであり、モデルの確信度に従うべきではない」。
リサーチ結果をセッションを超えて残す
エージェントが認証フローの挙動を把握してタスクを完了しても、セッションが終わればその知識は消える。チャット履歴は特にコンテキスト圧縮後では信頼できるシステムオブレコードにならない。
Osmaniが推奨するのは、イエロー・レッドゾーンの作業前に「コンプリヘンションメモ」を作る専用パスだ。内容はエントリーポイント、オーナー、コールサイト、既存の抽象化、テスト、本番シグナル、関連履歴、未解決の疑問点——各クレームはファイル、Issue、オーナーシップ記録、ダッシュボードへの参照を添える。
フローはこうなる：リサーチ（編集なし、読み取り専用）→メモ作成（チャットの外に残る成果物）→クリーンなコンテキストで計画（人間がパスを選ぶ）→実装（地図が間違っていたら停止）→クリーンなコンテキストでレビュー（受け入れ基準から逆算）。
キャラクタリゼーションテストから始める
ゼロリスクな作業から始めることを、Osmaniは強く推奨する。最初にやることは「モノリットをRustで書き直す」ではなく、現在の挙動を説明し、ロックすることだ。
**キャラクタリゼーションテスト**とは、レガシーコードの現在の実際の挙動をドキュメント化する自動テストのこと（Michael Feathersの著書『レガシーコード改善ガイド』で広く知られた手法）。醜い部分も含めて現状をピン留めする——なぜなら古いシステムでは、その「醜い挙動」がビジネスの根幹を支えていることがあり、エージェントはそれをグリーンスイートのままで「修正」してしまうからだ。
NetflixがGraphQL移行で実践したのも同じ発想だ——新旧のパスにリクエストをリプレイ・シャドウして、ペイロードの差分が消えたときだけ昇格させた。
また、テストを書くセッションと、テストをパスさせるセッションは分けるべきだ。同じエージェントセッションが両方を担うと、実装を証明するだけのテストが生まれる。
作業の順序は：説明する（編集なし）→現挙動をピン留め→コードモッド・リネームなどの機械的変換→デッドコード棚卸し→難しい部分は最後。
ハーネスを育てる
「繰り返される修正は、ハーネスの欠けているピースだ」というOsmaniの指摘は実践的だ。同じレビューコメントが再び現れたなら、それはlintルール、型、テスト、またはスキルに変換すべきサインだ。
ハーネスとは、エージェントの動作環境全体——コンテキスト、ツール、パーミッション、テスト、ログ、リカバリ——を指す。デナイルールやスコープ付きクレデンシャル、CIチェックは記憶する必要がない。時間をかけてハーネスは、チームが二度払うことを決めなかった失敗の記録になっていく。
まとめ
Osmaniはブラウンフィールドへのエージェント導入を、AI以前のモダナイゼーション作業の延長線上に位置づけている。変わったのは変更を試みるコストが下がったことであり、記事ではその分だけ慎重さを仕組みとして埋め込む必要があると論じている。ゾーニング、コンプリヘンションメモ、キャラクタリゼーションテスト、ハーネスの整備——これらはいずれも、エージェントに任せる前に人間が整える構造的な土台だ。
詳細はBrownfield Agentic Engineeringを参照していただきたい。
