Claude Code に CLAUDE.md を置くべきだ、という話はもう広く知られている。だが実際に書こうとすると手が止まる。アーキテクチャをどこまで書くか、コマンドはどう並べるか、何行が適量か。仕様が緩いぶん、正解の形が見えない。そこで、優良な CLAUDE.md を108件集めたキュレーションリスト josix/awesome-claude-md（★559） のリンク先を全件たどり、実物のファイルを取得して数えた。
30秒でわかる
・リストの規模 ★559、scenarios/ に108件。ただし最終更新は2026-06-05で停止
・実際に読める実例は66件 リンク付き84件のうち、10件はAGENTS.mdへの転送、4件はCLAUDE.mdが消滅、4件はリポジトリごと消滅
・共通構成の上位4つ コマンド89%・アーキテクチャ82%・テスト79%・概要70%
・分量 中央値197.5行。公式目安「200行未満」を48%が超過。ただし長さと品質は無相関
・進行中の移行 生存80件中24件がAGENTS.mdを併設。Top Picks 筆頭のOpenAI例は中身が移動済み
この記事のポイント
・実例集の看板と中身はずれている——リンク付き84件のうち、本文が残っていたのは66件だけだった
・優良例の骨格は4セクション——コマンド・アーキテクチャ・テスト・概要で、他は任意色が強い
・長さは品質を証明しない——公式目安200行を48%が超える一方、短い側のほうがスター中央値は高かった
CLAUDE.md をこれから設計するなら、まず全体像として Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き を押さえておくと、本記事の実測値が「どの層の話か」を見失わずに読める。
awesome-claude-md とは——実例を採点して並べた地図
awesome-claude-md は、公開リポジトリの優れた CLAUDE.md を集めて分類した GitHub のキュレーションリストだ。台湾・台北のエンジニア Josix（josix）が管理し、2025年7月14日に公開された。2026年8月19日時点で★559。
リストの実体は scenarios/ ディレクトリにあり、6カテゴリ・108エントリで構成される。各エントリは元リポジトリへのリンクと分析文を持つ「解説カード」で、CLAUDE.md 本体は転載していない。CONTRIBUTING の倫理ガイドラインが「直接コピーしない」「常に元ソースへリンクする」と定めているためだ。だから読者は必ずリンク先の原本を見にいくことになる——この設計が、後述するリンクの経年劣化をそのまま利用者に転嫁している。
| カテゴリ | 収録数 | 性格 | 代表例 |
|---|---|---|---|
developer-tooling | 41 | CLIツール・プラグイン・MCPサーバーなど開発者向けの道具 | Cloudflare Workers SDK / Lerna |
libraries-frameworks | 27 | ライブラリ・フレームワーク。APIと規約の明示が中心 | Pydantic GenAI Prices / ada |
complex-projects | 25 | 複数サービスや大規模アーキテクチャを持つ応用例 | OpenAI Agents Python / Sentry |
getting-started | 6 | 入門・スターターキット。小規模で全体を見渡しやすい | Anthropic Quickstarts |
infrastructure-projects | 6 | OS・ランタイム・VPNなど低レイヤ寄りの基盤 | Cloudflare workerd / Breenix |
project-handoffs | 3 | 引き継ぎ・ドキュメント主体。文章設計の参考になる | KentBeck B+ Tree |
偏りがそのまま示唆になる。開発者向けツールとライブラリで全体の63%（68件）を占める一方、getting-started と project-handoffs は合わせて9件しかない。既存の大きめのコードベースに CLAUDE.md を足す実例は豊富だが、ゼロから始める型や引き継ぎ用の型はまだ薄い。なお README には実例カタログとは別に「Tools & Ecosystem」節があり、CLAUDE.md を扱う周辺ツールも並ぶ。実例を探しに来て、運用ツールを見つけて帰ることもできる構成になっている。
採点は「人気」をほとんど見ない
収録判断の基準は README だけでなく、実装（scripts/discovery/evaluator.py）にも数値で書かれている。100点満点の配点は次の通りで、スターが属する Community Recognition は10点しかない。
| 基準 | 配点 | 何を見ているか | 自分のCLAUDE.mdに当てはめると |
|---|---|---|---|
| Content Depth | 30 | アーキテクチャ・ワークフロー・文脈を網羅しているか | 設計とデータの流れを書いたか |
| Educational Value | 25 | 独自のパターンやベストプラクティスを示しているか | このリポジトリ固有の勘所を書いたか |
| Project Maturity | 20 | 活発に保守され実運用されているか | 記述が現在のコードと一致しているか |
| AI Effectiveness | 15 | AIが読みやすい構造になっているか | 見出しと箇条書きで構造化したか |
| Community Recognition | 10 | 業界での認知・スター数 | （自分では動かせない項目） |
内容そのものを見る3項目（Content Depth・Educational Value・AI Effectiveness）で70点、プロジェクトの状態を見る2項目で30点。スターの寄与は10%だけで、下限も設けていない。この設計のおかげで、無名の個人プロジェクトでも書き方が優れていれば収録される——そして後述するように、この方針は「長さと品質の無相関」という実測結果とも整合する。
仕様が緩いドキュメントほど、優れた実例の価値が上がる。CLAUDE.md は公式仕様が最小限だからこそ、現場の良い書き方を集めたカタログが効く。
収録CLAUDE.md 84件を全部取得して測った結果
ここからが本記事の主題だ。リストが「実例」と呼ぶものが、今どうなっているかを確かめるため、108エントリの分析文からリンクを機械的に抽出し、CLAUDE.md へのリンクを持つ84件すべてを取得した（実測 2026-08-19）。
・中身のある CLAUDE.md：66件 本記事の測定対象
・AGENTS.md への転送のみ：10件 シンボリックリンク5件、@AGENTS.md などの短い橋渡し5件
・CLAUDE.md が消えていた：4件 うち3件は AGENTS.md に置き換わっている
・リポジトリごと消滅：4件 削除または非公開化
つまり「108件の実例集」を真に受けてリンクを開くと、5件に1件以上は実例として機能しない。これはリストの怠慢というより、CLAUDE.md 自体が動いている証拠でもある。
404の数え方に注意——ブランチ名の固定が5件を殺している
リンク切れを数えるときは、単純な404件数を鵜呑みにしてはいけない。実測すると、404のうち5件はリポジトリ側は健在で、リストのURLが /blob/main/ を固定で埋めていることが原因だった。デフォルトブランチが master や dev のリポジトリでは、それだけで404になる。
| リポジトリ | リンクのブランチ | 実際のデフォルト | 結果 |
|---|---|---|---|
ethereum/ethereum-org-website | main | dev | ブランチ名を直せば読める |
jeremymailen/kotlinter-gradle | main | master | 同上 |
broadinstitute/viral-assemble | main | master | 同上 |
ktaka-ccmp/oauth2-passkey | main | master | 同上 |
SepineTam/stata-mcp | main | master | リポジトリ名も mcp-for-stata へ改称 |
cloudflare/workerd ほか2件 | main | main | 実際にCLAUDE.mdが消えAGENTS.mdへ |
この区別は自分でリンク集を運用するときにも効く。「404＝コンテンツが消えた」ではない。リダイレクトを追い、デフォルトブランチを確認し、ファイルが移動していないかを見て初めて、本当の欠落数が出る。今回のケースでは、素朴に数えれば404は13件ある。だが内訳は「ブランチ名違いで実は健在」5件・「AGENTS.md へ移動」3件・「リポジトリ消滅」4件・「ファイル削除」1件で、本当に中身が失われたのは後ろの2つ、計5件だけだ。
優良CLAUDE.mdに共通する構成——実測で出た上位4セクション
66件の見出し（H2・H3）を正規表現で分類し、1リポジトリにつき1回だけ数えた結果が下の出現率だ。「こう書くべき」という規範ではなく、優良と評価された実物が実際に持っていた要素の頻度である。
最頻が「コマンド」の89%というのは示唆的だ。アーキテクチャ解説より、npm test が何をするのかを書いてあるほうが多い。AI が最初につまずくのは設計思想の理解ではなく「このリポジトリはどう動かすのか」であり、実例はそこに一番紙幅を割いている。
上位4つを日本語に均すと、こうなる。
・このリポジトリは何をするものか（概要・70%）
・どう組み立てられているか（アーキテクチャ・82%）
・どう動かすか（コマンド・89%）
・どう検証するか（テスト・79%）
この4点が事実上の骨格で、残りは任意だ。ディレクトリ構造52%、コード規約45%、セットアップ41%、開発フロー35%、デプロイ30%と、後ろへ行くほど「書いてあれば良い」領域になる。セクション設計の原則そのものは CLAUDE.mdの書き方とは？セクション設計とauto memory・.claude/rules/の使い分け で扱っているので、本記事の実測値はその原則の答え合わせとして読むと噛み合う。
4セクションに何を書くか——実例が入れている粒度
出現率だけでは「何を書くか」までは決まらない。実物を開くと、上位陣に共通するのはそのまま実行・検証できる粒度で書いてあることだった。
anthropics/claude-quickstarts（67行）は、Anthropic 自身が書いた例として基準になる。冒頭はいきなり命名規約で、SDK のクライアントインスタンスは client と名付けろ、と型まで指定する。禁止事項も具体的で、特定の略語をプロダクト名として使うなという指示が、識別子・ファイル名・ログ接頭辞のレベルまで降りている。コマンドは ruff check . / pyright / pytest を並べたうえ、単一テストの実行方法（pytest tests/path_to_test.py::test_name -v）まで書いてある。
lerna/lerna（193行・★36,050）も同じ性格だ。「Required checks」という節を置き、コア機能を変更したときに通すべきコマンドを列挙する。さらに特定コマンドだけをテストしたいときの絞り込み方（nx test commands-publish）も添える。
この2例が示すのは、コマンド節の価値は「全部流す方法」ではなく「一部だけ流す方法」にあるという点だ。AI は変更箇所に対応するテストだけ回したい場面が多く、そこが書かれていないと全体テストを回して時間を溶かすか、当てずっぽうで絞り込む。公式ドキュメントが具体性の例として「npm test を commit 前に実行」のような検証可能な書き方を挙げているのも同じ趣旨だ。
アーキテクチャ節も同様で、優れた例は抽象的な設計思想よりディレクトリと責務の対応を書く。lerna は /libs/ /packages/ /e2e/ /__fixtures__/ をそれぞれ見出しにして役割を説明しており、AI が「この変更はどこに置くか」を判断できる形になっている。
禁止事項を書いているのは3分の2
見落とされがちなのが「やってはいけないこと」の明示だ。禁止・注意事項に相当する見出しを持つのは64%、本文に NEVER / DO NOT / Don't といった禁止語を含むのは66件中31件（47%）だった。過半数は書いているが、全員ではない。
これは効き方がはっきりしている領域でもある。「main に直接 push しない」「このディレクトリは触らない」といった制約は、書いておかないと AI が善意で踏み抜く。LLM の典型的な暴走パターンを4原則に落とし込んだ Karpathy流CLAUDE.mdとは｜andrej-karpathy-skillsの4原則と導入方法 は、この禁止事項パートだけを純化した設計として読める。
なお構造面では、コードブロックを1つ以上含むのが66件中54件（中央値4個）、H2の個数は中央値7.5個だった。@ によるファイルimportを使っているのは66件中わずか3件で、分割よりも1ファイルに書ききる運用が圧倒的多数派だ。
長さは品質を保証しない——公式「200行未満」との乖離
Anthropic の公式ドキュメントは分量について明確な目標を出している。CLAUDE.md のサイズについて、公式は “target under 200 lines per CLAUDE.md file” と書き、長いファイルはコンテキストを消費して遵守率を下げると説明する。
ところが優良例とされる66件の実測は、中央値197.5行・平均301行。32件（48%）が200行を超えていた。最長は gemini-oss/rego の1,572行だ。
ここで重要なのは、長さと品質・人気が連動していないことだ。
・200行以下の34件：リポジトリのスター中央値 62
・201行以上の32件：リポジトリのスター中央値 21
・500行を超える8件のうち5件は★100未満のリポジトリ
・最長1,572行の gemini-oss/rego は★13
逆に、規模の大きなプロジェクトほど CLAUDE.md は短い傾向すら見える。anthropics/claude-quickstarts（★17,459）は67行、lerna/lerna（★36,050）は193行、platformatic/platformatic（★2,031）は88行だ。スター上位10リポジトリの行数中央値は206行で、全体の中央値とほぼ変わらない。
つまり、「丁寧に書く＝長く書く」ではない。1,000行超の CLAUDE.md は、書き手の熱意の証明ではあっても、AI の遵守率にとっては逆効果になりうる。前掲の採点表が Content Depth に30点を置いていることと、この結果は矛盾しない——深さは網羅性であって、行数ではないからだ。
行数を目標にしない。 200行はあくまで「これを超えたら分割やスキル化を検討する」という警告線であって、埋めるべきノルマではない。実測でも短い側のほうがプロジェクト評価は高かった。
長い側で実際に起きている3つのアンチパターン
では1,000行を超えるファイルは何で膨らんでいるのか。上位3件を開いて中身の構成比を測ると、膨張の理由がそれぞれ違っていた。
① コードの貼りすぎ。 最長の gemini-oss/rego（1,572行）は、ファイル全体の71%がコードブロックの中身だった。コードブロックは50個以上並ぶ。使用例やAPIの書き方を延々と貼っているが、これはリポジトリのソースを読めば分かる情報だ。公式ドキュメントも /doctor の整理機能について、コードベースから導ける内容（ディレクトリ一覧・依存リスト・アーキテクチャ概要）を削り、落とし穴や理由・ツール既定と異なる規約を残す方針だと説明している。AIが自力で辿れる情報は、常時読み込みに置く価値が薄い。
② 見出しの過剰分割。 ruvnet/ruflo（1,493行・★68,214）は見出しが167個あり、約9行に1つの見出しが立つ計算になる。構造化は公式も推奨するが、ここまで刻むと目次的な骨格が失われ、どれが重要な制約なのか判別しづらくなる。
③ 汎用プロンプトの丸ごと同梱。 li0on3/GoMall（1,392行）は冒頭が「RIPER-5」という汎用の思考プロトコル定義から始まり、目次と5つのモード定義が延々と続く。プロジェクト固有の文脈ではなく、どのリポジトリに置いても同じ内容だ。CLAUDE.md は「そのリポジトリでしか分からないこと」を書く場所であり、汎用の作業手順はスキルやユーザー設定側に置くほうが噛み合う。
この3つはいずれも「熱心に書いた結果」であり、手抜きではない。だからこそ気づきにくい。自分のファイルが200行を超えたら、増えた分がこの3類型のどれかになっていないかを先に疑うのが早い。
CLAUDE.mdからAGENTS.mdへ——収録リポジトリで進む移行
今回の実測でもっとも予想外だったのがこれだ。リストが誇る Top Picks の筆頭が、すでに CLAUDE.md に中身を持っていない。
openai/openai-agents-python（★28,752）は「Essential（Must Read）」の1番目に置かれている。だが現在の CLAUDE.md はシンボリックリンクで、実体は34,566バイトの AGENTS.md にある。リストがリンクしているコミット固定版でも、中身は「AGENTS.md を読め」という趣旨の41バイトの1行だった。2番目の basicmachines-co/basic-memory も同じくシンボリックリンクだ。
背景ははっきりしている。Codex や Devin など他のコーディングエージェントが AGENTS.md を読むため、指示を1ファイルに集約する動きが進んでいる。そして Claude Code は AGENTS.md を直接読まない。だから橋渡しが要る。公式ドキュメントはこの状況を想定し、CLAUDE.md から AGENTS.md を取り込む2つの書き方を案内している。
# 方法1: import 構文で取り込む（CLAUDE.md の中身を1行にする）
echo '@AGENTS.md' > CLAUDE.md
# 方法2: シンボリックリンク（Claude固有の追記が不要なとき）
ln -s AGENTS.md CLAUDE.md
実測された内訳は次の通り。生存80リポジトリのうち24件がAGENTS.mdを併設しており、うち13件はすでに CLAUDE.md 側を橋渡しに切り替えるか、削除している。
| パターン | 件数 | 実装 | 例 |
|---|---|---|---|
| シンボリックリンク | 5 | ln -s AGENTS.md CLAUDE.md |
openai-agents-python / basic-memory / ethereum-org-website |
| import 1行 | 3 | @AGENTS.md（10バイト） |
getsentry/sentry / codecompanion.nvim |
| 転送文＋追記 | 2 | 短いshim（131〜198バイト） | ComposioHQ/composio / cloudflare/workers-sdk |
| CLAUDE.md を削除 | 3 | AGENTS.md のみ残す | cloudflare/workerd / ada-url/ada / windpress |
シンボリックリンクとimportの違いは、Claude 固有の追記ができるかどうかにある。@AGENTS.md と書いた下に「src/billing/ の変更は plan モードで」のような Claude Code 専用の指示を足せるのがimport方式で、追記が不要ならシンボリックリンクのほうが管理対象が減る。Windows ではシンボリックリンク作成に管理者権限が要るため、公式は import 方式を勧めている。
AGENTS.md があるか} Q -->|ない| C[CLAUDE.md に直接書く
上位4セクションを満たす] Q -->|ある| R{Claude 固有の
指示を足したいか} R -->|足したい| I["CLAUDE.md に @AGENTS.md
＋その下に Claude 用の追記"] R -->|不要| S["ln -s AGENTS.md CLAUDE.md
シンボリックリンク"] I --> W[Claude Code が起動時に
AGENTS.md ごと読み込む] S --> W C --> W
キュレーションリスト自身は橋渡しをしていない
ついでに、awesome-claude-md 自身のリポジトリも測っておいた。結果は示唆的だ。CLAUDE.md が222行、AGENTS.md が101行あり、両者の内容は一致していない。橋渡しではなく、二重管理になっている。しかも AGENTS.md の冒頭には生成日時と対象コミットが記録されており、特定時点のスナップショットとして自動生成されたまま更新が止まっているように見える。
これは責めどころではなく、橋渡しパターンが解こうとしている問題そのものだ。指示ファイルが2つあれば必ず片方が古くなる。公式が import とシンボリックリンクを案内するのは、まさにこの分岐を構造的に防ぐためだ。優良例を集める側のリポジトリでも起きるのだから、自分のプロジェクトでも起きると考えたほうがいい。ちなみに222行という長さも、公式の200行目安をわずかに超えている。
この移行はリストの欠陥ではなく、CLAUDE.md というフォーマット自体の現在地を示している。 実例を参考にするときは、リンク先が今どちらの形式で運用されているかを確認したほうがいい。両ファイルの役割分担と使い分けは AGENTS.md 書き方・とは｜Codex/Devin/Claude Codeが読む指示ファイルとCLAUDE.mdの違い に詳しい。
実例から逆算する自分のCLAUDE.md改善手順
ここまでの実測を、そのまま自分のファイルに当てる手順に落とす。
第1に、上位4セクションが埋まっているかを見る。 概要・アーキテクチャ・コマンド・テスト。実例の70〜89%が持っている要素で、どれか欠けているならそこが最初の穴だ。とくにコマンドは最頻の89%であり、build / test / lint の実行方法が書いていないなら真っ先に足す。
第2に、行数を数える。 200行を超えているなら、増やす方向ではなく削る方向を検討する。公式が言う通り、長さは遵守率を下げる。実測でも長い側のスター中央値は低かった。超過分は .claude/rules/ の path スコープ付きルールやスキルへ移すと、常時読み込みの対象から外れる。
第3に、禁止事項を1ブロック足す。 実例の64%が持ち、47%が明示的な禁止語を使っている。「main に直接 push しない」「生成物を手で編集しない」など、AI が善意で踏み抜きうる制約を書く。
第4に、AGENTS.md の有無を確認する。 すでに置いているなら、CLAUDE.md を @AGENTS.md かシンボリックリンクにして二重管理をやめる。これは実例の上位が実際に採った選択だ。
第5に、リストを引くときは原本を確認する。 awesome-claude-md は最終更新が2026-06-05で止まり、オープンなIssueが24件たまっている。収録カードの分析文は執筆当時のスナップショットで、リンク先の現在とは一致しないことがある——本記事の実測がまさにその乖離を測ったものだ。
まとめ
・実例集は「地図」として有効だが、カードの説明文ではなくリンク先の原本を読む
・共通構成の骨格は概要・アーキテクチャ・コマンド・テストの4点
・200行を超えたら足すのではなく分ける。長さは品質の証明にならない
・AGENTS.md 併設なら橋渡し1行に寄せる（公式が推奨する書き方）
・リストの鮮度・ライセンス（LICENSE未設置）・リンクの経年劣化は自分で確かめる
自分の CLAUDE.md を実例と同じ尺度で測る
最後に、本記事と同じ物差しを自分のファイルに当てるコマンドを置いておく。行数と、コードブロックが占める割合——アンチパターン①の指標——をその場で出せる。
# 行数（200行が公式の目安。超えたら分割やスキル化を検討）
wc -l CLAUDE.md
# コードブロックの数と、ファイルに占めるコード部分の割合
awk '/^```/{n++} END{print "code blocks:", n/2}' CLAUDE.md
python3 -c "import re,sys;t=open('CLAUDE.md').read();c=sum(len(b) for b in re.findall(r'\`\`\`.*?\`\`\`',t,re.S));print(f'code ratio: {c/len(t)*100:.0f}%')"
# 見出しの一覧（上位4セクションが埋まっているかを目視で確認）
grep -n '^#\{1,3\} ' CLAUDE.md
コード占有率が7割に達していたら、貼ったコードの多くはリポジトリを読めば分かる情報のはずだ。見出しが10行に1つ立つようなら分割しすぎを疑う。どちらも、実例の長い側で実際に起きていたことである。
なお本記事の数値は2026-08-19時点の実測であり、リンク先リポジトリは今後も動く。リスト全体を追試したい場合は、各エントリの分析文からリンクを抽出し、raw.githubusercontent.com へ変換して取得すれば同じ手順を再現できる。その際、デフォルトブランチを main と決め打ちしないことだけ注意してほしい。今回の404の主因はそれだった。
参照ソース
- josix/awesome-claude-md（公式リポジトリ・README / CONTRIBUTING） — 収録108件・カテゴリ構成・選定方針の一次ソース
- awesome-claude-md の採点実装
scripts/discovery/evaluator.py— 配点30/25/20/15/10の一次ソース - Anthropic公式 — How Claude remembers your project（CLAUDE.md 仕様） — 200行未満の目標・AGENTS.md橋渡し・importとシンボリックリンクの記述
- Awesome Claude.md（GitHub Pages サイト） — リストのWeb版
