AGENTS.mdの書き方。AIに渡す引き継ぎノートの作り方

AIに作業を頼むたびに、同じ注意を書いていませんか。秘密情報は見ないで、勝手に公開しないで、既存の書き方に合わせて、変更前に説明して。毎回チャットへ貼っているうちに、何を頼みたいのかより、注意書きを思い出すことに時間を使ってしまいます。

その疲れは、AIへの頼み方が悪いからではありません。引き継ぎノートがまだ机の上にないことが原因です。AGENTS.mdは、AIに最初に読ませるプロジェクト用の引き継ぎノートです。長い規則集を作る場所ではなく、毎回言っている前提を1枚にまとめる場所です。

ここでは、初心者が自分用のAGENTS.mdを書く手順を扱います。AGENTS.md、Skills、Rules、Memoryの役割の違いはAGENTS.md・Skills・Rules・Memoryの役割。AIに引き継ぎ棚を渡す方法で整理しています。この記事では、そこから一歩進めて、今日作れる最小のAGENTS.mdに絞ります。

AGENTS.mdは、AIに渡す引き継ぎノート

AGENTS.mdは、AIに「この現場ではこう動く」と伝えるためのファイルです。新人スタッフに渡す引き継ぎノートに近いものだと考えると分かりやすいです。

たとえば、初めて入るお店で働く人に、いきなりレジや発注を任せることはありません。最初に、開店前に見る場所、触ってよい棚、店長へ確認する場面、使ってはいけない言葉を伝えます。AIも同じです。作業能力が高くても、現場の前提を知らないまま動くとズレます。

AGENTS.mdに書くのは、毎回守ってほしい前提です。すべての作業手順を詰め込む必要はありません。最初は、次の4つがあれば十分です。

• どんなプロジェクトか
• どんな文体や進め方にするか
• 触ってよい範囲と触らない範囲
• 作業後にどう確認するか

ここで大事なのは、AIを縛ることではなく、人間が確認しやすい形にすることです。AIへの指示は、忘れやすい注意を外に置く作業です。毎回のチャットに注意書きを積み上げるより、AGENTS.mdに置いたほうが、頼む側も落ち着いて作業を始められます。

Codexを使う前の作業場所や承認境界は、Codexを使い始める前に整える設定。初心者が最初に見る5つの場所でも扱っています。AGENTS.mdは、その作業場所に置く説明書です。

最初に書くのは目的、範囲、安全線

AGENTS.mdを書こうとすると、最初からきれいなルール集を作りたくなります。でも初心者が最初に書くべきものは、目的、範囲、安全線の3つです。

目的は、このフォルダで何をしたいのかです。記事下書きなのか、練習用サイトなのか、家計メモなのか、仕事用の資料整理なのか。目的がないと、AIは良さそうな改善を勝手に広げやすくなります。

範囲は、どこまで触ってよいかです。文章の下書きだけなのか、ファイル作成までよいのか、コマンド実行もよいのか。ここを曖昧にすると、頼んでいない場所まで変更されても気づきにくくなります。

安全線は、人間が止める場所です。秘密情報、顧客情報、外部送信、本番公開、支払い、データベース変更のように、ミスしたときの影響が大きい作業は、AIだけで進めない線として書きます。

最初の下書きは、このくらいで足ります。

# AGENTS.md

目的
このフォルダは、AIに記事下書きとメモ整理を手伝ってもらう練習用です。

進め方
- 日本語で短く説明する
- 変更前に、目的と変更範囲を確認する
- 既存ファイルの書き方に合わせる
- 依頼と関係ない変更はしない

安全線
- 秘密情報、APIキー、.env、顧客情報は扱わない
- 外部送信、本番公開、課金、DB変更は人間確認で止める
- 作業後は、触ったファイルと確認結果を説明する

これは完璧な規則ではありません。最初の赤い線です。部屋の片付けで、最初に「捨てるもの」「残すもの」「迷うもの」の箱を置くような感覚です。線を置くと、AIも人間も次の判断がしやすくなります。

同じ注意を2回言ったらAGENTS.mdへ移す

AGENTS.mdは、最初から完成させるものではありません。使いながら育てます。判断の目安は、同じ注意を2回言ったかどうかです。

たとえば、Codexへ毎回「まだファイルは変更しないでください」と書いているなら、AGENTS.mdの進め方に入れます。毎回「本文はやさしい日本語で」と書いているなら、文体ルールに入れます。毎回「SNS投稿はしないで」と止めているなら、安全線に入れます。

反対に、1回だけの依頼はAGENTS.mdに入れません。今日だけ使うタイトル案、今回だけの修正方針、単発の調査対象まで入れると、引き継ぎノートが読みにくくなります。AGENTS.mdは、毎回見る棚です。そこに一時メモを全部置くと、必要なものが埋もれます。

移すか迷ったら、次の3つで見ます。

• 次回も同じ注意をする可能性があるか
• 守らないと事故や手戻りが大きいか
• 1文で書けるか

1文で書けないものは、まだ整理できていない可能性があります。その場合は、まずチャットで使いながら言葉を短くします。

AIへの頼み方そのものを整えたい場合は、AIへの指示のコツ。頼み方を変えるだけで答えが変わるの考え方も使えます。チャットで毎回書く指示と、AGENTS.mdへ移す指示を分けると、頼み方がかなり軽くなります。

5分で作れる最小テンプレ

最初のAGENTS.mdは、短いほうが続きます。長い文章にすると、AIも人間も読まなくなります。最初は、目的、仕事の進め方、安全線、検証方法の4ブロックにします。

そのまま使うなら、次の形です。

# AGENTS.md

このプロジェクトの目的
ここに、何を作る場所かを1〜2文で書く。

作業の進め方
- 日本語で簡潔に説明する
- 変更前に、目的、前提、変更範囲、検証方法を短く整理する
- 既存の書き方、命名、ファイル構成に合わせる
- 依頼と関係ないリファクタリングや機能追加はしない

安全線
- 秘密情報、APIキー、トークン、.envは表示しない
- 顧客情報や個人情報を記事やサンプルに出さない
- 外部送信、本番公開、課金、DB変更は人間確認で止める

作業後の確認
- 変更したファイルを説明する
- 可能な範囲でテスト、ビルド、リンク確認を行う
- 検証できなかったことは未検証として書く

ここに自分のプロジェクト名を入れるだけでも、AIの動きは変わります。たとえば記事サイトなら「記事下書きと画像準備をする場所」と書く。練習用コードなら「ローカルで動く小さな練習アプリを作る場所」と書く。

テンプレを作るときの注意は、強い言葉で盛らないことです。「すべて完璧に確認する」「ミスを出さない」と書いても、実務では意味が薄いです。それより、「変更したファイルを説明する」「検証できなかったことを書く」のほうが使えます。

AGENTS.mdは、AIを賢く見せるための文章ではありません。人間があとから確認できるようにする文章です。短く、戻せる範囲で、毎回使う言葉にしておくのが一番扱いやすいです。

作ったあとにCodexへ読み合わせさせる

AGENTS.mdを書いたら、すぐ大きな作業を頼まず、読み合わせから始めます。人間同士の引き継ぎでも、紙を渡して終わりにはしません。「今の説明でどこまで分かったか」を確認します。Codexでも同じです。

最初に貼る依頼文は、これで十分です。

このフォルダのAGENTS.mdを読んでください。

まだファイルは変更しないでください。
次の3つを日本語で短く説明してください。

1. このプロジェクトでAIが手伝ってよいこと
2. 人間確認で止めること
3. 次に試す小さな依頼

この返答を見れば、AIがAGENTS.mdをどう読んだか分かります。もし「本番公開まで進めます」と返ってきたら、安全線が弱いか、依頼文が広すぎます。もし「何もできません」と返ってきたら、範囲が狭すぎるかもしれません。

読み合わせのあとに、小さな作業を1つだけ頼みます。

README.mdを読みやすくする候補を3つ出してください。
まだ編集はしないでください。

次に、提案を見てから編集を許可します。

1つ目の案だけ反映してください。
変更後に、触ったファイルと確認結果を説明してください。

この順番なら、提案、確認、編集、差分確認が自然に分かれます。AGENTS.mdは、AIに丸投げするための免許証ではありません。短いキャッチボールを安定させるための引き継ぎノートです。

最初の1枚は、粗くてかまいません。毎回同じ注意をチャットに書いている状態から、1つずつAGENTS.mdへ移す。これだけで、AIに頼む前の迷いと、作業後の確認漏れがかなり減ります。