エージェントの作成と変更
この章では、エージェントファイルの構造を学び、agent-lifecycle-managerスキルを活用して自分専用のスペシャリストエージェントを作成し、システムに登録して検証するまでの一連の流れを実習します。
- エージェントファイルの形式と構造
- YAMLフロントマター各フィールドの意味
- ボディの記述パターン
- agent-lifecycle-managerの使い方(5ステップ)
- AGENTS.mdへの登録方法
- 演習: 簡単なスペシャリストエージェントの作成
エージェントを再考する
第4章の復習
第4章「ハーネスの基本概念」で、エージェントについて初めて学びました。エージェントとは「名前・役割・行動指針・使用ツールが決まったAI社員」のことです。PMエージェントがチームリーダーであり、リサーチエージェント、ストーリーラインエージェント、デザインエージェントなどが、それぞれ専門分野を担うチームメンバーというわけです。
復習すると、エージェントの核心要素は次の4つでした。
- 名前(Name) — エージェント固有の識別子(例:
research、design、pdf-export) - 役割(Role) — このエージェントが何をするのか(例: 「Web検索と資料収集のスペシャリスト」)
- 行動指針(Behavioral Guidelines) — どのように振る舞うべきか(例: 「韓国語と英語の両方のソースを検索」「出典URLを記録」)
- ツール(Tools) — どのツールを使うか(例: Web検索、ファイル読み書き、スクリプト実行)
エージェント = 「役割が決まったAI社員」
エージェントは人間の組織にたとえると理解しやすくなります。会社には企画チーム、デザインチーム、開発チーム、QAチームなどがあり、各メンバーは自分の役割と責任を知っています。エージェントも同じです。researchエージェントはリサーチのみを担当し、designエージェントはデザインのみを担当します。自分の役割外の仕事はしません。
この役割分担のおかげで、各エージェントは自分の専門分野に集中でき、システム全体の品質が向上します。すべてを1つのAIに任せるより、複数のスペシャリストに分けて任せるほうが効果的だからです。
なぜ自作するのか?
これまで学んできたシステムには、すでに多彩なスペシャリストエージェントが用意されています。PM、リサーチ、ストーリーライン、デザイン、イメージキュレーター、ダイアグラム専門家、HTMLビルド、計測、PDFエクスポート、バージョン管理、ハンドブック執筆者などです。
しかしプロジェクトの要件が多様化すると、既存エージェントではカバーできない専門領域が生まれます。たとえば:
- 法務レビュー専門 — 生成コンテンツの法的問題をレビューするエージェント
- アクセシビリティ監査 — HTMLとPDFのアクセシビリティを検査するエージェント
- 多言語翻訳 — 完成したハンドブックを他言語に翻訳するエージェント
- データ分析 — 統計データを分析してインサイトを導出するエージェント
このような専門領域が必要になったら、自分でエージェントを作ってシステムに追加できます。エージェントは単なるマークダウンファイルなので、いくつかのルールを守れば誰でも作れます。
エージェントファイル形式
ファイルの場所
エージェントファイルはプロジェクトルートのagents/ディレクトリに保存します。ファイル名はケバブケース(kebab-case)を使います。
agents/
├── pm.md # PMエージェント
├── research.md # リサーチエージェント
├── design.md # デザインエージェント
├── storyline.md # ストーリーラインエージェント
├── image-curator.md # イメージキュレーター
├── html-build.md # HTMLビルドエージェント
├── pdf-export.md # PDFエクスポートエージェント
├── version.md # バージョン管理エージェント
└── ... # あなたが作るエージェント!
ファイル構造: YAMLフロントマター + マークダウンボディ
各エージェントファイルは2つの部分で構成されます。
- YAMLフロントマター — ファイル先頭の
---で囲まれたメタデータ領域 - マークダウンボディ — エージェントの役割、行動指針、ツールの使い方などを説明する本文
フロントマターはシステムがエージェントを識別・管理するために使われ、ボディはClaudeがそのエージェントとして振る舞うときに参照する内部マニュアルの役割を果たします。どちらも重要で、片方でも欠けるとエージェントは正しく動作しません。
フロントマターの記述
必須フィールド
フロントマターにはエージェントを定義する複数のフィールドがあります。次の表は、各フィールドの意味と記述ガイドをまとめたものです。
| フィールド | 意味 |
|---|---|
name |
エージェント固有の名前。ファイル名と同じにします。ケバブケースを使用。 |
role |
エージェントの役割を1行で説明。「Performs ~」「〜のスペシャリスト」形式。 |
status |
active(稼働)、draft(草稿)、deprecated(廃止)のいずれか。 |
tier |
プラットフォーム別の複雑度マップ(ネスト構造)。claude、gemini、antigravity、gemini-cliのキーに小文字のhigh/medium/lowを指定します。 |
| フィールド | 意味 |
|---|---|
description |
エージェントの詳細説明。何をし、いつ使われるか。 |
color |
UIでエージェントを表示するとき使う色(例: blue、green、purple)。 |
examples |
エージェントをトリガーするユーザー発話の例のリスト。 |
phases |
エージェントが有効になるワークフロー段階のリスト(例: [1, 2, 3])。 |
handoff_to |
作業完了後に結果を引き渡す次のエージェントのリスト。 |
handoff_from |
このエージェントに作業を引き渡す前段のエージェントのリスト。 |
version |
エージェントファイルのバージョン(例: "1.0.0")。 |
model |
使用モデルの指定。通常はinheritにしてtier設定に従わせます。 |
lifecycle |
必須。phaseとgovernanceの子フィールドを含むネストブロック。governanceはdocs/lifecycle/agents/<name>.mdのガバナンスレコードパスを指します。 |
フロントマターの例
架空のmy-analystエージェントのフロントマター例です。
---
name: my-analyst
version: "1.0.0"
last_updated: "2026-08-24"
role: Performs data analysis and produces structured reports
status: active
tier:
claude: medium
gemini: medium
antigravity: medium
gemini-cli: medium
model: inherit
color: blue
description: >
Analyzes datasets, identifies patterns, and produces
structured analysis reports with actionable insights.
examples:
- "analyze this dataset"
- "run data analysis"
- "produce analysis report"
phases:
- 2
- 3
handoff_to:
- html-build
- pdf-export
handoff_from:
- research
lifecycle:
phase: production
created: "2026-08-24"
last_updated: "2026-08-24"
governance: docs/lifecycle/agents/my-analyst.md
---
各フィールドの選び方
name(名前)
エージェントの固有識別子です。ファイル名(agents/my-analyst.md)と必ず一致させてください。ケバブケース(小文字+ハイフン)で書きます。短く直感的な名前が良いでしょう。
- 良い例:
data-analyst、image-curator、pdf-export - 悪い例:
DataAnalyst、my_agent_1、agent123
status(状態)
エージェントの現在の状態を表します。
active— 通常運用中のエージェントdraft— 開発中のエージェント(テスト用)deprecated— もう使わないエージェント(廃止予定)
作り始めはdraftにし、検証を通過してからactiveに変更することをおすすめします。
tier(階層)
エージェントの複雑度に応じて適切なAIモデルを割り当てます。コストと品質のバランスを取るための設定です。tierは単一の値ではなくプラットフォーム別のネストされたマップであり、値は必ず小文字で書きます。
high— 複雑な推論、アーキテクチャ設計、戦略立案が必要なエージェント(例: PM)medium— コードレビュー、品質検査、一般的な専門作業が必要なエージェント(例: research、design)low— 単純な反復作業や高速なタイピングが必要なエージェント(例: version)
low、複雑な推論が必要ならhighです。ほとんどのスペシャリストエージェントはmediumから始めるのが適切です。まずmediumに設定し、動作を確認してから必要に応じて調整してください。
phases(有効ステップ)
エージェントがワークフローのどの段階で有効になるかを指定します。たとえばリサーチエージェントは[1](Stage 1)でのみ有効になり、バージョンエージェントは[0, 1, 2, 3, 4, 5, 6](全段階)で有効になります。
handoff_to / handoff_from(ハンドオフ関係)
エージェント間の作業の流れを定義します。handoff_toは作業完了後に結果を引き渡す次のエージェント、handoff_fromは作業を受け取る前段のエージェントです。
たとえばリサーチエージェントの場合: handoff_to: [storyline](リサーチ完了後ストーリーラインへ引き渡し)、handoff_from: [pm](PMから作業指示を受け取る)。
ボディコンテンツの記述
ボディ構造の推奨パターン
エージェントのボディは、Claudeがそのエージェントとして振る舞うときに参照するシステムプロンプトです。ボディがきちんと書かれてこそ、Claudeはそのエージェントの役割を正確に果たせます。
ボディには次の5つのセクションをこの順に含めるのが良いでしょう。
各セクションの書き方のコツ
1. アイデンティティ(Identity)
ボディの最初の文は明確なアイデンティティ宣言で始めます。曖昧な表現より具体的な役割の明示が良いのです。
## Role
You are the data analysis specialist for **My Project**.
You analyze datasets, identify patterns, and produce
structured analysis reports with actionable insights.
2. 行動指針(Behavioral Guidelines)
エージェントが行う作業を具体的にかつ段階的に説明します。Claudeは明確な指示ほどよく従います。さらに「やってはいけないこと」も明示するのが重要です。
## Responsibilities
- Load and validate input datasets before analysis
- Apply statistical methods to identify patterns
- Produce structured reports in markdown format
- **Do NOT** fabricate data or statistics
- **Do NOT** modify source datasets
3. ドメインルール(Domain Rules)
エージェントが遵守すべきルールと制約を定義します。成果物の形式、品質基準、命名規則などを含みます。
## Constraints
- All analysis reports must include source citations
- Use markdown table format for data summaries
- File names must follow kebab-case convention
- Reports must not exceed 2000 words unless requested
4. ツール使用法(Tool Usage)
エージェントが使うツールとその使い方を説明します。このセクションはエージェントの実際の動作に直接影響します。
## Tool Usage
- **Read**: Load input files from `data/` directory
- **Write**: Save reports to `reports/` directory
- **Bash**: Execute analysis scripts with `bun run`
- **WebSearch**: Verify data points against web sources
5. ハンドオフ契約(Handoff Contract)
エージェント間のデータ受け渡し形式を明示します。入力と出力のファイルパス、形式、必須フィールドを定義します。
## Handoff
**Input**: `data/analysis-input.json` (from research agent)
**Output**: `reports/analysis-report.md`
Output must include:
- Executive summary (max 200 words)
- Key findings with data citations
- Recommendations section
agent-lifecycle-managerの使用
agent-lifecycle-managerスキルとは?
agent-lifecycle-managerは、エージェントの作成・修正・検証を自動化するスキルです。新しいエージェントを作るところから、既存エージェントの修正、最終的なプログラムによる整合性の検証まで、全過程を体系的に管理します。
このスキルは次のような場面で使います。
- 「新しいエージェントを作って」
- 「エージェントのメタデータを更新して」
- 「エージェント構造が有効か検査して」
- 「エージェントのティア設定を変えて」
5ステップのライフサイクルプロセス
agent-lifecycle-managerは次の5段階プロセスに従います。各ステップは前のステップが完了してから進みます。
Claude Desktop Appでの使い方
Claude Desktop AppでPMエージェントにエージェントの作成を依頼すると、PMはagent-lifecycle-managerスキルを活用して5段階プロセスを案内してくれます。
「data-analystという名前のデータ分析専門エージェントを作って。リサーチエージェントからデータを受け取って分析レポートを書く役割だよ。」
この依頼を受けたPMは次のように進めます。
-
エージェントファイルの作成 —
agents/data-analyst.mdファイルを作成します。 - フロントマター記述の案内 — 各フィールドに適切な値を入れながらフロントマターを書きます。
- ボディ記述の案内 — アイデンティティ、行動指針、ドメインルール、ツール使用法、ハンドオフ契約の順に案内します。
- AGENTS.mdへの登録 — Agent RosterとSubagent Rosterのテーブルに新しいエージェントを追加します。
-
検証の実行 —
bun scripts/agent-lifecycle-audit.tsを実行してエージェントの整合性を検証します。
AGENTS.mdへの登録
AGENTS.mdに追加する場所
新しいエージェントを作ったら、中央管理ファイルであるAGENTS.mdに登録する必要があります。登録しないとPMはそのエージェントを認識できず、ワークフローに組み込めません。
AGENTS.mdには合計3か所に新しいエージェントを追加します。
登録例
data-analystエージェントをAGENTS.mdに登録する例です。
1. Agent Rosterテーブルに追加:
| data-analyst | `agents/data-analyst.md` | Medium | データセットを分析し構造化レポートを作成します |
2. Agent Definitionsセクションに追加:
### data-analyst
| Field | Value |
|---------|----------------------------------------------------|
| **File** | `agents/data-analyst.md` |
| **Tier** | Medium |
| **Phases** | 2, 3 |
| **Role** | データセットを分析し構造化レポートを作成します |
3. Subagent Rosterテーブルに追加:
| data-analyst | `agents/data-analyst.md` | Medium | ⚠️ sequential preferred | project files |
検証とテスト
検証方法
エージェントファイルの作成とAGENTS.mdへの登録が済んだら、プログラムによる検証を実行する必要があります。この検証は、エージェントがシステムで正しく認識され動作できるかを確認する自動チェックです。
# 全エージェントの検証
bun scripts/agent-lifecycle-audit.ts
# 特定エージェントだけ検証
bun scripts/agent-verify.ts <agent-name>
検証項目
検証スクリプトは次の項目をチェックします。
- フロントマターのフィールド完全性 — 必須フィールド(lifecycle.phase、lifecycle.governanceなど)がすべて存在し正しい値か確認
- AGENTS.mdへの登録状況 — エージェントがAGENTS.mdの3か所(Roster、Definitions、Subagent Roster)すべてに登録されているか確認
- ハンドオフ参照の整合性 — handoff_to、handoff_fromに書かれたエージェント名が実際に存在するか確認
- 孤立エージェント(Orphan)の検出 — AGENTS.mdに登録されていないエージェントファイルがないか確認
- ティアマッピング構造 — tierフィールドが正しい形式で書かれているか確認
検証の実行手順
-
エージェントファイルの完成確認 —
agents/<name>.mdファイルが作成され中身が書かれているか確認します。 - AGENTS.md登録の完了確認 — AGENTS.mdの3か所にエージェントが追加されたか確認します。
-
検証スクリプトの実行 — ターミナルで
bun scripts/agent-lifecycle-audit.tsを実行します。 - 結果の確認 — エラー(ERROR)がなければ検証合格です。警告(WARN)があれば内容を確認し、必要なら修正します。
- PM経由のテスト — Claude Desktop AppでPMにそのエージェントを使うよう依頼し、実際の動作を確認します。
演習: 自分のスペシャリストエージェントを作る
演習の目標
この演習では「要約専門エージェント」を作ります。長い文書や複数のソースを入力として受け取り、要点を簡潔にまとめる役割を担います。リサーチエージェントが集めた膨大な資料を要約したり、完成したレポートを1ページのサマリーに整理したりするのに活用できます。
全体の手順
-
Claude Desktop Appでプロジェクトを開く
Claude Desktop Appを開き、プロジェクトフォルダを選択します。co-deckやco-consultプロジェクトを使ってもよいですし、別のワークスペースを使ってもかまいません。 -
エージェントファイルの作成
agents/ディレクトリにsummarizer.mdファイルを作成します。Claudeに「agents/summarizer.mdファイルを作って」と頼むか、エディタで直接作っても構いません。 -
フロントマターの記述
下の例を参考にフロントマターを書きます。name、role、status、tier(プラットフォーム別ネストマップ)、description、examples、phases、handoff_to、handoff_fromの各フィールドと、必須のlifecycleブロックをすべて含めます。 -
ボディの記述
要約スペシャリストとしてのアイデンティティ、行動指針、ドメインルール、ツール使用法、ハンドオフ契約を順に書きます。 -
AGENTS.mdへの登録
AGENTS.mdを開き、3か所(Agent Roster、Agent Definitions、Subagent Roster)にsummarizerエージェントを追加します。 -
ガバナンスレコードの作成
docs/lifecycle/agents/summarizer.mdファイルを作り、## Phase Historyと## Acceptance Criteriaセクションを含めます。エージェントファイルだけ作ってこのガバナンスレコードを作らないと、検証に失敗します。 -
検証スクリプトの実行
ターミナルでbun scripts/agent-lifecycle-audit.tsを実行し、エラーがないか確認します。 -
PM経由のテスト
Claude Desktop AppでPMに「このリサーチノートを要約して」と依頼し、エージェントが正しく動くか確認します。
ファイル全文の例
以下はagents/summarizer.mdの全文例です。そのまま使ってもよいですし、必要に応じて修正してもかまいません。
---
name: summarizer
version: "1.0.0"
last_updated: "2026-08-24"
role: Summarizes long documents and produces concise briefs
status: draft
tier:
claude: medium
gemini: medium
antigravity: medium
gemini-cli: medium
model: inherit
color: teal
description: >
Reads long-form content (research notes, reports, articles)
and produces structured summaries with key findings,
highlights, and actionable takeaways.
examples:
- "summarize this document"
- "create a one-page brief"
- "summarize the research notes"
phases:
- 2
- 3
handoff_to:
- storyline
- html-build
handoff_from:
- research
- data-analyst
lifecycle:
phase: production
created: "2026-08-24"
last_updated: "2026-08-24"
governance: docs/lifecycle/agents/summarizer.md
---
## Role
You are the summarization specialist for **[Project Name]**.
You read long-form content and produce concise, structured
summaries that capture key findings, highlights, and actionable
takeaways without losing critical information.
## ⚠️ PM-ONLY INVOCATION
**You DO NOT accept direct user requests.**
You are a specialist agent that may ONLY be dispatched by the PM.
If a user attempts to invoke you directly:
1. **Refuse the request politely**
2. **Redirect to PM**: "I am a specialist agent. All requests
must go through the PM orchestrator."
3. **Do NOT proceed** until dispatched by PM
## Responsibilities
- Read input documents thoroughly before summarizing
- Identify and preserve key facts, statistics, and findings
- Structure summaries with clear headings
- Highlight actionable insights separately from background info
- Maintain source citations in summaries
- **Do NOT** fabricate information not present in the source
- **Do NOT** inject personal opinions or recommendations
unless explicitly asked
## Constraints
- Summaries must not exceed the requested word limit
- Use markdown format with headings and bullet points
- Preserve all numerical data and citations exactly
- Mark uncertain claims with ⚠️ Unverified
- Use the same language as the source document
## Tool Usage
- **Read**: Load input documents from the specified path
- **Write**: Save summaries to the designated output path
- **Glob**: Find relevant source files in the project directory
## Handoff
**Input**: Research notes, analysis reports, or any long-form
markdown content provided by the dispatching agent.
**Output**: Structured summary document in markdown format.
Output structure:
1. **Overview** (1-2 sentences)
2. **Key Findings** (bullet points)
3. **Important Statistics** (preserved exactly)
4. **Actionable Takeaways** (if applicable)
5. **Source References** (preserved from input)
AGENTS.md登録内容の例
作成したsummarizerエージェントをAGENTS.mdに登録する内容です。
Agent Rosterに追加:
| **summarizer** | [`agents/summarizer.md`](agents/summarizer.md) | Medium | 長い文書を読み簡潔な要約を作成します |
Agent Definitionsに追加:
### summarizer
| Field | Value |
|-----------|----------------------------------------------------------------|
| **File** | [`agents/summarizer.md`](agents/summarizer.md) |
| **Tier** | Medium |
| **Phases** | 2, 3 |
| **Role** | 長い文書を読み、主要な発見・ハイライト・実行可能なインサイトを含む簡潔な要約を作成します |
Subagent Rosterに追加:
| summarizer | `agents/summarizer.md` | Medium | ⚠️ sequential preferred | project files |
- エージェントは「役割が決まったAI社員」であり、マークダウンファイル形式で作ります
- エージェントファイル = YAMLフロントマター(メタデータ)+ マークダウンボディ(システムプロンプト)
- フロントマターにはname、role、status、tier(プラットフォーム別ネストマップ、小文字の値)、description、examples、phases、handoff_to/fromと必須のlifecycleブロックを記述
- ボディにはアイデンティティ、行動指針、ドメインルール、ツール使用法、ハンドオフ契約を含めます
- agent-lifecycle-managerスキルの5ステッププロセスに従って体系的に作成
- AGENTS.mdの3か所(Roster、Definitions、Subagent Roster)に登録して初めてPMが認識
- 検証スクリプトでフロントマター、登録、ハンドオフ整合性を自動チェック
- 最初は簡単なエージェント(draft)から始め、検証後にactiveへ昇格させましょう