はじめに
AIエージェントを設計するとき、何を書けばいいのか迷いませんか。
「役割を書いて、指示を並べて……」で終わると、汎用的で個性のないエージェントになりがちです。
agency-agentsはOSSのエージェント集です。2026年3月14日時点で144個のエージェント定義を公開しています。
このリポジトリのCONTRIBUTING.mdには、エージェント設計のガイドラインが明文化されています。
本記事ではCONTRIBUTING.mdを読み解き、エージェント設計の5原則を整理します。
実例として「Frontend Developer」エージェントの構造も分析します。
本記事の引用はすべてagency-agents/CONTRIBUTING.md（MITライセンス）に基づきます。
「良いエージェント」の条件
CONTRIBUTING.mdの「What Makes a Great Agent?」セクションでは、良いエージェントの条件を明確に定義しています。
必須要素とアンチパターンを対比表にまとめます。
| 必須要素 | アンチパターン |
|---|---|
| 狭く深い専門化 | 広すぎるスコープ（何でも屋） |
| 個性的な声と人格 | 「I am a helpful assistant」的な汎用人格 |
| 具体的なコード例・テンプレート | コード例や成果物がない |
| 測定可能な成功指標 | 「I will help you with...」的な曖昧な説明 |
| ステップバイステップのワークフロー | 理論だけでテストしていないアプローチ |
| 実運用でのテストと改善 | — |
ここで重要なのは「狭く深い専門家を作る」という思想です。
1つのエージェントに多くの役割を持たせるほど、各タスクの品質は下がります。
逆に、専門領域を絞るほど具体的な指示が書けます。
具体的な指示が書けると、出力の品質が安定します。
この考え方は、ソフトウェア設計の「単一責任原則」と同じです。
クラスに複数の責務を持たせると保守性が下がるように、エージェントも1つの専門に絞るべきです。
エージェントファイルの構造分析
agency-agentsでは、エージェントファイルを2つのグループに分けています。
- Persona（誰か）: エージェントのアイデンティティを定義する
- Operations（何をするか）: エージェントの行動を定義する
Personaグループ
Personaは3つのセクションで構成されます。
Identity & Memory は、役割・性格・背景を定義します。
「フロントエンド開発の専門家」のような役割だけでなく、過去の経験から学習するメモリ機能も含みます。
たとえばFrontend Developerは「成功したUIパターンやパフォーマンス最適化手法を記憶する」と定義しています。
Communication Style は、応答のトーンや声のトーンを定義します。
技術的に正確でありながら親しみやすい、といった方向性を設定します。
Critical Rules は、エージェントが絶対に守るべき制約です。
やってはいけないことを明示することで、出力の暴走を防ぎます。
Operationsグループ
Operationsは5つのセクションで構成されます。
Core Mission は、エージェントの主要な責務を列挙します。
Frontend Developerなら「モダンWebアプリケーションの構築」「パフォーマンスとUXの最適化」などです。
Technical Deliverables は、具体的な成果物を定義します。
コードテンプレート、設定ファイル、チェックリストなど、実際に出力するものを記載します。
Workflow Process は、タスク遂行の手順を定義します。
Discovery（調査）→ Planning（計画）→ Execution（実行）→ Review（レビュー）のような段階的な手順です。
Success Metrics は、成功を判定する測定可能な基準です。
「Lighthouseスコア90以上」のように、達成・未達成が明確に判定できる値を設定します。
Advanced Capabilities は、高度なテクニックや応用スキルです。
YAMLフロントマター
各エージェントファイルの先頭には、メタデータを記述するYAMLフロントマターがあります。
---
name: Agent Name
description: One-line description
color: colorname or "#hexcode"
emoji: 🎯
vibe: One-line personality hook
services: # optional
- name: Service Name
url: https://service-url.com
tier: free
---
nameとdescriptionはエージェントの識別に使います。
colorとemojiはUI表示用です。
vibeはエージェントの個性を1行で表現するフックです。
たとえばFrontend Developerのvibeは「Builds responsive, accessible web apps with pixel-perfect precision.」です。
この1行で、エージェントの方向性が伝わります。
5つの設計原則
CONTRIBUTING.mdの「Agent Design Principles」セクションに基づき、5つの原則を解説します。
原則1: 狭く深い専門化
エージェントの対象範囲を絞るほど、具体的な指示が書けます。
「何でもできるアシスタント」は、結局どのタスクも平均的な品質になります。
「フロントエンド開発に特化したエージェント」なら、React固有のベストプラクティスまで踏み込めます。
なぜ重要か: スコープが狭いほど、プロンプト内に具体的な知識を詰め込めるからです。
原則2: 個性的な声
CONTRIBUTING.mdは「not 'I am a helpful assistant'」と明記しています。
汎用的な口調は、出力の差別化を妨げます。
たとえばEvidence Collectorエージェントは次のように定義しています。
"I default to finding 3-5 issues and require visual proof"
「問題を3〜5件見つけ、視覚的な証拠を求める」という具体的な行動パターンが個性になっています。
こうした定義があると、LLMは一貫した振る舞いを維持しやすくなります。
なぜ重要か: 個性を定義すると、出力の一貫性とブレの少なさが向上するからです。
原則3: 具体的な成果物
エージェントは「アドバイスする存在」ではなく「成果物を出す存在」です。
コード例、テンプレート、フレームワークなど、そのまま使えるものを含めます。
たとえばFrontend Developerは、Reactコンポーネントの雛形やTypeScriptインターフェースを成果物として定義しています。
「良いコードを書きましょう」ではなく、実際のコード例を出力する設計です。
なぜ重要か: 抽象的なアドバイスより、具体的な成果物のほうが実用価値が高いからです。
原則4: 測定可能な指標
成功と失敗を客観的に判定できる基準を設定します。
CONTRIBUTING.mdでは以下の例を挙げています。
- 「Page load times under 3 seconds on 3G」（3G回線で3秒以内のページ読み込み）
- 「10,000+ combined karma across accounts」（アカウント合計カルマ10,000以上）
「パフォーマンスを改善する」ではなく「3G回線で3秒以内」と書くことで、達成判定が明確になります。
なぜ重要か: 曖昧な目標は達成したかどうか判断できず、改善サイクルが回らないからです。
原則5: 実証済みワークフロー
理論上正しいだけでは不十分です。
実際に使って検証済みの手順を記載します。
ステップバイステップで書くことで、エージェントの出力が再現可能になります。
ワークフローは「やったことがある手順」から抽出するのが理想です。
なぜ重要か: 机上の空論ではなく、実運用で動作確認された手順だけが信頼に値するからです。
実例分析: Frontend Developer エージェント
5原則がどのように実装されているか、Frontend Developerエージェントで確認します。
YAMLフロントマター
name: Frontend Developer
description: Expert frontend developer specializing in modern web technologies, React/Vue/Angular frameworks, UI implementation, and performance optimization
color: cyan
emoji: 🖥️
vibe: Builds responsive, accessible web apps with pixel-perfect precision.
descriptionで「modern web technologies, React/Vue/Angular」と技術領域を明示しています。
vibeの「pixel-perfect precision」で、細部にこだわる姿勢を1行で伝えています。
5原則とのマッピング
| 原則 | Frontend Developer での実装 |
|---|---|
| 専門化 | 「Modern web technologies, React/Vue/Angular」に限定 |
| 個性 | 「Detail-oriented, performance-focused, user-centric」 |
| 成果物 | Reactコンポーネント、TypeScriptインターフェース等 |
| 指標 | 「Page load times under 3 seconds on 3G」「Lighthouse 90以上」 |
| ワークフロー | Discovery → Planning → Execution → Review |
Identityの設計
Identity定義を見てみます。
- Role: Modern web application and UI implementation specialist
- Personality: Detail-oriented, performance-focused, user-centric, technically precise
- Memory: 成功したUIパターン、パフォーマンス最適化手法、アクセシビリティのベストプラクティスを記憶する
Personalityに4つの形容詞を並べることで、応答のトーンが決まります。
「Detail-oriented」と「performance-focused」があるため、大雑把な提案は出にくくなります。
Memory定義は、対話を重ねるごとにエージェントが学習する仕組みです。
過去の成功パターンを蓄積し、類似タスクで再利用します。
良い点
- 技術スタックが具体的で、スコープが明確
- 成功指標が数値で定義されている（3秒、90点、WCAG 2.1 AA）
- ワークフローが段階的で再現しやすい
改善の余地
-
descriptionがやや長く、1行で読み切るのが難しい - Personality の形容詞が4つ並んでおり、優先順位が不明確
- Core Missionに「Build editor extensions with navigation commands」があり、フロントエンド開発から少し外れている印象がある
このように、良い設計にも改善点はあります。
完成品として捉えるのではなく、イテレーションで磨く前提で設計するのが現実的です。
自分のプロジェクトに活かす
agency-agentsの設計思想を、自分のエージェント設計に取り入れる方法を紹介します。
エージェント設計テンプレート
以下のテンプレートを起点にしてみてください。
# [エージェント名]
## Identity
- Role: [1文で役割を定義]
- Personality: [2〜3個の形容詞]
- Memory: [何を記憶し、どう活用するか]
## Core Mission
- [主要タスク1]
- [主要タスク2]
- [主要タスク3]
## Technical Deliverables
- [成果物1: コードテンプレート、設定ファイルなど]
- [成果物2]
- [成果物3]
## Workflow Process
1. [調査・情報収集]
2. [計画・設計]
3. [実行・実装]
4. [レビュー・検証]
## Success Metrics
- [測定可能な指標1]
- [測定可能な指標2]
## Critical Rules
- [絶対にやってはいけないこと]
- [必ず守るべき制約]
3ステップで始める
エージェント設計は、最初から完璧を目指す必要はありません。
以下の3ステップで最小限の定義から始められます。
ステップ1: 役割を1文で定義する
「Reactを使ったSPAの開発を担当する」のように、技術領域と範囲を絞ります。
「Web開発全般を担当する」では広すぎます。
ステップ2: 具体的な成果物を3つ列挙する
そのエージェントが実際に出力するものを書きます。
「Reactコンポーネント」「Storybookのストーリーファイル」「Jestテストコード」のような粒度です。
ステップ3: ワークフローを5ステップ以内で書く
タスクの受け取りから完了までの手順を書きます。
最初は粗い粒度で構いません。
使いながら手順を追加・修正していくのが効果的です。
Claude Code / CLAUDE.mdとの組み合わせ
agency-agentsの設計思想は、Claude CodeのCLAUDE.mdにもそのまま応用できます。
CLAUDE.mdにはプロジェクト固有の指示を書けます。
agency-agentsの構造に倣い、以下のように整理すると効果的です。
- Identity: プロジェクトの技術スタック、コーディング規約
- Core Mission: よく行うタスクの種類
- Critical Rules: やってはいけない操作、触ってはいけないファイル
- Success Metrics: テストカバレッジ、ビルド時間の目標値
Claude Code Skillsと組み合わせれば、特定タスクに特化したワークフローを定義することもできます。
agency-agentsの「1エージェント1専門」の考え方は、「1スキル1タスク」にそのまま置き換えられます。
まとめ
agency-agentsのCONTRIBUTING.mdから読み取れるエージェント設計の要点を整理します。
- スコープを絞る: 何でも屋より専門家のほうが品質が高い
- 個性を与える: 汎用的な応答を避け、一貫した行動パターンを定義する
- 成果物を明示する: アドバイスではなく、使えるものを出力する
- 数値で測る: 曖昧な目標ではなく、達成判定できる指標を設定する
- 実証済みの手順を書く: 理論ではなく、実際にテストした手順を定義する
これらの原則は、LLMベースのエージェントに限らず、プロンプト設計全般に適用できます。
まずはテンプレートを使って1つエージェントを定義し、実際に使いながら改善してみてください。
参考リンク
関連記事
導入手順に戻りたい方は、以下の記事もご覧ください。
- （リンクは後で設定）