Claude CodeとCodexで共通のデザインシステムを作る
2つのコーディングツールが共通のデザイン指針を参照する方法を紹介します。
同じリポジトリでClaude CodeとCodexを使い分けていると、一方はデザインルールに従うのに、もう一方は初期設定に戻ってしまうことがあります。この差を減らすには、ツールごとの作業指示と製品のビジュアルルールを分け、両方のエージェントが同じデザイン情報を参照できるようにします。
大切なのは、すべてのツールでファイル名を統一することではありません。それぞれのファイルに明確な役割を持たせます。
デザイン原則とエージェント指示
製品のビジュアルアイデンティティとUIルールはDESIGN.mdにまとめます。カラートークン、タイポグラフィ、余白、角丸、重要なコンポーネントの使い方や状態を記録します。一方、CLAUDE.mdとAGENTS.mdにはエージェントの作業手順を書きます。既存コンポーネントを先に調べること、プロジェクトの慣習を確認すること、依頼とデザインルールが衝突したときに説明することなどです。
こう分けると、ブランドの基準は一か所で更新し、ツール固有のコマンドやレビュー手順は各指示ファイルで調整できます。デザイン文書が視覚的な判断の原本であり、ツール指示ファイルはその原本を見つけ、適用する方法を知らせる案内役になります。
CLAUDE.mdとAGENTS.mdの構成
Claude Codeはプロジェクト指示としてCLAUDE.mdに対応し、AGENTS.mdも読み込めます。ただし、デフォルトの読み込み条件に注意が必要です。作業ディレクトリまたはその親ディレクトリにCLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.mdのいずれかがあると、標準設定ではCLAUDE.md系だけを読み、AGENTS.mdは読みません。該当するファイルがない場合、Claude Code v2.1.277以降は作業ディレクトリと親ディレクトリのAGENTS.mdおよび.claude/AGENTS.mdを読みます。/configでclaude-md-and-agents-mdを選べば両方を読み込めます。またCLAUDE.mdに@AGENTS.mdインポートを記す方法でもルールを共有できます。実際に読み込まれたかは/memoryまたは/context allで確認しましょう。
Codexはリポジトリの指示ファイルとしてAGENTS.mdを認識します。リポジトリの構成例は次のとおりです。
project/
├── DESIGN.md
├── AGENTS.md
├── CLAUDE.md
├── src/
└── docs/
長いルールをAGENTS.mdとCLAUDE.mdの両方に複製するのではなく、各ファイルには共通の参照先を簡潔に書き、ツール固有の指示だけを追加します。重複した内容が少なくなり、デザインルールの食い違いも防ぎやすくなります。
たとえばAGENTS.mdには次のように書けます。
## Project instructions
- Before changing UI, read the root DESIGN.md and relevant component docs.
- Reuse existing tokens and components before adding new values.
- If a request conflicts with the design rules, explain the conflict and use the narrowest change.
- For visual changes, report the pages and states that need review.
共通ファイルを一つにしたい場合は、CLAUDE.mdから@AGENTS.mdで読み込むか、/configでclaude-md-and-agents-mdを選びます。AGENTS.mdを直接読み込むにはv2.1.277以降が必要で、一部のセッションや設定では利用できない場合があります。/memoryまたは/context allで読み込みを確認してください。
プロジェクト指示の作成基準
繰り返し使う指示はルートのファイルに置きます。「新しいボタンを作る前に既存のButtonコンポーネントのバリアントを確認する」は、多くのUI作業に適用できます。特定ディレクトリだけのアクセシビリティ確認や個別のテスト手順は、必要な場所だけに置いてもよいでしょう。Claude Codeは.claude/rules/にパス別ルールを置けます。Codexでは階層下にAGENTS.mdを置いてディレクトリごとの指示を定義できます。
範囲の広すぎるルールは、小さな変更まで重くしてしまいます。「作業のたびにすべての文書を読む」より、「レイアウトを変えるときはDESIGN.mdを、APIを変えるときはAPI文書を確認する」と書きましょう。OpenAIのCodexガイドも、指示を具体的にし、作業に関係する情報を示すことを勧めています。
DESIGN.mdのデザインルール
ツール指示でデザイン文書を読むよう伝えても、抽象的な形容詞だけでは結果に差が出ます。実際の選択につながるルールを書きましょう。「親しみやすくミニマルに」ではなく、目で確認できる基準を示します。
---
name: Northstar Console
colors:
primary: "#2457D6"
canvas: "#F4F6FA"
ink: "#172033"
border: "#D8DEE9"
rounded:
control: 8px
spacing:
sm: 8px
md: 16px
lg: 24px
components:
button-primary:
backgroundColor: "{colors.primary}"
textColor: "#FFFFFF"
rounded: "{rounded.control}"
padding: 10px
---
## Overview
注文状況をすばやく把握するための運用コンソールです。
強い色は主要な操作と選択状態にだけ使います。
通常のカードには影を付けず、選択項目は枠線で区別します。
たとえばCodexに注文一覧の空状態を実装するよう頼むとき、DESIGN.mdに空、エラー、選択状態で使う色や文言のルールがあれば、結果をレビューしやすくなります。Claude Codeも同じ色の役割や余白のルールを参照できます。
AI生成結果の検証
Claude Codeの公式ドキュメントは、CLAUDE.mdとAGENTS.mdを強制設定ではなく、会話のコンテキストとして説明しています。ファイルが読み込まれても、すべてのルールに必ず従うとは限りません。具体的で簡潔な指示のほうが安定して伝わります。必ず禁止したい操作は、指示ファイルの文章だけでは保証できないため、権限設定やフックなどの強制機能を使います。
DESIGN.mdも、すべてのコーディングエージェントが自動で読み込むわけではありません。各ツールが形式に対応しているか、ファイルが実際にコンテキストに含まれているかを確かめてください。必要に応じてCLAUDE.mdとAGENTS.mdから明示的に参照し、タスクのプロンプトにもファイル名を書きます。
画面とコンポーネント状態の確認
最初からアプリ全体を作り直さず、小さな画面一つで二つのツールを比較しましょう。たとえば「注文詳細画面に通常、エラー、無効状態のボタンを実装し、既存コンポーネントを先に確認してください」と依頼します。色や余白だけでなく、キーボードフォーカス、無効状態、長い文言、狭い画面でのレイアウトも確認します。
両方の出力が同じルールを外したなら、DESIGN.mdを改善します。一方だけが指示ファイルを見つけられなかったなら、そのツールの読み込み設定やプロジェクト案内を見直します。原因を分けて考えることで、仕組みを保守しやすくなります。
デザインシステムの変更管理
デザイン文書をコードと別に管理すると、内容が古くなることがあります。CSSトークンやコンポーネントが変わったら、同じ作業でDESIGN.mdも更新し、実装と一緒にレビューしましょう。ルールが増えてきたら、製品全体で使うものと特定の領域だけで使うものを分けます。
二つのエージェントが同じデザインシステムを使うことは、出力が完全に一致するという意味ではありません。同じデザイン判断を出発点にし、各ツールでその判断を読み込んで適用する手順を明確にすることです。作業結果に読み込んだファイルと確認した画面状態を記せば、文書のルールが製品に反映されたかを確認しやすくなります。