AIコーディングエージェントを「チームの資産」にする3つの設計パターン

こんにちは。クラウドエース株式会社 第一開発部の喜村です。
日ごろの開発や運用で AIDD（ AI 駆動開発）を意識しながら業務を進める中で、ナレッジ共有の仕組みを考えてみました。

はじめに

Claude Code や Cursor のようなAIコーディングエージェントは、日々の開発やインフラ運用でもう手放せない存在になりました。一方で、継続的なクライアントワークでAIエージェントを使い込んでいくと、ある共通の壁にぶつかります。

「このエージェント、毎回ゼロから話を聞いている気がする」

チケット対応で得た知見も、障害調査で得た勘所も、セッションが終わればそのエージェントの中には残りません。次に似た対応をするときは、また一から状況を説明し、また一から調べ直すことになります。これは人間のチームで言えば、優秀な担当者が毎回記憶喪失で出社してくるようなものです。

この記事では、あるクライアントの継続案件でAIエージェント運用の基盤を作る中で見えてきた、「AIエージェントをチームの資産として育てる」ための3つの設計パターンを紹介します。特定のツールやクライアントに依存しない、リポジトリ構造だけで実現できる話です。

考え方のベースには、弊社公式 note の AI 駆動開発の全体像#6 探索と収束を「同じ仕組み」で回す があります。同記事で述べられている「決めごとをファイルとして管理し、探索で得た知見を積み上げていく」という発想を、継続案件におけるAIエージェント運用の現場に落とし込んで考えています。

なお、ここで紹介する仕組みはまだ運用を始めたばかりの「たたき台」段階であり、完成形ではなく改善の余地しかないものだという前提でお読みください。それでも仮説として共有する価値はあると考え、現時点の形をまとめています。

発想の転換：AIエージェントを「育つ新人」として扱う

人間の新人が入社したとき、私たちは何をするでしょうか。役割ごとのオンボーディング資料を渡し、過去の対応事例を共有し、わからないことは先輩に聞ける状態を作ります。そして新人自身も、対応した案件をメモに残し、次第に自分の判断で動けるようになっていきます。

AIエージェントに対しても、同じことをリポジトリ構造としてやってあげればいい——これが出発点になった発想です。エージェントの「記憶」をセッションやモデルの中に期待するのではなく、Gitリポジトリという外部の記憶装置に持たせるわけです。

具体的には、次の3つの設計パターンに落とし込みました。

パターン1：役割ごとの作業ディレクトリ

まず、エージェントが担う役割（ユースケース）ごとにディレクトリを切り、それぞれに「役割定義」「手順書」「作業用の3分割フォルダ」を持たせます。

agents/
└── <ユースケース名>/
    ├── AGENT.md      # このエージェントの役割・使い方
    ├── playbooks/    # 実際の作業手順（積み上がっていく）
    ├── inbox/        # インプット資料（読み込ませたい入力）
    ├── work/         # やり取り中の作業ファイル（一時領域）
    └── outbox/       # 完成したアウトプット

ポイントは inbox → work → outbox という一方向の流れと、work/ だけは意図的にバージョン管理から外すことです。作業中のファイルは個人的・一時的なものになりがちで、複数人がAIエージェントを並行して使うチームでは、ここをバージョン管理下に置くとコンフリクトの温床になります。逆に inbox（入力）と outbox（成果物）はチームで共有する価値があるため、通常どおりGit管理下に置きます。

「何でもGitで管理する」のではなく、衝突しやすいものは意図的に管理外にするという線引きが、地味ですがチーム運用では効いてきます。

パターン2：単一の知識源と、ツールを乗り換えても失われないアダプタ設計

2つ目は、ナレッジを1箇所に集約するパターンです。

knowledge/
├── domain/       # 用語集など、全ユースケース横断の知識
├── constraints/  # アカウント・権限・体制などの制約
└── work-log/     # 過去の対応の生ログ（蓄積されていく資産）

ここで重要なのは、AIツールごとの設定ファイル（Cursorのルールファイル、Claude Codeの CLAUDE.md など）にナレッジそのものを書かないということです。ツールの設定ファイルは、あくまで「ここを見に行ってください」と指し示す薄いアダプタに徹させ、知識の本体は knowledge/ に一本化します。

[ツールA用ルールファイル] ─┐
                          ├─→ knowledge/ （唯一の知識源）
[ツールB用ルールファイル] ─┘

こうしておくと、チームが使うAIツールが変わっても（CursorからClaude Codeへ、あるいはその逆へ）、アダプタを1枚差し替えるだけで済み、蓄積したナレッジ自体は失われません。ツールの主導権争いから、ナレッジを切り離しておくということです。

イメージを掴みやすくするために、複数案件で見られた要素を合成した架空の例を載せます（実在の案件・企業・システムとは無関係です）。

# CLAUDE.md

このファイルは、Claude Code がこのリポジトリで作業する際のガイダンスを提供します。

## このリポジトリについて

架空案件（複数マイクロサービスの運用支援）における、チームメンバー向けAIエージェント基盤。
ルール・エージェント定義・ナレッジを一元管理する。

## マルチルートワークスペース構成

このリポジトリは単独ではなく、マルチルートワークスペースで運用する。

| フォルダ名 | リモート | 内容 |
|---|---|---|
| `agent-workspace` | 社内GitLab | このリポジトリ（作業ブランチ運用） |
| `deploy-manifest` | パートナー先GitLab | 各サービスのデプロイマニフェスト |

## git 運用（重要）

2つのリポジトリは git が完全に独立しており、push先が異なる。操作前に必ずリモートを確認すること。

### ブランチ運用

`agent-workspace` は2段階構成：`feature/*` → `working` → `main`

- 日常的なルール・ナレッジ更新は `working` ブランチへ（チーム内レビューのみ）
- `working` → `main` は先方承認が必要。内容が固まったタイミングで出す

## エージェント構成とナレッジの場所

    agents/
    ├── billing/   # 請求系サービス
    ├── auth/      # 認証基盤
    └── infra/     # インフラ・デプロイ

    knowledge/
    ├── domain/       # 全サービス横断の用語集・コーディングルール
    └── constraints/  # 環境・権限制約

ナレッジ追加時は `knowledge/` 配下の適切なディレクトリへ追記し、MRを出す。

## デプロイ依頼対応の2ステップフロー

1. **レビュー提示**（ファイル変更なし）：対象ファイル・変更内容・コミットメッセージ・ブランチ名を提示
2. **了承後に一括実行**：ブランチ作成 → ファイル修正 → commit → push

ポイントは、CLAUDE.md 自体には「どこに何のルールが書いてあるか」という目次以上の情報を持たせず、実際のドメイン知識やデプロイ手順の詳細は knowledge/ や agents/<ドメイン>/ の側に置いていることです。この薄さが、ツールを乗り換えるときの身軽さに直結します。

パターン3：記録専任エージェントによる二段階の知識蓄積

3つ目が、個人的には一番効いていると感じているパターンです。

知見を資産化する上で最大の敵は「面倒くささ」です。対応が終わった後に「このケースはナレッジ化する価値があるか」を毎回判断させようとすると、判断コストが高くて誰もやらなくなります。

そこで、記録を 「機械的に記録するだけの係」 と 「たまに選んで昇華させる係」 の二段階に分けました。

• 記録係エージェント：判断は一切せず、対応が一段落するたびに knowledge/work-log/ へ1件ずつ機械的にログを追記するだけの専任エージェント。「何をした・何が起きた・詰まった点」を3行程度で書くだけなので、ほぼ思考コストがかからない。
• ナレッジ化プロンプト：work-log が溜まってきて、同じパターンが何度も出てきたときに初めて、人間が取捨選択しながら playbooks/ や knowledge/ へ昇華させる。

対応完了
  → 記録係が work-log に1件記録（機械的・判断不要・毎回やる）
       → パターンが見えてきたら
            → 人間が選んでplaybook/knowledgeへ昇華（たまに・判断が必要）

「とりあえず全部記録する」ハードルを極限まで下げつつ、「価値あるものだけを整理された知識にする」判断は別のタイミングに切り離す。この二段構えによって、ナレッジ化するほどではない個別ケースも、後で検索できる資産として残せるようになります。

ガードレール：自律と承認のバランス

ここまでの仕組みは、エージェントに「自律的に動いてよい範囲」を広げるための土台でもあります。だからこそ、ガードレールもセットで決めておく必要があります。

• 読み取り・調査は自律実行可：検索・閲覧・過去ログの参照は、都度確認を挟まずエージェントに任せる
• 書き込みは承認制：ファイル変更・送信・作成・削除など、あらゆる変更操作は内容をドラフト提示してから承認を得て実行する
• 本番影響のある操作は必ず事前レビュー：権限変更やインフラの本番適用など、取り返しがつきにくい操作は、通常の承認よりさらに一段階厚いレビューを挟む

「知見を蓄積して賢くなったエージェントに、どこまで裁量を渡すか」は、蓄積の仕組みとセットで設計しておかないと、賢くなるほど怖くなる仕組みになってしまいます。

この形が「正解」かは、正直まだわからない

ここまで3つのパターンを整理してきましたが、これが最適解だと言い切る自信はありません。

• inbox / work / outbox の3分割は本当にこの粒度でいいのか、もっと少なくても回るのではないか
• knowledge/domain と constraints の切り分けは、ナレッジが増えたときに破綻しないか
• 記録係エージェントによる二段階運用も、チーム規模が大きくなったときに同じように機能するのか

といった問いには、まだ自分の中で答えが出ていません。今のところ小規模なチームでうまく回っているというだけで、別のクライアント・別の規模で同じ構造を持ち込んだときに同じように機能するかは未検証です。

「現時点で試している仮説の1つ」くらいの温度感で読んでもらえると、実態に近いと思います。

それでも、動かしながら検証してみる価値はあると思っています。最初から完成形を狙うのではなく、うまくいかなかった部分は都度見直せばいい。むしろ、やってみないことには「どこが破綻するか」すら分からないというのが実感です。失敗も含めて、まず小さく試してみることの方が、机上で正解を探し続けるより早く前に進めます。

おわりに：小さく始めて、使いながら育てる

この3つのパターンに共通しているのは、特別なツールやプラットフォームを必要としないということです。必要なのは、Gitリポジトリと、フォルダを分ける規律、そして「機械的な記録」と「人間の取捨選択」を分けるという運用ルールだけです。

紹介した仕組み自体も、最初から完璧な形で導入したわけではありません。今もまだ「少人数チームだから」で済ませている簡易な運用がありますし、整理しきれていないメモも残っています。それでも、"エージェントが記憶をなくさない仕組み" を先に作ってしまうことで、使えば使うほどチームとエージェントの両方が賢くなっていく状態には近づけたと感じています。

もし皆さんのプロジェクトでも「AIエージェントに聞いたことが、また同じことを聞き返される」という状況に心当たりがあれば、まずは work/ を切り出してGit管理から外すところからでも、試してみてもらえると嬉しいです。