指示書は 4 回、形を変えた — CLAUDE.md と AGENTS.md の 8 か月

型 1：概要メモ（2 月）

最初のころの指示書は、英語の見出しで 40〜50 行でした。Overview、Architecture、Key Rules、Project Structure の 4 節だけです。

社内の巡回 Bot（2 月）の Key Rules から
- 優先度の計算の正は src/prioritize.js
- スキルは仕様書に徹する。API の呼び出しや通知の送信はしない
- 出力は必ず JSON 形式

短くて読みやすいのですが、約束に理由が書かれていません。「なぜ JSON なのか」「なぜ送信してはいけないのか」が分からないので、想定していない場面に出会ったとき、AI には判断の手がかりがありませんでした。

型 2：設計書をまるごと渡す（3〜6 月）

春になると、指示書は一気に長くなります。300 行を超えるもの、あるいはファイル単位の仕様まで書いたものが 8 本あり、どれも 3〜6 月に始めたものでした。

いちばん長い 972 行の指示書は、見出しの半分がファイル名でした。型の定義、計算の関数 1 つずつの仕様、データベースのスキーマ、画面の仕様、実装の順番（Step 1〜7）まで入っています。「設計を全部渡せば、AI が一気に作ってくれる」と考えていた時期の書き方です。

ねらいは、最初の実装を速くすることと、設計と実装をずらさないことでした。

しかしながら、設計は作りながら育っていくものです。設計が変わるたびに長い指示書を直し続けるのは手間で、指示書と設計のあいだに差が生まれやすくなりました。長くなるほど、どこが「絶対に守ってほしい約束」なのかも見えにくくなります。

7 月以降に始めたプロジェクトには、この型は 1 本もありません。

型 3：実装憲法（4〜5 月）

型 2 と同じ時期に、別の書き方も生まれています。絵文字の見出しで、決まった 7 つの節を持つ形です。

型 2 との違いは、設計の中身を別の文書に出したことです。指示書には「どう振る舞うか」だけを書き、設計そのものは書きません。

公開サービスのバックエンド（4 月）の「迷った時の判断軸」から
「計算結果が基準値と合わない」とき
1. 設計書が正、実装が間違いと仮定する
2. 中間の値をすべてログに出し、どこで差が出ているかを特定する
3. どうしても合わなければ、設計判断の記録（ADR）を書き、「設計書と実装のどちらが正か」を担当者に判定してもらう

同じ指示書の「絶対にやってはいけないこと」から
基準値を、設計判断の記録なしに変えない。
基準値は「不変の絶対値」ではなく、ある時点のデータで取った基準のスナップショット。テストの入力（945 件）から、いつでも同じ値を再現できる。

禁止に、理由と、どうしても変えたいときの手順がついています。これがあると、AI は止まるだけで終わらず、「変える必要があるなら、記録を書いて人に判断を返す」という動き方ができます。この書き方は、いまでもよく効いていると思います。

型 4：入口と、決めたことの記録（7〜9 月）

夏以降の指示書は短くなります。代わりに、2 つのものが増えました。

1 つは「入口」です。「このリポジトリで作業する前に必ず読むこと」として、引き継ぎ資料や設計判断の記録へ案内するだけの節です。もう 1 つは「日付つきの節」で、運用の中で新しく決めたことがあると、その日付と経緯をつけて 1 節ずつ足していきます。

ある管理画面の AGENTS.md（見出しの変遷。5 行の雛形から 84 行まで、10 回の変更）
- ★このリポジトリで作業する前に必ず読むこと
- 複数の AI エージェントで作業しています
- 同じ確認を繰り返さないための参照先
- 配備の手順と、その範囲（日付つき）
- ★個人情報の扱いの原則（日付と、誰が決めたかつき）

同じ指示書の「個人情報の扱いの原則」から（要約）
- 判定は 1 か所で行う。画面ごとに独自の判定を書かない
- 読めなかったら、出さない（迷ったら安全なほうを選ぶ）
- 記録は消さない。見るときは、理由を選んで開く

型 3 の「判断軸」が、運用の中で確かめられ、「原則」に育っていく流れです。原則の正本は別の文書に置き、指示書には要約と、正本への道筋だけを書いています。日付と「誰が決めたか」を残しておくと、あとから「この原則はなぜあるのか」をたどれます。

残っている指示書から見えること

45 本を読み比べてみて、私が「効き続けている」と感じる書き方は 4 つありました。禁止に理由と変えたいときの手順を添えること、よくある迷いごとに判断の手順を書くこと、設計の中身は別の文書に置いて指示書をそこへの入口にすること、新しく決めたことを日付と経緯つきで 1 節足すこと、です。

反対に、見直したいと思ったのは、設計をまるごと指示書に入れる書き方（仕様が変わると指示書だけが古くなる）と、理由のない約束を並べる書き方（例外の場面で判断できない）でした。一度書いたら読み返さないことも、見直したいところです。指示書は長く使われるので、読み返す日を決めておく必要があります。

指示書が「会社の回し方」を運び始めた

7 月から、どのプロジェクトにも同じ節を入れるようになりました。1 つは秘書ダッシュボードへの現在地の連携で（7 月 11 日から。20 ファイル）、作業に一区切りがついたら、社内のダッシュボードに「いまどこまで進んだか」を 1 行書いてもらいます。もう 1 つは Backlog への記録で（9 月 8 日ごろから。8 本以上）、作業したら課題管理に 1 行残してもらいます。

このあたりから、指示書はそのプロジェクトの説明に加えて、「会社の仕事をどう回すか」を運ぶものになりました。40 本以上を同時に動かしていると、一つひとつの進み具合を私が覚えておくことはできません。エージェントに、自分で現在地を報告してもらう必要がありました。

ちなみに、9 月 25 日の時点では、すべてのプロジェクトに共通する指示は 56 行しかなく、中身は開発サーバーのポート番号の割り当て表だけでした。並行して動かしてみて最初にぶつかったのは、技術の難しさより、「同じポートを取り合う」ことだったのです。

この特集をまとめる中で、10 月 1 日に、この共通の指示へ「基本」の節を足しました。確かめてから書くこと、人が決めることと AI に任せることの線、秘密と公開の決まり、受けた訂正を仕組みにする手順です。プロジェクトごとの指示書に貼っていた現在地の報告と課題の記録の決まりも、ここに置きました（各プロジェクトの指示書からの整理は、これからです）。

2 つのエージェントに、同じ指示を渡す

9 月 10 日から 13 日の 4 日間で、26 本のプロジェクトに AGENTS.md を作りました。中身は CLAUDE.md をそのまま写したものです。実装の一部を、もう 1 つの AI エージェントに任せ始めたためです。

同じ指示を 2 つのファイルに持つと、片方だけを直す、ということが起きやすくなります。1 つの正本にまとめる形を、次に試すことの候補にしています。

もう 1 つ、面白い変化もありました。Next.js の最新版では、プロジェクトの雛形が最初から AGENTS.md を作ります。中身は 5 行で、要約すると「このバージョンは、あなた（AI）が学習した Next.js とは違う。書く前に手元の説明書を読め」。フレームワークの側が、AI 向けの指示書を配り始めています。

指示書は、毎回ゼロから読まれる

AI エージェントの指示書は、人向けの手順書と少し違います。違いを 4 つ書いておきます。

まず、指示書は毎回、まっさらな状態で読まれます。エージェントとの会話（セッション）は、始まるたびに、前の会話を覚えていない状態から始まります。そこで最初に読むのが指示書です。毎朝やってくる「優秀だけれど、この会社のことを何も知らない新しい同僚」に渡す引き継ぎ書のようなものだと思います。

次に、指示書は命令ではありません。エージェントは指示書を「読んで考える材料」として扱うので、書いてあることを必ず守るとは限りません。本番への配備、データの削除、外部への送信のように絶対に止めたい操作は、文章で頼むのでは足りず、ツールの設定（フックや権限）で止める必要があります。

そして、長いほど一つひとつが守られにくくなります。指示書は毎回、会話の最初に丸ごと読み込まれるので、長くなるほど会話に使える余白が減り、個々の約束も埋もれます。Claude Code の公式ドキュメントは、1 ファイル 200 行以内を目安にしています。

書き足すきっかけは「2 回目」です。同じ間違いを 2 回したときや、同じ訂正を前の会話でも書いたときに足す。公式ドキュメントもそう勧めていて、型 4 の「決めたことを日付つきで 1 節」は、これに近いやり方でした。

振り返り

こうすればよかった

いちばんは、設計を最初から別の文書に置いておけばよかった、ということです。型 2 の 8 本は、設計が育つたびに指示書もそろえる必要がありました。

AGENTS.md も、複製せずに 1 つを正にしておけば、2 つのファイルをそろえる手間はいりませんでした。それから、読み返す日を決めておけばよかったと思います。一度書くと長く使われるものだからこそ、定期的に読み返す仕組みが必要でした。

一般的なやり方と比べて

Claude Code の公式ドキュメント（指示書と記憶の章）が勧めるやり方と、私たちの 45 本を並べました。

一方で、禁止に理由を書くことと、決めたことを日付つきで 1 節足すことは、公式の「具体的に書く」「同じことが 2 回目に起きたら書き足す」という勧めと整合しています。

ちなみに、Next.js の雛形が作る「@AGENTS.md の 1 行だけの CLAUDE.md」は、この「共有」の方法の 1 つです。私たちの手元には、見本が最初からあったことになります。

この特集の中で実施したこと（2026 年 10 月 1 日）

まず、すべてのプロジェクトに共通する指示に、「基本」の節を足しました。確かめてから書く、人が決めることと AI に任せること、秘密と公開、訂正を仕組みにする、の 4 つです。

あわせて、操作で止められる決まりは、仕組みでも止めるようにしました。すべてのプロジェクトに共通の設定で、秘密の読み出し・main への直接の push・広い範囲の削除などを実行の直前に止め、本番への配備や外への送信は人の確認を求めます。

この仕組みの考え方と、AI エージェントと開発するときの情報の守り方は、特集「情報漏えい対策 2026」で詳しく書いています。

次に試すこと（候補）

今後の運用の中で試し、続けるかどうかを決めます。

1. 2 つのファイルに持っている 26 本は、AGENTS.md を正本にする。CLAUDE.md を残す場合は @AGENTS.md の 1 行と、Claude だけに必要な数行にする
2. 200 行を超える 14 本は、200 行以内に整える。設計は別の文書へ、何段階もの手順はスキルへ出す
3. 月初の集計で、しばらく直していない指示書を並べ、読み返す

第 7 回で、この 3 つを試したかどうかと、その結果をまとめます。

御社で最初の 1 本を書くなら

8 か月の変遷から、最初の 1 本はこの形で始めるのがよいと考えています。型 3 の 7 節を下敷きに、型 4 の習慣を足したものです。

合計で 30 行ほどです。設計書は別に置いてください。長い指示書を最初に書き切るより、同じ迷いが 2 回目に出たときに 1 節ずつ足していくほうが、使われ続ける指示書になると思います（これは、私たちの経験からの考えです）。足していって 200 行を超えたら、分けどきです。

ほかの AI ツールも使うなら、最初から AGENTS.md に書いておくと、正本を 1 つに保てます。私たちがあとから整えることを、最初の 1 本で済ませられます。

次回

第 2 回は、100 本の傾向を見ます。何を作ってきたのか、どれが残り、どれが 3 日で終わったのか。「AI で新しいものを作る」より「いまある仕事を 1 つずつ置き換える」ほうに数が寄っていった理由を、分類と実数で追います。

---

この記事の数字について
最初の 100 本のうち、CLAUDE.md がある 45 本を集計しました（2026-09-25 時点）。すべてのプロジェクトに共通する指示と設定は、2026-10-01 に変えたあとの状態を書いています。長さは行数、直した回数は git のコミット数で、履歴のない 9 本は数えていません。抜粋は、顧客名・人名・フォルダ名を伏せ、意味を変えない範囲で言葉を整えています。