READMEはもう人間だけのものではない — AIエージェントが読む前提のドキュメント設計

このサイトのリポジトリには、AIエージェント向けの指示を書いたCLAUDE.mdというファイルがあります。2025年8月までは、これが1404行の1ファイルでした。今は63行です。中身のほとんどは機能別の5ファイルに移してあります。分割したのは見た目を整えるためではなく、書き方を変えるとエージェントの動きが変わるからです。

ドキュメントの読者が人間だけだった頃は、こういう悩み方はしませんでした。READMEの記述が少し古くても、読んだ人が「これは昔の話だな」と勝手に補正してくれます。AIエージェントは補正しません。書いてあることを、書いてあるとおりに実行しようとします。

この記事では、AIが読む前提でドキュメントを設計すると何が変わるのかを、当サイトの実例とClaude Codeの公式ドキュメントの記述をもとに整理します。ドキュメント整備は後回しにされがちな作業ですが、少なくとも自分の運用では、ここに手を入れたときのリターンがこの1年でかなり変わりました。

1. ドキュメントの新しい読者

AIコーディングエージェントの振る舞いは、初日にドキュメントを全部読んでから作業を始める新人に近いです。しかも、毎回が初日です。

Claude Codeの場合、セッションは毎回まっさらなコンテキストから始まり、その冒頭でCLAUDE.mdが読み込まれます。前のセッションでチャットに書いた補足は残りません。「前回言ったでしょう」が通じない相手なので、ファイルに書いてあるかどうかが、そのまま毎回の挙動の差になります。

ここで正確に押さえておきたいのは、書けば必ず守られるわけではないという点です。公式ドキュメントは、CLAUDE.mdはシステムプロンプトの一部ではなく、その後に渡されるユーザーメッセージとして扱われ、厳格な遵守は保証されないと明記しています。あくまでコンテキストであって、設定ファイルではありません。どうしても外したくない操作 — コミット前に必ずlintを走らせる、特定のディレクトリを触らせない — は、フック（hook）やpermissions.denyのように、モデルの判断を経由しない仕組みで押さえるほうが確実です。

なので「ドキュメントの質がそのままAIの出力の質になる」という言い方は、少し雑だと思っています。より正確には、書いていないことは毎回ゼロから推測されるということ。推測が当たることもあります。困るのは当たり外れが毎回変わることで、レビューの手間はそこに集中します。

人間向け・AI向け・共通の境界

とはいえ、ドキュメントを人間向けとAI向けに二重管理するのは現実的ではありません。実際には大部分が共通で、それぞれにしか要らない部分が周辺にある、という関係になります。

右側、AI向けに固有な部分を見ると、新しい種類の情報を書き足しているわけではないことがわかります。これまで書かずに済んでいたことを書く作業です。チームで暗黙に共有していた前提、レビューで毎回同じ指摘をしていた項目、「まあそれはやらないよね」で通っていた不文律。AI向けのドキュメント整備の実務は、その言語化にほとんどの時間を使います。

2. 効いた3原則 — 明示性・構造化・制約の言語化

明示性 — 「いつもの」が通じない

人間の新人なら、二回目には「いつもの感じでお願い」が通じます。エージェントには通じません。省略した部分は、そのつど推測で埋められます。

当サイトのURLに関するルールは、こう書いてあります。

## URL・リンクルール
- **禁止**: index.htmlを含むリンク使用は厳禁
  - ❌ `href="index.html"` `href="../index.html"` `href="blog/index.html"`
  - ✅ `href="/"` `href="../"` `href="blog/"`
- **理由**: SEO最適化とURL統一のため
- **適用範囲**: 全HTMLファイル、sitemap.xml含む

人間向けのコーディング規約なら「内部リンクはディレクトリ形式に統一する」の一文で足ります。❌と✅を3パターンずつ並べるのは、率直に言って冗長です。ただ、この冗長さは判断の余地を消すために書いています。「ディレクトリ形式に統一」だけだと、blog/index.htmlがその範囲に入るのかどうかを、エージェントがその場で判断することになります。sitemap.xmlも対象なのかは、なおさら伝わりません。

公式ドキュメントも、検証できる程度に具体的に書くことを推奨していて、例として「Format code properly」ではなく「Use 2-space indentation」を、「Test your changes」ではなく「Run npm test before committing」を挙げています。読み返して「これは自動でチェックできるか？」と自問すると、抽象的すぎる項目はすぐ見つかります。

構造化 — 見出しと箇条書きは入力フォーマット

公式ドキュメントには、Claudeは人が読むときと同じように構造を走査するので、密な散文よりも整理されたセクションのほうが追いやすい、という記述があります。実務的には、条件を長い文章に埋め込まないということです。

たとえば「なお画像を扱う場合は拡張子と実体の形式が一致していることに注意が必要で、特にSNSでの表示に影響します」と一文で書いても、たいてい効きません。当サイトでは同じ内容を、画像形式検証という見出しの下に、fileコマンドの実行例、正しい例と間違いの例、5項目のチェックリスト、そして「なぜ重要か」の説明に分けて書いています。行数は増えますが、エージェントが自分の作業結果を照合できる形になります。

制約の言語化 — 「やらないこと」がいちばん効く

運用していての感触では、いちばん効くのは禁止事項です。やってほしいことのリストは網羅できませんが、やってほしくないことは案外少数で、しかも具体的に書けます。

## コード実行ルール【重要】
- **禁止**: Python、Node.js等の一時的なコード生成・実行は禁止
- **理由**: 実行環境依存を避け、シンプルな構成を維持するため
- **画像素材**: 必要な場合は著作権フリーの素材を使用すること

これは当サイトのルールの実物です。ポイントは禁止と理由をセットで書いているところ。理由まで書いてあると、明示していない周辺のケース — たとえば一時的なシェルスクリプトはどうなのか、既存のツールをコマンドとして呼ぶのは許されるのか — を、エージェントが方針に沿って判断できます。理由のない禁止は、書いていないケースであっさり破られます。

ひとつ留保をつけておくと、この「いちばん効く」は運用していての感触で、A/Bで比較した結果ではありません。禁止事項を足したら同じ手戻りが起きなくなった、という個別の観察の積み上げです。効き方はプロジェクトの性質にも寄るはずなので、そのまま一般化はできません。

3. ファイル別の役割分担

AI向けの指示を書く場所は、いくつか選択肢があります。役割を混ぜると読み込みのコストと更新のコストが両方上がるので、分けておくほうが扱いやすくなります。

README.md — 人間とAIの共通の入口

READMEは引き続き、人間とAIの共通の入口です。何をするプロジェクトか、どう動かすか、どこに何があるか。ここに書くべき内容はAIの登場で大きく変わっていません。変わったのは、古いままだと実害が出ることです。人間の読者は古い記述を読み飛ばしますが、エージェントは書いてあるビルドコマンドを素直に実行します。

CLAUDE.md と AGENTS.md — AIへの作業指示

プロジェクト固有の作業ルールを書く先が、CLAUDE.mdやAGENTS.mdです。

AGENTS.mdは、複数のツールで共通に読める形式を目指した仕様です。OpenAIが公開したものが出発点で、2025年12月9日にLinux Foundation傘下のAgentic AI Foundation（AAIF）へ、AnthropicのMCPやBlockのgooseとともに寄贈されています。同財団の発表では、採用しているプロジェクトは6万件を超え、Codex、Cursor、GitHub Copilot、Gemini CLI、Devin、Jules などが読み込む対象として挙げられています。中身は普通のMarkdownで、独自の記法はありません。

ここで実務でいちばん引っかかるポイントを先に書いておきます。Claude CodeはAGENTS.mdを読みません。読むのはCLAUDE.mdだけです（2026年7月27日時点の公式ドキュメント）。すでにAGENTS.mdを運用しているリポジトリでClaude Codeも使うなら、CLAUDE.md側からインポートして両方が同じ指示を読むようにします。

@AGENTS.md

## Claude Code

（ここにClaude Code固有の指示を書き足せる）

Claude固有の追記が不要なら、シンボリックリンクでも足ります。ただしWindowsでのシンボリックリンク作成には管理者権限か開発者モードが必要なので、チームの環境が混在しているなら@AGENTS.mdのインポート記法のほうが無難です。

ln -s AGENTS.md CLAUDE.md

「AGENTS.mdを置いたのにルールが守られない」と感じたときの確認手順は決まっています。セッション内で/contextを実行し、Memory filesの一覧に目的のファイルが載っているかを見ます。ここに出ていなければ、そもそも読まれていません。指示の書き方を直すより先に、読み込まれているかどうかを確認したほうが早く解決します。

スキル — 手順書を実行可能にする

CLAUDE.mdに書き続けていると、ある時点から「事実」ではなく「手順」が混ざってきます。公式ドキュメントはこの見分け方を、毎セッション持っていてほしい事実（ビルドコマンド、規約、構成）はCLAUDE.md、複数ステップの手順や一部のディレクトリでしか関係しない内容はスキルかパス限定のルールへ、と整理しています。

スキルの利点は読み込みのタイミングです。スキルの本文は呼ばれたときだけ読み込まれるので、長い参照資料を持っていても、使わないセッションではコストがほぼかかりません。当サイトでも.claude/skills/にブログ執筆用のスキルを置いています。文章の方針は毎回必要な「事実」ではなく、記事を書くときだけ必要な「手順」なので、常時読み込まれる場所に置く理由がありません。

当サイトのビフォーアフター

冒頭に書いた分割の中身です。2025年8月21日のコミットで、1ファイルだったCLAUDE.mdを機能別に分けました。

この分割で個人的にいちばん面白かったのは、行数の内訳です。コミットの差分は1356行の削除に対して319行の追加でした。つまり、消えた1356行のうち新ファイルに移されたのは4分の1弱で、1000行以上はどこにも移されず、そのまま捨てられています。当時すでに使っていない画像生成APIの手順や、重複した記述が積み上がっていたわけです。分割作業そのものが棚卸しを強制した、というのが実際に起きたことでした。

分割の落とし穴 — インポートではコンテキストは減らない

分割するとき、参照の書き方に注意が必要です。CLAUDE.mdには@path/to/fileという記法で他のファイルを取り込む機能がありますが、インポートされたファイルは起動時に展開されてコンテキストに載ります。公式ドキュメントも、インポートは整理には役立つがコンテキストの削減にはならないと明記しています。1ファイル2000行を4ファイル500行にインポートで分けても、読み込まれる量は変わりません。

当サイトのCLAUDE.mdは、@インポートではなく通常のMarkdownリンクで各ファイルを指しています。

## 📖 機能別詳細ガイド

以下の機能について作業する際は、該当する詳細ファイルを参照してください：

- **🎨 画像生成**: [CLAUDE_image_generation.md](CLAUDE_image_generation.md) - Fireworks APIの使用方法
- **📝 ブログ記事作成**: [CLAUDE_blog_rules.md](CLAUDE_blog_rules.md) - テンプレート準拠、画像配置、SEOルール

リンクなら起動時には読み込まれず、エージェントが必要と判断したときにファイルを開きます。実際、ブログ記事を書く作業ではCLAUDE_blog_rules.mdが読まれ、用語集のルールは読まれません。

ただしこの書き方には裏返しの弱点があります。読むかどうかがエージェントの判断次第になるということです。必ず適用させたいルールは、本体に直接書くか、.claude/rules/に置いてpathsで対象ファイルを指定するほうが確実です。pathsを指定したルールは、該当するファイルをエージェントが読んだ時点で自動的にコンテキストに入ります。

---
paths:
  - "blog/**/*.html"
---

# ブログHTMLの必須要素

- OGPタグとJSON-LDのURLはcanonicalと一致させる

常時読み込む（本体に書く）／条件付きで自動的に読み込む（paths付きルール）／必要になったら読む（リンク・スキル）の3段階を、ルールの重要度で使い分ける、というのが今のところの整理です。

4. アンチパターン

巨大な1ファイルに全部書く

公式ドキュメントは、1ファイルあたり200行以下を目標に挙げています。長くなるとコンテキストを食うだけでなく、指示の遵守率が下がるという説明です。当サイトの1404行は、この目安を大きく超えていました。

自覚しづらいのは、この肥大化が正しい行動の積み上げで起きるところです。同じ間違いが二度起きたらルールを書く、というのはむしろ推奨されている運用です。それを1年続けると1000行を超えます。書き足す運用には、置き場所を見直す運用を組み合わせないと成立しません。Claude Codeには/doctorという点検コマンドがあり、v2.1.206以降ではコードベースから推測できる記述（ディレクトリ構成や依存関係の一覧など）を削る提案を出してくれます。棚卸しの入口としては使えます。

古い記述の放置 — AIは古いルールも忠実に守る

そしてこれが、この記事を書きながら自分のリポジトリで見つけた失敗です。

当サイトのブログ記事作成ルールには、記事公開前の必須要素チェックリストがあり、その中に次の項目が入っています。

- [ ] **New Relic MCPバナー**: ヘッダーのプロダクトバナー

ところが2026年7月7日のコミットで、ヘッダーバナーは600ファイル規模で3サイトを紹介するバナーに差し替えられています。現在のblog/template.htmlのヘッダーは「大家One」、トップページは「クポ活レーダー」です。CLAUDE.md本体の側にも「New Relic MCP Chat banner on all main pages」という記述が残っていて、すでに差し替えた要素の確認項目が2箇所生き残っていたことになります。

では実害が出ていたのか。ここが自分でも意外だったところで、差し替え以降の記事のヘッダーを並べてみると、こうなっていました。

バナーを差し替えた4日後と6日後に公開した2記事だけ、引退させたはずのNew Relic MCPバナーが復活しています。7月17日以降の記事は現在のテンプレートどおりです。

ここは因果を断定できないので正直に書きますが、チェックリストが原因だと証明したわけではありません。テンプレートの古い版を参照した可能性もあります。ただ、「存在しない要素を確認せよ」という指示が残っているドキュメントのもとで、その要素が実際に2記事だけ復活していたという事実は、この種の放置がどう作用するかの一例として十分だと思っています。人間なら「これは古い項目だな」と飛ばすところを、そのまま実行してしまうのがこの相手の性質です。

公式ドキュメントもこの点には触れていて、矛盾する指示が複数あるとClaudeはどちらかを任意に選ぶことがあるため、古い記述や矛盾する記述を定期的に見直して削るように、と書かれています。書き足すコストは低いのに、消すきっかけがないというのが、この問題の構造だと思います。

対策として当サイトでやっているのは、ルールに追加日を書くことです。

### 画像形式検証【2026-05-03 追加・必須】
### JSON-LD特殊文字エスケープルール【2026-02-19追加】
## 🔍 SEO構造化データルール【2025-09-21制定】

日付があると、棚卸しのときに「これは何を防ぐために足したルールだったか」を追いかけられます。git logを追うより速いというだけの、地味な工夫です。今回のバナーの記述に日付がなかったのは、そのまま今回見落とした理由でもあります。

まとめ

ドキュメントを整備しても、読むのが人間だけだった頃は、効果を実感するまでに時間がかかりました。今は違います。禁止事項を1行足せば次のセッションから挙動が変わるので、手を入れた結果がその日のうちに返ってきます。ドキュメント整備が、書いた分だけ跳ね返ってくる作業になったという意味で、優先順位を上げる理由はあると思います。

ただ、跳ね返りが速いのは悪いほうも同じです。古い記述は、古いまま忠実に実行されます。今回自分のリポジトリで見つけたのがまさにそれで、書き足す運用だけでは追いつきません。/contextで読み込まれているファイルを確認し、日付を頼りに古い記述を落とし、手順に育った部分はスキルへ移す。この3つを回すところまで含めて、ようやく「整備した」と言えるのだと思っています。

自分の環境で最初に手をつけるなら、CLAUDE.mdを開いて行数を数えるところからでしょうか。200行を大きく超えているなら、まず何が捨てられるかを見たほうが早いはずです。当サイトの場合、それが1000行でした。

参考にした一次情報

• Claude Code Docs - How Claude remembers your project（CLAUDE.mdの読み込み順、200行の目安、@インポートの挙動、AGENTS.mdの扱い、.claude/rules/のpaths指定。2026年7月27日確認）
• Claude Code Docs - Extend Claude with skills（スキルの構成と読み込みタイミング。2026年7月27日確認）
• Linux Foundation - Announces the Formation of the Agentic AI Foundation（AGENTS.mdのAAIFへの寄贈、採用規模、対応ツール。2025年12月9日発表／2026年7月27日確認）
• AGENTS.md（仕様本体）