LegalOn Technologies Engineering Blog

LegalOn Technologies 開発チームによるブログです。

社内デザインシステム「Aegis」を用いた実装精度を30%から90%以上に引き上げた Agent Skills の開発方法

AI Frontend Design System

はじめに

こんにちは、株式会社LegalOn Technologies ソフトウェアエンジニアのわたりょーです。デザインシステムチームに所属し、社内デザインシステム「Aegis」を開発・運用しています。

「Aegis」は、LegalOn Technologiesのプロダクト群で一貫した UI を実現するための社内デザインシステムです。UI コンポーネントライブラリ、デザイントークン、ガイドラインなどを提供し、複数プロダクトの開発効率と品質を支えています。

本記事では、AI コーディングエージェント（Claude Code / Codex など）向けに Agent Skills（以下、Skills）を活用した取り組みを紹介します。 この取り組みにより、限定的な検証（3タスク×各10回）において、「Aegis」コンポーネントの生成精度を30%から90%以上に引き上げました。

MCP（Model Context Protocol）サーバー、AGENTS.md / Rules、Skills の3つのアプローチを試行錯誤してきた過程と、Skills の読み込み率を100%に近づけるためのプロンプト設計のノウハウもあわせて共有します。

精度の検証では、「一覧画面」「フォーム入りのダイアログ」「テーブル上に Drawer で表示するフィルター」の3タスクを用い、各条件で10回ずつ生成しました。検証時は毎回 AI コーディングエージェントの会話コンテキストをクリアし、プロンプトとコードベースをそろえて比較しています。

評価は人手で行い、生成物が大きな修正なしに使える場合を OK、大幅な手直しが必要な場合を NG としました。本記事中の「精度」は、この条件下で10回中何回 OK の判定になったかを示す割合です。

本記事は、AI コーディングエージェントを活用している方や、社内独自のライブラリを AI に正しく理解させたい方を対象とした内容です。

精度向上に向けた課題と背景

社内コンポーネントは AI の「知らない世界」

AI コーディングエージェントは、OSS（Open Source Software）のライブラリであれば学習データに含まれている可能性が高いため、比較的正しいコードを生成しやすい傾向があります。しかし、社内独自のコンポーネントライブラリは AI の学習データに含まれていません。

「Aegis」は社内にしか知見がないデザインシステムです。AI にそのまま「Aegis のコンポーネントを使って画面を作って」と依頼しても、存在しない Props を使ったり、非推奨のパターンで実装したりして、正しく動作するコードを生成できませんでした。

この課題を解決するために、AI に対して「Aegisの正しい使い方」をどのように伝えるか、約1年にわたり試行錯誤を重ねてきました。

解決策／解決方法

精度を30%から90%超へ引き上げたアプローチの変遷

精度向上の道のりは、大きく3つのフェーズに分かれます。

  1. MCP サーバー → 精度: 約30%
  2. AGENTS.md / Rules → 精度: 60-70%
  3. Skills → 精度: 90%超

フェーズ1: MCP サーバー時代（精度30%）

最初のアプローチは、MCP サーバー内に「Aegis」の利用ガイドやルールをすべて格納し、AI から参照させる方法でした。

全コンポーネントを取得する API と個別コンポーネントの詳細を取得する API を設計し、AI が「Aegis」の情報へアクセスできるようにしました。しかし、以下の問題がありました。

  • コンテキストの大量消費: MCP サーバーから取得した情報がコンテキストウィンドウを圧迫し、本来の実装タスクに使えるトークンが減少しました
  • 呼び出しの不安定さ: MCP サーバーが呼び出される場合と呼び出されない場合があり、精度が安定しませんでした
  • 軽量化の限界: Claude Code の MCP ツール出力上限はデフォルトで25,000トークンです（Anthropic Docs: Connect Claude Code to tools via MCP）。この制約に収めるため MCP サーバーを軽量化しましたが、必要な情報が欠損し、出力精度が低下しました。（最大値は変更可能ですが、社内メンバーへの展開を考慮すると望ましい方法ではありません。）

結果として、10回中3回程度しか正しい実装を生成できず、精度は約30%にとどまりました。

たとえば、ダイアログ実装では、存在しない Props を前提にしつつ推奨構成からも外れたコードを生成するケースがありました。以下は実際の失敗傾向を簡略化した例です。

<Dialog
  // 実際には存在しない Props を前提にしている例
  unsupportedOpenProp={open}
  unsupportedTitleProp="ユーザー追加"
>
  <TextField label="名前" required />

  {/* 推奨の DialogFooter / ButtonGroup を使わずに直接配置している例 */}
  <Button>キャンセル</Button>
  <Button variant="primary">保存</Button>
</Dialog>

このように、存在しない Props の利用と、推奨コンポーネントを使わない実装が同時に起きるため、そのままでは採用できないケースが多くありました。

また、Figma のデータを MCP サーバーで取得し「Aegis」のコードを生成することも試しました。しかし、Figma のコンポーネント構成に依存し、トークン数も膨大だったため、望ましい成果物を得られませんでした。画面全体を取得する場合、MCP サーバーの出力上限（約2.5万トークン）に対して Figma のレスポンスが約17万トークンに及び、MCP サーバーを使えないケースもありました。

以下は、このフェーズでの生成結果です。

PageLayout や Button は「Aegis」のコンポーネントを利用していますが、それ以外の Table や Pagination などは「Aegis」のコンポーネントが使われていません。

ぱっと見はよく見えるものの、内部のコード品質は許容できるものではありませんでした。

MCP サーバーのみの生成結果：テーブルやページネーションが独自実装

フェーズ2: AGENTS.md / Rules 導入期（精度60-70%）

次に試みたのは、AGENTS.mdと Rules に「Aegis」の情報を記載するアプローチです。

AGENTS.md と Rules は AI コーディングエージェント起動時や対象ファイル参照時に読み込まれるため、MCP サーバーのような「呼ばれない」問題は解消されました。最初に正解がある状態でコード生成が行われるため、精度は60-70%まで向上しました。

しかし、ここでも壁にぶつかりました。

  • トークンの過剰消費: AGENTS.md や Rules は AI エージェント起動時に自動でコンテキストへ読み込まれるため、情報を詰め込むほど毎回のトークン消費が増大しました。Anthropic の公式ドキュメントでも、AGENTS.md はプロジェクト固有の重要事項に絞って管理することが案内されています（Anthropic Docs: How Claude remembers your project）
  • Rules の削減による精度低下: Rules の情報量を減らすと精度が30〜40%低下しました。つまり「全部載せるとトークンが溢れる、減らすと精度が落ちる」というトレードオフに陥りました

次のアプローチとして、Rules の外にドキュメントを配置し、必要なタイミングで対象となる情報を参照させる方法を試したところ、精度が向上しました。

そのような試行錯誤を続けている最中に、Skills が公式に発表されました。

フェーズ3: Skills 導入後（精度90%超）

Skills の活用により、各種情報をオンデマンドで AI エージェントに参照させられるようになりました。

フェーズ2末に整備していたドキュメントをそのまま Skills に移行し、試行錯誤を経て90%以上の精度を達成しました。前述の3タスクで各10回ずつ検証した範囲では、30回中27回が OK 判定となりました。Skills を読み込む確率も90%に向上しました。

Skills が決定打となった理由は、以下の3点です。

  • コンテキストの効率的な利用: Skills では起動時に各 Skills のメタデータ（Name / Description）のみを事前読み込み。SKILL.md 本文は、関連する Skills があると判断されたときにだけ読み込まれる設計（Anthropic Docs: Skill authoring best practices）
  • 必要に応じた Rules との併用: 「必ず参照してほしい」場面では、Rules で利用条件を補助する運用
  • Vite と React のみの環境でも動作: Rules や既存コードベースがない新規環境でも、Skills のみで「Aegis」コンポーネントを生成可能

以下は、このフェーズでの生成結果です。

全体を通して、「Aegis」コンポーネントを適切に用いた構成で出力できました。

Skill ありの生成結果：Aegis コンポーネントで統一

Skills の出力精度を上げるための工夫

成果物の目視チェックと Skill Creator の活用

Skills の文面改善や Description の最適化はほとんど AI に任せ、人間は input/output（「こんな画面を作りたい」→「スクリーンショット」）の検査をしていました。

Skill Creator が登場する前から PDCA サイクルを回しており、このプロセスで得た知見が Skills の品質を支えています。

Anthropic が公開した anthropics/skills に含まれる skill-creator Skills が登場してからは、より評価や改善のサイクルを回しやすくなりました。（詳しい仕組みはリンク先を参照してください。）

以下は、今回作成した Skills を Skill Creator で評価した結果です。

すべてのケースで Skills による効果が出ています。

評価結果：全31アサーションで100%通過を達成

段階的開示（Progressive Disclosure）

Skills の設計で最も重要だったのは、Progressive Disclosure（段階的開示）の考え方です。情報を3つの層に構造化し、AI が必要な深さまで段階的にアクセスできるようにしました。

3層構造の設計

  1. Name / Description（第1層・常時ロード）: Skills の概要と、どのような場面で使うべきかを簡潔に記述。起動時には全 Skills の Name / Description がシステムプロンプトに事前読み込みされる。AI が Skills を読み込むかどうかを判断するための情報（Anthropic Docs: Skill authoring best practices）
  2. SKILL.md（第2層・トリガー時のみロード）: 実行手順、参照先の選び方、守るべき制約、references/ の索引を記述する軽量なハブ。AI が Skills の利用を決定した段階で初めてコンテキストに読み込まれる設計
  3. その他リファレンス（第3層・必要時のみロード）: references/ 配下に置く、具体的なコンポーネント構成、レシピ、Props / API 仕様 / 型定義。SKILL.md 内の指示に従って必要なファイルだけを読み込む構成

実際のファイル構成例

実際の Aegis Skills で、この考え方を採用しました。SKILL.md を軽量なハブにして、画面ごとのレシピを references/ に分割しています。

aegis-skills/
├── SKILL.md
└── references/
    ├── dialog-form-create.md
    ├── filter-drawer.md
    ├── list-toolbar-and-search.md
    ├── table-container-basic.md
    └── ...

SKILL.md には、どのレシピを読むかを決めるための手順だけを置きます。

## 実行手順

1. ユーザー要件から対象画面の種類を判定する。
2. `references/` から最も近いレシピを 1-3 件選ぶ。
3. 選んだレシピの「使うコンポーネント」「ポイント」「NG 例」を優先して反映する。
4. Props が曖昧な場合は `mcp__aegis__get_component("ComponentName")` で確認する。

具体的な UI の組み方は references/ 側に逃がします。例えば追加ダイアログ用のレシピでは、使うコンポーネント、配置のポイント、NG 例を1ファイルに閉じ込めています。

# 追加ダイアログ（フォーム + フッターアクション）

## 使うコンポーネント
- `Dialog`
- `FormControl`
- `TextField`
- `Select`
- `ButtonGroup`

## ポイント
- フッターの複数アクションは `ButtonGroup` で横並びにする
- `DialogFooter` は右寄せを基本とする
- 必須項目は `FormControl required` を使って明示する

このように、SKILL.md では「どのレシピを読むか」という導線だけを持たせ、具体的な実装ルールは references/ に段階的に分離しました。

この3層構造により、AI は常にすべての情報を読み込む必要がなくなり、コンテキストウィンドウを効率的に利用できるようになりました。

既存コードベースとの関係：アンチパターンと向き合う

コードベースが十分に育っている環境では、AI は agentic search（AI が自律的にコードベースを検索・探索する機能）で既存コードを参照して実装できます。しかし、これには落とし穴があります。

既存コードベースには必ずしもベストプラクティスに沿ったコードだけが含まれているわけではないからです。

例えば、大規模リポジトリでは、以下の問題が発生します。

  • 非推奨パターンの参照: 古い実装パターンを AI が「正しい」と判断して模倣してしまう
  • チーム間の書き方の不一致: 同一リポジトリ内でもチームごとにファイル・コンポーネント分割の方針が異なる
  • AI のバイアス: 既存コードの傾向に AI が引きずられ、Skills で示したベストプラクティスが無視される

Skills の導入と並行して、Rules で「Skills と agentic search で競合した場合、Skills の情報を優先する」という原則を AI に提供しました。これにより、AI は既存コードよりも先にベストプラクティスを参照します。その結果、アンチパターンの学習を防げます。ただし、サービス側のコードがベストプラクティスと大きく乖離している場合は、Skills の恩恵を十分に受けられないケースもあり、コードベースの改善も並行して進める必要があります。

<!-- Rules に記載する例 -->
## Aegis コンポーネントの実装ルール
- Aegis コンポーネントを実装する際は、必ず Aegis Skills を先に参照すること
- 既存コードベースの実装パターンと Skills の記述が矛盾する場合、Skills の情報を優先すること

Skills の読み込み率を引き上げるための工夫

Skills を導入すると精度は向上しますが、Skills が読み込まれるかどうかは安定しません。

この Skills の読み込み率は、何も工夫しない場合は30〜80%にとどまりました。この幅が生じたのは、タスクの種類やプロンプトの具体性によって読み込まれやすさに差があったためです。ここでは、読み込み率を100%に近づけるために行った工夫を紹介します。

Description の最適化

Skills の読み込み率を左右する最大の要素は Description（説明文）です。Skills の選択は LLM（Large Language Model）の推論に委ねられており、すべての Skills の Name / Description はシステムプロンプト内の「Skill」メタツールにフォーマットされます。モデルはそれをもとにユーザーのリクエストとのマッチングを判断するため、Description の書き方がそのまま読み込み率を決定します。

公式ドキュメントでも、Description には「何をするか」と「いつ使うか」の両方を明確に含めることが求められています（Anthropic Docs: Skill authoring best practices）。

Description の最適化をする際に、具体的には以下のことをしました。

  • AI がどのようなプロンプトに反応して Skills を読み込むかを観察
  • 他の Skills との組み合わせ時に干渉が起きないかを検証

たとえば、初期の Description は「Aegis のコンポーネントに関するスキル」のような曖昧な記述でした。最終的には以下のように、具体的なコンポーネント名とユースケースを明示する形に収束しました（※実際の Description とは異なります）。

Use this skill when implementing UI with Aegis Dialog, Modal, or Drawer components. Covers Props, composition patterns, and accessibility requirements.

これにより、「Aegis の Dialog を使って…」というプロンプトであれば、ほとんどのケースで Skills が読み込まれるようになりました。基本的には Skills だけでも問題なく使えます。実際、Rules や既存コードベースがない新規環境でも、Skills があれば正しい「Aegis」コンポーネントを生成できました。

しかし、Skills の数が増えると状況は変わりました。Description 同士が競合し、意図した Skills が選ばれにくくなる傾向が出てきたのです。また、「似たように実装して」のような曖昧なプロンプトでは、いくら Description を改善しても Skills が無視されやすいという問題も残りました。Description の最適化だけでは読み込み率80%が限界でした。

Rules との連携

残りの20%を埋めるために、Rules と Skills を連携させるアプローチを採用しました。

「Aegis」の Skills はリポジトリ内で厳守すべきルールに近い性質を持っています。そこで、Description に書いていた「いつ使うか」の内容を Rules 側にも記載し、Skills の利用を強制する運用にしました。実際には、この2要素の役割分担が重要でした。Skills 側の Description では「何をするか」を厚めに書き、Rules 側では「いつ使うか」「どの状況で対応する Skills を参照するか」を重点的に書くと、利用率が上がりました。

具体的には、「Aegisのコンポーネントを実装する際は、必ず対応する Skills を参照すること」というように、Rules に指示を記載します。

これにより、AI は起動時に Rules を読み込んだ段階で「このタスクにはこの Skills が必要だ」と判断できるようになり、前述の検証条件では読み込み率が30回中30回となりました。

考察／今後の展望

Aegis Skills はまだ解決すべき課題と、さらなる発展の余地があります。

現時点での課題は、「Aegis」のコンポーネント数が多く、すべての組み合わせや利用パターンに十分対応できていないことです。今後も新しいコンポーネントや API が増えていくため、Skills や references/ に載せるデータ、評価用の観点を継続的に増やし、対応していく必要があります。

最終的には、「Aegis」のコンポーネントが更新されたら Skills も自動的に追従し、妥当な内容が生成され続ける状態を目指しています。

まとめ

本記事では、社内デザインシステム「Aegis」の Skills を活用して、AI コーディングエージェントの精度を30%から90%以上に引き上げた取り組みを紹介しました。

ポイントをまとめます。

  • MCP サーバー → AGENTS.md / Rules → Skills と3つのアプローチを経て、段階的に精度を向上させた
  • Skills の読み込み率を高めるには、Description の最適化を基本にしつつ、厳密な遵守が必要な場面では Rules で利用条件を補助するのが有効
  • Progressive Disclosure（段階的開示）の考え方で、情報を3層に構造化することが重要
  • 既存コードベースのアンチパターンの学習を防げる
  • 今後は最新の Aegis に自動で追従し続ける仕組みの構築とカバレッジ拡大を目指す

社内独自のライブラリやフレームワークを持つ組織にとって、Skills は非常に強力なツールです。AI にとっての「知らない世界」を「熟知した世界」に変えることで、開発効率を大きく向上させられます。

参考文献

謝辞

本プロジェクトを一緒に進めていただき、且つ本ブログをレビューしてくださった時武さん、ありがとうございました。

仲間募集！

LegalOn Technologiesでは、一緒に働く仲間を募集しています。ご興味のある方は以下のリンクからぜひご応募ください。お待ちしております。

herp.careers

recruit.legalontech.jp