AI エージェント（自分のパソコンのファイルを読み書きしながら開発を進める AI）に頼むとき、同じことを頼んでも、伝え方しだいで結果が大きく変わります。この記事では、何をどう伝えるとねらいどおりに動くかを、実際に頼み比べながら確かめます。
練習には、小さな Web ページを使います。エージェントの作業場所に選んだ空のフォルダで、次の1文を送れば同じページができます。
このフォルダに index.html を1つ作ってください。「今日のひとこと」というボタンがあり、押すと、用意した5つの言葉から1つがランダムに選ばれてボタンの下に表示されるページにします。HTML・CSS・JavaScript は index.html の1つのファイルにまとめてください。
頼む前に、戻れる地点を作っておいてください。Git でコミットするか、フォルダをコピーしておきます。この記事ではわざとあいまいな頼み方も試すので、何度か元に戻すことになります。
AI は書かれていないことを想像で埋める
エージェントの中の AI は、渡された文章の続きを予想して答えを作ります。答えを作るときに AI が見ているのは、次の5つだけです。
AI が答えを作るときに見ている文章全体を、コンテキスト（文脈）と呼びます。自分の頭の中にある「こういう感じにしたい」「ここは触ってほしくない」は、文にして渡さないかぎりコンテキストに入りません。入っていないことを、AI は想像で埋めます。
あいまいに頼んでみる
練習用のフォルダを作業場所にして、新しいチャットで、次の1文だけを送ってください。
ページをおしゃれにして
ブラウザでページを開き、エージェントの報告と変わった所を見ます。色を全部変え、文字の大きさを変え、影や角の丸みを足し、ボタンの文言や HTML の組み方まで変えていることがあります。外部のフォント（インターネットから読み込む文字の形）を足すこともあります。
どれも「おしゃれにする」の範囲に入るので、エージェントは間違えたとは思っていません。おしゃれとは何か、どこまで変えてよいか、何を変えてほしくないかを、エージェントが自分で決めた結果です。見終わったら、戻れる地点まで戻してください。
頼む文に書くこと
頼むときは、次の5つのことを書きます。全部を毎回書く必要はなく、頼む中身に合わせて選びます。
| 書くこと | 例 |
|---|---|
| 変えてほしいこと | 「ボタンを、角が丸くない四角にして、背景を青にする」 |
| どこを変えるか | 「CSS の部分だけを変える」 |
| できあがりの条件 | 「スマホの幅（375ピクセル）でも、ボタンの文字が1行に収まる」 |
| してほしくないこと | 「ボタンの文言と、言葉を選ぶ動きは変えない」 |
| どこで止まってほしいか | 「変えたら止まって、変えた所を箇条書きで教えて」 |
「おしゃれにして」を5つで書き直すと、たとえば次のようになります。
ページの見た目を整えてください。
- 背景は白、文字は黒 #111114、ボタンは青 #1E5BFF に白い文字にしてください
- ボタンの角は丸めず、影も付けないでください
- 変えるのは CSS の部分だけです。ボタンの文言と、言葉を選ぶ動きは変えないでください
- 外部のフォントやライブラリ（ほかの人が作ったプログラムの部品）は読み込まないでください
- スマホの幅（375ピクセル）でも、ボタンの文字が1行に収まるようにしてください
- 終わったら、変えた所を箇条書きで教えてください
送って、さっきの結果と比べます。変わる所が CSS だけになり、確かめる所が少なくなります。
理由を一言書く
条件だけでなく、なぜそうしたいかを添えると、書いていない細かい所も AI がその理由に合わせて決めます。
スマホで見る人が多いので、スマホの幅で崩れないことを一番に考えてください。
この1文があると、頼まれていない文字の大きさや余白も、スマホで読みやすいほうに寄せて決めます。理由が書かれていないと、AI はパソコンの広い画面を思い浮かべて決めることがあります。
自分で決められないことは先に選択肢を出してもらう
どう頼めばよいか自分でも分からないときは、作らせる前に選択肢を出してもらいます。
このページに「お気に入りの言葉を保存する」機能を足したいです。
やり方をいくつか、それぞれの良い点と困る点を添えて挙げてください。まだファイルは変えないでください。
挙がった中から選び、選んだものを5つのことで書いて頼みます。何を作るかを決めるのは自分で、AI はその材料を出す役です。
書かせる前に計画を出してもらう
大きめの頼みごとは、書かせる前に「何をどう変えるつもりか」を出してもらうと、ずれを早く直せます。
押した回数を数えて表示する機能を足したいです。
まだファイルは変えずに、どのファイルのどこに何を足すつもりかを、計画として箇条書きで出してください。
計画を読んで、考えていたことと違う所があれば、その場で直します。
計画の 3 は要りません。回数は、ページを開き直したら 0 に戻ってかまいません。それ以外はこの計画で進めてください。
計画の段階で直せば、ファイルはまだ変わっていないので、戻す手間がかかりません。
エージェントによっては、ファイルを変えずに調べて計画だけを出すプランモードがあります。Codex のアプリにも同じような使い方があるかもしれませんが、公式の説明では確かめられていません。どのエージェントでも、「まだファイルは変えずに、計画を出して」と書けば同じことができます。
大きなことは小さく分けて頼む
「このページを、言葉を投稿できるサイトにして」のような大きな頼みごとは、一度に頼まないほうがうまくいきます。一度にたくさんのファイルが変わると、確かめるのも、どこで間違えたかを探すのも手間がかかります。
「言葉を入力する欄を作る」「入力した言葉を一覧に足す」「一覧を保存する」のように分けて、1つ頼むごとに確かめ、戻れる地点を作り直します。途中でうまくいかなくなっても、1つ前の地点に戻ればやり直せます。
資料の渡し方
頼みごとの文のほかに、AI に見てほしいものを渡す方法がいくつかあります。
ファイルを指す
どのファイルの話かを名前で指します。ファイルの名前を、文の中にそのまま書けば伝わります。エージェントによっては、打つ欄で @ を打つとファイルの候補が出て、選べます。Codex のアプリで使えるかは、画面で試して確かめてください。
@index.html のボタンの部分だけを直してください。
名前を書かないと、エージェントはフォルダの中を探して、関係ありそうなファイルを自分で選びます。小さなフォルダでは困りませんが、ファイルが何十個もあると、違うファイルを直してしまうことがあります。
エラー文はそのまま全部貼る
動かないときは、画面やターミナルに出たエラー文を、言い換えずにそのまま貼ります。どの操作で起きたかも書きます。
ボタンを押しても何も表示されません。ブラウザの開発者ツールの Console に、次の赤い文字が出ています。
Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')
at index.html:42:10
原因を探して直してください。直す前に、原因が何だったかを説明してください。
「動きません」とだけ伝えると、エージェントはどこを見ればよいか分からず、関係ない所まで書き換えることがあります。このエラー文には、何が起きたか（null、つまり何も無いものの addEventListener を読もうとした）と、どこで起きたか（index.html の 42 行目）が入っているので、探す範囲が狭まります。
「直す前に、原因を説明して」と書くのにも理由があります。原因が分からないまま直してもらうと、たまたま動くようになっただけのことがあり、同じ失敗がまた起きます。
見た目のずれは画面の写真で渡す
「ボタンが少し右にずれている」のような見た目の問題は、言葉で説明するより、画面の写真（スクリーンショット）を渡すほうが伝わります。
Windows の場合
Windows キーと Shift と S を同時に押すと、画面の一部を選んで写真にできます。撮った写真はコピーされた状態になるので、入力欄で Ctrl を押しながら V を押すと貼れます。貼れないときは、写真のファイルを保存して、入力欄にドラッグして落とします。
Mac の場合
Command と Control と Shift と 4 を同時に押すと、画面の一部を選んで写真にでき、コピーされた状態になります。入力欄で Command を押しながら V を押すと貼れます。貼れないときは、写真のファイルを保存して、入力欄にドラッグして落とします。
貼ったら、写真のどこがどうおかしいかと、どうなってほしいかを文で添えます。
公式ドキュメントや見本を渡す
AI は、学習した時点より新しいことを知りません。新しく出た道具の使い方や最近変わった書き方は、間違えることがあります。そういうときは、公式ドキュメント（作った会社や団体が出している説明書）の URL を渡して、「これに従って書いて」と頼みます。
次のページに書かれている書き方に従ってください。
https://developer.mozilla.org/ja/docs/Web/API/Window/localStorage
エージェントの多くは、渡された URL のページを読みに行けます。読めなかったと言われたら、ページの必要な部分をコピーして貼ります。「このページのような見た目にしたい」というときは、見本のページの写真を貼るか、似せたいコードを貼ります。
ルールのファイルを置く
「色は青と黒だけ」「外部のライブラリは使わない」「終わったら変えた所を教えて」のように、毎回の頼みごとに書きたいことがあります。毎回書くのは手間で、書き忘れもあります。そこで、フォルダの一番上に、そのフォルダでのきまりを書いたファイルを置きます。エージェントは作業を始めるとき、このファイルを自動で読んでコンテキストに入れます。
| エージェント | 読むファイル |
|---|---|
| Codex | AGENTS.md |
| Antigravity CLI | GEMINI.md か AGENTS.md |
| Claude Code | CLAUDE.md。無ければ AGENTS.md |
AGENTS.md は、いろいろなエージェントが共通で読む名前として広まっているファイルで、Codex はこの名前を読みます。ここでは AGENTS.md を使います。名前の最後の .md は、見出しや箇条書きを記号で書く Markdown という書き方のファイルを表す拡張子です。
Codex の公式の説明では、作業するフォルダのいちばん上から今の作業場所まで、AGENTS.md を上から順に読んでつなげます。近い場所にあるファイルのほうが、あとから読まれて優先されます。合わせた大きさの上限は 32KiB です。
書いてみる
練習用のフォルダに、VS Code で AGENTS.md というファイルを作り、次のように書いて保存します。
## このフォルダのきまり
- ページは index.html の1つのファイルにまとめる（CSS と JavaScript も中に書く）
- 色は青 #1E5BFF と黒 #111114 と白だけを使う
- 外部のライブラリやフォントは読み込まない
- 変更が終わったら、変えた所を箇条書きで報告する
公式の説明では、ルールのファイルは作業を始めるときに1回だけ読まれます。ファイルを作る前から Codex のアプリを開いていた人は、アプリを一度閉じて開き直し、新しいチャットを始めます。そのあと、次のように聞きます。
このフォルダのきまりを、ファイルを開かずに、知っている範囲で教えてください。どこで知りましたか。
4つのきまりが返ってきて、AGENTS.md から知ったと答えれば、読まれています。
Claude Code を使う人は、同じフォルダやその上のフォルダに CLAUDE.md があると、そちらが読まれて AGENTS.md は読まれません。読まれていないときは、同じ中身を CLAUDE.md という名前で置いてください。
よく守られる書き方
ルールのファイルは、AI が読んで従おうとするもので、守られるとは限りません。守られやすくするには、次のように書きます。
- 確かめられる形で書きます。「きれいに書く」より「インデント（行の頭の空白）は2文字」、「確かめておく」より「終わったらブラウザで開く手順を書く」のほうが守られます
- 短くします。長いと、1つ1つのきまりが守られにくくなります。Codex では合わせた大きさに上限もあります
- 食い違うきまりを書きません。2つのきまりがぶつかると、AI はどちらかを勝手に選びます
- 同じことを2回注意したら、ファイルに書き足します。毎回言い直していることが、書くべきことです
ルールのファイルの下書きは、エージェントに頼んで作ってもらうこともできます。「このフォルダの中身を調べて、AGENTS.md の下書きを作って」と頼みます。下書きは、そのまま使わずに読んで、自分の言葉で直してから使います。
会話が長くなったら
1つの会話で頼みごとを重ねると、それまでのやりとりも全部コンテキストに入ります。入る量には上限があり、長くなるほど、最初のほうに書いたことが守られにくくなったり、前の失敗を引きずって同じ間違いをくり返したりします。
次のようなときは、会話を最初からにします。
- 1つの頼みごとが終わって、別の話に移るとき
- 同じ所を2回、3回と直してもらってもうまくいかないとき
Codex のアプリでは、New chat で新しいチャットを始めると、会話が最初からになります。ファイルはそのまま残ります。続きの話をするときは、新しい会話の最初に「今こういう状態で、次にこれをしたい」と短くまとめて渡します。ずっと渡したい前提は、会話に書かずルールのファイルに書いておけば、最初からにしても消えません。
渡してはいけないもの
頼みごとの文や貼ったファイル・写真は、AI のモデルを動かしている会社に送られます。パスワード、API キー（サービスを使うための合言葉）、人の名前や連絡先が入ったデータは、文にも写真にも入れないでください。写真を貼るときは、ほかのタブや通知に、見られて困るものが写っていないかも確かめます。
課題：お気に入りの言葉を保存する機能を足す
練習用のページに、「お気に入りの言葉を保存する」機能を足します。この課題で練習するのは、コードよりも頼み方です。
作るものは次のとおりです。
- 表示された言葉の横に「お気に入り」ボタンを置く。押すと、その言葉がページの下の一覧に足される
- ページを開き直しても、一覧が残っている
- 今ある「今日のひとこと」の動きは、そのまま動く
進め方は、AGENTS.md を置いてエージェントが読んでいることを確かめ、戻れる地点を作り、「まだファイルは変えずに、計画を出して」と頼み、計画を読んで直す所を直してから進めてもらい、必要な5つのことを書いて頼み、ブラウザで確かめます。うまくいかなければ、エラー文か画面の写真を渡して直してもらいます。
確かめ方は次の4つです。
- お気に入りに足した言葉が、一覧に出る
- ページを再読み込みしても、一覧が残っている
- 色が AGENTS.md のきまり（青・黒・白）から外れていない
- 自分が送った頼みごとの文を見返して、5つのことのうちどれを書いたかを言える
計画を頼む文は、たとえば次のようになります。
表示された言葉の横に「お気に入り」ボタンを置き、押すとその言葉がページの下の一覧に足されるようにしたいです。
ページを開き直しても一覧が残るようにしたいです。
まだファイルは変えずに、どこに何を足すつもりかを計画として出してください。
ページを開き直しても残すために、どんな方法を使うつもりかも書いてください。
計画には、たいてい localStorage（ブラウザの中に小さなデータを残しておく場所）を使うと書かれます。「開き直しても残す」とだけ書くと、サーバーやデータベースを用意する大がかりな方法を選ぶこともあるので、計画で方法を確かめます。計画に問題が無ければ、次のように続けます。
この計画で進めてください。
- 変えてよいのは index.html だけです
- 今ある、言葉をランダムに表示する動きは変えないでください
- 同じ言葉を2回お気に入りにしたときは、一覧に2回出なくてかまいません
- 終わったら止まって、足した行を説明してください
3つ目の行は、計画を読んで気づいた「同じ言葉を2回押したらどうなるか」を、こちらで決めて伝えたものです。書かなければ、エージェントが想像で決めます。どちらに決めても間違いではありませんが、自分で決めておけば、できあがりを見たときに迷いません。
参考にした資料
- Codex「Custom instructions with AGENTS.md」（ルールのファイルを置く場所と優先順位）: https://developers.openai.com/codex/agent-configuration/agents-md
- Codex「Prompting」（目的・前提・出力の形・守ってほしい範囲を伝える考え方）: https://developers.openai.com/codex/prompting