- 大規模な プロダクションコードベース で最新の言語モデルから成果を引き出すための コンテキストエンジニアリングの原則 と実務ワークフローを提示する記事
- 核心は Frequent Intentional Compaction であり、開発の全過程でコンテキストを構造化・圧縮して、エージェントの判断品質と進行 トラジェクトリ を安定化させる
- 研究→計画→実装の3段階で 事前調査の成果物と計画文書 を作成し、人間のレビューを高レバレッジな地点に配置して スロップ(slop) と手戻りを減らす
- 実際に Rust ベースの30万 LOCの BAML で バグ修正 や キャンセル/WASM 対応 などの複雑な課題を短期間で達成した事例を通じて、ブラウンフィールド環境 でも有効であることを示す
- 結論として、AIコーディングはおもちゃではなく 精緻なエンジニアリングの手仕事 であり、チーム単位の プロセス/文化の転換 が競争優位の鍵だと述べる
背景: 複雑なコードベースにおけるAIの限界と問題意識
- ほとんどの開発者は、AIコーディングツール が実際のプロダクションコードベースでは期待ほどにはうまく機能しないことをよく理解している
- AIコーディングツールが大規模コードベースや 複雑な課題 では生産性を下げるという研究結果がある
- Stanford の研究では、AIツールが追加するコードの かなりの部分が、以前にAIが生成した不十分なコードを再び手直しする形で 反復作業を招く とされる
- AIコーディングエージェントは新規プロジェクトや小規模な変更には効果的だが、大規模コードベースではむしろ開発者の生産性を下げる可能性がある
- そのため現場では「今は難しい、もっと賢いモデルが出てきたら」という慎重な姿勢が見られることが多い
- しかし実際に 300,000 LOC の大規模 Rust コードベースで コンテキストエンジニアリング を適用してみると、既存モデルだけでも生産性と品質の両方で市場水準を上回れた
- 核心は 頻繁な意図的圧縮(frequent intentional compaction) で、開発過程を通じてAIに与える文脈を構造化され管理された形にすること
- 結局のところ「AIコーディング」とは 技術的職人技 を要する領域だ
思想的基盤: “Specs are the new code” と生産性研究
- AI Engineer 2025 での2つの発表が思考様式の変化をもたらした
- Sean Grove の "Specs are the new code" では、「対話型プロンプトを捨てて 仕様をコードとして 保存せよ」と語られている
- プロンプトを捨てて生成コードだけをコミットする慣行は、ソースなしでバイナリだけをチェックイン することにたとえられる
- Stanford のAIが開発者生産性に与える影響の研究 は、AIが短期的な産出を増やしても 品質低下と手戻り により純効果が減少しうることを示唆する
- 10万人の開発者のコミット分析の結果、AIツールが手戻りの増加を招き、生産性向上の利益を相殺する現象が観察された
- グリーンフィールドでは効果的だが、ブラウンフィールド や 高難度の作業 では逆効果が頻発するという洞察を示す
原則: Frequent Intentional Compaction の概念
- コンテキストウィンドウを 常に40–60% 程度に管理し、内容過多・欠落・誤情報を最小化する 継続的圧縮戦略 を採用する
- 圧縮対象は ファイル検索ログ、コードフロー追跡、修正履歴、テスト/ビルドログ、大きな JSON などのノイズ
- 各段階の成果物を 構造化アーティファクト として残し、次のターンの入力品質を保証する
- 例: 進捗サマリー、目標とアプローチ、完了した段階、現在の失敗箇所 を記録した progress 文書を作成する
ワークフロー: Research → Plan → Implement
- Research 段階では関連ファイル・フロー・原因仮説を調査し、要約リサーチ文書 を成果物として作る
- 必要に応じて サブエージェント により、新鮮なコンテキストでスコープ探索と要約を行う
- Plan 段階では、修正対象ファイル、変更方法、検証・テスト手順 を詳細に記述した 実装計画 を作成する
- 計画はコードレビューよりも 高レバレッジなレビュー の地点として活用される
- Implement 段階では計画を段階的に実行し、各段階の検証後に 計画文書へ状態を再圧縮 して蓄積する
- 複雑な作業では段階ごとの合流時に コンテキストの再整列 を行う
アンチパターンと漸進的高度化
- ナイーブなアプローチ では、チャット型フローでコンテキストが汚染され、謝罪ループや脱線につながる問題が露呈する
- 少し良い方法として セッション初期化 と「追加指示プロンプト」があるが、根本的なノイズ制御 が不十分
- 意図的圧縮 は、進捗サマリー（ファイル）と コミットメッセージ を使って文脈を再構成する、より良い方法である
- 理想的な圧縮成果物フォーマットの例を示し、正確性/完全性/サイズ/トラジェクトリ の最適化を目標に据える
コンテキスト最適化の技術的観点
- LLM は ステートレス関数 なので、品質は完全に 入力コンテキスト に左右される
- 最悪の状況の順序は 誤情報 > 欠落 > ノイズ過多 である
- コンテキストは小さいほど有利なため、最小入力 で 最大の整合性 を得る圧縮が重要となる
- 単純なループ型 エージェント実行戦略（例: 「Ralph」プロセス）など、別の見方にも言及されている
サブエージェントの役割: 人間のロールプレイではなくコンテキスト制御
- サブエージェントは 探索/要約/整理 を独立したコンテキストで行い、主エージェント のウィンドウをクリーンに保つ
- 理想的な応答は 目標/現状/経路 が構造化された圧縮成果物の形で返される
- サブエージェントによって 探索コスト を局所化し、本来の作業コンテキストの 集中度 を高める
事例1: BAML のバグ修正が一発で通る
- Rust 30万 LOC の BAML で、初参入者が バグ修正 PR を数時間で提出・承認された事例を示す
- リサーチ文書 を何度も回して品質を高め、最終的には計画ベースの実装で 初回通過 を達成した
- ブラウンフィールド適合性、スロップ除去、整列維持 という目標の多くを満たしている
事例2: BAML にキャンセル/WASM 対応 35k LOC
- 2人が 7時間 で キャンセル機能 と WASM コンパイル 対応を追加する大規模変更を実演した
- チーム見積もりでは各3–5日分の作業を リサーチ/計画/実装 パイプラインで短縮した
- 一部の PR は即時マージされ、一部は 動作デモ 水準のまま公開を維持しつつ、高難度課題の解決可能性 を証明した
限界と失敗からの学び
- Parquet Java で Hadoop 依存の除去 を試みた件は、依存ツリーの掘り下げ不足により失敗事例として残った
- 結論: すべての問題が 7時間のプロンプティング で解けるわけではなく、ドメイン専門家 の参加が必要である
- 人間レビューのレバレッジ は research > plan > code の順に大きくなり、誤った調査結果の1行が 数千行の誤り に拡大する危険がある
チームの整列のための文書第一主義
- コードレビューの本質は メンタルアラインメント(mental alignment) の維持にあるという観点を示す
- 大規模 PR の連鎖はチームの プロダクト理解の喪失 と不安を招くため、仕様/計画/リサーチ により整列コストを下げる
- エンジニアは 2000行のコードより 200行の計画文書 を、より頻繁に・より正確に読める
- 不慣れな領域の課題対応でも リサーチプロンプト が素早いガイドの役割を果たす
総まとめとコスト構造
- 目標をすべて満たしている: ブラウンフィールド互換、複雑問題の解決、スロップ最小化、チーム整列の維持 を達成している
- 運用コストの観点では、3人のチームが Opus のトークン費用として月約 $12k 規模で運用している
- 例外はあるものの、全体として 機能する方法論 として定着しつつあることを強調する
今後の変化と製品化
- コーディングエージェントは コモディティ化 していき、組織とワークフローの変革 が真の難題になる
- AI がコードの99%を書く世界では、協業の方法の全面改編 が競争力の分岐点になる
- これを支援するため、CodeLayer という「ポスト IDE」ツールを プライベートベータ として公開した
- Superhuman for Claude Code を志向し、スペックファースト のエージェント型開発を加速する
3件のコメント
広告エンディング...
CodeLayerというサービスの紹介で締めくくり…
Hacker Newsの意見
興味深い読み物で、新鮮なアイデアもあった。ただ、こうした主張には問題があると思う。Seanは、AIが進化すれば今後は仕様書が本当のコードになると予測していた。今後2年以内に、人々がIDEでPythonファイルを確認する頻度は、今日人がアセンブリを見るためにhex editorを開く頻度と同じくらいになる、という主張だ。自分も最初は不快だったが、PRのコードをいちいち読む代わりにテストへ集中し、仕様を本当のソースとみなすやり方を受け入れるようになったという。しかしLLMの非決定性の問題により、どれだけプロンプトを工夫しても、常に合理的な実装が得られるとは期待できない。コンパイラは決定的で、バグがあっても再現・デバッグできるが、LLMはそうではない
ジュニア開発者と作業するときでさえ、実装はある程度決定的だ。だがAIモデルでは、明確に指示してもまったく異なる実装が繰り返し出てくる
面白いのは、実は仕様書そのものもすでに非決定的だという点だ。誰にも誤解されないようrequirementsを英語で書こうとすると、結局はプログラミング言語になってしまう
「プロンプトが完璧でも、LLMがそれを合理的な実装に変えてくれる保証すらない」という懸念には同意する。むしろ自然言語で書かれたプロンプトは、本質的に曖昧で不完全なことが多い。だから創造的な結果が必要な場面では良い方向性だが、ソフトウェア要件定義に自然言語が適しているのなら、ソフトウェア工学は何十年も前に解決していたはずだ。LLMには熱狂したが、これであらゆる問題を解決しようとするのは無理があると思う。要件定義という点では、昔の形式体系や数学的検証の試みに似ているが、その正反対にある感じだ。これも部分的な失敗に終わるとしても、ソフトウェア開発に新しい洞察を与える実験だと思う。あるドメインでは本当に価値が生まれ、別の場所では完全に捨てられるかもしれない。興味深い時代だ
そもそも人は明確で詳細な技術仕様や文書を書くのがほとんど得意ではない。仮にあったとしても、それが2年以内に一般化するとも思えない。ソフトウェア工学を本当に深く理解している技術文書ライターが、実際のコードを見ずにAIエージェントへプロンプトを与えるだけで満足するだろうか。私はそうは思わない。典型的な「エンジニアが人を機械のように扱う」発想に近い
「コンパイラのおかげで、ビルドのたびにhex editorでアセンブリを見る必要がない」という主張も、もちろんツールが良くなったおかげではあるが、実際にはHPCの科学研究分野では、コンパイラが重要なループを正しくベクトル化したか確認するために、Intel VTuneなどでアセンブリを直接精査することが多かった
2つの異なるコードベースでこのパターンを使ってみた。ひとつは50万行規模のapache airflowの大規模モノリシックrepoで、もうひとつはflutterでゼロから作る個人のサイドプロジェクトだった。flutterとdartは本当に未知の分野だった。それでもこの方法は有効だと感じた。グリーンフィールドのプロジェクトでは、ほぼ /create_plan だけ回せばよく、エージェントのあらゆる支援を活用できた。重要なのは、AIが出してくる文書を丁寧にレビューすることだ。自分が見落としている、あるいは気にしているエッジケースを扱っているか、技術選定が妥当かを自分で確認すればいい。たとえばsqliteのパターンを破ってpostgresを勧めるような誤った意思決定があれば、すぐに分かる。たいていはエージェントと直接チャットしながら、その場でプランを修正できる。会社ではgithub copilotを使わなければならないので、プロンプトは少し変える必要があったが、段階間の意図的な要約(compaction)は今でもしている。copilotはclaude codeのようにサブエージェントをサポートしていないが、それでも生産性は保てている。
個人的な体験もひとつ共有したい。AIコーディング支援の時代の直前、仕事があまりにも退屈になっていると感じて、かなり落ち込んでいた。複数のrepoやチーム、人の性格などのせいで、大規模コードベースでの作業はいつも雑務だらけだった。AIコーディングの一番良かった点は、こうした細かな作業をなめらかに処理してくれることだった。私は何かがうまく動くものを作ることに大きなやりがいを感じるのだが、何度もこうした雑事に阻まれてその喜びが失われていた。今では継続して良い結果を出せているし、自分でも誇らしく思える
私は大規模コードベースで作業するときに使うパッケージを作った [GitHub.com/iambateman/speedrun]。まず /feature で機能説明を入力すると、コードベースの分析が始まり、質問を投げてくる。私が答えると、計画をmarkdown形式で書いてくれる。この過程で8〜10個のmarkdownファイルができ、何をするかとサンプルコードまで含まれている。次は「code critic」段階で、エラーを見つけようとするが、実際には60%は間違っている。私はこのフィードバックから的外れなエラーを取り除く。このあたりまで来ると、自分が望む変更点と機能説明が入ったきれいなフォルダが完成する。あとはClaude Codeに「進めて」と言うだけで、段階ごとに作業が始まる。このやり方のおかげで方向性がずれるのを防ぎ、成果物に確信を持てる。こうしたワークフローを日に何度も大きな作業に使い、比較的具体的な作業には普通のClaude codeだけを使っている。かなり効率的なワークフローだと思う
なぜこんな複雑な手順を踏みたがるのか、私にはまったく理解できない。LLMを少し参考にする程度の普通のコーディングのほうが、この方式より生産的だと思う
LLMを大規模コードベースに使う際の大きな問題は、同じミスを繰り返す点だ。各作業ごとにアーキテクチャ上の判断をどうやって文脈の中で継続的に追跡しているのか気になる
本当に素晴らしく見える。途中に疑似コード(pseudo code)の段階があるが、実際に事前にワークフローやプロセス定義を行うことが役立ったのか気になる。また、各ファイルを100行以内に保つのが重要だという話も聞いたことがあるが、本人も同じように感じたか気になる
この記事は、まるで自分がClaude codeで文脈(context)管理を完全にあきらめた瞬間をタイムカプセル化したように感じる。私はコードの各部分ごとにフォルダで仕様を分け、機能別ログを入れていた。PythonでAPIサーバの複数サブシステム（アカウント、通知、サブスクリプションなど）を管理していた。状況が複雑になるにつれ、Claudeはビジネスロジックを正しく把握できなくなり、文脈管理が極端に難しくなった。たとえば簡単なRBACシステムを作ろうとするとき、アカウントとプロフィールの関係を説明するUMLダイアグラムや例まで与えて、ようやく期待どおりに動く程度だった
AI活用についてはさまざまな宣言や主張があふれているが、実際に具体的なプロセスやプロンプトを公開する例はない。口先でそれらしく語るのは簡単で、本当に有用であるためにはプロンプトログが残されていなければならない。AIが生成したコミットには、どのプロンプトが適用されたかというログも含まれていて、コミットログを追うようにプロンプトログもたどりながらコード作成の過程を知れるべきだ
筆者は35K行のコードを7時間で調査・実装したと自慢している一方で、実際には7日間で40件のコミットが残っているらしい。1日1時間ずつやったのかと疑いたくなる。そして最新コミットのひとつが「テストの一部を無視」なのも笑える
「数週間後、@hellovai と一緒にBAMLへ35k LOCを追加し、キャンセル対応やWASMコンパイルなどの新機能を導入した。既存チームでは各機能に3〜5日かかると予測していた」という文があったが、それはシニアエンジニアが1日に4〜6KLOCずつ書くと思っていたということか？（genAI以前に？）
ここで欠けている事実は、シニアエンジニアなら実際には2KLOCで解決していただろうという点だ
しかも筆者自身も別の場所で、この作業が実際には1週間かかったと認めている https://news.ycombinator.com/item?id=45351546
「最初は不快だったが、PRのすべてのコードを読むのをやめて、テストだけを丁寧に確認するようになった。仕様が本当のソースになった」という部分には全面的に同意する。私たちの役割は、実装の詳細を自分で書くことではなく、動作を定義し検証する側へ移っていくと感じる。最近では、S3-to-SFTPのPython operatorに再帰アップロードを追加する必要があったが、複雑なパスフラグが多かった。私のプロセスはこうだった。1) 既存の動作を明確な仕様として抽出する（つまり、単体テストを通す形で） 2) 新機能に合わせて仕様を拡張する 3) 問題とテストをコーディングエージェントに渡す。結局、古いコードをまったく理解する必要はないと気づいた。自分の焦点は、新しいコードが仕様に正しく従っているかどうかだけだった。今後の未来では、正しさを検証することに私たちの価値があり、実際のコードはエージェントが処理する細部になるだろう
「私たちの役割が実装の詳細を書くことから、動作の定義と検証へ移る」という点には同意する。実際、それこそが主な仕事ではなかったかとも思う。高級言語やコンパイラ、その他の抽象化のおかげで、実装の詳細を書く時間は着実に減っている
「自分のフォーカスは新しいコードが仕様どおりに動作するかどうか」という点で、Postelの法則(Postel's Law)を思い出した。広く使われるシステムでは、観測された動作が事実上そのシステムの公開インターフェースと仕様になり、そこにはあらゆる誤りや実装バグまで含まれてしまう。コードのクライアント側が仕様を本当に守っているかをテストし、もし乖離があればそれを検知して処理する必要もある
Claude Plays Pokemon も同じ点を示していた。AIは（何かがうまく動いているかを）判断するのが苦手だ。むしろ同じところをぐるぐる回り続ける。だが、人間が途中で方向を修正してやれば、強力な組み合わせになりうる
実際に動作のあらゆる側面を定義しようとするなら、結局ほとんどコードを書いているのと同じだ。PRの中のある1行の意味すらすぐ理解できないなら、おそらく全体の動作を十分には定義できていない
「今後数年で仕様書が実際のコードになり、Pythonファイルを開いて見ることはほとんどなくなる」という主張があった。これが実現するには、AIコード生成が99.9%正確で、hallucinationもほぼない必要がある。私たちがコンパイラを信じてアセンブリコードを見ないのは、結果が常に同一でエラーがないと確信しているからだ（まれにバグや最適化の問題はあるが、ほぼ一度で修正される）。現時点では、AIが生成したコードが仕様（つまり元のコード）と異なる動作をしたら、結局は人間が修正しなければならない
実装を細分化して作業単位ごとに処理・レビューするという助言は非常に印象的だった。