AI Agent Manager (AAM) として生きていく : 作業環境とワークフローの設計

20XX 年、開発現場はエンジニアの人数より AI Agent のセッション数が多くなっていた。自然と、人間のエンジニアをまとめる Engineering Manager (EM) よりも AI Agent を管理する AI Agent Manager (AAM) の役割が重要となり、かつて人の採用とカルチャーの醸成に腐心していた VPoE は、VPoA (Vice President of AI) となり優秀な基盤モデルの API Call の獲得とそれらに言うことを聞かせる CALTURE.md や CODING_RULE.md の作成に割く時間が増えるようになったのだった・・・

そんな時代は意外と早く来るかもしれません。最近下記の Pull Request をほとんど Claude Code (と Amazon Q Developer) で作成した中で、自分の役回りが「開発者」から AI Agent のマネージャー、すなわち AI Agent Manager (AAM) に移り変わっていることを強く感じました。

具体的には次のような作業です。

• AI Agent に目的を共有する
• AI Agent のコンテキストにプロジェクトとタスクを丁寧に入れてオンボーディング
• AI Agent の進捗管理
• AI Agent の計画・実装の評価
• AI Agent の行動結果を基にした作業プロセス改善の PDCA をまわす

この中にかつて大半を占めた「俺のコーディング」はほぼ含まれません。

私たちが"エンジニア"という名前の職業についてその名を冠した書籍や資格を通じ学びを深めてきたように、まもなく到来する時代における新しい役割に「名前」を付けることが、行うべき仕事の内容を定義しスキルを洗練させるのに不可欠と考え、本記事では "AAM" という名を付けました。

本記事では、AAM 初級編ということで実際 Claude Code / Amazon Q Developer を使う中で見えてきた「AI Agent のマネジメント」の具体的な仕事の一つである「働く環境の整備」と「ワークフローの設計」について得られた経験を基にノウハウを共有します。

1. AI Agent が働く環境の整備
2. AI Agent のワークフロー設計
3. AI Agent Managerとして求められるスキル

AI Agent が働く環境の整備

多くの場合、Git リポジトリが AI Agent の作業環境となります。AI Agent が十分正確にリポジトリ内のコードを編集できるようにするには、「コンテキストの付与」が不可欠になります。なぜなら、私達人間のエンジニアが Git リポジトリ以外から得ているコンテキスト情報、具体的には Figma のデザイン、 Notion / Google Doc やファイルサーバーにある仕様書をはじめとしたドキュメント、 Slack / Teams における会話などに AI Agent 単体はアクセスできないからです。

コンテキストの付与を行う方法は 3 つあります。

1. リポジトリ内の文書 (commit 対象)
   • Claude Code ならCLAUDE.md 、Amazon Q Developer なら .amazonq/rules など
2. リポジトリ内の文書 (commit 対象外)
   • Git リポジトリにコミットするまでもない、あるいは外部システムに細かく書くほどではない、記録しておきたいタスク固有の情報や進捗、Tips などを .gitignore で除外するフォルダ内に格納する
3. MCP Server
   • Figma や Atlassian 、GitHub などはオフィシャルの MCP サーバーを提供しておりここから外部情報を得ることが出来ます
   • ブラウザを動かせる Playwright など、自分から情報を取るためにも必要

Commit 対象のファイルはリポジトリの開発に関わる人全体へ共有したいルールです。

Commit 対象外のファイルは、私は .workspace というフォルダを作成しその中にタスク固有のファイルを配置し .gitignore で除外しています。 launch.md に書いたプロンプトで task.md を生成して進捗管理を開始します。sandbox は、依存パッケージの動作を確認するための一時的なスクリプトを置くのに使用します。詳細なワークフローは次節で解説します。

repository-root/
├── .workplace/                # Workspace files for AI Agent
│   ├── sandbox/               # Temporary scripts to interact dependent packages
│   ├── launch.md              # Prompt to generate task.md
│   └── task.md                # Mainly todo list to complete a task 
│

この方法のデメリットは、除外しているのでコンテキストを別セッションと共有したい場合ファイルをコピーする必要があることです。これは git worktrees などを使いディレクトリを丸ごと分けてパラレルで走らせる場合手間になります (git worktrees は上記の Anthropic のガイドで紹介されている手法の一つです (6.c. Use git worktrees)。ただ、個人的にはあんまり恩恵を感じなかったです)。

最後に MCP Server です。今回は MCP サーバーではなく GitHub にアクセスする gh を直接使ってます。CLAUDE.md や gh による操作は Anthropic のベストプラクティスガイドでも紹介されています。具体的な作成方法については次節の "ワークフローの設計" で触れます。

• 1.a. Create CLAUDE.md files
• 1.d. If using GitHub, install the gh CLI

AAM として作業環境を整えるにあたり重要なこと

最も重要な作業は MCP Server の拡充と考えています。会社やチームで複数リポジトリを持っている場合、それらの間で CLAUDE.md やコミットしないローカルルールはガラパゴス化しがちです。そのため、会社 / チーム単位で MCP Server を作りそこにルールを集約、個々プロジェクトの CLAUDE.md などは本体 MCP Server のキャッシュとみなす、あるいは CLAUDE.md 等の編集は禁止してプロジェクト固有のファイル (PROJECT.md など) に固有のルールを記載するといった運用を取ることでガバナンスを効かせられると思います。

AI Agent のワークフロー設計

あれこれ試した結果、AI Agent のワークフローは次の形が一番はまっています。

1. initialize repository : CLAUDE.md とかを作りリポジトリ全体のルール (ガードレール) を定める
2. launch task : 特定のタスク (今回議事録ユースケースの追加) の方針と進捗を管理するための task.md を作成する
3. onboard : タスクの進捗状況やリポジトリの関連ファイルを読んで作業可能な状態になる (ためのプロンプト)。clear とかで記憶を消去した後にも実行
4. think : task を complete するための実装方針やアプローチを叙述させる (ためのプロンプト)
5. learn : 依存パッケージなどの動作確認をするための簡単なスクリプトを ./workplace/sandbox に書いて実行する (ためのプロンプト)
6. implement : 実装する
7. test : テストする
8. retrospect : task を完了 (失敗) するまでの一連で work した方法、not work だった方法を叙述させて task.md や場合によって CLAUDE.md などプロジェクトレベルのファイルにノウハウやルールを反映させる (ためのプロンプト)。実行後に /compact か /clear を行う

各工程で必要なプロンプトを ./workplace に保管してます。Claude Code では custom slash commands としてプロンプトを登録できるのでそこに登録しておきます (めちゃめちゃ便利 : 2.c. Use custom slash commands)。

個人的には カスタムコマンドを決められたルール通り実行していくだけで作業が終わる ことが AAM として理想的なワークフローを設計できているかの指標になると感じています。

各工程の Tips やノウハウを紹介します。

initialize repository : CLAUDE.md を含め、基本的にコンテキストを付与するためのファイルはエージェント自身に書いてもらっています。コンテキストの情報源 (README.md) は人間のために書いてますが、他のファイルはあくまで "AI Agent が効率的に作業するために必要な情報" という位置づけになるので AI Agent が自分で情報を把握しやすいように書いてもらう方が良かろうというスタンスです。人間でも、それぞれの人がメモを取るスタイルにまで干渉しないのと同じです。また、最初はシンプルにして徐々に更新するのも重要です。(記載の有効性を検証しないまま) 最初にルールもりもりな CLAUDE.md を投入するのは Anthropic のガイドで Bad Practice として言及されています (1.b. Tune your CLAUDE.md files)。

launch task : 実行すべきタスクの目的や背景と Todo リストをまとめた task.md を書き出します。Claude Code は勝手にタスクを分解して進捗を連絡してくれたりしますが、それでも実装の背景などを含めると実ファイルにあったほうがいいという感覚です。

結構長いので、実際使ったものを共有します (日本語で書くと日本語の問題なのか指示の問題なのか判別できないので主に英語で書いてます。翻訳は LLM がやってくれるのであまり苦ではないです)

Please read README.md to understand the specifications, then create a step-by-step task list for implementation that your subordinate developer can follow. This file, named tasks.md, should be stored in the .workplace directory. Think of this file as a checkpoint in a role-playing game - it will be used when your subordinate starts or resumes implementation and reports progress to you.

Premises:

• All dependencies have already been set up in this workspace
• You will ask your subordinate to check off completed tasks in tasks.md
• To verify completion, you will review test results. Therefore, all implementation should begin with creating tests (which will initially fail). The purpose of these tests is to: 1) establish agreement on interface design (classes, methods, functions, etc.), 2) define clear completion criteria, and 3) break down tasks into subtasks by representing each unit test as a discrete subtask
• You recommend to use .workplace/sandbox to understand how to use dependent packages. Because it is necessary to understand package's interface and functionality before implementing tests and scripts.
• Before finishing each task and subtask, ask to run linter.

Please remember communication starts from building trust. Therefore tasks.md should starts from your purpose and thought in addition to tasks itself.

onboard : 重要な処理で、周辺のコンテキストを把握して実装 ready な状態にします。Anthropic のガイドで 3.a Explore, plan, code, commit Try common workflows とあるように、探索、計画、実装、コミットが基本的なワークフローになります。Claude Code の場合結構勝手にやってくれますが、それ以外の場合は明示的に workspace のファイルを読む、事前にアプローチを考える、と指示しないといきなり実装を始めるので注意が必要です。この処理は、clear とかで一回記憶を失ってもらった時に復旧してもらうにも役立ちます。

think / learn / implement / test : onboard でも言及した Explore / plan / code / commit を進めていくコマンドです。think は計画で、learn では ./workplace/sandbox 内に依存ライブラリや既存モジュールを実行する簡単なスクリプトを書いて理解を高めてもらいます。implement は画一的なコマンドがあるわけではなく、状況に寄ります。test は、Anthropic のガイド的には最初にやる方が好ましいのですが (3.b. Write tests, commit; code, iterate, commit) 、私が試した中ではテストが通るようテストデータに合わせて実装を書き換えたりモックだらけのテストを書いたりして機能しなかったです。最終的にメソッド等の API 仕様とその完了条件について合意ができればよいので、 "テスト" と言わずにテスト的なコードを実装してもらった方が機能するかもしれません。

retrospect : タスク、あるいはサブタスクが完了した段階で「何がうまくいったか」「いかなかったか」を列挙してもらい、それらを task.md あるいは CLAUDE.md などに反映するよう依頼します。これを実行後は /compact で圧縮するという流れを取っています。ポイントとして、どうにもうまくいかなくて /clear する前も同じことをします (テストコードでチートをしたとか)。これにより望まない挙動をどんどん抑えることが出来ます。体感として 3~4 周ぐらいすると Sonnet でも割と意図した挙動になります。

AAM としてワークフローを整えるにあたり重要なこと

前述の通り、AI Agent が意図した実装をするようコマンドとコマンドの実行順を整えることが重要だと考えています。これが出来てしまえば、パラレルでの仕事依頼も楽になります。最終的には、1 コマンド (test や review など) を担当する特化したエージェントが必要になると考えており、この時 Fine Tuning が必要不可欠になると考えています。つまり、次 3 点が AAM として重要なオペレーションになります。

• コマンドを定義する
• コマンドをつなげてワークフローを作る
• コマンドの執行に特化した Agent を構築する

です。実際 Agent を使った方は感じると思いますが test でテストコードをハックしたり review で曖昧な指摘をして coding agent が不用意なコード修正をして品質が下がるデフレスパイラルの発生はよくあります。これらは、RAG / MCP Server による外部知識だけで矯正するのはおそらく困難で、振る舞いを学ばせる instruction tuning が必要になってくると考えています。このチューニングのオペレーションの必要性を挙げているのが 3 で、この点を使いこなせるかは開発生産性に大きな影響を与えると思います

AI Agent Manager として求められるスキル

AAM にとって最重要なスキルは、AI Agent による開発の生産性を最大限向上させることです。人間と同じよう、作業環境とワークフローの設計はその中でも重要な仕事になります。自動化の最大の障壁がテストとレビューと考えており、これらを人間の手がなくパスできるようにするのは大きなチャレンジと認識しており、場合によってモデルチューニングの知識が必要になると思います。将来的なスキル要件は次のようになるのではないでしょうか。

1. 作業環境の準備
   • 並行作業が可能な環境の設計 : Docker + Remote SSH による個別 AI Agent の開発環境の実現
   • ユニバーサルなオンボーディングの実装 : Agent の特性ごと異なる CLAUDE.md 等の制御ファイルをデザインする、MCP Server を通じた配布などを行う
   • コンテキスト取得環境の拡充 : MCP Server を拡充し人間同等以上のコンテキストを得られるようにする
   • コスト最適化 : 定額のサブスクリプションは上限まで使い切っている場合を除きコスト効率が悪いため、従量課金とのミックスにより AI Agent にかかるコストを最適化する
2. ワークフローの設計
   • コマンド/プロセス設計 : 人間の作成する仕様を可能な限り Automatic に処理していくための効果的な作業単位 (Command) とその連結、連結をするためのツールセットの実装 (LangGraph 的な処理など)
   • 成果物のマージ戦略 : 個別環境で開発した成果物をどのようにコンフリクトなくマージしていくのかの設計
   • ナレッジのマージ戦略 : 個別環境で得た working / not working の知見を統合的な制御ファイルへどう反映するか (Federated Learning 戦略)
   • プロセス最適化 : Claude 使うまでもない処理など、必要十分なモデルのアロケーションにより Cost per Issue をさいてきかすｒ
   • 最適化の研究 : 各作業の品質を向上させるための特化型プロンプト、また Fine Tuning による性能向上の研究開発など

全体としては生産性として Time per Issue 、品質として Human Review per Pull Request の最小化が大きな KPI になると思います。

まだ新米 AAM の今日この頃ですが、働きやすく成果の出る環境めざして知見をためていく所存です！