Claude & Jozo · 9 min read · 2026/02/12

AIエージェントCharacterデザイン開発方法論

Characterデザイン方法論：本当に機能するAIエージェントの作り方

ほとんどのAIエージェントチュートリアルは、ツールの設定から始まります。このMCPサーバーを接続する。あのskillを登録する。これらのプロンプトを設定する。

そしてユーザーは首をかしげます。「マーケティングディレクター」エージェントがある日はSendGrid経由でメールを送り、翌日はMailgun経由で送るのはなぜか。「SEOアナリスト」がGoogle Analyticsを照会したり、Search Consoleを照会したり、時にはメトリクスをでっち上げたりするのはなぜか。

エージェントは理論上は有能です。メールツールもあります。アナリティクスへのアクセスもあります。しかし、信頼性を持って機能しません。

TeamDayで14体のAI Characterを構築して学んだことがあります：問題はツールではありません。問題は方法論です。

抽象化の罠

AIエージェントのエコシステムは分類法を好みます。ツールvsMCPサーバーvsskillsvsプラグインvsプロンプト。開発者はメールをMCPツールにすべきか、bashスクリプトのskillにすべきかを何時間も議論します。

ビジネスユーザーの視点では、これらの違いは無意味です。

誰かがマーケティングディレクターに「週次レポートを送って」と頼むとき、メールが以下のいずれで送られようと気にしません：

Resend APIを呼び出すMCPツール
bash curlコマンドを実行するskill
環境変数の認証情報を使うTypeScriptスクリプト
sendmail経由の直接SMTP

重要なのは、メールが送られるかどうかです。正確に。毎回。

抽象化を取り除けば、正確に2つのプリミティブが残ります：

1. 実行可能な関数 — 実行して結果を返すコード（ツール、MCPツール、bashコマンド、スクリプト）

2. プロンプトテキスト — AIが読んで従う指示（システムプロンプト、skills、CLAUDE.mdファイル）

それ以外はすべて、この2つのプリミティブを包むパッケージと組織構造です。

抽象化の罠は、信頼性（本当に機能するか？）ではなく、分類法（ツールタイプの選択）のために最適化するときに発生します。

動作するサンプルの原則

AIエージェントの能力の真の単位はこれです：

認証情報を含む動作するサンプル。

ツールの登録ではありません。MCPサーバーの設定でもありません。skillの説明でもありません。

動作するサンプルはこのようなものです：

# Resend経由でメールを送信
curl -X POST https://api.resend.com/emails \
  -H "Authorization: Bearer $RESEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "週次レポート",
    "html": "<p>内容はこちら</p>"
  }'

# 期待されるレスポンス：
# {"id": "abc-123", "status": "sent"}

# 認証情報：.envのRESEND_API_KEY
# 最終テスト：2026-02-10
# 担当：マーケティングチーム

動作するサンプルがなければ、Claudeは1000の選択肢から恣意的に選びます。動作するサンプルがあれば、毎回実証済みのパターンに従います。

「理論上はメールを送れる」と「私たちの認証情報を使ってResend経由で確実にメールを送れる」の違いは、テスト済みで文書化された動作するサンプルです。

レシピモデル

レシピとは、特定のタスクのためのテスト済みの動作するサンプルです。

マーケティングディレクターCharacterには以下のレシピがあります：

Resend経由でメールを送信（テスト済み、envに認証情報あり）
Search Console APIを照会（テスト済み、OAuth設定済み）
Ahrefsでキーワードを分析（テスト済み、envにAPIキーあり）
Google Analyticsデータを取得（テスト済み、プロパティIDが文書化されている）

各レシピには以下が含まれます：

使用するタイミング — 「トランザクションメールの送信に使用」
認証情報の参照 — 「APIキー：RESEND_API_KEY（.env内）」
動作するサンプル — 実際に動作するcurlコマンドまたはコードスニペット
期待されるレスポンス — 成功がどのように見えるか
最終テスト — 実際に機能することを確認した日付

レシピは抽象的なツールの定義ではありません。実際に実行したからこそ機能することがわかっている、具体的でテスト済みの手順です。

レシピがアトミックな構成要素です。Characterはその組み合わせです。

ボトムアップCharacterデザイン

実際に機能する方法論はこちらです：

ステップ1：このCharacterは誰か？

抽象的な能力ではありません。具体的な役割と目的。

悪い例：「マーケティング能力を持つAIアシスタント」

良い例：「ステークホルダーに週次パフォーマンスレポートを送るマーケティングディレクター」

役割が明確なほど、設計が容易になります。

ステップ2：この役割が実際に行うタスクは何か？

理論上できることではありません。火曜日の朝に文字通り行うこと。

マーケティングディレクターの場合：

キャンペーンパフォーマンスを確認（月曜日9時）
オーガニックトラフィックのトレンドをレビュー（毎日）
ステークホルダーに週次レポートを送信（金曜日16時）
キーワードランキングを分析（依頼時）

これらはタスクであり、ツールではありません。「キャンペーンパフォーマンスを確認する」は行うべき仕事です。それにGoogle Ads APIを使うか、Search Consoleを使うか、両方使うかは実装の詳細です。

ステップ3：実際の人間はこれらのタスクをどのように行うか？

ここでテクスタックについて具体的になります。

「キャンペーンパフォーマンスを確認する」の場合：

実際の人間がGoogle Analyticsにログイン
過去7日間のトラフィックを表示
前の期間と比較
重要な変化をメモ

技術的な翻訳：

Google Analytics APIを照会
プロパティID：478766521
メトリクス：セッション、ページビュー、直帰率
日付範囲：過去7日間 vs 前の7日間
OAuth認証情報が必要

これで構築すべきレシピがわかりました。

ステップ4：テクスタックがこれをサポートするか？

ランタイム環境からこれらのAPIにアクセスできますか？

確認：

認証情報はありますか？（.envを確認、OAuthセットアップを確認）
サンドボックスからAPIを呼び出せますか？（curlコマンドをテスト）
必要なパッケージはインストールされていますか？（Dockerイメージを確認または必要時にインストール）

答えがいいえの場合：

ランタイムに機能を追加する（パッケージをインストール、OAuthを設定）
別のアプローチを使用する（重い依存関係がある場合はMCPサーバー）
Characterの役割を調整する（制限を認める）

ランタイムの現実が可能なことを制約します。psqlがサンドボックスにインストールされていなければ、どれだけプロンプトエンジニアリングをしてもClaudeにデータベースアクセスは与えられません。

ステップ5：レシピを書いてテストする

これが多くの人が飛ばす重要なステップです。

書いてはいけない例：

エージェントはAPIを使ってGoogle Analyticsを照会できます。

書くべき例：

# Google Analyticsを照会 — 過去7日間のトラフィック
curl -H "Authorization: Bearer $GA_ACCESS_TOKEN" \
  "https://analyticsdata.googleapis.com/v1beta/properties/478766521:runReport" \
  -d '{
    "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
    "metrics": [{"name": "sessions"}]
  }'

# 最終テスト：2026-02-10（動作確認済み）
# 担当：マーケティングチーム
# 認証情報：OAuthのGA_ACCESS_TOKEN（有効期限1時間）

次に実際に実行します。機能することを確認します。壊れているものを修正します。機能するバージョンを文書化します。

レシピはテストされて初めて本物になります。

ステップ6：Characterを組み立てる

これで揃いました：

明確な役割（マーケティングディレクター）
具体的なタスク（週次レポート、トラフィック分析）
テスト済みのレシピ（Search Console、Analytics、Resend）

Characterはこの組み合わせです：

# マーケティングディレクターCharacter

## 役割
あなたはTeamDayのマーケティングディレクターです。パフォーマンスを
監視し、トレンドを分析し、ステークホルダーにインサイトを伝えます。

## 主な責任
- 週次パフォーマンスレポートを送信（金曜日16時）
- オーガニックトラフィックを毎日監視
- 依頼に応じてキーワードランキングを分析

## 利用可能なレシピ

### Resend経由でメールを送信
使用時：ステークホルダーへの更新送信時
レシピ：/recipes/send-email-resend.md

### Search Consoleを照会
使用時：オーガニックトラフィックやキーワードの分析時
レシピ：/recipes/search-console-query.md

### Google Analyticsを取得
使用時：全体的なトラフィックトレンドの確認時
レシピ：/recipes/google-analytics-query.md

## コミュニケーションスタイル
- 直接的で、企業用語なし
- 数字から始める（「先週比+15%のトラフィック」）
- 何が変わったかとその重要性を説明する

Characterはレシピを参照します。レシピには動作するサンプルが含まれます。

これが実際に機能するCharacterの構築方法です。

テクスタックの重複による再利用性

ここでレシピモデルの価値が発揮されます。

マーケティングディレクターはSearch Consoleへのアクセスが必要です。SEOアナリストもSearch Consoleへのアクセスが必要です。同じレシピ。

営業担当者はメールを送る必要があります。マーケティングディレクターもメールを送る必要があります。同じレシピ。

レシピは自然にライブラリになります：

/recipes/
├── send-email-resend.md
├── search-console-query.md
├── google-analytics-query.md
├── ahrefs-keyword-analysis.md
├── postgres-query.md
└── notion-page-create.md

新しいCharacterはおそらく1〜2個の新しいレシピを追加します。ほとんどは再利用されます。

**ただし、これはレシピがテスト済みの動作するサンプルである場合にのみ機能します。**抽象的なツールの定義であれば、そもそも信頼性を持って機能しないため再利用性は意味をなしません。

品質ゲート

Characterの能力は、テスト済みレシピと同じくらいしか実在しません。

問うべき質問：

「このCharacterはメールが設定されているか？」ではなく

「メールレシピが実際にメールを送ることを確認したか？」と問うべきです。

「このCharacterはデータベースにアクセスできるか？」ではなく

「実際の認証情報でデータベースクエリレシピをテストしたか？」と問うべきです。

ファサードであるCharacterと成果を出すCharacterの違いは、テスト済みレシピです。

これを痛い経験から学びました。マーケティングサイトの/teamページ用にCharacterを構築しました。見栄えは素晴らしかった。14体の雇用可能なAI社員。プロフェッショナルな説明文。印象的な能力。

実際の仕事に使おうとしたとき、ほとんどがエンドツーエンドで機能しませんでした。依存関係の欠如。未テストのレシピ。動作するサンプルのない抽象的な能力。

品質ゲート：テストしていないものはリリースしない。

ランタイムの現実：実際に可能なこと

サンドボックス環境が可能なことを制約します。これらの制約を理解することで、より良いCharacterデザインが生まれます。

どこでも機能するもの

curl経由のHTTP API：

curl -H "Authorization: Bearer $API_KEY" https://api.example.com/endpoint

すべてのサンドボックスにcurlがあります。HTTPでAPIにアクセスできれば、統合できます。

Bashスクリプト：

#!/bin/bash
# スクリプト化できるロジックはサンドボックスで動作する

一般的なCLIツール：

git, grep, sed, awk, jq, node, python

セットアップが必要なもの

データベースクライアント：

psqlまたはmysqlのインストールが必要
オプション1：Dockerイメージに事前インストール
オプション2：HTTP APIラッパー（pg-gateway）
オプション3：複雑なクエリ用MCPサーバー

重いパッケージ（Puppeteer、Playwright）：

大きな依存関係ツリー
バイナリ依存関係（Chrome）
オプション1：ベースイメージに事前インストール（よく使われる場合）
オプション2：MCPサーバー（分離され、個別に管理）

OAuthフロー：

インタラクティブ認証
トークンリフレッシュロジック
オプション1：トークンを事前設定（環境変数）
オプション2：MCPサーバーが認証を処理

実用的な意思決定ツリー

curlでできるか？ → レシピを書き、テストし、完了
50MB未満のパッケージが必要か？ → Dockerイメージにインストール
重い依存関係が必要か？ → MCPサーバー（最終手段）
インタラクティブ認証が必要か？ → MCPサーバーまたは事前設定トークン

ランタイム要件がシンプルなほど、Characterの信頼性が高くなります。

一般的な構築方法との違い

トップダウン（一般的なアプローチ）：

AIエージェントフレームワークを選択
MCPサーバーを設定
skillsとツールを追加
システムプロンプトを書く
機能することを期待する

問題点：

ツールは設定されているがテストされていない
動作するサンプルなし、抽象的な能力のみ
Characterは理論上は何でもできるが、確実には何もできない
最初の実際の使用で機能しないことが判明

ボトムアップ（私たちのアプローチ）：

具体的な役割とタスクを定義する
タスクを実際の人間のワークフローにマッピングする
各ワークフローをテストして検証する（レシピを書く）
テスト済みレシピからCharacterを組み立てる
品質ゲート：すべての能力が検証済み

結果：

すべてのレシピがテスト済みで機能することがわかっている
Characterの能力がテスト済みの現実と一致している
レシピが検証済みなので最初の使用が機能する
壊れたとき、どのレシピを修正すべきかわかる

方法論はプロセスを逆転させます：検証済みのワークフローから始め、Characterへと上向きに組み立てる — ツールをトップダウンで設定して期待するのではなく。

実際の例：マーケティングディレクター

私たちのCharacterの一体における実際の設計プロセスをお見せします。

ステップ1：役割の定義

誰： TeamDayのマーケティングディレクター 目的： マーケティングパフォーマンスの監視とインサイトの伝達

ステップ2：実際のタスク

実際のマーケティング業務を観察した後：

トラフィックトレンドのためにGoogle Analyticsを確認（毎日）
オーガニックキーワードランキングのためにSearch Consoleを監視（毎週）
パフォーマンスレポートをステークホルダーに送信（毎週）
依頼に応じて特定のキャンペーンを分析

ステップ3：実際の人間のワークフロー

「週次レポートを送信する」の場合：

人間がGoogle Analyticsにログイン
過去7日間を表示：セッション、ページビュー、上位ページ
前の週と比較
重要な変化をメモ
上位クエリのためにSearch Consoleを確認
発見事項を含むメールを作成
Gmail経由で送信

ステップ4：テクスタックの確認

Google Analytics：

✅ APIアクセスあり
✅ プロパティID：478766521
✅ OAuth設定済み
✅ curl経由で照会可能

Search Console：

✅ APIアクセスあり
✅ サイト：teamday.ai
✅ OAuth設定済み
✅ curl経由で照会可能

メール：

✅ Resendを使用（Gmailではない）
✅ envにAPIキーあり：RESEND_API_KEY
✅ curl経由で送信可能

ステップ5：レシピを書く

レシピ1：Google Analytics — 過去7日間

#!/bin/bash
# Google Analyticsから過去7日間のトラフィックを取得

curl -H "Authorization: Bearer $GA_ACCESS_TOKEN" \
  "https://analyticsdata.googleapis.com/v1beta/properties/478766521:runReport" \
  -d '{
    "dateRanges": [
      {"startDate": "7daysAgo", "endDate": "today"},
      {"startDate": "14daysAgo", "endDate": "8daysAgo"}
    ],
    "metrics": [
      {"name": "sessions"},
      {"name": "totalUsers"},
      {"name": "screenPageViews"}
    ],
    "dimensions": [{"name": "pagePath"}]
  }'

# テスト結果（2026-02-10）：
# {
#   "rows": [
#     {"dimensionValues": [{"value": "/"}],
#      "metricValues": [{"value": "1243"}, {"value": "892"}, ...]}
#   ]
# }

# 認証情報：GA_ACCESS_TOKEN（OAuth、有効期限1時間）

テスト済み： ✅ 機能する 最終確認： 2026/02/10

レシピ2：Resend経由でメールを送信

#!/bin/bash
# Resend APIでメールを送信

TO="$1"
SUBJECT="$2"
BODY="$3"

curl -X POST https://api.resend.com/emails \
  -H "Authorization: Bearer $RESEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"from\": \"[email protected]\",
    \"to\": \"$TO\",
    \"subject\": \"$SUBJECT\",
    \"html\": \"$BODY\"
  }"

# テスト結果（2026-02-10）：
# {"id": "abc-123", "status": "sent"}

# 認証情報：.envのRESEND_API_KEY

テスト済み： ✅ 機能する 最終確認： 2026/02/10

ステップ6：Characterを組み立てる

# マーケティングディレクター

あなたはTeamDayのマーケティングディレクターです。パフォーマンスを
監視し、インサイトを伝えます。

## 週次レポートタスク

毎週金曜日16時：

1. Google Analyticsを照会（過去7日間 vs 前の期間）
   レシピ：/recipes/google-analytics-7day.sh

2. Search Consoleを照会（上位オーガニッククエリ）
   レシピ：/recipes/search-console-top-queries.sh

3. メールを作成：
   - 件名：「TeamDay マーケティングレポート — [日付]の週」
   - フォーマット：
     **トラフィック：** [セッション数]（先週比[+/-]%）
     **上位ページ：** [上位3件のリスト]
     **上位クエリ：** [上位3件のリスト]
     **注目の変化：** [20%超の変化があるもの]

4. Resend経由で送信
   レシピ：/recipes/send-email-resend.sh
   宛先：jozo at teamday.ai

結果： 各ステップがテスト済みレシピなので、週次レポートを確実に送信するCharacter。

痛い経験から学んだこと

1. 「テスト済み」は本当にテスト済みを意味する

レシピを文書化しました。見栄えは良かった。Characterをリリースしました。

使おうとしたとき、レシピの半分が一度も実行されていませんでした。APIエンドポイントが変わっていました。認証情報が間違っていました。プロパティIDが古くなっていました。

解決策： 各レシピをテストする。実際に実行する。レスポンスを確認する。APIが変わったら更新する。

2. レシピは劣化する

APIは変わります。認証情報は期限切れになります。サービスは廃止されます。

解決策： 各レシピに日付を付ける。Characterが失敗したとき、レシピの日付を確認する。再テストして更新する。

3. ランタイムのギャップは現実的

データベースを照会するSQLアナリストCharacterを設計しました。その後、psqlがサンドボックスにインストールされていないことを発見しました。

解決策： Characterを設計する前にランタイムの能力をテストする。psqlがなければ、インストールするかHTTP APIラッパーを使う。

4. 組み立てが設定に勝る

様々な能力のためにMCPサーバーの設定に何週間も費やしました。複雑なセットアップ。多くの可動部品。

その後、curlコマンドを使ったシンプルなbashスクリプトを書きました。すぐに機能しました。

教訓： シンプルに始める。curlを使ったbashスクリプトで80%の道のりをカバーできます。シンプルが機能しないときだけ複雑さを追加する。

メタインサイト

この方法論全体は、デモが上手くいくだけでなく、本当に機能しなければならないAI Characterを構築することから生まれました。

デモのために構築する場合：

抽象的な能力で十分
「メールを送れる」で十分
設定のスクリーンショットが印象的に見える

本番環境のために構築する場合：

テスト済みレシピが必要
「私たちの認証情報でResend経由で確実にメールを送れる」が基準
設定の複雑さより動作するサンプルが重要

方法論の違い：デモは能力の幅を最適化し、本番は信頼性の深さを最適化します。

私たちはCharacterが実際の仕事をするAIチームを構築しています。それが私たちに信頼性の問題を解決することを強いました。

ボトムアップのレシピファーストの方法論がその結果です。

ぜひ試してみてください

本当に機能するCharacterを構築するには：

具体的な役割を定義する NG：「マーケティングAI」 OK：「週次レポートを送るマーケティングディレクター」
3つの実際のタスクを列挙する NG：「マーケティングデータを分析する」 OK：「Google Analyticsで過去7日間のトラフィックを確認する」
1つの動作するサンプルを書く ツールを文書化しない。機能するcurlコマンドを書く。テストする。レスポンスを確認する。
1つのレシピファイルを作成する 動作するサンプルを/recipes/タスク名.mdとして保存する含める内容：使用タイミング、認証情報、機能するコード、最終テスト日
Characterから参照する システムプロンプトがレシピファイルを参照する Characterはいつ使うか、どう呼び出すかを知っている
エンドツーエンドでテストする 実際にCharacterをタスクに使用する壊れているものを修正するレシピを更新する

1つのタスク、1つのレシピ、1体のCharacterから始める。

確実に機能するものを1つ構築したら、方法論が腑に落ちます。その後、より多くのレシピとCharacterに拡大します。

/teamページには14体のAI Characterがいます。プロフェッショナルに見えます。印象的な能力。しかし学びました：有能に見えることと実際に有能であることは別物です。

実際に機能するものはテスト済みレシピを持っています。ファサードのものは抽象的なツール定義を持っています。

方法論は複雑ではありません：動作するサンプルからボトムアップで、Characterへと組み立て、エンドツーエンドでテストする。

しかし、ほとんどの人がAIエージェントを構築する方法を逆転させます。その逆転がCharacterを信頼できるものにします。

レシピから構築する。すべてをテストする。機能するものをリリースする。