本文へスキップ

指示ファイルを、読まれる形で書く

レベル 2土台づくりリポジトリ側を整える75

先に読む回:毎回渡す情報と、そのときだけ渡す情報

この回でできるようになること

  • 指示ファイルの適用範囲と、指示がぶつかったときの優先順位を決めて書ける
  • 実際に動くコマンドと、確かめた事実だけを指示ファイルに書ける

おさえておくこと

指示ファイルは、エージェントが毎回読むもの

多くのコーディングエージェントは、リポジトリに置かれた AGENTS.md を読みます。置いておくだけで、毎回の前提として扱われます。

ただし、すべてのエージェントが同じファイルを読むわけではありません。Claude Code は CLAUDE.md を読みます。AGENTS.md を使いたい場合は、CLAUDE.md から取り込むか、シンボリックリンクを張ります。

どのツールが何を読むかは変わります。FRKZ の「指示ファイル同期」(/tools/instruction-sync)に、確認日つきで一覧があります。

書いていいのは、確かめた事実だけ

指示ファイルの怖いところは、間違っていてもエラーにならないことです。存在しないコマンドを書いても、エージェントは黙って失敗します。

書く
実際に動かして通ったコマンド。リポジトリに実在するファイルの場所。決めた規約。
書かない
たぶんこうだろうという推測。他のプロジェクトの慣習。試していないコマンド。

書く前に、そのコマンドを一度手元で動かしてください。通らなかったものは、直すか消します。

範囲と優先順位を、先に決めておく

指示ファイルが1つとは限りません。リポジトリ全体のものと、特定のフォルダのものが同時にあることはよくあります。

どちらが優先されるかを書いていなければ、その場の判断になります。「より狭い範囲の指示が優先される」といった決まりを、指示ファイル自体に書いておきます。

それでも決められない食い違いが残ったときは、勝手に決めずに確認する、という方針も書き添えます。

長い指示ファイルは、読まれません

毎回読ませるものなので、長さはそのまま毎回のコストになります。詳しい手順は別ファイルに置き、指示ファイルからは参照だけにします。

「毎回渡す情報と、そのときだけ渡す情報」の回で決めた上限を、ここでも使います。

ここまでで分からないところがあれば、この回の本文だけを使って答えてもらえます(任意・自分のAPIキーが必要です)。

この回では扱わないこと

  • AGENTS.md の完全な書式の解説
  • 各ツールの設定画面の操作手順

ツールごとのちがい

Claude Code

CLAUDE.md を読みます。AGENTS.md に本文を置き、CLAUDE.md から取り込む形にすると、内容が二重にならずに済みます。

ここに書いたちがいの出どころは、下の「この回の情報の出どころ」にあります。仕様は変わるので、実際に設定する前に必ず元の資料で確かめてください。

やってみる

自分のリポジトリで60

指示ファイルを、確かめた事実だけにする

自分のリポジトリの指示ファイルを1つ選び、書いてあるコマンドを実際に動かして確かめます。通らないものを直し、範囲と優先順位を書き足します。

やること

  1. 指示ファイルに書かれているコマンドを、すべて書き出します。
  2. 1つずつ手元で実行し、通ったかどうかを記録します。
  3. 通らなかったものを、直すか消します。消した場合は理由を残します。
  4. 存在しないファイルやフォルダへの言及がないか確かめます。
  5. この指示がどこまでの範囲に効くのかを、冒頭に1段落で書きます。
  6. 指示がぶつかったときにどちらを優先するか、決められないときはどうするかを書き足します。

できあがるもの:実行したコマンドと結果の一覧、および更新した指示ファイルの変更点

できたかどうかの確かめ方

作ったものを点検する自分で採点する

範囲と優先順位が書いてあるか

更新した指示ファイルを、次の観点で点検してください。

どこまでに効くか

まだ
適用範囲が書かれていない。
できた
この指示がどの範囲に効くのかが、冒頭で分かる。
よくできた
範囲外については、どこを見ればよいかまで書かれている。

ぶつかったときの決まり

まだ
優先順位について何も書いていない。
できた
どちらが優先されるかの決まりが書かれている。
よくできた
決められない場合に勝手に決めず確認する、という方針まで書かれている。
実際に動かして確かめる実行した結果で確かめる

書いてあるコマンドは、本当に動くか

指示ファイルに書いたコマンドを、上から順にすべて実行してください。通らなかったものがないことを、出力で示します。

pnpm typecheck && pnpm lint && pnpm test

実行して確かめたか

まだ
実行していない、または一部しか実行していない。
できた
書いてあるコマンドをすべて実行し、結果を記録している。
よくできた
通らなかったものを直したうえで、直した後にもう一度通していることが分かる。

この回の情報の出どころ

  • 仕様書AGENTS.md
    AGENTS.md

    2026-09-10 に確認/2026-12-10 までにもう一度確認

  • 公式の説明Anthropic
    Claude Code - Memory

    2026-09-10 に確認/2026-12-10 までにもう一度確認

この回で触れている外部の情報は、いちばん古いもので 2026-09-10 に確かめたものです。 この日付は ADR-0019 の一次情報一覧から引き継いでいます。

この回の記録

書いた内容はこのブラウザの中だけに残ります。送信はしません。 成果物そのものではなく、どこにあるか(ファイルの場所、ブランチ名など)を書いてください。 鍵やパスワードは書かないでください。

確かめた結果

範囲と優先順位が書いてあるか
書いてあるコマンドは、本当に動くか
置き場所を書き、すべての確認を「できた」以上にすると、記録つきの完了になります。

AIに見てもらう(任意)

使わなくても、すべての回は完了できます

作ったものを、この回の観点表に照らして見てもらえます。返ってくるのは助言であって、 合否ではありません。完了にするかどうかを決めるのは、いつでもあなたです。 自分のAPIキーを使うため、料金はご自身のアカウントに請求されます。

先に、上の「この回の記録」ですべての確認に自分で評価を付けてください。 モデルの評価を先に見ると、自分の判断がそれに引きずられます。

プロバイダ

キーはこの実行にのみ使われ、保存もログ出力もしません。ブラウザにも残らないため、ページを離れると再入力が必要です。

APIキーを発行する