AGENTS.mdでClaude CodeとCodexの指示書を一本にする方法を、飯塚浩也さんの動画で整理する

出典: 【超朗報】Claude Codeで開発が変わる！AGENTS.mdの書き方から作成まで完全解説【Codex】【Cursor】

指示書を、AIごとに書き分けていませんか？動画は、飯塚さんと聞き手の会話から始まります。話題は、AIエージェントの指示書です。

聞き手が、最近 Claude Code でも AGENTS.md が使えるようになったと聞いた、と切り出します。二人の話は、そこから始まります。

飯塚さん（動画の中で・0:46〜）

書き直したりとかクロードコード使う時はここ読んでねみたいな形で誘導しなければいけなかった。人に説明する時にクロードコードだけ別なんですよとか正直めんどくさかったんですよ。

これまで Claude Code は AGENTS.md を読めませんでした。だから書き直すか、別のファイルへ誘導する手間がかかりました。人に説明する時も、Claude Code だけ別扱いで面倒だった、という話です。

飯塚さん（動画の中で・1:00〜）

カーソル、クロードコード、コデックス、その他のAIを使ってる方は特にインパクトが大きい内容だと思ってます。

Cursor と Claude Code と Codex。AIを何本も使う人ほど、この変化は大きい、と飯塚さんは話します。

私の Mac には、Claude Code 用の起動ファイルが71行、Codex 用が163行、Grok 用が68行あります（10月30日に数えた行数です）。どれも別のファイル。

で、Codex と Grok の側には、同じ見出しの絶対ルール索引があります。本文の正本は、共通のルール置き場にある62ファイル。AIは違っても、別々の入口から同じ索引を指す形です。

AIを乗り換えるたびに、指示書の作り直しが要った。動画は、その理由を、AIエージェントを順に並べるところから語ります。

飯塚さんが用意したのは、Cursor と Codex と Claude Code。Cursor は2023年ごろから使っている、と話します。

Cursor では、AIの動きを調整するために、ルールという考え方が生まれました。最初は .mdc という特殊なファイルで作った、と飯塚さんは振り返ります。

その後、Codex と Claude Code が出てきます。ところが、どちらも別々のファイルでルールを作りました。統一は無し。

みんな縄張り意識が強い、と飯塚さんは話します。いちばん偉かったのは Cursor で、AGENTS.md なども読めるようにしました。Codex は昔から AGENTS.md 一択です。

スキルは、Cursor でも Codex でも Claude Code でも使えます。MCP も同じ。共通の規格があればツールを変えても困らない、電化製品のタイプCの端子のようなもの、と飯塚さんは例えます。

飯塚さん（動画の中で・2:44〜）

なぜかこのルールに関してはもうずっと統一されてない状態が続いてきました。

ところが、ルールだけは揃わないままでした。Claude Code だけが、別の名前のファイルを使っていたからです。

飯塚さん（動画の中で・3:03〜）

なので今までこれができなかったので何をしてたかと言うとこのファイルの中身にここを読んでねっていう風に指示を出したりシンボリックリンクって言ってこのファイルからここを常に参照するようにしたと。

これまでの回避策は二つ。一つは、Claude Code 用のファイルに、別のファイルを読むよう書いておく方法です。二つ目は、シンボリックリンクで別のファイルを常に参照させる方法で、同期に近い形。

そんな複雑な設定は、要らなくなりました。AGENTS.md だけで全てのAIエージェントを使える、と飯塚さんは話します。

私の記事より（AGENTS.mdと権限・フックの使い分けをチャエンさんが解説。「メールは送らないで」と書いても守られない時の止め方・AGENTS.mdとフォルダ。開く場所で、乗る約束が変わる）

私の作業フォルダでは、AGENTS.mdが本文の実ファイル。CLAUDE.mdは、その同じ本文を指す別名になっています。Claude CodeとCodexに、名前を変えて同じ約束を読ませる形です。

シンボリックリンクにあたる形は、私の作業フォルダですでに使っています。本文の実ファイルは AGENTS.md で、CLAUDE.md はその別名。中身は1枚です。

別のファイルへ案内する形も、私の手元にあります。Codex と Grok の起動ファイルで、索引の見出しとして使っている形です。

これからは、AGENTS.md に揃えれば済みます。私の作業フォルダでは、本文の実ファイルは AGENTS.md の1枚です。

AGENTS.md の置き場所は、一番上だけではありません。飯塚さんは、Obsidian の保管庫を例にして説明します。

例にするのは、保管庫の中で Claude Code や Cursor を使う場面です。AGENTS.md は、その一番上に置く、と飯塚さんは話します。

これまでは、同じ場所に CLAUDE.md も別に書く必要がありました。今は AGENTS.md 1本で大丈夫。

保管庫の中に、二つのフォルダがあるとします。一番上のルールは、全部のワークスペースに効きます。

飯塚さん（動画の中で・4:17〜）

本当はマーケティングの時だけAIエージェントにルールを適用したいなそういうシーンがあったとします。

マーケティングの時だけ効かせたいルールがある。そんな時は、マーケティングのフォルダの中にも AGENTS.md を作ればいい、という話です。

Codex ではこれまでもできました。Claude Code でもできるようになった、と飯塚さんは話します。

下のフォルダの AGENTS.md は、起動の時には読まれません。公式のページにも、下のフォルダの AGENTS.md は、そのフォルダのファイルを Claude が開いた時に読まれる、とあります。置けば最初から効く、とは別の話です。

私の置き場は三層です。全案件用、プロジェクト用、そして案内役の短いファイル。

AIが失敗するたびに、ここ直して、と頼んでいませんか？その一言が積み重なると、AGENTS.md は静かに太っていきます。この章は、長さの話。

飯塚さんは、AGENTS.md のポイントとして、いっぱい書いてしまうことを挙げます。油断すると、ファイルの中身はすぐ大きくなる、と話します。

飯塚さん（動画の中で・4:56〜）

AIエージェントって失敗するじゃないですか。失敗した時にここ直してって言うんですよ。

失敗のたびに出る、直しての一言。その分だけ、AGENTS.md に追記が増えていきます。繰り返すと肥大して、かえって性能が劣化すると言われている、と飯塚さんは話します。

飯塚さん（動画の中で・5:12〜）

500行以下がいいですよっていう風に公式ドキュメントでは言ってるんですね。

まずは Cursor の話。公式ドキュメントでは、中身は500行以下がいいと言っている、と飯塚さんは紹介します。

飯塚さんは、Codex では目次のように書くのが大事だと紹介します。Obsidian で言う Map of Content の形。見出しだけを並べ、詳しくは、ここを読んでね、と案内役に回します。

次は Anthropic。Claude を作る会社の公式ドキュメントでは200行以下がいい、と飯塚さんは話します。だらだら書かない、が結論でした。

私の記事より（CLAUDE.mdは何行までが目安？200行以内でも起動時の文字数は増える・1枚が短くても合計が増えれば指示は埋もれる）

私の手元の指示書46枚は、200行を超える物が1枚もありません。

起動時に読む私の四つのファイルは、全案件用の Claude Code 用が71行、作業フォルダの AGENTS.md が153行、Codex 用が163行、Grok 用が68行。どれも200行未満です。公式のページにも、1ファイル200行未満が目安とあります。

同じ記事に書いたとおり、1枚ずつなら短いのに、合計は7万9千文字を超えていました。10月12日の数え方です。行数と、毎回読む総量は、別の話！

飯塚さんの話は、1枚の長さを抑える方向。私は、1枚を短くするだけで止めません。毎回読む総量を積み減らす方に、線を引きます！

AGENTS.md に、フォルダの一覧まで書く必要はありません。飯塚さんの線引きは、とてもはっきりしています。見れば分かることは、書かない側。守ってほしいことだけが、書く側。

飯塚さんは具体例を挙げます。マーケティングフォルダ、ビジネスフォルダ。今のフォルダ構成は、いちいち書かなくていい、と話します。

飯塚さん（動画の中で・5:46〜）

なぜならAIエージェントたち見たら分かるからです。

理由は、AIエージェントが見れば分かるから。飯塚さんも以前はフォルダの構成を書いていて、それが不要になった、と振り返ります。

スキルの一覧も、長い説明も、よく変わる情報も、ここに書く必要は無い、と飯塚さんは続けます。

飯塚さん（動画の中で・6:07〜）

書くべき内容なのは例えばAIエージェントが触っていい場所、触ってはいけない場所とかやってはいけない操作とか作業の終わりに確かめることとかこのフォルダー操作する上で特有の落とし穴とかそういう情報はこの中にしっかり書いてあげるんですね。

書くのは4つ。触っていい場所と触ってはいけない場所、やってはいけない操作、作業の終わりに確かめること、そのフォルダ特有の落とし穴です。

まさに、守ってほしい、という特有のルールを書く形。油断すると増えるので、定期的に中身をチェックする必要がある、と飯塚さんはまとめます。

AIが見れば分かることは、書かずにおく側。推測できない行き先は、1行で書く側。

Claude Code で AGENTS.md を置いたのに、読まれない。そんな場面が、実演の中で起きます。鍵になるのは、Claude Code が読むファイルの順番。実演は、そこがよく見える流れです。

実演はゼロからです。デスクトップに新しいフォルダを作って、Obsidian で保管庫として開き、ターミナルから Claude Code を起動。

何も設定が無い状態で、/init を打ちます。これは CLAUDE.md というルールファイルを最初に作るコマンド。AGENTS.md を直接作る選択肢は無い、と飯塚さんは話します。

ややこしいのは、Claude Code の公式ドキュメントの表。AGENTS.md と CLAUDE.md の両方があると、CLAUDE.md を読みます。CLAUDE.md が無ければ、AGENTS.md だけ。聞き手は、まだ縄張りを張っているんですね、と笑います。

つまり、/init で CLAUDE.md を作った後に AGENTS.md を足しても、読まれない状態。聞き手は、1回 CLAUDE.md を消さないといけないのか、と驚きます。

飯塚さん（動画の中で・8:47〜）

だからこそこれを消して名前を変えてあげると。

やることは、CLAUDE.md の名前を AGENTS.md に変えるだけ。それだけなんですか、と聞く聞き手に、飯塚さんは、そうですね、と答えます。

/init が作った CLAUDE.md には、Obsidian のリンクやデイリーノートなどの初期設定が並んでいます。

飯塚さん（動画の中で・9:19〜）

ルールファイルに、ま、こうしたしょうもない情報を入れてもノイズになっちゃうと思うんですね。

こういう情報は、貴重なルールファイルのノイズ。200行以下がいいと言われているので書くべきではない、と飯塚さんは話します。

名前を変えたあと、ターミナルを一度閉じて、改めて Claude Code を起動。AGENTS.md を読んでいる表示が出て、飯塚さんは動きを確かめます。

/init が作るのは、CLAUDE.md の下書き。名前を変える手が要るのは、その順番があるからなんですよね。CLAUDE.md の中で AGENTS.md を取り込む書き方もあります。

AGENTS.md を直接読むには、公式のページによると、Claude Code の v2.1.277 以降が必要です。

AGENTS.md には、AIの行動の決まりまで書けます。動画は、飯塚さんが実際に使っているファイルを画面に出す場面へ進みます。置き場所や長さの話から、中身の話へ。

飯塚さんは、Obsidian で勉強したことをまとめている保管庫の、実際のファイルを見せます。保管庫の情報に加えて、行動ルールがやっぱりすごく大事だと話します。

飯塚さん（動画の中で・9:44〜）

行動ルールですね。これがやっぱりすごい大事です。不明な点は積極的に質問してください

分からない点は、AIの方から質問してもらう決まり。選択肢を出す時は、おすすめと理由を必ず添えてもらいます。飯塚さんは、推奨度を星の数で示してもらうのが好きだと話します。

飯塚さん（動画の中で・9:55〜）

オブシディアンの中のノートを移動する時にタイトルを変えてリンクが壊れちゃったってことはよくあるんですね。

Obsidian の中でノートを動かし、タイトルを変えた時のリンク切れ。飯塚さんは、これがよく起きると話します。だから移動には mv コマンドを使わず、Obsidian CLI を使うように書いておきます。

そうすると、リンクの構造を保ったまま、Claude Code がファイルを動かしてくれます。これ超大事ですね、と飯塚さん。Obsidian CLI は、Obsidian の設定でコマンドラインインターフェイスをオンにすると使えます。

ほかにも、複雑な話は5歳児に説明するつもりで図を使って、という設定。Obsidian でメモを書く時は Obsidian スキルを使う、という1行。最初はこれくらいで始めて、必要になったら足せばいいと話します。

確認の場面では、ファイルの名前を良いものに変えてほしいと頼みます。出てきたのは、理由と星つきの選択肢。1番を選ぶと、Obsidian CLI の rename コマンドが動きました。

私の作業フォルダの AGENTS.md にも、選択肢の決まりがあります。おすすめを先頭に置き、ラベルの末尾に（おすすめ）と付ける形。

動画が見せるのは、一つの保管庫の行動ルール。私なら、質問の仕方と選択肢の出し方は、どのAIにも同じ文で読ませたいので、正本の1か所に書きます！

AIが書いた文書が、自分のノートの間に混ざっていませんか？最後の章は、AIの置き場と、セッションの始まりと終わりの話。動画のまとめもここに入ります。

飯塚さんは、AIが作った成果物を Obsidian の中に書かないでほしいと指示しています。AIが書く物の行き先は、Obsidian の外の決めた置き場。

そうしないと、Obsidian の中身がAIのアウトプットで汚れていきます。飯塚さんは、Obsidian にはなるべく人間が書いたものを残すべきだと考えている、と話します。AIの置き場は、汚し放題。

飯塚さん（動画の中で・10:46〜）

あとはセッションが始まったら最初にこれをしてくださいと。私はAIエージェントのルールだけじゃなくて人間としてのルールファイルっていうのも作ってます。

セッションが始まったら、最初にやることが書いてあります。人としてのルールファイルを読むこと。最近の記憶を思い出すこと。AIのルールとは別に、人間用のファイルも用意しているわけです。

終わる時は、メモリとして保存して次へ引き継ぎます。デザイン基盤やスキルは、目次のように、ここを見てね、と案内するだけ。そうして200行以下に保ち、見た目は全部で50行ぐらいだと飯塚さんは話します。

動画のまとめでも、注意点が挙がります。まず、最初に /init で CLAUDE.md を作って名前を変えること。次に、何でもかんでも書かないこと。最後が、Obsidian でAIの出力と人間の文を分けること。

飯塚さん（動画の中で・15:14〜）

なのでもう最初の時点からAIが出力する場所と人間が書く場所をしっかり分けてあげて

分けるのは、最初の時点から。中をいじる時は Obsidian CLI を使います。そうすれば Claude Code を快適に使える環境が整う、と飯塚さんは締めくくります。

私の記事より（Obsidianを第二の脳にせず、AIの裏方にする。8分の動画と私の見方・人の考えとロボットの考えの分け方。各フォルダの取扱説明書）

私が AI に毎回読ませているルール集には、人の考えを置く場所と、AIが整える記憶の場所について、役割を混ぜない、という1行があります。同じ置き場の中で、役割として分けています。

私が引いた線は、同じ置き場の中での役割の線です。動画は、置き場そのものを外に分ける話。分け方は違っても、先に線を引く向きは同じなんですよね。

私の起動ファイルには、成果物と作業ファイルを作業フォルダの work の下に置く決まりがあります。セッションの最初に、索引の2ファイルを読む決まりも。

分けるのは、早いほど楽です！

飯塚さんの日本語の動画で、Claude Code でも AGENTS.md が読めるようになったこと、置き場所、書き過ぎない長さ、書くことと書かなくてよいこと、名前の変え方、Obsidian でAIに触らせる決まりを、動画の順に見てきました。

動画は、AGENTS.md に揃えれば Claude Code・Codex・Cursor で同じ一本のファイルが使える、と伝えています。私なら、置き場を増やさずに、正本を1つにします。

飯塚さんが紹介した200行以下は、1枚ずつの目安。私は、毎回読む総量の方で長さを見ます。目次のように短くして、細かい決まりは別のファイルへ案内する形が答えです。

/init で作った CLAUDE.md の名前を AGENTS.md に変えること、ノートの移動は Obsidian CLI に任せること、AIの成果物は Obsidian の外に置くこと。この流れは、最初に決めておくほど後で迷いません！

Claude Code、Codex、Cursor と使う道具が増えても、AIに読ませる正本は1つで足ります。では、自分の指示書の正本は、今どこにありますか？