CodexのAGENTS.mdはいつ書くか — その場の指示を「恒常ルール」に昇格させる4つの合図

結論 — 同じ指摘を2回したら、その場で書く

判断はこれだけです。同じ指摘を2回した瞬間に、言い直すのではなくファイルに書く。1回目は偶然かもしれませんが、2回目は仕組みの問題です。

多くの人が損をしているのは、その場で言い直す方が早いからです。指摘して直れば作業は進みます。しかし次のセッションでは同じことが起きます。指示はその場限りで、判断基準として残らないためです。

AGENTS.mdは毎回読まれるファイルです。ここに1行足すことは「以後ずっと前提として渡す」ことを意味します。だからこそ、足すタイミングを意識的に決める必要があります。

合図① 同じことができる手段が複数あって、遅い方を選ばれる

最も分かりやすい合図です。当社で実際に起きた例を書きます。業務で使っているマーケティングツールには、Codexから触る経路が3つありました。

• REST API — 数秒で完了し、結果も確実。対応している操作なら最短
• MCPサーバー — 接続は簡単だが、対応している操作の範囲が狭い
• ブラウザを直接操作 — 何でもできるが、遅く、画面の変更に弱く、都度の許可も必要

起きたのは、APIなら数秒で終わる作業に、Codexが繰り返しMCPを使いたがるという現象でした。MCPでは対応していない操作なので当然失敗し、そのうえで「できませんでした」と報告が返ってきます。

原因はAIの判断力ではなく情報の非対称です。AIは「実行できそうか」で手段を選びますが、「速いか・確実か」では選びません。速さや成功率は、何度も試した人の中にしかない情報だからです。

そこで「このツールはAPIを第一選択にする。まず対応するエンドポイントの有無を確認してから、他の手段を検討する」という趣旨をAGENTS.mdに書きました。次から間違えなくなります。日々の運用で、体感の改善幅が最も大きかった変更のひとつです。

合図② 出力の表記を毎回同じように直している

社名・製品名・日付の書式・敬称——毎回同じ直しを入れている箇所は、そのまま恒常ルールの候補です。

特に効くのが音声入力を使っている場合です。当社では依頼の多くを音声で出しますが、固有名詞は辞書に登録しても表記が揺れます。「揺れて入力されても、成果物では必ずこの表記に寄せる」とAGENTS.mdに書いておくと、入力側の揺れをAIが吸収してくれます。

この種のルールは判断を伴わないので、書けば確実に効きます。最初の1行に迷ったら、ここから始めるのが手堅い選択です。

合図③ 「やってほしくなかったこと」を一度やられた

既存ファイルを上書きされた、下書きのつもりが送信されかけた、顧客名をそのまま成果物に書かれた——一度ヒヤリとした操作は、その日のうちに禁止事項として書きます。

この合図は①②と違い、2回目を待ってはいけません。1回目の被害が小さかったのは運の要素があるためです。

合図④ 「終わったかどうか」の説明を毎回している

「元データと件数が一致していれば完了」「スマホでも崩れないことを確認したら完了」——完了の判定基準を毎回口頭で足しているなら、それも恒常ルールです。

ここを書いておくと、成果物が出てきた時点で自己検証まで済んだ状態になります。書き方の型はCodexのプロンプトの書き方の完了条件と同じで、全作業に共通するものだけをAGENTS.mdへ上げます。

AGENTS.mdに書かない方がいいもの

合図が出ても、行き先がAGENTS.mdとは限りません。毎回読まれるファイルなので、入れすぎるとAIが一度に扱える情報量を圧迫し、かえって精度が落ちます。

迷ったときの目安は「この前提は、関係ない作業のときにも読ませたいか」です。読ませたくないなら、AGENTS.mdではありません。全体の整理はCodexのハーネスとはにあります。

書き方 — 禁止形ではなく「肯定形＋確認手順＋代替」

同じ内容でも、書き方で効き目が変わります。合図①の例で比べます。

第一選択・確認方法・外れたときの次点の3つが揃うと、AIが自分で判断して動けます。1つでも欠けると、迷ったところで止まるか、勝手に選び直します。

書く作業そのものはCodexに任せる

合図に気づいたら、人がやるのは何を恒常ルールにするかを決めることだけです。文章化と配置はCodexに任せられます。

「今指摘した内容を、次回から守るようにルールへ書き足して」と伝えれば、適切な場所に追記されます。その場で言い直すのと、ほぼ同じ手間でルール化まで済みます。この一手間が積み上がると、同じ説明を繰り返す時間が目に見えて減ります。

当社のCodex研修・導入伴走支援では、貴社の業務で「Codexが毎回迷っている箇所」を洗い出し、その場でAGENTS.mdに落とすところまで行います。ここが埋まると、日々の言い直しが減り、担当者以外が使っても結果が揃うようになります。