AIエージェントアーキテクト入門

AI駆動開発で成果を出すには、「AIに何を指示するか」だけでなく「AIが最大限の力を発揮できる環境をどう設計するか」が鍵です。このページでは、AIエージェントをアーキテクトする上で意識すべき5つの観点を解説します。

なぜ「5つの観点」が必要なのか

Claude Code をインストールして対話するだけでも AI の恩恵は得られます。しかし、プロジェクトが大規模化しチームで運用するにつれ、以下の課題が顕在化します。

5つの観点の全体像

5つの観点は独立した要素ではなく、土台から順に積み上げる構造です。観点1の最適化が観点2〜4の効果を高め、観点5で全体をチームに展開します。

観点 1: トークン消費を最適化する

Rules のパス別適用でコンテキストを節約

全てのルールを常時読み込むのではなく、paths フロントマターで対象ファイルを絞ります。

---
paths:
  - "src/api/**/*.ts"
---
# API 開発ルール
- 全エンドポイントに入力バリデーションを実装する
- 統一されたエラーレスポンス形式を使用する

API ファイルを触るときだけこのルールが読み込まれ、フロントエンド作業時にはコンテキストを消費しません。

サブエージェントによる隔離コンテキスト

メインの会話コンテキストを汚さずに、専門作業を別のエージェントに委譲できます。各サブエージェントは独立したコンテキストで動作するため、メインエージェントのトークンを消費しません。

Skills のオンデマンド読み込み

Skills は呼び出されたときだけコンテキストに読み込まれます。CLAUDE.md に全ての専門知識を詰め込むのではなく、Skills に分離することで普段のトークン消費を抑えられます。

観点 2: 対応範囲を拡張し品質を向上させる

レビュー専門サブエージェントの準備

コードを書くエージェントとレビューするエージェントを分離します。人間のチーム開発と同じように、AI にも「実装者」と「レビュアー」の役割分担を設計します。

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: コードの品質レビューを実施する専門エージェント
---
実装されたコードを以下の観点でレビューしてください:
- ロジックの正確性
- セキュリティ脆弱性（SQLインジェクション、XSS 等）
- パフォーマンス問題（N+1 クエリ、メモリリーク等）
- コーディング規約準拠（.claude/rules/ 参照）

指摘には 🔴 Critical / 🟡 Warning / 🔵 Suggestion のレベルを付与してください。

レビュー用 Skills・カスタムコマンドの準備

定型的なレビュー手順を Skills やカスタムコマンドとして形式知化します。誰が実行しても同じ品質のレビューが行われます。

/code-review #42
/fix-pr-review #42
/security-check

/simplify
/explain-code src/app.ts

Hooks によるゲートウェイ整備

CLAUDE.md やルールは「指示」ですが、Hooks は「仕組みで強制する」ガードレールです。AI がコードを書いた後、コミット前に自動で品質チェックを実行します。

// .claude/settings.json（hooks セクション）
{
  "hooks": {
    "PreCommit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run test:affected"
          }
        ]
      }
    ]
  }
}

観点 3: 外部ソースを読み込ませる

MCP（Model Context Protocol）による外部連携

MCP は AI に外部サービスへのアクセスを提供する標準プロトコルです。.mcp.json に設定するだけで、AI が GitHub、DB、ドキュメントサイト等を直接参照できるようになります。

// .mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "..." }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."]
    }
  }
}

CLI ツール + Skills による外部情報取得

MCP サーバーが存在しないツールでも、CLI コマンドをインストールし Skills から実行させることで AI の対応範囲を拡張できます。

# .claude/skills/aws-check/SKILL.md
---
name: aws-check
description: AWS リソースの状態を確認するスキル
---
以下のコマンドを実行して AWS リソースの状態を確認してください:

```bash
# ECS サービスの一覧
aws ecs list-services --cluster production

# RDS インスタンスの状態
aws rds describe-db-instances --query 'DBInstances[].{ID:DBInstanceIdentifier,Status:DBInstanceStatus}'

# 直近のデプロイ状況
aws ecs describe-services --cluster production --services api-service
```

結果を要約し、異常がある場合は警告してください。

観点 4: 継続学習させる仕組みを作る

学習サイクル

学習の永続化先

レビューで発見した知見を、適切な場所に永続化します。

実践例: レビューから学習への流れ

観点 5: チーム全体へ展開する

Git で共有される設定ファイル群

観点1〜4で作成した成果物は全て .claude/ ディレクトリと .mcp.json に集約されます。Git にコミットするだけでチーム全員に配布されます。

.claude/
├── CLAUDE.md          ← 観点4: 学習結果の蓄積先
├── rules/             ← 観点1: パス別トークン最適化 + 観点4: ルール蓄積
│   ├── security.md
│   ├── database.md        （paths: "src/db/**/*"）
│   └── api.md             （paths: "src/api/**/*"）
├── settings.json      ← 観点2: Hooks による品質ゲート
├── commands/          ← 観点2: レビュー・作業の標準化
│   ├── code-review.md
│   └── dev-issue.md
├── agents/            ← 観点1,2: 隔離コンテキスト + レビュー専門
│   ├── code-reviewer.md
│   └── security-reviewer.md
└── skills/            ← 観点1,3: オンデマンド知識 + 外部ツール
    ├── explain-code/
    └── aws-check/
.mcp.json              ← 観点3: 外部ソース連携

ゼロコンフィグ・オンボーディング

新メンバーは以下の3ステップだけで、シニアエンジニアと全く同じ AI 環境を手に入れます。

git clone && cd project

claude

/dev-issue #42

Plugins による複数プロジェクトへの横展開

社内の複数プロジェクトで共通のルール・エージェント・スキルがある場合、Plugins としてパッケージ化することで一括配布・アップデートが可能です。

5つの観点の成熟度モデル

5つの観点は一度に全て導入する必要はありません。現在のチームの状況に応じて段階的に導入してください。

次のステップ

5つの観点を理解したら、具体的な実装例で手を動かしましょう。以下のページでは、これらの観点を実際のプロジェクトにどう適用するかを設定ファイル全文付きで解説しています。