AIエージェントの成果物を「型」で揃える——スキーマ・スキル・Figma MCPの4層テンプレート駆動ガイド

ポイント

• AIエージェントの成果物を「テンプレートに沿った型」で安定的に出力させるための実践的なアプローチを整理
• スキーマ定義、スキル設計、Few-shot例示、Figma MCP連携の4層で品質と一貫性を確保
• 2026年3月の最新動向（Figma use_figma、Claude Skills、Structured Output）を踏まえたベストプラクティス

なぜテンプレート駆動が必要なのか

AIエージェントに「いい感じにやっておいて」と任せると、毎回微妙に異なる形式の成果物が出てくる。記事、コード、デザイン、レポート——どの領域でも同じ問題が起きる。

テンプレート駆動のアプローチは、この問題を**「型を先に定義し、エージェントをその型に沿わせる」**という発想で解決する。人間のチームでも新人にテンプレートを渡すのと同じだ。

4層のテンプレート制御アーキテクチャ

成果物の一貫性を高めるために、以下の4層を組み合わせる。

第1層：出力スキーマの定義

最も基本的なレイヤー。成果物の「構造」をJSON SchemaやPydanticモデルで定義する。

Structured Output（API レベル）

OpenAIやAnthropicのAPIでは、レスポンスのJSON構造を事前に定義できる。モデルに「JSONで返して」と頼むのではなく、生成レベルで強制するため、構造の逸脱が原理的に起きない。

from pydantic import BaseModel

class ArticleDraft(BaseModel):
    title: str
    summary: str  # 200字以内
    key_points: list[str]  # 3〜5個
    body_sections: list[dict]  # {heading, content}
    score: int  # 1〜30
    tags: list[str]

いつ使うか: API経由で成果物を生成し、後続処理（DB投入、ファイル生成等）に自動で流す場合。人間の介在が少ないパイプラインほど効果が高い。

第2層：スキル（SKILL.md / CLAUDE.md）

Claude CodeやCodexで使われる「スキル」は、エージェントの行動指示をMarkdownで記述する仕組み。テンプレート駆動の中核を担う。

Anthropic公式のスキル設計ベストプラクティス:

原則	説明
簡潔さ	Claudeがすでに知っていることは書かない。トークンは公共財
自由度の設定	壊れやすい操作は低自由度（スクリプト固定）、文脈依存は高自由度
段階的開示	SKILL.mdは概要のみ。詳細はreferences/に分離
Few-shot例示	入出力ペアを示して「正解の型」を伝える

テンプレート制御のためのスキル設計例:

## 記事テンプレート

以下の構成で記事を生成する：

1. `## ポイント` — 箇条書き3点（各1行）
2. `## 何が起きたか` — 事実の要約（200〜400字）
3. `## 技術的な背景` — 開発者向けの解説
4. `## 開発者にとっての意味` — 実務への影響
5. `## スコア: N` — 1〜30の評価

### 禁止事項
- スコアの内訳を本文に載せない
- 「NVA」という用語は使わない

CLAUDE.md / AGENTS.mdでの横断的なルール定義:

プロジェクト全体で一貫させたい規約は、CLAUDE.md（Claude Code）やAGENTS.md（Codex等）に書く。スキルが個別の「型」を定義するのに対し、CLAUDE.mdは全成果物に適用される横断ルールを担う。

# CLAUDE.md

## 出力規約
- 日本語で出力。用語は「個人開発者」で統一
- コードブロックには必ず言語指定をつける
- 画像パスは /thumbnails/{slug}.jpg 形式
- コミットメッセージは Conventional Commits 形式

第3層：Few-shot例示とリファレンス

スキーマやスキルだけでは伝わらない「暗黙の品質基準」を伝えるための層。

入出力ペアの提供:

Anthropicのスキル設計ガイドでも推奨されている手法。「こういう入力に対して、こういう出力が正解」を具体的に示す。

## コミットメッセージの例

**入力:** ユーザー認証にJWTを追加
**出力:**
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

リファレンスファイル（progressive disclosure）:

SKILL.mdに全部書くとコンテキストウィンドウを圧迫する。詳細な例やテーブル定義はreferences/ディレクトリに分離し、必要なときだけ読み込ませる。

my-skill/
├── SKILL.md              # 概要と手順
├── references/
│   ├── template.md       # 成果物テンプレートの詳細
│   ├── examples.md       # 入出力例
│   └── schema.json       # JSONスキーマ
└── scripts/
    └── validate.sh       # 出力の自動検証

第4層：外部ツール連携（Figma MCP / use_figma）

2026年3月の最大のブレークスルー。Figmaがuse_figmaツールを公開し、AIエージェントがFigmaキャンバスに直接書き込めるようになった。

従来: コーディングエージェントがHTMLを生成 → 人間がFigmaに手動で反映 現在: エージェントがFigmaのデザインシステム（コンポーネント・変数・オートレイアウト）を直接操作

use_figmaの仕組み:

ツール	役割
use_figma	基盤レイヤー。Figmaファイルの読み書き
generate_figma_design	Code → Figmaデザインへの変換
figma-generate-library	デザインシステム全体の生成
figma-create-design-system-rules	CLAUDE.md / AGENTS.md の自動生成

テンプレート制御との関係:

Figmaのデザインシステム自体がテンプレートの役割を果たす。コンポーネント、変数（カラー・スペーシング）、オートレイアウトのルールがあるFigmaファイルに対して、エージェントがuse_figmaで操作すると、デザインシステムの制約が自動的に適用される。

つまり「テンプレートに沿った成果物」を実現するために、エージェントに細かくルールを伝える必要がない——Figma側の制約が自然にそれを担保する。

スキルとの組み合わせ:

FigmaはMCPサーバーと同時に「スキル」の概念も導入した。Markdown形式の指示ファイルで、エージェントがFigmaキャンバス上でどう振る舞うかを定義する。

## Figmaスキル例: カード生成

1. use_figmaでプロジェクトのコンポーネントライブラリを読み込む
2. CardBaseコンポーネントのインスタンスを作成
3. テキストプロパティにタイトルと説明を設定
4. カラー変数はbrand/primaryを使用
5. オートレイアウトの設定はライブラリの規定に従う

実践ガイド: 段階的に導入する

Step 1: CLAUDE.md / AGENTS.mdにルールを書く（即日）

最もコストが低い。プロジェクトルートにファイルを置くだけで、全エージェント操作に反映される。

Step 2: スキルを定義する（1〜2日）

繰り返しの多いタスク（記事作成、レビュー、デプロイ等）にスキルを書く。Few-shot例示を含めて、出力の「型」を定義する。

Step 3: Structured Outputでパイプラインを自動化（1週間）

API経由のワークフローにJSON Schemaを導入。成果物がスキーマに準拠していることをプログラム的に保証する。

Step 4: Figma MCP連携でデザインを統合（実験的）

use_figmaを使ってデザイン成果物もテンプレート制御の対象に。デザインシステムの制約がエージェントの出力品質を自動的に底上げする。

注意すべき落とし穴

落とし穴	対策
テンプレートが厳格すぎて創造性が死ぬ	「自由度の設定」を使い分ける。固定すべき部分と裁量を持たせる部分を明確に
スキルが肥大化してコンテキストを圧迫	500行以下を目安に。超えたらreferences/に分離
テンプレートとモデルの能力がミスマッチ	Haiku/Sonnet/Opusで動作検証。Haikuには詳細な指示、Opusには概要で十分
デザインシステムが未整備でuse_figmaが活きない	まずFigma側のコンポーネント・変数を整理してから連携
「テンプレートがあるから安心」と検証を省く	出力の自動バリデーション（スクリプト、CI）は別途必須

まとめ: テンプレート駆動の核心

AIエージェントのテンプレート駆動は、**「制約を正しく設計する技術」**に他ならない。

1. スキーマで構造を定義し
2. スキルで手順と判断基準を伝え
3. 例示で暗黙の品質基準を共有し
4. **外部ツール（Figma等）**でデザインシステムの制約を自動適用する

この4層が揃ったとき、エージェントは「テンプレートに沿った、かつ文脈に応じた」成果物を安定的に生成できるようになる。