プロジェクトのたびに表記や確認方法を伝え直すと、抜けや食い違いが起きます。
AGENTS.mdは、Codexへプロジェクトの共通指示を伝えるために使える文書です。
このレッスンでは、架空の研修サイトを例に、何を書くか、どこまで共通化するかを考えます。
長い注意書きではなく、次の作業者が同じ前提で仕事を始められる1枚を作ります。
この記事で学ぶこと
- 共通条件と今回の依頼を分ける
- 正本と確認方法を明示する
- 実行結果からルールを更新する
続けて使う前提を選ぶ
AGENTS.mdへ置くのは、複数の依頼に共通する条件です。
対象利用者、設計上の約束、編集方法、必要な検証などが該当します。
今日だけの文言修正や、一度限りの締切は今回の依頼へ書きます。
恒常的なルールと単発の作業を分けると、過去の条件が次の修正へ混ざることを避けられます。
架空の研修サイトなら、「利用者はAIに不慣れな社会人」「表示文章は日本語」「確定した料金はdata内の指定資料を正本とする」が共通条件です。
「今週はトップの見出しを変える」は一時的な依頼です。
前者をファイルへ、後者を会話へ置くことで、作業のたびに何を説明するかが整理されます。
OpenAIの公式資料では、AGENTS.mdの探索や適用範囲が説明されています。
上位と下位のフォルダに指示がある場合など、読み込まれる条件を確認してください。
最初は対象プロジェクトの直下で最小構成を作り、複数の場所へ分ける必要が出たら範囲を見直します。
名前だけ同じファイルを増やすと、矛盾の保守が難しくなります。
ルールの候補を選ぶ際は、次の担当者が知る必要のある前提かを問います。
個人の過去の好みをすべて残すより、表示上の約束や正本の場所を優先します。
一度だけ起きた特殊な不具合は、関連する作業へ進むときに参照できる記録として分ける方法もあります。
共通指示を読みやすく保つ工夫です。
目的と正本を明記する
目的には、利用者が何を判断できればよいかを書きます。
「魅力的なサイトにする」だけでは、文章を増やすか短くするかの基準がありません。
「研修の対象、内容、申込方法を確認して参加を判断できる」と書けば、必要な情報が選べます。
技術の好みより、成果を使う人の行動を先に置きます。
正本は、情報が食い違ったときに戻る基準です。
料金、日時、講師名などは、見た目のページより確定資料を根拠にする場合があります。
どの情報をどのファイルで管理しているかを書きます。
古い画面の文字列を正解とすると、変更するたびに過去の誤りを再利用することがあります。
参照先は、実際に開けるかを確かめます。
ファイル名が変わっている、手順が別の場所へ移っている場合は更新が必要です。
正本が見つからないときに、似た資料で置き換えるのか、未確認として止めるのかも決めます。
業務上の確定情報なら、根拠のない代替を選ばない条件が適しています。
正本を決めた後も、内容の確認が必要な場合があります。
確定資料の中で日付と曜日が一致しないなら、どちらかを推測して直さず矛盾を報告します。
正本は判断の出発点であり、誤りが絶対にないという保証ではありません。
資料の場所と、矛盾した際の確認先を合わせて示します。
変更の境界を操作で書く
禁止事項は、何を変えないかが分かる言葉にします。
「安全に作業する」ではなく、「依頼にない料金変更をしない」「認証情報を成果物へ書かない」「本番公開は指定の確認後に行う」と書きます。
操作の対象が明確であれば、成果物から守られたかを確認できます。
許可する範囲も一緒に示します。
文言の修正なら、指定ページの文章を編集し、必要な表示確認を行えると書きます。
すべての操作へ承認を求めるルールは、通常の仕事も止めてしまいます。
不可逆な操作や、業務上の責任を伴う判断を中心に境界を設けます。
既に明確な許可がある操作は、その範囲で進められるようにします。
AGENTS.mdの記述と、実行環境のアクセス制御は異なります。
ファイルへ「秘密を読まない」と書いても、技術的に読み取れない状態になるとは限りません。
権限設定や秘密の保管場所も別途整えます。
指示だけを防壁と考えず、実行できる範囲と作業のルールを一致させます。
変更の例外を認める条件も短く示します。
対象ページだけの修正では直せない場合、共通部品への影響と理由を説明するなどです。
範囲を守るために不具合を残すことも、勝手に全面改修することも避けます。
必要性を説明できる追加変更と、関係のない改善を区別する基準になります。
検証を実際の手順へ結び付ける
検証欄には、プロジェクトで実際に使える確認方法を書きます。
想像したコマンドや、以前の別案件の手順をそのまま貼ることは避けます。
構文確認、表示確認、リンク確認など、それぞれが調べる対象を示します。
何のために実行するかが分かれば、変更に応じた確認を選べます。
架空のサイトでは、文章変更後に対象ページを開き、指定の文言、リンク先、狭い画面での折り返しを確認するとします。
処理を変更した場合は、既存のテストも使います。
軽微な文章修正へ不要な大規模検査を強制するより、影響に応じた条件を明記すると、確認の負担を適切にできます。
報告には、変更の要点、実施した検証、未確認事項を含めます。
「すべて確認済み」と書くより、何が確認できたかを具体化します。
検証が実行できなかった場合は理由を残し、成功に含めません。
次の担当者が、採用か追加確認かを判断できる報告形式にします。
確認方法には、実行できなかった場合の次の行動も置きます。
表示環境がないなら、どの画面の確認が残ったかを報告します。
別の担当者が見ればよいのか、環境を準備する必要があるのかが分かる形にしてください。
単なる未実施の表示より、解消方法がある記録の方が引き継ぎに役立ちます。
実例で指示の働きを見る
AGENTS.mdを書いたら、見本の修正を1件実行して結果を確認します。
ファイルを読んだという返事より、正本に従ったか、編集対象を守ったか、検証を行ったかを見ます。
実際の差分と報告から確認すると、曖昧なルールを見つけられます。
例えば「不要な変更をしない」と書いても、全体の整形まで実行されたとします。
期待が指定箇所のみなら、「今回の要求に関係しない整形を含めない」と具体化します。
ただし、正しい実装に必要な変更まで禁じないよう、例外時には理由を示す条件を置きます。
失敗のたびに禁止を増やすより、判断基準を直します。
運用後は、使わなくなった手順と矛盾する記述を減らします。
依存する仕組みが変われば、検証方法も更新が必要です。
更新した理由と確認日を残しておくと、次の人が背景を理解できます。
共通ルールは長さで価値が決まるものではなく、現在の仕事に合った前提を維持できるかで評価します。
ルールを更新した日は、代表的な依頼で読みやすさも確認します。
指示が増えた結果、目的や正本が埋もれていないかを見ます。
見出しで役割を分け、同じ条件を複数回書かないようにします。
長いことを丁寧さと考えず、実際の判断に必要な情報を探せる構成へ整えます。
実践課題
実践課題：共通指示を一枚にする
つくるものは、練習用研修サイトのAGENTS.mdです。
用意するのは、サイトの目的、確定情報の見本、実際に使える検証方法です。
今日だけの依頼と共通条件を分け、見本の文言修正を使って確認します。
読んだ人が具体的な操作へ移せる内容にしてください。
- 目的と利用者を書く
- 確定情報の正本と参照先を示す
- 編集できる範囲と承認が必要な操作を記す
- 検証と報告形式を定め、見本で試す
架空の完成例：「研修の参加判断を支援する。料金と日時はconditions.mdを正本とする。指定ページだけ変更し、無関係な整形は含めない。表示とリンクを確認し、変更箇所・確認結果・未確認を報告する。」
自己確認
- 一時的な依頼が混ざっていない
- 正本と検証方法が実在する
- 結果から指示の有効性を確認した
まとめ
AGENTS.mdには、次の仕事でも有効な目的、正本、変更の境界、検証方法を残します。
権限設定とは役割が異なると理解してください。
次の小さな修正で結果を確かめ、解釈が分かれた箇所だけを具体化します。
- 共通条件と今回の依頼を分ける
- 正本と確認方法を明示する
- 実行結果からルールを更新する
