AIエージェント開発の実務 — 原則と手札を分けて覚える

「AIエージェント」が指しているものを、コード補完やチャットと並べて定義します。決定的な違いであるツールの有無、エージェントループの構造、ハーネスという考え方、そしてこの区別が実務でなぜ効くのかを扱います。

公開されている調査からエージェントの普及状況を確認しつつ、それ以上に重要な「その数字が何を測っていないか」を扱います。アンケートと行動ログの違い、AIツールとエージェントの混同、そして年号だけ差し替えられた記事の実例まで整理します。

体感と実測が正反対を向いたランダム化比較試験と、その後に著者自身が公表した見直しを追いながら、AIの効果を測ることの難しさを扱います。何を測ると誤導されるのか、代わりに何を見るべきかまで整理します。

エージェントの実行環境を、並列性・環境隔離・権限境界・再現性の4軸で選ぶための整理です。クラウドが見ているコードはどこか、隔離されているから何を許せるのか、ローカルとの往復、そしてクラウドに向かない作業を扱います。

Claude Codeのクラウド実行を実際に導入する手順を、GitHubの接続、実行環境の作成、依存インストールの置き場所、pushの順序、結果の受け取りまで通しで扱います。初回に必ず踏むつまずきどころを、実際のエラー出力とあわせて示します。

AIエージェントの権限をどこまで緩めてよいかを、脅威モデルから逆算して設計します。プロンプトインジェクションと「致命的な三要素」、禁止が許可より強い理由、権限とサンドボックスという層の違い、ネットワーク出口の段階的な絞り方を扱います。

環境を隔離しても、渡した認証情報は隔離されません。エージェントから見える範囲、クラウド側が採用している「本物を渡さない」設計、セッション共有とworktreeという見落としやすい漏洩経路、そして実務で取るべき5つの型を整理します。

並列実行で実際に壊れるものを整理します。worktreeが隔離するものとしないもの、作業ディレクトリの外にある共有状態、新しいチェックアウトが空であること、そして並列度の上限を決めるのが人間側だという話まで扱います。

エージェントの前で待つ時間をなくすための設計です。完了を知らせる仕組み、手を離しても走り続ける実行環境、こちらから起動しないイベント駆動の運用、そして自動応答が持つ副作用への注意を整理します。

AIエージェントに情報を渡せば渡すほど精度が上がる、という直感がなぜ成り立たないのかを、研究とベンダー公式の見解を根拠に整理します。コンテキストが有限資源であること、長さによる劣化、事前取得と実行時取得の使い分け、圧縮・記録・分離という3つの対処法まで扱います。

エージェントの設定ファイルが「誰に届くか」を整理します。5階層の優先順位、Gitに入れるものと入れないもの、「今後は聞かない」が保存される場所、リストが合成される規則、そして設定が効かないときにスコープを疑う手順を扱います。

AIエージェント向けの指示ファイルに何を書き、何を書かないかを、各ツールの公式ドキュメントの記述を根拠に整理します。毎回読まれるコンテキストという性質、指示が守られない理由、肥大化したときの分割、ツールを乗り換えても失われない置き方まで扱います。

AIエージェントの成否がタスクの大きさでどれだけ変わるかを、測定された研究をもとに整理します。検証できる単位への分割、作らせる前に計画を出させる進め方、ワークフローとエージェントの使い分け、失敗したときに指示を足すのではなく切り直す判断を扱います。

エージェントに渡す道具の設計を扱います。MCPが標準化したこと、ツールがAPIのラッパーではない理由、数を絞る根拠、トークン効率を設計に組み込む方法、そしてMCPサーバーを増やすことが信頼できない入力の経路を増やすという側面まで整理します。

エージェントが「できました」と言った内容を人間が毎回確かめる状態から抜け出す方法を整理します。検証手段の種類、停止をどこまで強く縛るか、フックによる決定的な強制、レビュー用サブエージェント、そして過剰に指摘させないための注意まで扱います。

AIエージェントが書く量が増えると、ボトルネックはレビューに移ります。公開データで確認できる品質指標の変化、人間のレビューが持つ物理的な上限、機械の指摘で先に収束させる運用、そして人間が最後まで手放せない判断を整理します。

「なんとなく良くなった」を潰すための評価の作り方を整理します。ふつうのテストとの違い、結果と経路のどちらを採点するか、何件から始めるか、モデルに採点させるときの注意、採点器そのものを疑う姿勢、そして評価の飽和まで扱います。

エージェントの利用料が思ったより高くなる理由を、仕組みから説明します。長いセッションでコストが積み上がる構造、プロンプトキャッシュが前方一致であること、モデルを仕事に合わせる基準、そしてトークン消費を減らす具体的なレバーを整理します。

個人で効いた工夫が、そのままチームで効くとは限りません。AIが既存の状態を増幅するという調査結果、土台のない組織に配ったときに起きること、生産性と負荷が同時に増える構造、そして効果の測り方を間違えないための視点を整理します。

製品の優劣ではなく、選ぶときの軸を扱います。実行場所と操作面という2つの軸、製品がカテゴリをまたぐようになった現状、乗り換えコストを決めるもの、そして評価すべき7つのチェック項目を整理します。

本書の内容を実務で引ける形に圧縮しました。指示の型、設定ファイルがどこに届くかの早見表、権限とフックの使いどころ、セッション運用、そして新しいプロジェクトを始めるときのチェックリストをまとめています。