AGENTS.mdの書き方|Codexが足しがちな補足ラベルを減らすUI指示

公開 更新 10 分で読了
AGENTS.mdの書き方|Codexが足しがちな補足ラベルを減らすUI指示

Codexが設定画面に足す重複した補足を、AGENTS.mdの指示で減らす方法を解説します。ファイルの置き場所と読み込み順、入力欄のラベル・単位・エラー理由を残すひな型、狭い画面やアイコンボタンまで確認できる判定表を紹介します。

AGENTS.md は、Codexにプロジェクトの作業ルールを渡すMarkdownファイルです。ファイルは無料で作成できます。CodexはChatGPT Freeにも含まれ、CLIで試す場合は利用中のプランでCLIが使えるかを公式の料金ページで確認できます。12 設定画面の見出しと重なる補足だけを削り、入力欄の名前・単位・エラーの理由を残す指示を、プロジェクト内に保存できます。

AGENTS.mdでUIの補足ラベルを減らす

補足ラベルを除き、時間とエラーの情報を残すイメージ

架空の「通知設定」画面を使います。画面には「メール通知」のスイッチと「通知間隔」の数値入力があり、通知間隔には5〜60分の整数を設定できるとします。

まず削れるのは、「通知設定」という見出しの直下にある「通知の設定を変更できます」のような一文です。「メール通知」の下に「メール通知を設定します」と付け足しても、いつ・誰に・何が届くのかは分かりません。

画面上の文言 判断 判断の理由
通知設定 残す 開いている画面が分かります。
通知の設定を変更できます 削る 見出しと同じ内容を繰り返しています。
メール通知 残す スイッチが何を切り替えるか分かります。
通知間隔 残す 数値入力の目的が分かります。
分 残す 入力値「15」の単位が分かります。
5〜60分の整数 残す 入力できる値を操作前に判断できます。
5〜60分の整数を入力してください エラー時に表示 対象の入力欄と修正方法が分かります。

同じ数字や語句が出ていても、表示の役割が異なる場合があります。たとえば「5〜60分の整数」は入力前の条件で、エラー時の案内は、入力した値を次にどう直すかを伝えます。

削る前に文言の役割を確認する

  1. 画面が伝える情報を書き出します。 「通知設定」では、切り替える通知の種類、間隔の単位、入力できる範囲を拾います。
  2. 候補の一文を外して読みます。 「通知の設定を変更できます」を外しても、見出しと項目名で画面の用途が分かります。「分」を外した場合は「15」が何の単位か分からなくなるため、単位を残します。
  3. 状態が変わっても伝わるか確認します。 初期表示、入力中、エラー時の順に見ます。値を入力したあとも欄の名前が読めて、入力に失敗したら理由と修正方法が分かれば、必要な説明が残っています。

別の節に「通知設定」という見出しがある画面でも、冒頭の要約と操作場所の見出しはそれぞれ役割を持つことがあります。文字の一致だけで消すと案内が途切れるので、文言の近くにある項目や利用者の次の操作まで見て判断します。

Codexが読むAGENTS.mdをどこに置くか

プロジェクトのルートから設定ディレクトリまでたどるイメージ

設定画面を含むプロジェクト全体で使うなら、プロジェクトのルートにある AGENTS.md に追記します。OpenAIのCookbookでも、プロジェクトの作業方針やテストのルールを継続して伝える場所として、このファイルを紹介しています。3

プロジェクト内の配置を決める

  1. 対象画面と作業ディレクトリを確認します。 たとえば apps/web/settings/ を作業の起点にするなら、プロジェクトのルートからその場所までにある指示ファイルを上から確認します。
  2. 影響させたい範囲に追記します。 UI全体のルールならルートが候補です。既存のルールで別のフォルダに適用範囲を分けている場合は、対象の作業ディレクトリまでの経路にある指示も読みます。
  3. Codexを対象のディレクトリで起動します。 新しいセッションで「読み込んだ指示ファイルと、通知設定に適用する文言ルールを要約してください」と依頼します。想定したファイルと、削る対象・残す対象の両方が回答に出るかを確認します。1

公式ガイドの探索順は、グローバルの指示から始まり、プロジェクトのルートから現在の作業ディレクトリまで進みます。プロジェクト内の各階層では AGENTS.override.md、AGENTS.md、設定済みの代替ファイル名の順で探し、階層ごとに最大1ファイルを取り込みます。1

たとえばルートで起動していて、今回のルールを apps/web/settings/AGENTS.md に置いた場合、公式ガイドの起動時の探索経路はルートまでです。下位の指示を起動時から取り込む構成では、対象ディレクトリを作業起点にできます。1

codex --cd apps/web/settings "読み込んだ指示の出典と、通知設定に適用するUI文言ルールを挙げてください。ファイル編集はしないでください。"

既存の指示と重なる場合

たとえばルートに「設定フォームの入力条件は操作前に表示する」とあり、下位に「補足文を減らす」とだけ書くと、条件まで削除候補に見えます。「同じ情報を繰り返す説明を減らす。単位と有効範囲は保持する」と書き換えると、どちらのルールも同時に満たせます。

Codexは作業ディレクトリに近いファイルの指示を後から結合します。同じ階層の AGENTS.override.md が選ばれる場合、AGENTS.md への追記が読み込まれないため、要約に出てこなければファイルの位置と選択順を調べます。1

Claude Codeを併用する場合は、Claude Code側でプロジェクトの指示ファイルがどう選ばれるかも調べます。実装前に対象と確認項目を詰める流れは、Claude Codeのplanモードの使い方に具体例があります。

AIのUIデザイン指示に削る文言と残す文言を書く

文言ルールと入力欄のラベルを対応させるイメージ

「補足を減らして」と頼むときは、補足のうち何を減らすかと、どの情報を表示し続けるかをセットで書きます。特にフォームでは、常時見えるラベル、入力例、支援技術に伝える名前を分けると、実装後の差分を判断しやすくなります。

要素 通知設定での例 実装後に見る箇所
表示ラベル 通知間隔 入力欄のそばに表示し、欄と関連付けます。
入力例 例:15 例がなくても意味が伝わるか確認します。
単位・入力条件 分、5〜60分の整数 何を入力できるか事前に読めるようにします。
アクセシブルな名前 「通知テストを送信」 アイコンボタンが支援技術に伝える名前を確認します。

表示ラベルは、たとえばHTMLの label 要素を使って対応する入力欄と関連付けられます。アイコンだけのボタンにも、操作を示すアクセシブルな名前を持たせます。47

コピーして使えるAGENTS.mdのひな型

次のブロックは、チームで繰り返し使うルールとして追記できます。「説明は簡潔に」と抽象的に書く代わりに、削除する情報、表示を保つ情報、変更報告の形式を記載します。

### 設定画面の文言

- 見出しやラベルで伝わる内容を、直下の説明で繰り返さない。
- 入力欄の表示ラベル、単位、有効範囲、形式、必要な操作結果は保持する。
- 入力例を追加する場合、入力しても項目名と必要な条件が読めるようにする。
- エラー時は、対象の項目と修正できる内容を文章で伝える。
- アイコンだけのボタンには、実行される操作が分かる名前を付ける。
- 実装後に削った文言と理由、残した説明、確認した表示状態を報告する。

一つの画面で適用する

  1. 変更対象を一つに絞ります。 「通知設定コンポーネントで、見出し直下とメール通知の補足だけを点検してください」と依頼し、対象ファイルや画面の経路が分かれば添えます。
  2. 先に候補を出してもらいます。 文言ごとに「削る」「残す」と理由を示すよう頼みます。数値入力の単位やエラー原因が削除候補になったら、どの場面で必要かを指示に足します。
  3. 変更後の差分を確認します。 意図した重複が消え、ラベルと入力欄の関連付け、エラー表示の条件、ボタンの名前が保たれていれば、次の画面にも同じルールを適用できます。

色や動きの指定も同じ文書に集める場合は、文言のルールと該当する見出しを分けます。動きについて何を具体化するかは、UIアニメーションの指示例で、変化・時間・イージングの指定例を確認できます。

画面の意味が保たれているかレビューする

狭い画面、エラー表示、通知アイコンを点検するイメージ

文言を削ったあとに見るのは、残ったテキストだけで設定を終えられるかどうかです。次の表は、幅の狭い画面、保存時のエラー、ラベルの見えないボタンまで、同じ「通知設定」の作例で点検できるようにした判定表です。

通知設定の差分を点検する判定表

場面 確かめる操作 合格の目安
幅の狭い画面 320 CSS pxを一つの確認幅にして通知間隔を読む 項目名、単位、範囲に横スクロールや切れがなく、どの入力欄に対応するか分かります。
値の入力後 通知間隔に「15」を入力する 値が入っても「通知間隔」と「分」が読み取れます。
エラー時 作例の入力範囲外にあたる「4」で保存を試す 通知間隔のエラーだと特定でき、5〜60分の整数を入力すれば直せると分かります。
アイコンだけの操作 通知テストのボタンへキーボードで移動し、支援技術が受け取る名前を確かめる 操作の名前が「通知テストを送信」と分かり、キーボードでも実行できます。
正常値に戻した後 値を「15」に直して保存し、表示を確認する エラーが解消され、保存後も値と単位が正しく読めます。

幅の確認では、横並びだったラベルと説明が折り返された位置も見ます。たとえば入力欄の「分」が直後の設定項目に近づきすぎると、文字が読めてもどちらの単位か迷うため、同じ欄の情報としてまとまるように表示を調整します。5

エラー時に赤枠だけが出る場合は、通知間隔に何を入れれば修正できるかを文章で示します。アイコンボタンでは見た目と別に、実装した名前が支援技術に届くことを確かめます。67

結果を変更差分に残す

  1. 正常値と不正値を切り替えます。 表の入力値を使い、エラーが出る条件と解消される条件を同じ欄で確認します。
  2. 狭い幅とキーボード操作を確認します。 狭い幅で名前・単位・エラー文を読み、キーボードでボタンまで移動して、支援技術に伝わる名前と役割を確かめます。
  3. 試した場面だけを報告します。 「320 CSS pxで項目名と単位を確認」「4分でエラー表示」「支援技術での読み上げは未確認」のように、どの状態をどこまで見たかを書きます。

公開前のプレビュー運用も整える場合は、Cloudflare PagesにAIで作ったサイトを公開する手順を参照できます。画面の文言を直したあとは、変更前に比べて短くなったかに加えて、値の入力から保存まで必要な情報が各場面で読めるかを見ます。

よくある質問

Q. 既存のAGENTS.mdに追記できる?
追記できます。既存のフォームやアクセシビリティのルールを確認し、見出しと内容が重なる補足だけを削る条件を加えます。
Q. どのフォルダに置く?
プロジェクト全体に使うならルートが候補です。対象の作業ディレクトリに近い指示や、同じ階層のAGENTS.override.mdの有無も確認します。
Q. プレースホルダーでラベルを代用できる?
入力欄には、値を入れたあとも見えるラベルを付けます。プレースホルダーを使うなら、入力例などの補助に使います。[4]
Q. Claude Codeでも同じファイルを読む?
Claude Code v2.1.277以降は対応しています。作業ディレクトリか上位にプロジェクトのCLAUDE.mdなどがある場合、既定ではそちらが優先されます。対応環境ではProject instructionsの設定で両方を読み込めます。[8]

出典・参考データ

  1. [1] AGENTS.mdによるカスタム指示 (OpenAI) — 取得 2026-11-19
  2. [2] ChatGPTとCodexのプランと利用枠 (OpenAI) — 取得 2026-11-19
  3. [3] Codexを使った開発ワークフローの改善 (OpenAI) — 取得 2026-11-19
  4. [4] フォーム入力欄のラベル (W3C WAI) — 取得 2026-11-19
  5. [5] 狭い表示幅でのリフロー (W3C WAI) — 取得 2026-11-19
  6. [6] 入力エラーの特定 (W3C WAI) — 取得 2026-11-19
  7. [7] 操作要素の名前・役割・値 (W3C WAI) — 取得 2026-11-19
  8. [8] Claude Codeのプロジェクト指示 (Anthropic) — 取得 2026-11-19

この記事を書いた人

水島 翔吾

株式会社kairos 代表取締役 / AgentSignal 開発者

AI クローラー・AI 流入計測と AIO 診断ツール AgentSignal を開発。実測データを元に AI 検索時代の計測と対策を書いています。

関連記事