この本は、AIエージェントを賢く見せるための本ではない。Prompt を工夫して気の利いた答えを引き出すところで止まらず、曖昧な要求を仕様へ変換し、repo を読ませ、変更させ、verify し、仕事を完了させるところまで扱う本である。

扱う軸は 3 つだけに絞る。Prompt Engineering、Context Engineering、Harness Engineering である。Prompt Engineering は単一タスクの契約を作る工程、Context Engineering は判断材料を壊れにくく渡す工程、Harness Engineering は安全に実行・検証・再開させる工程である。本書はこの 3 つを順に積み上げ、AIエージェントを「もっともらしい出力」から「完了した仕事」へ近づける。

本書の約束

本書の約束は明確である。読み終えた時点で、読者は次のことを実務の単位で説明し、再現できるようになる。

• 曖昧な依頼を Prompt Contract、spec、acceptance criteria、ADR に分解できる
• repo context、task brief、Progress Note、context pack を使って、AIエージェントの前提崩壊を防げる
• verification harness、permission policy、restart protocol、operating model を使って、AIエージェントの仕事を最後まで閉じられる

この本は、特定モデルの性能比較や、会話だけで完結するプロンプト小技集を約束しない。対象は、実務での変更、verify、review、handoff を伴う作業である。

2026年版で固定する前提

2026 年版では、単発の UI や一時的な product tip ではなく、商用運用で残る判断基準を先に固定する。本文と supporting artifact は、次の前提で読み進める。

• durable な設計原則を優先する: 画面配置や一時的なコマンド差分より、artifact、権限境界、verify、handoff の設計を優先する
• recurring case を通しで使う: support-hub と 4 つの recurring case を繰り返し使い、章ごとの小技ではなく仕事の閉じ方を学ぶ
• chapter ごとに artifact を残す: 本文の主張は、prompt、spec、context pack、checklist、runbook、evidence など repo に残る artifact へ落とす
• 一次情報で実行条件を確認する: runtime の挙動、権限、課金、protocol 仕様は、利用中ツールの official docs と組織ポリシーで確認する

想定読者

想定読者は次のいずれかに当てはまる人である。

• ChatGPT や coding agent を業務に導入したいが、出力の見た目以上に完了品質を安定させたいエンジニア
• issue、spec、tests、docs を使う開発プロセスの中で、AIエージェントを壊れにくく運用したいテックリード
• prompt の工夫だけでは限界があると感じ、context と harness まで設計対象に含めたい実務者

前提として、Git、issue、テスト、コードレビューの基本を知っていることを想定する。Python や特定フレームワークの深い知識は必須ではないが、repo を読んで変更する開発フローには慣れている方が読みやすい。

想定しない読者

次の期待には、この本は正面から応えない。

• ノーコードで AIエージェント活用を始めたい読者
• モデル選定や API パラメータ最適化を主題として期待する読者
• 会話だけで完結する利用法や、一般的な生成 AI 入門を求める読者

本書は、repo と artifact を持つ開発現場を前提にしている。そのため、コード変更や verify を伴わない利用形態には踏み込まない。

前提知識

本書を無理なく読むための前提は、次の 3 点である。

• Git の基本操作と、差分・履歴・ブランチの役割を理解している
• issue、spec、テスト、コードレビューを使った開発フローを知っている
• repo を開き、ファイルを読んで変更し、verify を実行する流れに抵抗がない

Python や特定フレームワークの深い知識は必須ではない。ただし、shell、CI、テスト実行、Pull Request といった artifact を実務で見たことがある方が、本書の価値は高くなる。

この本で扱うことと扱わないこと

扱うのは、AIエージェントに仕事を完了させるための設計である。具体的には、Prompt Contract、task brief、context pack、verification harness、restart packet、review budget といった artifact と運用である。

扱わないのは、次の領域である。

• モデルの内部原理や学術的な最適化手法の詳細
• 実際の出版契約、営業戦略、入稿デザイン
• プロダクト組織全体の人事制度や評価制度

本書では、必要な理論は扱う。ただし理論だけで終わらせず、必ず repo に残る artifact へ落とす。

安全に使うための注意

AIエージェントに repo 変更や verify を任せる運用は、そのまま本番へ持ち込んでよい前提ではない。特に次の点は先に確認する必要がある。

• 権限境界: 書き込み権限、秘密情報、外部接続、課金対象 API の扱いを作業前に固定する
• verify 境界: local test、CI、review 証跡のどこまでを通れば done と言えるかを先に決める
• 監査性: Prompt、Context、Harness の変更を chat log ではなく repo artifact として残す

本書の例は reader-facing な説明用に簡約している。実務へ移すときは、利用中のモデル、CLI、権限設定、組織ポリシー、法務要件を読者自身の環境に合わせて確認すること。

利用と更新情報

• 公開版: https://itdojp.github.io/ai-agent-engineering-book/
• リポジトリ: https://github.com/itdojp/ai-agent-engineering-book
• 更新差分: GitHub の commits / PR 一覧 を参照する
• Pages 生成の仕組み: docs/pages-publishing.md

Prompt、Context、Harness に関わるツールや UI は更新頻度が高い。具体的な導入時は、本文だけでなく repository の最新差分と、利用中ツールの official docs を併読することを前提にする。

source of truth の優先順位

本書、repo、利用中ツールの挙動が食い違うときは、次の順で判断する。

1. 実行境界、権限、課金、protocol 仕様は利用中ツールの official docs と組織ポリシーを優先する
2. recurring case と再利用 artifact の役割は、本書本文と sample-repo を優先する
3. 表記や命名が揺れる場合は docs/glossary.md を正本にする

つまり、本書は durable な設計原則と artifact の責務を固定するための source であり、日々変わる runtime detail を固定する source ではない。runtime detail は一次情報で読み替える前提で使う。

recurring case の見方

本書では support-hub という小さなサポートチケット管理システムを、sample-repo として使う。毎章題材を変えるのではなく、同じ repo と同じ 4 つの recurring case を繰り返し使う。

• BUG-001: バグ修正をどう閉じるか
• FEATURE-001: 曖昧要求をどう仕様化するか
• FEATURE-002: 長時間タスクをどう分割し、再開可能にするか
• HARNESS-001: verify と evidence をどう整えるか

同じケースを繰り返す理由は、章ごとに小技を増やすためではない。Prompt、Context、Harness が別々の話ではなく、同じ仕事を完了に近づける層だと見えるようにするためである。

まず何を見ながら読むか

本書は紙面だけでも読めるように設計するが、repo と併読すると理解は深くなる。読み進めるときは、次の順で意識すると迷いにくい。

1. その章で何を安定化したいのか
2. その章で新しく増える artifact は何か
3. その artifact が support-hub のどの recurring case に効くのか

この 3 点が見えていれば、細部を後から見返しても戻りやすい。次のファイルでは、本書全体の読み方と 3 部構成の使い分けを整理する。