Building AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned

本論文は、IDE プラグインからターミナルネイティブな AI エージェントへとパラダイムが移行する中で、安全性とコンテキスト管理の課題を解決し、自律的なソフトウェア開発を実現するためのオープンソース CLI エージェント「OPENDEV」のアーキテクチャと設計原則を提案するものである。

要約

論文『OPENDEV』の解説：ターミナルで働く「AI 助手」の仕組み

この論文は、**「OPENDEV（オープンデブ）」**という新しい AI プログラミング助手について書かれています。

これまでの AI 助手（GitHub Copilot など）は、主に「コードを書く場所（IDE）」に埋め込まれていて、人間が指示を出さないと動かない「受け身」の存在でした。しかし、OPENDEV は**「ターミナル（黒い画面に文字が出る場所）」そのもので動き、人間に代わってファイルを探したり、コードを書き換えたり、テストを実行したりする「自律的なエージェント（自律型 AI）」**です。

まるで、**「優秀な新人エンジニアを雇って、彼に『このプロジェクトを直して』と任せる」**ようなイメージです。

この論文では、そんな AI を安全に、長く、賢く動かすために、どんな工夫（技術）がなされているかが語られています。以下に、難しい専門用語を使わず、身近な例え話で解説します。

---

1. 核心となるアイデア：「一人の天才」ではなく「チームの連携」

多くの AI は「一つの巨大な脳みそ（モデル）」で全てを処理しようとしますが、OPENDEV は**「 compound AI system（複合 AI システム）」**という考え方を取り入れています。

• 例え話：
  一人の天才が全てを解決しようとするのではなく、**「プロジェクトマネージャー」「設計士」「職人」「検査員」**など、役割ごとに分かれた小さなチームを組ませています。
  • 計画（Planner）： 何をするか考える（書き込みは禁止）。
  • 探索（Code Explorer）： 既存のコードを調べる（書き込みは禁止）。
  • 実行（Main Agent）： 実際にファイルを書き換える。
  • 批評家（Critic）： 考え方がおかしくないかチェックする。

それぞれに「得意な AI モデル」を使い分けています。単純な作業には安くて速い AI を、複雑な推理には高機能な AI を使うことで、コストと品質のバランスを完璧に調整しています。

2. 最大の課題：「記憶力（コンテキスト）の限界」とその解決策

AI は一度に扱える情報量（コンテキスト）に限りがあります。長い作業をしていると、過去の情報が溢れてしまい、「最初の話」を忘れてしまいます。これを**「記憶の枯渇」**と呼びます。

OPENDEV はこれを**「適応型コンテキスト圧縮（Adaptive Context Compaction）」**という技術で解決します。

• 例え話：
  机の上に書類が積み重なって、もう置く場所がない状態を想像してください。
  • 70% 満杯： 「あ、少し狭くなってきたな」と警報を鳴らす。
  • 80% 満杯： 「古い書類の表紙だけ残して、中身は倉庫に片付ける（要約する）」（マスキング）。
  • 90% 満杯： 「さらに古い書類は、箱に入れてラベルだけ貼っておく（アーカイブ）」（剪定）。
  • 99% 満杯： 「本当に必要なものだけ残して、後は全部要約して一本のメモにする」（完全圧縮）。

このように、**「いかにして古い情報を捨てずに、必要な情報だけを残すか」**を段階的に行うことで、AI が長時間の作業でも「最初の話」を忘れないようにしています。

3. 安全性：「壊さない」ための 5 重のガード

AI に「何でもできる権限」を与えると、誤って重要なファイルを消したり、サーバーを壊したりするリスクがあります。OPENDEV は**「防御の深さ（Defense-in-Depth）」**という考え方で、5 つの壁を設けています。

• 例え話：
  子供に包丁を持たせるようなものです。
  1. ルール（プロンプト）： 「危ないから切っちゃダメ」と教える。
  2. 道具の制限（スキーマ）： 包丁自体を机から隠す（計画段階では「切る」道具が見えないようにする）。
  3. 承認システム： 「本当に切る？」「はい/いいえ」を人間に聞く。
  4. 実行時のチェック： 「そのコマンドは危険すぎるから実行しない」とシステムが止める。
  5. 巻き戻し（Undo）： 万が一間違えても、**「元に戻すボタン」**で直せるようにする（Git のスナップショット機能）。

特に**「計画する AI」と「実行する AI」を分ける**ことで、計画段階で「誤ってファイルを消す」ような指示が出ないようにしています。

4. 長期的な行動：「忘れっぽさ」を克服する

AI は長い会話になると、最初の指示（「テストを必ず実行してね」など）を忘れがちです。これを**「指示の薄れ（Instruction Fade-out）」**と呼びます。

OPENDEV は、**「タイミングの良いリマインダー」**という仕組みを使います。

• 例え話：
  料理をしている AI 助手に「最後に必ず味見してね」と言っても、料理が長引くと忘れがちです。
  そこで、AI が「完成！」と言おうとした瞬間に、システムが**「あ、味見まだだよ！」と、一番最近のメッセージとして差し込みます。
  これを「システムリマインダー」と呼び、AI がミスしそうになる直前**に、必要な指示を「思い出させる」ようにしています。

5. 人間との協力：「スラッシュコマンド」でコントロール

AI に任せる部分と、人間が直接指示する部分のバランスも重要です。

• 例え話：
  AI に「コードを直して」と頼むのは自然言語ですが、「/undo（元に戻す）」や「/mode plan（計画モード）」のように、「/」から始まるコマンドは、AI の思考ループをバイパスして、人間が直接システムを操作できるようにしています。
  これにより、AI が暴走したときにすぐに止めたり、設定を変えたりすることが可能です。

---

まとめ：この論文が伝えたいこと

この論文は、単に「新しい AI が出た！」と報告しているだけではありません。**「AI を実務で使うには、どんな工夫が必要か？」という「エンジニアリングの知恵」**を共有しています。

• 一人の天才に頼らず、役割分担させる。
• 記憶が溢れないように、段階的に整理する。
• 危険なことは、最初からできないように仕組みを作る。
• 忘れっぽさを、タイミングよく思い出させる。

これらは、AI だけでなく、**「複雑なシステムをどう管理するか」**という普遍的な課題に対する答えでもあります。OPENDEV は、ターミナルという「開発者の心臓部」で、安全かつ賢く働く AI 助手の青写真（ブループリント）を示した論文なのです。

技術概要

論文サマリー：Building AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned

著者: Nghi D. Q. Bui (OpenDev)
概要: 本論文は、IDE プラグインからターミナルネイティブな AI エージェントへのパラダイムシフトに対応し、オープンソースのターミナルネイティブ・コーディングエージェント「OPENDEV」の設計、実装、およびそこから得られた教訓を包括的に報告したものです。

1. 問題定義 (Problem)

従来の AI コーディングアシスタントは IDE に統合され、人間による常時の監視を必要とする「リアクティブなコパイロット」として機能していました。しかし、ターミナルネイティブなエージェント（CLI ベース）は、ソースコントロール、ビルド、デプロイなど、開発の中心となる環境で直接動作し、自律的な長期タスク実行を可能にします。

しかし、このアプローチには以下の 3 つの根本的な工学的課題が存在します：

1. コンテキストの限界: 長期にわたるセッションにおいて、モデルのトークン予算を超えてしまう「コンテキストの肥大化（Context Bloat）」と、その結果生じる推論能力の低下。
2. 安全性: エージェントが任意のシェルコマンドを実行できるため、破壊的な操作を防止する厳格な制御が必要。
3. 拡張性と効率性: 機能拡張がエージェントのプロンプト予算を圧迫することなく、いかに拡張するか。

既存のシステムは、ベンチマーク評価向けに設計されたものか、クローズドソースでアーキテクチャが不明瞭なもの、あるいは技術報告書が未発表のものに限られており、ターミナルネイティブな対話型エージェントの設計指針が欠如していました。

2. 方法論とアーキテクチャ (Methodology)

OPENDEV は、単一の巨大な LLM ではなく、複数のモデル、検索器、ツールを組み合わせた「複合 AI システム（Compound AI System）」として設計されています。そのアーキテクチャは 4 つの主要レイヤーで構成されます。

2.1 4 レイヤー・アーキテクチャ

1. Entry & UI Layer: CLI (TUI) と Web UI の両方をサポートし、共通のコールバック契約を通じてエージェント層と対話します。
2. Agent Core Layer: エージェントの思考ループとオーケストレーションの中核。
   • Scaffolding（足場組み）: 実行前にシステムプロンプト、ツールスキーマ、サブエージェントを構築する。
   • Harness（ハーネス）: 実行時のオーケストレーション層。ツールディスパッチ、コンテキスト管理、安全性 enforcement を担当。
   • 拡張 ReAct ループ: 標準の ReAct ループに「思考（Thinking）」と「自己批評（Self-Critique）」のフェーズを追加。
   • マルチモデル・アーキテクチャ: 作業負荷に応じて異なるモデルをルーティング（例：思考用には推論モデル、実行用にはアクションモデル、要約用には軽量モデル）。
3. Tool & Context Layer:
   • ツールシステム: ファイル操作、シェル実行、Web 検索、LSP による意味的コード分析、MCP による外部ツール発見など 35 種類のビルトインツールと、MCP を通じた動的な外部ツール連携。
   • コンテキストエンジニアリング: 限られたトークン予算を管理するための高度な技術（後述）。
4. Persistence Layer: セッション履歴、設定、モデルメタデータ、ファイル操作ログをローカルファイル（JSON/JSONL）に永続化。Git スナップショットによる「シャドウ Undo」機能も実装。

2.2 安全性アーキテクチャ (Defense-in-Depth)

単一のチェックではなく、5 つの独立したレイヤーで安全性を確保します：

1. プロンプトレベル: システムプロンプトによる行動指針と制約。
2. スキーマレベル: プランモードでは書き込みツールのスキーマ自体を除外し、エージェントが「書き込みができない」状態を構造的に強制。
3. 実行時承認: ユーザーによる明示的承認、パターンベースの自動承認/拒否ルール。
4. ツールレベル: 危険なパターン（rm -rf など）のブロック、古いファイルの読み込み検知。
5. ライフサイクルフック: 外部スクリプトによる実行前のブロックや引数変更。

2.3 コンテキストエンジニアリング (Context Engineering)

長期セッションにおけるコンテキスト管理を第一級の工学的課題として扱っています。

• 適応的コンテキスト圧縮 (Adaptive Context Compaction): トークン使用率が 70%、80%、85%、90%、99% の 5 つの段階で、警告、観測マスキング、高速剪定、LLM による要約など、段階的に圧縮を強化します。
• 二重メモリ構造: 思考フェーズにおいて、長期の文脈（要約されたエピソード記憶）と短期の文脈（直近の会話）を分離して注入。
• イベント駆動型システムリマインダー: 会話が進むにつれて初期プロンプトの指示が忘れ去られる（Attention Decay）問題を解決するため、意思決定の直前に特定の状況に応じたリマインダーをユーザーメッセージとして注入します。
• 遅延ツール発見 (Lazy Discovery): MCP ツールやスキルを起動時にすべて読み込むのではなく、必要になった時点で検索・読み込むことで、初期コンテキストの肥大化を防ぎます。

3. 主要な貢献 (Key Contributions)

1. ワークフローごとの LLM 設定: 複合 AI システムの観点から、思考、実行、批評、圧縮など、各フェーズで最適なモデルを独立して選択・設定可能なアーキテクチャ。
2. 拡張 ReAct 実行パイプライン: 明示的な思考フェーズと自己批評フェーズ、および段階的なコンテキスト圧縮を統合したループ。
3. 長期にわたる行動誘導: 指示の忘却を防ぐためのイベント駆動型リマインダーと、優先順位付きの条件付きプロンプト構成パイプライン。
4. トークン効率の高い拡張性と多層防御: MCP による遅延ツール発見と、5 層構造の安全性アーキテクチャ。
5. コンテキストエンジニアリングの第一級化: 適応的圧縮、リマインダー、経験駆動型メモリ（ACE プレイブック）によるプロジェクト固有知識の蓄積。

4. 結果と知見 (Results & Lessons Learned)

本論文は定量的なベンチマークスコア（SWE-bench など）の報告ではなく、設計上のトレードオフとエンジニアリングの教訓に焦点を当てています。

• コンテキストはバッファではなく予算: コンテキスト削減は「緊急時のみ」ではなく、段階的に行うべきです。古いツール出力をマスキングしたり、ファイルシステムにオフロードしたりすることで、高価な LLM 要約を回避できます。
• 安全性は構造的制約で: 実行時の権限チェックよりも、ツールスキーマから危険なツール自体を除外する方が堅牢です（モデルが「できない」ことを認識できないため）。
• LLM の不正確さへの適応: エディットツールは、LLM が生成するテキストのわずかな不一致（空白、インデントなど）を吸収できるよう、9 段階のファジーマッチングチェーンを実装しました。
• 遅延読み込みの重要性: 起動時にすべてのツールスキーマを読み込むとコンテキストの 40% を消費しますが、遅延発見によりこれを 5% 未満に抑えました。
• リマインダーの役割: 初期プロンプトの指示は長セッションでは無視されがちです。意思決定の直前に「ユーザーメッセージ」としてリマインダーを注入することで、遵守率を大幅に向上させました。

5. 意義と将来展望 (Significance & Future Work)

OPENDEV は、クローズドソースの産業実装とオープンな学術議論の架け橋となる、最初の包括的な技術報告です。

• 実用性の証明: 長期にわたるターミナル操作において、コンテキスト管理と安全性をどうバランスさせるかという実用的な課題に対する具体的な解決策を提供しています。
• 設計パターンの共有: 「足場組み（Scaffolding）」と「ハーネス（Harness）」の分離、複合 AI システムとしてのモデルルーティング、コンテキストエンジニアリングの手法など、他のエージェント開発者にとって転用可能な設計パターンを提示しています。
• 今後の方向性: 定量的なベンチマーク評価、適応的なリソース割り当て、プロジェクト間での知識転移、より高度なマルチエージェント協調、および IDE と CLI のハイブリッド統合などが今後の研究課題として挙げられています。

総じて、本論文は「AI による自律的ソフトウェアエンジニアリング」を実現するための、堅牢で拡張可能、かつ安全なターミナルネイティブ・エージェントの青図（ブループリント）を提供する重要な文献です。