「AIにコードを書かせても、大きなコードベースでは結局うまくいかない」——この感覚を、モデルがもっと賢くなるまでの問題として片付けるのか、それとも今のモデルへの渡し方の問題として扱うのか。コンテキストエンジニアリングは後者の立場を取る考え方だ。GitHubの humanlayer/advanced-context-engineering-for-coding-agents（★1,977・2026年7月26日時点）は、その考え方をまとめた文書だけで構成されたリポジトリで、2025年8月の原典と2026年7月に追加された続報の2本が並んでいる。この記事では、その2本が何を主張し、10か月のあいだに何が変わったのかを読み解く。
- ・正体：LLMを状態のない関数とみなし、コンテキスト窓に何を入れるかを工程ごとに設計する考え方。原典はhumanlayer創業者のDex Horthy氏による文書2本。
- ・リポジトリの実体：Markdown 2本（27.8KB・49KB）＋補足1本＋図版36枚のみ。READMEもLICENSEもリリースも無い。動かすものではなく読むもの。
- ・中心となる型：「頻繁で意図的な圧縮（Frequent Intentional Compaction）」＝研究→計画→実装の3段で文脈を畳みながら進める。
- ・2026年の続報：同じ著者が「人間がコードを読まない運用は自分たちには機能しなかった」と振り返り、レビューを工程の前へ動かす4フェーズを提示している。
- ・注意：著者はこの領域で製品を売る立場にあることを文書冒頭で自ら明記している。数値の多くは自社事例か概念上の見積りであり、追試された計測ではない。
この記事はAIコーディングの方法論をひとつ深掘りしたものです。ツール選定や始め方を含む全体像は Vibe Codingとは？AIコーディングの始め方・ツール比較・実践ワークフロー2026 をご覧ください。
コンテキストエンジニアリングとは何か｜原典リポジトリの実体
まず、扱っている対象の実体をはっきりさせておく。humanlayer/advanced-context-engineering-for-coding-agents は2025年8月29日に作られたリポジトリで、GitHub API で確認できる範囲では次の状態にある。
・スター1,977・フォーク151・ウォッチ36（2026年7月26日時点）
・コミット履歴はdexhorthy氏の単独（26コミット）
・リリース0件・タグ0件
・LICENSEファイルなし（GitHubのライセンス判定も未設定）
・READMEなし——リポジトリのトップページに説明文が表示されない構造になっている
ルート直下にあるのは4つだけだ。ace-fca.md（27,797バイト）、wsff.md（49,067バイト）、side-quests/where-does-the-time-go.md（3,422バイト）、そして図版を収めた images/（PNG 36枚）。つまりこれはツールでもライブラリでもなく、方法論を読むためのリポジトリである。
LICENSEファイルが存在せず、GitHub上でもライセンスは未設定です。原文の長文引用・翻訳転載・自社ドキュメントへの取り込みには、明示的な許諾がない限り制約があると考えるのが安全です。本記事も要点の紹介と要約にとどめ、原文の逐語訳は行っていません。
2本の文書は何が違うのか
ace-fca.md は「Getting AI to Work in Complex Codebases」という題で、2025年8月にY Combinatorで行われた講演が下敷きになっている。wsff.md は「Why Software Factories Fail」（副題は「ハーネスエンジニアリングだけでは足りない」）で、リポジトリへ追加されたのは2026年7月22日。AI Engineer World’s Fair 2026の基調講演を土台にしたと本文に書かれている。
| 観点 | ace-fca.md（2025年8月） | wsff.md（2026年7月） |
|---|---|---|
| 中心の主張 | 今のモデルでも文脈設計で相当遠くまで行ける | 文脈設計だけでは保守性の劣化は止まらない |
| 提示する型 | 研究→計画→実装（頻繁で意図的な圧縮） | 製品要件→アーキテクチャ→プログラム設計→垂直スライス |
| 人間の役割 | 研究と計画をレビューする | 加えてコードも読む（lights-onへ戻す） |
| 根拠の置き方 | 自社事例とOSSへのPR実績 | モデルの学習・評価構造（RLとベンチマーク）の分析 |
| 速度の言い方 | 1日で1週間分を出荷した事例を紹介 | 「10〜100倍」ではなく「安全に2〜3倍」を提案 |
続報のほうが分量で1.8倍あり、内容も「なぜうまくいかないのか」の分析に踏み込んでいる。片方だけ読むと像を取り違えやすいので、この記事では2本を通した流れとして扱う。
① 何ができる：AIコーディングの成果が安定しない原因を、モデルの能力ではなく工程設計の問題として切り分けられる。② 何を解決する：大きな既存コードベースで「動くが読めないコード」が積み上がる状態。③ 何を代替できる：ツールの代替ではない。プロンプト集や設定ファイルの寄せ集めで進めていた運用を、工程の設計で置き換える。
コンテキストエンジニアリングの4つの軸｜正確性・完全性・サイズ・軌道
原典の出発点はシンプルだ。LLMは状態を持たない関数であり、モデル自体を訓練しない限り、出力の質を左右するのは入力の質だけである——という見方を、コーディングエージェントの使い方にそのまま当てはめる。Claude Codeのようなエージェントでも、1ターンは「コンテキスト窓を入れて次の一手を出す」関数呼び出しにすぎない、と原典は説明する。
だとすれば、手元にあるレバーはコンテキスト窓の中身しかない。Horthy氏はここを最適化すべき軸として4つ挙げている。
・正確性（Correctness）——入っている情報が正しいか
・完全性（Completeness）——必要な情報が欠けていないか
・サイズ（Size）——余計なもので膨れていないか
・軌道（Trajectory）——このまま進んで狙いの方向へ向かうか
そして裏返しに、コンテキスト窓に起きる最悪のことを悪い順に並べている。
この順序は実務的な示唆を含んでいる。トークン数を削ることに気を取られやすいが、原典の優先順位ではサイズの問題は最後だ。間違った前提が1つ入っているほうが、無駄なログが10個入っているより高くつく。
何がコンテキストを食い潰すのか
原典は、コンテキストを消費する典型として次を挙げる。ファイル探索、コードの流れの把握、編集の適用、テストとビルドのログ、ツールが返す巨大なJSON。いずれも作業に必要な行為でありながら、成果物としては残らない中間生成物である。
ここで重要なのは、圧縮が「要約機能を使うこと」ではない点だ。原典が挙げる素朴なやり方は、コンテキストが埋まってきた段階で「ここまでやったことを progress.md に書き出して。最終目標、取っている方針、済んだ手順、いま直面している失敗を必ず含めて」と指示し、新しいセッションで再開する、というものだった。これを著者は「意図的な圧縮（intentional compaction）」と呼ぶ。
サブエージェントの位置づけも同じ文脈で説明される。原典は、サブエージェントを役割のごっこ遊びとして使うのではなく、コンテキストの制御手段として捉える。探索と要約を別のコンテキスト窓に追い出せば、親エージェントの窓が検索履歴で曇らずに済む、という理屈だ。トークン消費そのものを削る発想については、context-mode徹底解説｜AIコーディングのトークン浪費を防ぐMCPサーバー【ツール出力98%圧縮】 が別のアプローチを扱っている。
意図的な圧縮（FCA）｜研究→計画→実装で文脈を畳む
原典の中心にあるのが「頻繁で意図的な圧縮（Frequent Intentional Compaction、FCA）」だ。定義は「開発ワークフロー全体をコンテキスト管理を軸に設計すること」であり、Horthy氏はコンテキスト使用率を40〜60%の範囲に保つことを目安として挙げている（問題の複雑さによる、とも添えている）。
具体的な進め方は3段構えになっている。
関係するファイル・情報の流れ
原因の候補を洗い出す"] B --> C{"研究結果は
納得できるか"} C -- いいえ --> B2["捨てて舵を切り直す
（steeringを足して再実行）"] B2 --> B C -- はい --> D["② 計画（Plan）
編集するファイルと手順
フェーズごとの検証方法を明記"] D --> E{"計画は
納得できるか"} E -- いいえ --> D E -- はい --> F["③ 実装（Implement）
フェーズ単位で進める"] F --> G["各フェーズの検証後
状況を計画ファイルへ畳み直す"] G --> H{"残りフェーズ
あり？"} H -- はい --> F H -- いいえ --> I["PR"]
原典はこの3段を唯一の型とはしていない。「調査を飛ばして計画から入ることもあるし、実装に入る前に圧縮した調査を何度か重ねることもある」と明記されており、実際の記述でも「3（くらいの）ステップ」という書き方をしている。
各段で使われるプロンプトは、著者の会社のリポジトリ humanlayer/humanlayer の .claude/commands/ 配下に置かれており、research_codebase.md / create_plan.md / implement_plan.md として公開されている。原典には「独自のサブエージェントを使う版と、汎用のTaskツールを使う版があり、汎用版でもほぼ同じくらい動く」と書かれている。
もう1つ、実務的に効く細部がある。git worktreeが必要なのは実装の段だけで、調査と計画はmainブランチのままで済ませている、という運用だ。並行作業のためにworktreeを常用している人には、切り分けの基準になる。
この型で何が出荷されたか
原典が挙げる検証事例は、いずれも公開されたPRに紐づいている。
・30万行規模のRust製プロジェクト BAML のバグ修正PRが、翌朝メンテナに承認された（PR #2259）。Horthy氏は自身をRustの素人と述べ、当該コードベースに触れたことも無かったと書いている
・数週間後、2人で7時間（調査・計画に3時間、実装に4時間）かけてキャンセル対応とWASMコンパイル対応を進めた。キャンセル対応のPR #2357 はマージ済み、WASM対応のPR #2330 は執筆時点で未マージと記されている
・一方で、parquet-javaからHadoop依存を外す試みは7時間かけてうまくいかなかったとも書かれている。原因は「調査が依存ツリーの奥まで潜れておらず、上流へクラスを移せると誤って仮定した」こと。著者はここから「少なくとも1人はそのコードベースの専門家が要る」という教訓を引いている
これらはいずれも著者本人による自己申告の事例で、第三者による追試ではありません。失敗例（parquet-java）も同じ文書内に併記されている点は誠実ですが、「同じ手順を踏めば同じ結果が出る」ことを示す計測データではない、という前提で読むのが妥当です。
レビューのレバレッジ｜研究1行の誤りが数千行になる
原典を通じて最も繰り返されるのが、人間の時間をどこに置くかという話だ。Horthy氏はこう整理する。悪いコード1行は、悪いコード1行でしかない。しかし計画の1行の誤りは数百行の悪いコードを生み、調査の1行の誤り——コードベースの仕組みや機能の在り処についての誤解——は数千行の悪いコードにつながる。
だから人間のレビューは、コードよりも計画へ、計画よりも調査へ寄せたほうがレバレッジが大きい——というのが原典の結論だ。これは「コードを読まなくていい」という話ではなく、「読む時間が有限なら、どこから読むかを選べ」という話として書かれている。
コードレビューは何のためにあるのか
ここで原典は、Blake Smith氏の整理を引いて「コードレビューの最も重要な役割はメンタルアラインメント——コードがどう変わり、なぜ変わったのかについてチームの認識を揃えること」という立場を取る。
Horthy氏が自チームで直面していたのは、数日おきに2,000行規模のGoのPRが飛んでくる状況だった。彼が挙げる最大の苦痛は、正しさや設計ではなく「自社プロダクトが何であり、どう動くのかの感覚を失いつつあった」ことだったという。
なお原典は「研究/計画/実装がほとんどのチームにとって正しい方法だとは主張しない」と明記したうえで、「①メンバーの認識が揃い、②不慣れな箇所を素早く学べる、engineering processは必要だ」と条件のほうを強調している。多くのチームにとってそれはPRと社内ドキュメントであり、著者のチームでは仕様と計画と調査になった、という書き方だ。大きなPRを人間がどう扱うかという論点は、本番環境でVibe Coding｜Anthropic研究者が語る2.2万行PR成功の実践戦略 でも別角度から扱われている。
2026年の続報｜「レビューを外す運用」が失敗した構造的な理由
ここからが wsff.md、つまり10か月後の続報だ。冒頭でHorthy氏は、自身がこの領域で製品を売る会社を経営しているためバイアスがありうる、と自ら断っている。そのうえで批判の矛先を向けるのは、他社ではなく2025年夏の自分自身の立場である。
続報が扱うのは「lights-off（消灯）ソフトウェアファクトリー」——人間がコードを読まず、テスト・サンドボックス・自動レビュー・監視・段階的ロールアウトへ投資を寄せる運用だ。この呼称はDan Shapiro氏によるもので、StrongDMの実装についてはSimon Willison氏が書いている、と続報は紹介している。
「2025年7月に完全なlights-offへ移行した。エージェントが解けないほど厄介な問題に必ず1つはぶつかる。読むのをやめて3か月経ったコードベースを掘り返すはめになり、その間サイトは落ち、ユーザーは怒っていた。11月に3度目が起きたとき、作り直したほうが早いと判断し、共同創業者が2週間かけて手作業でパターンを引き直した」——wsff.md の記述の要約。
なぜモデルは保守性を維持できないのか
続報の核心は、これがスキルの問題でもハーネスの問題でもなく、モデルの学習と評価の構造の問題だという主張にある。論の運びはこうだ。
まず、コーディングモデルの強化学習はおおまかに「①エージェントの試行を生成する→②検証器で採点する→③良い試行が出やすくなるよう重みを更新する」を膨大な回数繰り返すことで進む。問題はその採点軸にある、と続報は指摘する。
例として挙がるのが SWE-bench Multilingual だ。Redis・jq・Djangoなどのリポジトリから集めた、1件あたり15分程度の小さな課題で構成されており、報酬は次の2つで決まる。
・FAIL_TO_PASS——直せと言われたものを直したか
・PASS_TO_PASS——その過程で他を壊していないか
続報は fastlane の実課題（fastlane__fastlane-19304）を挙げて手順を具体的に説明している。モデルには修正前のコミットとバグ報告だけが渡され、正解パッチも採点用テストも見えない。生成されたパッチのうちテストファイルへの編集は捨てられる（失敗するテストをコメントアウトしたり、意味を失わせるモックを差し込んだ例が観測されているため）。その上でベンチマーク側のテストを適用し、通れば1、通らなければ0になる。
結果として現れる症状として、続報は「あらゆる箇所をtry/catchで包む」「型システムの利点を無効化するような雑なキャスト」を実際のコード画像つきで挙げている。
採点できないものは報酬にできない
続報はさらに、この問題が単なるベンチマーク設計の不備ではないと述べる。テストは数秒で合否が返るからこそ強化学習は何百万回も回せる。一方でまずい設計のコストは数週間・数か月・場合によっては数年かけて表面化する。誰かがそのファイルを1行直そうとして、1行では直せないと気づき、同じ修正を11か所に入れる羽目になった時点で初めて顕在化する——という説明だ。この症状はMartin Fowler氏が言う「shotgun surgery」にあたる、と続報は結びつけている。
インシデントが起きても、それを引き起こした数か月前の設計判断まで誤差を逆伝播させる方法が無い。だから報酬にできない。続報は「もしモデルが良いコードと悪いコードを取り違えずに見分けられるなら、最初から良いほうを書いていたのではないか」という言い方でこの点をまとめている。
前進の兆しとして続報が挙げるのは3つだ。SWE-Marathon（400時間規模の課題を単一の合否ではない複合報酬で採点）、DeepSWE（現実には作られなかった課題を使い、学習データへの混入を構造的に避ける）、Frontier Code（複数PRにまたがる課題。修正前コードで失敗しないテストを書いたら減点する仕組みと、差分に対する判定モデルによるコード品質ルールの評価を組み合わせる）。ただし「モデルに品質を判定させるやり方には限界がある」というのが著者の見立てである。
続報は Faros AI のレポートとして「レビューコメントが増え、レビューを経ずにマージされるPRが増え、インシデントとバグが増えた」という傾向を紹介しています。ただし著者自身が「決定的な証拠というより相関のシグナル」と注釈しており、本記事もその注釈込みで扱います。数値の詳細は原典と Faros AI のレポート本体をご確認ください。
なお、続報が否定しているのは「ループを回す設計」そのものではない。主張は「ループを増やしても保守性は買えない」という限定的なものだ。反復制御の設計論としてのループそのものは、ループエンジニアリングとは｜AIエージェントの反復制御を設計する5つの軸と主要OSS実装 が別の軸で扱っている。
灯りを戻す4フェーズ｜AIコーディングの工程をどう組み直すか
では続報は何を提案しているのか。結論は「今のところ判定者は人間なので、コードレビューを戻す」。ただし戻したうえで、レビューが重くならないよう合意を工程の前へ動かす。そのための4フェーズが提示される。
| フェーズ | 決めること | 成果物の形 |
|---|---|---|
| 製品要件レビュー | 解く課題（ユーザーの言葉で）と、出荷後に何を見て成功と判断するか | 短い文書＋画面のHTMLモック |
| システムアーキテクチャ | サービス・エンドポイント・スキーマ・キュー・ストアの関係 | シーケンス図、API契約、テーブル定義 |
| プログラム設計 | 型・メソッドシグネチャ・プログラム配置・呼び出し経路 | 呼び出し木、ファイル木の差分、型定義 |
| 垂直スライス | 機能を貫く薄い断面をどう刻むか | 実装順序の並べ替え |
過小評価されている「プログラム設計」
続報が最も紙幅を割くのがプログラム設計だ。アーキテクチャが正しければモデルは走れる、と多くの人が仮定するが、実際にはその1段下——コードの形を先に決めておくと結果が変わる、という主張である。
著者は、最初に作ったプログラム設計用の指示は読みづらく消耗するものだったと振り返り、Mermaidも試したうえで、実際に手応えがあったのは擬似コードによる軽い可視化だったと書いている。挙げられている形式は3つで、いずれも数分で書けて、レビュー時に暗黙のうちに下していた判断を前倒しできる点が利点とされる。
1つ目は、制御フローの変更を示す呼び出し木。変わる部分が本題のときは差分記法で書く。
entrypoint
runCommand
+ handleCreateResource
+ ResourceClient.create(input)
+ POST /resources
+ renderResult
- legacyCreateFlow
2つ目は、コードベースのどこに何が置かれるかを見失わないためのファイル木の差分。
src
└── resource
+ ├── resource-client.ts # NEW - API契約の呼び出しをラップ
+ ├── resource-client.test.ts # NEW - リクエスト/レスポンス変換を検証
~ └── resource-route.ts # MODIFIED - 作成アクションをUIへ接続
3つ目は、主要な新規関数の型とシグネチャ。アーキテクチャ文書に書くには内部的すぎるが、モデルが取り違えやすい部分がここに当たる、と説明されている。
水平ではなく垂直に刻む
4つ目のフェーズが「垂直スライス」だ。Basecampの Shape Up でいうトレーサーバレットに相当する、と続報は紹介している。
続報によれば、モデルは放っておくと水平な計画を好む。DBマイグレーション、サービス層、API、フロントエンドという、スタックの順に積む計画だ。この形の弱点は、完成するまで解決策に触れないこと。ブラウザで開くこともcurlで叩くこともできない状態が長く続く。
著者自身がAI以前に取っていた順序として挙げられているのは、API契約を作ってモックを返す→フロントエンドをモックで作り込む→サービス層へ配線する→マイグレーションを足して本物のDBへ繋ぐ→業務ロジック→エラー処理、という流れだ。各段で触って確かめる。そして「1〜3スライスずつモデルに投げ、進みながらコードを読む。100〜200行を確認して舵を切り直すほうがずっと安い」と続けている。
全部にこの工程を通すわけではない
重要な但し書きとして、続報は工程の適用率を示している。文言どおりに引くと「ざっくりの分布」として、約40%のタスクは一発、または1〜2回の軽いフィードバックで片付く。中規模なら製品と設計を1つの計画文書にまとめ、フェーズ分割はしない。大規模なときだけ全ステップを踏み、大きなリファクタリングのように意味が薄い場合は製品要件のフェーズを飛ばす。
この判断基準は補足文書「where does the time go」でもう少し踏み込んで説明される。2文のプロンプトを投げた場合の手戻り確率をおよそ50%、半日かけて詳細な仕様を手書きした場合をおよそ10%、全部を自分の手で書けば0%と置くと、前倒しの労力と「期待される痛み」のあいだには逓減の関係が現れる。著者が導く教訓は「最初の10分で8割の痛みが消えるタスクに、6時間の計画を費やすな」である。
同じ補足文書は、AI以前でも機能出荷にかかる時間のうちコードを書く時間は25〜50%に過ぎなかった、という前提も置いている。だからコードを書く部分だけAIで速くしても全体は縮まず、計画と合意にもAIを使って初めて2〜3倍に近づく、という組み立てだ。AIコーディングの習慣そのものを計測・改善する道具立てについては、Microsoft AI Engineer Coach完全解説：VS Code拡張でAIコーディング習慣を可視化・診断・改善する45ルール が具体例を扱っている。
まとめ｜コンテキストエンジニアリングは「今のモデル」を使い切る技術
2本を通して読むと、コンテキストエンジニアリングが何を指しているかは明確になる。モデルがもっと賢くなるのを待つのではなく、今のモデルに何をどう渡すかを工程として設計する取り組みだ。そのうえで、原典と続報の関係は「撤回」ではなく「範囲の確定」に近い。
・文脈設計は有効だが、それだけでは保守性の劣化は止まらない——止められない理由は、保守性に速い採点手段が無く、強化学習の報酬にできていないから
・したがって当面、品質の判定者は人間である。ただしコードレビューを重いまま戻すのではなく、製品要件・アーキテクチャ・プログラム設計・垂直スライスで合意を前倒しし、レビューを軽くする
・すべてのタスクにこの工程を通す必要はない。著者の見立てでは4割は一発で片付く。工程を通すかどうかの判断自体が設計である
・リポジトリの実体は文書2本と図版だけ。READMEもLICENSEも無く、動かすものではない
・コンテキスト窓の最適化軸は正確性・完全性・サイズ・軌道。最悪の順は誤情報→欠落→ノイズで、サイズ削減は最優先ではない
・人間の注意は上流（調査・計画）へ。1行の誤りの被害が桁で違うため
・2026年の続報は「人がコードを読まない運用」を著者自身の失敗として否定し、レビューを前倒しの設計で軽くする4フェーズを提示している
・提示される数値の多くは自社事例か概念上の見積り。方法論の骨格として読み、自分のコードベースで確かめる前提で扱うのが妥当
最後に、著者が締めくくりに置いている4項目をそのまま紹介しておく。制約をよく学ぶこと、その制約の中で仕組みを最適化すること、レバレッジを探すこと、そして——コードを読むこと。10〜100倍ではなく「安全に2〜3倍」という言い方を選んでいる点も含めて、この文書の温度感を示している。
参照ソース
・humanlayer/advanced-context-engineering-for-coding-agents（公式リポジトリ） — リポジトリ構成・スター数・ライセンス未設定の確認元
・ace-fca.md — Getting AI to Work in Complex Codebases — 4つの最適化軸、意図的な圧縮、研究/計画/実装、レバレッジの議論
・wsff.md — Why Software Factories Fail — lights-offの失敗、RLとベンチマークの構造、4フェーズ、著者自身のバイアス表明
・side-quests/where-does-the-time-go.md — 80/20と「期待される痛み」の見積り
・BoundaryML/baml PR #2259 — 原典が挙げる、承認されたバグ修正PRの実物
・SWE-agent論文（arXiv:2405.15793） — ツールの形状がエージェントの挙動を左右するという、続報が引く先行研究
