【クイックサマリー】本記事で紹介するのは、既存プロダクトのUI規約・デザイン制約をAIコーディングエージェントに守らせるための「AGENTS.md（横断ルール）・Skill（タスク別手順）・テスト（機械的検証）」という3層の知識配置設計です。AGENTS.mdとAgent Skillsはオープンな仕様・慣習であり、Claude Code・Codex CLI・Antigravity CLIなど主要なAIコーディングCLIで応用できます。
AIに既存のUIコンポーネントを使って画面を実装させると、「それらしい画面」はできるのに、一覧画面の操作列の契約が外れたり、フォーム部品の使い分けが崩れたりして、レビューでの差し戻しに消耗していませんか？ この課題に対して、株式会社Digeonのエンジニアy-fujimura氏がZennで公開した検証記事は、「AIの能力ではなく、知識の置き場所を変える」という具体的な解決策を、スコア付きの比較実験とともに示しています。
- AGENTS.md・Skill・テストのそれぞれに「どの種類の知識」を置くべきかの判断基準
- 知識の置き場所だけを変えた4パターン比較検証の実測スコア
- Claude Code / Antigravity CLI でのAGENTS.md・SKILL.mdの具体的な配置手順
- 実際の画面実装タスクに3層設計を組み込むフロー
AGENTS.md・Skill・テストの3層役割分担とは
元になっているのは、神戸大学発のAIベンチャーである株式会社DigeonがZennで公開した検証記事「AIに既存UIの制約を守らせるAGENTS.mdとSkillとテストの役割分担」です。記事は無料で公開されており、扱われているAGENTS.mdはagents.mdで公開されているオープンなフォーマット、Agent Skills（SKILL.md）も複数のCLIが採用する公開仕様のため、特定ベンダーへのロックインなしに試せます。
記事の出発点は「AIは既存コンポーネントを使うことはできるが、その制約を守り続けることができない」という観察です。一覧画面の操作列に決まった契約があるのに独自実装に流れる、画面遷移と行内アクションの責務が混ざる、フォームで入力種別ごとの部品の使い分けを外す——人間ならレビューで自然に拾えるルールが、AIでは「それっぽい実装」のまま通ってしまいます。
そこで提案されているのが、知識の性質に応じた3層の配置です。
各層の得意・不得意
- AGENTS.md: 常に参照させやすい反面、詳細を増やすと読みづらくなる。→ 短く横断的なルール（操作列の基本契約、画面遷移と行内アクションの責務分離、フォーム部品利用の最低限ルールなど）を置く
- Skill（SKILL.md）: タスクに合わせて手順や組み立て方を渡せる反面、対象外のタスクでは呼び出されない。→ 画面種別ごとの実装手順（一覧画面でのfilter / order / paginationの組み合わせ方、フォームでのschema / payload変換やsubmitまわりの組み立て方など）を置く
- 型 / lint / テスト: 違反を機械的に検出できる反面、文脈や文章の良し悪しは判断できない。→ 破ると危険で判定可能な契約（一覧部品の型定義、フォーム部品の誤用検出、共通部品の回帰テストなど）を落とし込む
判断基準は「常に読ませたい短いルールか」「特定タスクで使う組み立て知識か」「コードから違反を判定できる契約か」の3択です。
検証データ：知識の置き場所でAIの出力はどう変わったか
この記事の価値は、抽象論ではなく統制された比較検証にあります。記事によると、検証にはCodex Desktop（親スレッドはGPT-5.4）を使い、各パターンの実装はコンテキストを引き継がないsubagentに依頼することで、モデルと実行環境をそろえて「AIが参照できる知識」だけを変えて比較しています。
比較したのは、Baseline（補助なし）/ AGENTS.mdのみ / Skillのみ / Hybrid（両方）の4パターン。ケースは「操作列を含む一覧画面」「filter / order / pagination付き一覧画面」「部品の使い分けが必要な入力フォーム」の3つで、採点は100点満点（制約遵守50点・既存UIの活用度25点・アクセシビリティ / 一貫性15点・修正コスト10点）に固定されています。
結果の要点は次のとおりです。
- 入力フォームのケースで差が最大：Baseline 89点に対しSkillは95点（6点差）
- filter / order / pagination付き一覧：Baseline 91点、AGENTS.md 93点、Skill / Hybrid 94点
- 操作列を含む一覧：93〜95点に収まり差が最小（既存実装の影響を受けやすいケース）
記事自身が「各組み合わせは原則1回ずつの実行であり、この点数だけで優劣を断定するものではない」と明記している点は誠実で、そのうえで「横断ルールにはAGENTS.mdが一定の効果を持つが、画面種別ごとの組み立て知識はSkillの方がやや効果が高い」という傾向を導いています。一方、機械的に判定できる契約を文章に任せる理由はなく、型 / lint / テストに落とす方針が示されています。
3層をプロジェクトに配置する手順
元記事は特定CLIの設定手順までは踏み込んでいないため、ここではAGENTS.md・Agent Skillsの公開仕様に沿った一般的な配置方法を紹介します。
AGENTS.mdの配置
AGENTS.mdはプロジェクトルートに置くMarkdownファイルで、公式サイト（agents.md）によると多数のAIコーディングエージェントが読み取りに対応しています。3層設計に沿うなら、書くのは「短く横断的なルール」だけに絞ります。
# AGENTS.md（抜粋例）
## UIの横断ルール
- 一覧画面の操作列は共通の ActionColumn コンポーネントを必ず使う
- 行クリックは画面遷移、行内ボタンは操作。責務を混ぜない
- フォーム部品は共通ラッパー経由で使う（素のinput禁止）
- 補足説明文はラベルの言い換えを書かないSkill（SKILL.md）の配置
Claude Codeの場合はプロジェクトの .claude/skills/<スキル名>/SKILL.md に配置します。Antigravity CLI（agy）の場合は、ワークスペース単位なら <プロジェクトルート>/.agents/skills/、グローバルなら ~/.gemini/antigravity-cli/skills/ が配置場所です。SKILL.mdの記述例は次のようになります。
---
name: list-page-builder
description: 一覧画面（filter / order / pagination付き）を既存UI規約に沿って実装する手順
---
# 一覧画面の組み立て手順
1. 表示部品は DataTable を使い、列定義は columns.ts に分離する
2. filter / order / pagination は useListQuery フックに集約する
3. ソートUIはヘッダーセル経由のみ。独自ボタンを追加しない
4. 操作列は ActionColumn の契約（項目数・並び順）に従う配置後の動作確認は、Claude Codeならセッション内で「一覧画面を追加して」と該当タスクを依頼し、descriptionに基づいてスキルが読み込まれるかを確認します。呼び出されない場合はdescriptionにトリガーとなるキーワード（「一覧画面」「フォーム」等）が含まれているかを見直してください。
型・lint・テストへの落とし込み
「破ると危険で、違反を機械的に判定できる契約」は文章ではなくコードに落とします。元記事では、一覧部品の型定義・画面操作の競合テスト・フォーム部品の誤用検出・共通部品の回帰テストが例示されています。たとえば「素のinput要素を直接使わない」というルールは、ESLintのカスタムルールや型で強制すれば、AIが忘れてもCIで確実に検出できます。
実際の開発フローに3層設計を組み込む方法
実務での回し方を、Claude Codeを例にしたシナリオで示します。
- タスク依頼: 「検索結果の一覧画面を新規実装して」と依頼すると、AGENTS.mdの横断ルールが常時コンテキストに入り、一覧系Skillが手順を供給する
- 実装中: AIはSkillに書かれた「表示部品＋useListQuery＋ActionColumn」の組み立て手順に沿って実装する
- 検証: hooksでlint・テストを自動実行し、型・lintに落とした契約違反（部品の誤用など）を機械的に検出する
- レビュー: 人間は「文章化も機械化もできない設計判断」だけに集中する
職種別のユースケースとしては、次のような場面で特に効果が期待できます。
- 自社SaaSのフロントエンドチーム: 一覧・フォーム・詳細画面のパターンが確立しているため、画面種別ごとのSkill化の投資対効果が高い
- 受託開発・SIer: 案件ごとに異なるデザインシステムの制約をAGENTS.md＋Skillに externalize しておけば、メンバー交代やAI併用時の規約逸脱を減らせる
- デザインシステム運用担当: 「コンポーネントの正しい使い方」ドキュメントをSkill形式で提供することで、利用側チームのAIにも規約を届けられる
元記事の重要な指摘は「課題はAI側だけでなく、既存UI資産の暗黙知がコードやドキュメントに表れていないことにもあった」という点です。人間には自然な暗黙知でも、AIにとっては書かれていない限り存在しません。この3層設計は、プロンプトの工夫ではなく実装資産の再設計だと捉えるのが本質的と考えられます。
類似アプローチとの比較
AIに規約を伝える手段は複数あります。主な選択肢を整理します。
| 手段 | 対応CLI / 環境 | ライセンス | 最終更新 | 特徴 |
|---|---|---|---|---|
| AGENTS.md | Codex CLI・Antigravity CLIほか多数（公式サイトに対応ツール一覧あり） | オープンなフォーマット | 随時更新 | 常時参照される横断ルール置き場。短く保つのが前提 |
| Agent Skills（SKILL.md） | Claude Code・Antigravity CLI等 | 公開仕様 | 随時更新 | タスクに応じてオンデマンド読込。手順・組み立て知識向き |
| CLAUDE.md / copilot-instructions.md | Claude Code / GitHub Copilot（各CLI固有） | 各ベンダー仕様 | 随時更新 | 役割はAGENTS.mdと同系。CLI固有のため複数ツール併用時は重複管理が必要 |
| 型 / lint / テスト | CLI非依存（CI / ローカル） | 各ツールに依存 | — | 機械的に違反検出可能。AIが忘れても効く唯一の層 |
使い分けの軸は「常時か、タスク時か、機械検証か」です。どれか1つで全部を賄おうとすると、AGENTS.mdの肥大化やSkillの未発火といった各層の弱点を踏むことになります。
注意点・制約
- 検証の統計的限界: 元記事の検証は各組み合わせ原則1回ずつで、点差も最大6点と大きくありません。記事自身が断定を避けているとおり、「この構成なら必ず良くなる」とは言えない点に注意が必要です
- Skillの未発火リスク: Skillは対象外と判定されたタスクでは呼び出されません。descriptionの書き方がトリガー精度を左右します
- AGENTS.mdの肥大化: 詳細を書き足すほど読まれにくくなります。「短く横断的なルールのみ」の原則を守り、手順はSkillへ逃がす運用が必要です
- メンテナンスコスト: UI規約が変わったらAGENTS.md・Skill・テストの3か所を同期する必要があります。放置すると「古いルールをAIが忠実に守る」事故につながります
- セキュリティ: AGENTS.md / SKILL.md自体はリポジトリ内のローカルファイルで、これ自体が外部通信を行うことはありません。ただしAIコーディングCLI自体はコードをモデル提供元へ送信するため、機密プロジェクトでは各CLIのデータ取り扱い規約の確認が前提です。また、ファイル内にAPIキー等のシークレットを書かないでください
まとめ
要点は次の3つです。
- AIに既存UIコンポーネントを「使わせる」ことと「制約を守らせる」ことは別の課題であり、後者には知識の置き場所の設計が効く
- 横断ルールはAGENTS.md、画面種別ごとの組み立て知識はSkill、機械的に判定できる契約は型 / lint / テストへ——知識の性質で3層に分ける
- Digeonの検証（Codex Desktop・GPT-5.4・採点固定）では、フォーム実装でBaseline 89点に対しSkill 95点と、タスク特化知識の効果が最も明確に表れた
「AIに何を知っていてほしいか」ではなく「その知識をどこに置けば再利用しやすいか」まで設計する——この視点は、Claude CodeでもAntigravity CLIでもそのまま応用できます。さらに詳しい検証条件や採点内訳は元記事（Zenn）を、AGENTS.mdの仕様と対応ツールはagents.md公式サイトを参照してください。
コメント