この論文は、ブラジルの企業 Zup Innovation が自社のエンタープライズソフトウェアチーム向けに社内で構築・ 展開した AI コーディングエージェント である CodeGen について報告する。CodeGen は開発チームの メンバー 2 人による概念実証として始まった。当時、同社の主力開発者プラットフォームである StackSpot AI は、 コードを提案できても環境の中で行動することはできない IDE 拡張機能を提供していた。プロトタイプは あえてそのプラットフォームのコードベースとリリースサイクルの外で構築され、次第に開発者が日常的に使う 本番システムになっていった。著者らの前提は、コーディングエージェントに関する既存の文献はベンチマーク、 プロンプティング、推論戦略といったモデルレベルの性能に集中しており、エージェントが本番で成功するか どうかを決めるエンジニアリング上の判断はほとんど報告されていない、というものである。
CodeGen は ReAct パターンに従う。自然言語のプロンプトを受け取ると、推論し、 ツールを選んで呼び出し、結果を観察し、完了するまで反復する。構成要素は 3 つある。ユーザーとの やり取りを担い、開発者のマシン上でツールをローカルに実行する Node.js の CLI（主要な IDE はすべて すでにターミナルを組み込んでいることから選ばれた）、認証、ルーティング、エグゼキューター向けの WebSocket 接続、Web ポータル向けの Server-Sent Events を扱う FastAPI バックエンド、そしてエージェント型 ループを実行するオーケストレーションエンジンの Maestro である。Maestro はモデルにシステムプロンプト、 履歴、環境に関するブートストラップメタデータ、ツールマニフェストを送り、要求されたツール呼び出しを CLI に中継して結果をモデルに返すことを、モデルがテキストで回答するまで続ける。セッション状態は PostgreSQL に保存され、Redis がキャッシュとメッセージング層を担う。中断されたタスクは再開でき、永続的なイベント タイムラインがすべてのツール呼び出し、モデルの応答、状態遷移を記録する。
論文は、アーキテクチャとフレームワーク、ツール設計と安全性、人間による監督にわたる 13 の設計判断を、 それぞれのトレードオフと教訓とともに整理し、6 つの未解決の問いで締めくくっている。
要点
- 著者らは、ツールの説明、パラメータのスキーマ、エラーの契約を洗練させたほうが、プロンプト エンジニアリング単独よりもエージェントの信頼性を一貫して改善したと報告し、ツールの仕様には API 設計と同じ厳密さが必要だと論じている。
- 編集ツールはファイル全体の書き直しではなく、狙いを定めた文字列置換を行う。モデルは長いファイルを 再生成する際に内容を切り詰めたり省略したりしがちだからである。編集前に読むというポリシーは、ツール 自体ではなくシステムプロンプトを通じて強制され、古い、あるいは想像上のファイル内容への編集を防ぐ。
- シェルツールは最も有用であると同時に最も危険なツールとされ、多層的な ガードレール によって管理される。完全に無効化でき、設定によって特定のコマンドをブロックでき、承認モードでは すべての呼び出しに確認を求めることができ、すべての実行はログに記録される。
- 安全性はシステムレベルの性質であることが判明した。直接のファイル削除のような 1 つの機能を ブロックしても、制限のないシェルで同じ効果を実現できる限り効果がなかったため、ポリシーはツール マニフェスト全体に一貫して適用する必要があった。
- 開発者は、編集やシェルコマンドに確認が必要な承認モードから始め、自信がつくにつれて自分のペースで 自律モードへ移行した。著者らはこうした ヒューマン・イン・ザ・ループ の仕組みを過渡的な足場と 捉え、エージェントの変更に対する開発・ステージング・本番のデプロイパイプラインにも同じ段階的な 公開のパターンを見ている。
- 実行前にユーザーがレビューできる行動計画を提示する専用の計画モードが追加された。1 回の実行で 済ませる方式は、複雑なタスクや重大なタスクでは問題があると判明したためである。
- LangChain を用いた初期の試みは、その当初の一方向のチェーンモデルが循環的な ツール呼び出しループに合わなかったため断念された。チームはループを手作業で実装し、 LangGraph のような新しいオーケストレーションの抽象化が自分たちがすでに 構築していたものとよく似ていることがわかった後、現在はそうした現代的な抽象化へ移行しつつある。 著者らはこれを、まず自作し、後から採用するという戦略の妥当性を裏付けるものと読んでいる。
- 推論はモデルに委ねられ、思考エフォートの設定で調整される一方、オーケストレーターは停止基準、 ツールの順序、エラー処理、ガードレールを強制する。著者らは、より強力なモデルは手書きのロジックを 減らすが、オーケストレーションの必要性をなくすわけではないと論じている。
補足
著者らが提示する未解決の問いは、誤用を最小限にするためにツールマニフェストをどう設計すべきか、 モデルに委ねる推論とオーケストレーターが強制する制御の境界をどこに置くべきか、機能が重なり合う ツール間で安全性ポリシーをどう一貫して規定できるか、承認モードと自律モードの二者択一のスイッチに 代わる適応的な信頼モデルとはどのようなものか、セッションをまたぐ長期記憶をどう構造化すべきか、 そしてエージェントがより大きな変更を担うにつれて、エージェントが生成したコードをどのように品質保証の パイプラインに組み込むべきか、というものである。また著者らは、ほとんどの判断を単一の指標の最適化 ではなく明示的なトレードオフとして捉えている。たとえば承認モードは摩擦を増やし、推論の委任は 決定論的な制御を減らす。
この論文は 1st AI Agent Journal（2026）に掲載されている。ここで抽出したバージョンは arXiv:2604.09805v1 [cs.SE] である。