AI銉勩兗銉玚

AI Agent エンジニアリング実践ロードマップ：Codex、Claude Code、MCP、Skills の学び方

Codex、Claude Code、MCP、Skills、検証、コンテキスト設計、安全境界、チーム運用を段階的に学ぶための AI Agent エンジニアリング実践ロードマップ。

AI Agent は、製品名から追い始めるとすぐに混乱します。

Codex、Claude Code、Cursor、Gemini CLI、MCP、Skills、Hooks、権限、サンドボックス、長期記憶、マルチ Agent ワークフローは、すべて同じ階層の話ではありません。

まず考えるべきなのは、Agent に何を任せるのか、どのファイルを読ませるのか、どこまで編集させるのか、どう検証するのか、危険を見つけたときどこで止めるのかです。

結論

AI Agent エンジニアリングは、七つの層に分けて学ぶと整理しやすくなります。

  • タスク定義。
  • コードベースのコンテキスト。
  • コマンド実行と検証。
  • MCP によるツール接続。
  • Skills、Hooks、プロジェクトルールによる再利用可能なワークフロー。
  • 権限、サンドボックス、監査。
  • PR、CI、ロールバック、コスト管理を含むチーム運用。

最初から完全自動化を目指さないでください。

まず一つのリポジトリで小さなタスクを安定して完了させます。その後でツールを追加し、最後に長時間タスクや複数 Agent を検討します。

最初は VS Code で Codex を使う方法 から始め、次に Claude Code と Codex のコードレビュー手順 を読み、繰り返す作業は Codex Skills に落とし込みます。

対象読者

このロードマップは、すでにコードを書けるが、Bug 修正、テスト追加、依存関係の確認、ドキュメント更新を Agent に手伝わせたい開発者に向いています。

個人のプロンプト技術ではなく、再現できるチーム手順を作りたい小規模チームにも向いています。

ブログ、内部ツール、CLI、ドキュメントサイト、自動化システムを保守している人にも役立ちます。

ただし、いきなり本番の無人運用を目指すための手順ではありません。

個人情報、決済、アカウント権限、本番環境、セキュリティスキャンに関わる場合、最初の目標は自動化率ではなく、制御と監査です。

第 1 層：タスクを実行可能な単位にする

Agent が失敗する理由は、タスクが難しいからだけではありません。多くの場合、目標が曖昧です。

よい依頼には次の要素が必要です。

  • 何を変更するか。
  • 何を変更してはいけないか。
  • どう検証するか。
  • 失敗時にどこで止めるか。
  • 最終報告に何を含めるか。

悪い例：

1

このプロジェクトを最適化して。

よい例：

1
2
3
4
5

src/auth と tests/auth を読んでください。
ログイン失敗後のエラーメッセージ不一致を修正してください。
database schema は変更しないでください。
修正後に auth 関連テストを実行してください。
依存関係が不足している場合は、検証を飛ばさず不足内容を報告してください。

この段階では MCP も大きな Skill も不要です。

必要なのはタスク境界です。

第 2 層：Codex と Claude Code の役割を分ける

Codex は、既存リポジトリの中でファイルを読み、編集し、コマンドを実行し、テスト失敗を説明する作業に向いています。

Claude Code は、長いコンテキスト、ターミナル中心の作業、広めの設計相談に向いています。

Cursor は IDE 内の補完、局所編集、対話的なコード理解に向いています。

タスク 向いている入口 理由
小さな Bug 修正 Codex ファイル編集と検証がしやすい
設計相談 Claude Code 長い説明と推論に強い
局所補完 Cursor IDE ループが自然
ドキュメント更新 Codex / Claude Code リポジトリ文脈が必要
コードレビュー Codex + グラフツール diff と呼び出し関係が必要
長時間タスク復旧 Codex + タスク記録 状態と検証履歴が必要

VS Code 中心なら Codex、ターミナル中心なら Claude Code から始めると自然です。

第 3 層：正しいコンテキストを渡す

すべてをプロンプトに詰め込むのはよい方法ではありません。

コンテキストは四種類に分けます。

  • 安定ルール：構成、テストコマンド、禁止ディレクトリ、デプロイ条件。
  • 今回のタスク：ログ、再現手順、関連ファイル。
  • コードインデックス：関数、ルート、依存関係、呼び出し関係、最近の変更。
  • 履歴記憶：過去の判断、既知の落とし穴、移行背景。

安定ルールは AGENTS.md、CLAUDE.md、プロジェクト文書へ。

今回のタスクは現在の依頼へ。

コード構造は code-review-graph、Serena、codebase-memory-mcp へ。

歴史的判断は ADR、Issue、短いノートへ置きます。

詳しくは AI Agent コードベース記憶ツール比較 を参照してください。

第 4 層：検証ループを作る

検証がなければ、Agent はもっともらしい文章を出しているだけです。

検証には三種類あります。

  • 静的検証：format、type check、lint、front matter。
  • 動作検証：テスト、スクリーンショット、API 応答。
  • 人間の確認：文言、リスク、範囲、業務判断。
1
2
3

git status --short
rg -n "TODO|FIXME" src tests
npm test -- --runInBand

1
2

python -m pytest tests/auth -q
python -m ruff check src tests

検証コマンドが明確であるほど、Agent は言い訳をしにくくなります。

第 5 層：必要になってから MCP を入れる

MCP はツール接続の問題を解決します。

ブラウザ、ドキュメント検索、コードインデックス、データベース、Office ファイル、内部システムを共通の方法で Agent に使わせられます。

最初は読み取り専用ツールから始めます。

次に草稿生成や一時ファイル作成のような低リスク書き込みを追加します。

デプロイ、DB 書き込み、外部 API、メール送信などは最後です。

MCP は、Agent がファイルを見つけられない、公式ドキュメントを調べる必要がある、ブラウザで確認する必要がある、Word/Excel/PDF を読む必要がある、といった場合に有効です。

タスクが曖昧で、テストがなく、権限境界もない状態では、MCP は根本問題を解決しません。

第 6 層：繰り返しを Skills にする

Skills はモデルを強くする機能ではありません。

繰り返し説明している作業手順を保存する仕組みです。

Hugo 記事作成、翻訳同期、デプロイ、SEO クールダウン確認、動画文字起こし、定型レポート生成などに向いています。

一度だけの作業や、まだ手順が固まっていない作業には向きません。

まず手動で成功した流れを小さく書き、実タスクで改善します。

第 7 層：長時間タスクを復旧可能にする

長いタスクは必ずどこかで止まります。

必要なのは、現在の目標、完了済みの手順、残りの手順、重要ファイル、実行済みコマンド、検証結果、未解決リスク、次の入口です。

詳しくは AI Agent 長時間タスクの復旧方法 を参照してください。

安全境界

Agent がコマンドを実行できるようになると、リスクは誤回答だけではありません。

ファイルを変更し、秘密情報に触れ、外部サービスを呼び、ログに機密情報を書く可能性があります。

ローカル開発では git status --short を確認し、破壊的コマンドを自動実行せず、未知のディレクトリを削除せず、秘密情報をプロンプトやログに入れず、本番デプロイには人間の確認を残します。

チームでは最小権限トークン、ブランチ制限、CI secret の最小化、PR の人間レビュー、Agent ログの監査が必要です。

実プロジェクトで練習する

個人ブログ、テストリポジトリ、内部スクリプト、ドキュメントサイト、CLI など、壊しても安全な小さなプロジェクトを選びます。

Git 履歴、明確な入口、検証コマンド、限定されたファイル範囲、ロールバック手段があるものが向いています。

最初は Agent に読ませるだけにします。入口、検証コマンド、関連ファイルを説明できるか確認します。

次に小さな修正を一つだけ任せ、変更理由と検証結果を報告させます。

最後にブラウザ、ドキュメント検索、コードインデックスなどを一つずつ追加します。

30 日の学習計画

第 1 週は一つのツールを安定して使います。モジュールを読み、低リスク Bug を直し、テストを追加し、ドキュメントを更新し、検証コマンドを整理します。

第 2 週はコンテキストを改善します。短い AGENTS.md を書き、Codex と Claude Code を比較し、code-review-graph を試し、diff レビューを記録します。

第 3 週は MCP を慎重に追加します。読み取り専用ツールから始め、ブラウザ検証、コードインデックス、権限メモを作ります。

第 4 週は Skills とチーム手順です。Skill 草案を作り、実タスクで使い、失敗処理、PR テンプレート、安全な CI、ロールバック練習まで行います。

成長の測り方

回答の見た目ではなく、タスク時間、人間のレビュー時間、編集ファイル数、テスト一発成功率、手戻り回数、コンテキスト不足、権限不足、ツール設定失敗、モデル能力不足を記録します。

よい傾向は、タスク範囲が明確になり、検証が安定し、ルールが短くなり、Skills が少なく正確になることです。

読む順序

最後のロードマップ

AI Agent エンジニアリングは、最強モデル探しから始まりません。

一つの小さなタスクを確実に終えるところから始まります。

タスク、コンテキスト、検証、MCP、Skills、権限、CI、コスト管理の順で積み上げると、Codex、Claude Code、MCP、Skills はばらばらの用語ではなく、一つの運用できる工程になります。