Claude Code に CLAUDE.md を置くべきだ、という話はもう広く知られている。だが実際に書こうとすると手が止まる。アーキテクチャをどこまで書くか、コマンドはどう並べるか、禁止事項をどう伝えるか。仕様が緩いぶん、正解の形が見えない。
その空白を埋めるのが、本記事で扱う josix/awesome-claude-md だ。公開リポジトリから集めた優良な CLAUDE.md を採点し、カテゴリ別に並べたキュレーション集である。空のファイルを前に悩む代わりに、自分のスタックに近い実例を開いて真似られる。
CLAUDE.md にどんなセクションを置くかという設計の原則は CLAUDE.mdの書き方｜AIに仕事を任せる人が最初に学ぶべきセクション設計 で扱っている。本記事はその先、原則が有名プロジェクトでどう実装されているかを実例から読む段階に絞り、リストの歩き方と取り込み手順を解説する。
30秒で理解する awesome-claude-md
・何のリスト？ 公開GitHubプロジェクトの優良な CLAUDE.md を集めたキュレーション集
・作者 台湾のエンジニア Josix（josix、Appier 所属）
・規模 ★389（2026-06-17・GitHub API実測）、scenarios/ に108件の実例
・選定基準 100点満点で60点以上。スター数の寄与は10%だけ
・方針 CLAUDE.md を転載せず、元リポジトリへのリンクと分析文を置く
・使いどころ 書き方の原則を学んだ後、自分のスタックに近い実例を探すとき
awesome-claude-md とは何か
awesome-claude-md は、公開リポジトリの優れた CLAUDE.md ファイルを集めて分類した GitHub のキュレーションリストだ。台湾・台北のエンジニア Josix（josix、ブログは josix.tw）が管理し、2025年7月14日に公開された。2026年6月17日時点で★389、最終更新は同年6月5日と、CLAUDE.md 関連のリストとしては継続的に手が入っている。
README は冒頭でリストの狙いをこう述べる。収録例は「複雑なコードベースに AI アシスタントをオンボーディングするための業界ベストプラクティスを示す」ものだ、と。プロンプトの書き方ではなく、プロジェクト全体の文脈を AI にどう引き渡すかに照準が合っている。
リストの実体は scenarios/ ディレクトリにある。リポジトリには scenarios/ のほかに、候補を機械的に見つける scripts/、検証用の tests/、運用ルールを書いた CLAUDE.md や AGENTS.md、自動収集の設計を記した AUTOMATED_DISCOVERY.md が並ぶ。リスト自身が Claude Code で運用されている構造で、リポジトリ全体が一つの実例にもなっている。
awesomeリストとは、特定テーマの優良リソースを有志がキュレーションする GitHub の文化だ。検索で断片的に集めるより、選別済みのリストを起点にしたほうが速い。CLAUDE.md のように「公式仕様は最小限で、良い書き方は各プロジェクトの暗黙知に散らばっている」題材では、実例を一箇所に集めた地図の価値が高い。
なぜ CLAUDE.md ベストプラクティス集が必要か
Anthropic の公式ドキュメントは、CLAUDE.md について「Claude が記憶しておくべき指示を書くファイル」とだけ定め、具体的な中身はプロジェクトに委ねている。メモリの階層（プロジェクト直下・ホーム配下・エンタープライズ）と読み込み順は決まっているが、各セクションに何を書くかは開発者の裁量だ。
この自由度が、書き手をつまずかせる。アーキテクチャ概要は何行が適切か、コマンド一覧は全部載せるのか主要なものだけか、コーディング規約は禁止事項まで書くのか。仕様が答えを持たない問いに、初めて書く開発者は一人で向き合うことになる。
CLAUDE.md が薄すぎれば AI は文脈を取り違え、厚すぎればトークンを浪費しノイズに埋もれる。ちょうど良い分量と構造は、結局のところ「うまくいっているプロジェクトがどう書いているか」を見るのが近道になる。Karpathy 流の設計原則を整理した Karpathy流CLAUDE.md｜LLMコーディング暴走を止める4原則 のような原則論と、実物の実例は補い合う関係にある。
awesome-claude-md は、その実例側を引き受ける。OpenAI・Microsoft・Cloudflare・Sentry といった既知のプロジェクトが、自分たちの CLAUDE.md に何を書いているかを並べて見せることで、「正解の形」を一つに固定せず、複数の妥当な型を提示する。書き手は自分の状況に近い型を選んで出発できる。
仕様が緩いドキュメントほど、優れた実例の価値が上がる。CLAUDE.md は公式仕様が最小限だからこそ、現場の良い書き方を集めたカタログが効く。
CLAUDE.md のメモリ階層をおさらいする
実例を読む前に、CLAUDE.md がどの場所に置かれ、どう読み込まれるかを押さえておくと、各実例の「どのレイヤーの話か」を見分けやすい。Anthropic公式のメモリ仕様では、CLAUDE.md は置き場所によって役割が分かれる。
組織全体の共通ルール] --> P[プロジェクト直下
./CLAUDE.md
チームで共有・git管理] P --> U[ユーザー設定
~/.claude/CLAUDE.md
個人の好み・全プロジェクト共通] U --> L[ローカル上書き
サブディレクトリの CLAUDE.md
その階層に入ったとき追加読込] P -.読み込み.-> AI[Claude Code セッション] U -.読み込み.-> AI E -.読み込み.-> AI
プロジェクト直下の CLAUDE.md は git でチームに共有され、awesome-claude-md が集めているのはおもにこの層だ。ホーム配下の ~/.claude/CLAUDE.md は個人の好みを全プロジェクトに効かせる層で、共有しない。サブディレクトリにも CLAUDE.md を置けて、その階層で作業するときに追記読み込みされる。
awesome-claude-md の各実例は、ほとんどがプロジェクト直下の共有 CLAUDE.md だ。だから読むときは「これはチーム全員に効かせる前提で書かれている」と意識すると、なぜ口調が指示的で、なぜ禁止事項まで明記してあるのかが腑に落ちる。個人の ~/.claude/CLAUDE.md をどう書くかは別の関心事になる。
収録カテゴリの全体像
scenarios/ は6つのカテゴリに分かれ、合計108件の実例が入る（2026-06-17時点、GitHub API でディレクトリ実測）。カテゴリは「プロジェクトの性格」で切られており、自分の状況に近いものから読める。
| カテゴリ | 収録数 | 性格 | 代表例 |
|---|---|---|---|
| developer-tooling | 41 | CLIツール・プラグイン・MCPサーバーなど開発者向けの道具 | Cloudflare Workers SDK / Lerna / cctx |
| libraries-frameworks | 27 | ライブラリ・フレームワーク。APIと規約の明示が中心 | Pydantic GenAI Prices / Agentic / ada |
| complex-projects | 25 | 複数サービスや大規模アーキテクチャを持つ応用例 | OpenAI Agents Python / Sentry / Overreacted.io |
| getting-started | 6 | 入門・スターターキット・小規模で全体を見渡しやすい例 | Anthropic Quickstarts / Microfolio / Dotfiles |
| infrastructure-projects | 6 | OS・ランタイム・VPNなど低レイヤ寄りの基盤 | Cloudflare Workerd / Breenix OS / TrailOfBits Algo |
| project-handoffs | 3 | 引き継ぎ・ドキュメント主体。文章設計の参考になる | KentBeck B+ Tree / Tasker Systems Book |
README はこのカテゴリ分類とは別に、言語別（TypeScript/JS が38件で最多、Python 25件、Rust 10件、Go 5件、Swift 4件ほか）と用途別（AI開発13件、インフラ8件、Web3が4件など）のフィルタも用意する。同じ実例が複数の切り口に登場するため、言語で絞っても用途で絞っても、自分の関心からたどり着ける構成だ。
OpenAI・Microsoft・Cloudflare・Anthropic・Sentry・PyTorch といった名の通ったプロジェクトと、個人開発のニッチなツールが同じ粒度で並ぶ。後述する採点方式がスター数をほとんど見ないため、無名でも書き方が優れていれば収録される。
採点方式：人気ではなく中身で選ぶ
awesome-claude-md の特徴は、収録判断の基準を README に明示している点だ。100点満点で採点し、60点以上を収録ラインとする。配点は次のように分かれる。
・内容の深さ（Content Depth） アーキテクチャ・ワークフロー・文脈を網羅しているか
・教育的価値（Educational Value） 独自のパターンやベストプラクティスを示しているか
・AIにとっての有効性（AI Effectiveness） AIアシスタントが読みやすい構造か
・プロジェクトの成熟度（Project Maturity） 活発に保守され実運用されているか
・コミュニティの評価（Community Recognition） 業界での認知やエンゲージメント
前者3つで70%、後者2つで30%を占める。README は「スターの寄与は全体の10%だけ」「スター数の下限は設けない」と明記する。人気のリポジトリを並べるのではなく、規模が小さくても学べる中身があれば拾う設計だ。
この方針が効いているのは、CLAUDE.md の良し悪しがスター数とほとんど相関しないからだ。スターはプロダクトの人気を測るが、CLAUDE.md の質は別物で、無名の個人プロジェクトが驚くほど丁寧なオンボーディング文書を持つことがある。採点をプロダクト人気から切り離したことで、リストは「CLAUDE.md として参考になるか」だけを純粋に並べられる。
候補の発見は機械化されている。AUTOMATED_DISCOVERY.md によれば、自動収集が候補を見つけ、コミュニティが教育的価値を評価し、最後に人手で選別する三段構えだ。GitHub検索の filename:CLAUDE.md "## Architecture" のようなクエリで、特定セクションを持つ CLAUDE.md を機械的に探している。
カテゴリ別の優良事例ハイライト
リストの読み方を掴むために、性格の異なる4例を取り上げる。いずれも本物は元リポジトリにあるので、リンクから直接確認してほしい。
anthropics/anthropic-quickstarts（getting-started） は、Claude を作る Anthropic 自身のサンプル集だ。複数プロジェクトを一つのリポジトリにまとめる構成で、computer-use デモを含む。公式が CLAUDE.md をどう書くかという基準点として、最初に開く価値がある。
openai/openai-agents-python（complex-projects） は OpenAI のマルチエージェントフレームワークで、Top Picks の Essential に置かれている。複数エージェントの協調を扱う大規模なコードベースで、AI システムの設計意図を CLAUDE.md にどう落とすかの実例になる。
gaearon/overreacted.io（complex-projects） は React コア開発者 Dan Abramov の技術ブログだ。awesome-claude-md は「技術的な深さと書き手の人格が両立した例」と評する。Next.js と MDX の静的サイトながら、開発ワークフロー全体を CLAUDE.md に書ききっている。規約集が無味乾燥になりがちな中で、読ませる文章でも要件を満たせると示す。
ebergstedt/action-idle（complex-projects） は、CLAUDE.md の指示を ESLint ルールで強制した例として目を引く。/src/core/ を純粋な TypeScript に保つアーキテクチャ境界を、ドキュメントの文章だけでなく lint ルールで縛っている。TypeScript と GDScript の対応表や、✅/❌ のコード比較を添えた11の設計原則も持つ。「書いた規約をどう守らせるか」まで踏み込んだ実例だ。
developer-tooling や infrastructure からも学べる例は多い。cloudflare/workers-sdk はモノレポとテストの書き方を CLAUDE.md に落とした例として、複数パッケージを一つのリポジトリで扱うときの指示の出し方が参考になる。ruvnet/claude-flow は64エージェントを協調させる構成を CLAUDE.md で説明しており、エージェント同士の役割分担をどう文書化するかの極端な実例だ。Rust 圏なら nwiizo/cctx が Claude Code のコンテキスト管理ツールとして、UX 哲学まで CLAUDE.md に書き込んでいる。
4例とこれらを並べると、CLAUDE.md に唯一の正解がないことが見えてくる。公式の標準、大規模AIシステムの設計記述、人格のにじむ規約、機械で強制する境界。目的に応じて型が変わる。リストはその振れ幅ごと見せてくれる。自分のプロジェクトに「いちばん近い性格」の例を探す感覚で開くと、迷わずに済む。
CLAUDE.md の構成パターン
108件を横断すると、優れた CLAUDE.md に繰り返し現れる4つの構成要素が見えてくる。awesome-claude-md の採点基準と各実例の分析文が示す共通項を整理する。
第一に、コンテキスト共有だ。プロジェクトの目的、アーキテクチャ概要、技術スタック、ディレクトリ構造を冒頭に置く。AI が最初に読む地図に当たる部分で、採点の「内容の深さ」が見ているのもここが中心になる。複雑なプロジェクトほど、サービス間の関係やデータの流れを図や箇条書きで先に渡している。
第二に、コーディング規約だ。命名規則、使う／使わないライブラリ、フォーマット、テストの書き方を指示形で書く。action-idle の ✅/❌ コード比較のように、良い例と悪い例を並べると AI が判断を誤りにくい。
第三に、コマンド一覧だ。ビルド・テスト・デプロイ・lint の実行コマンドを列挙する。CONTRIBUTING が例示する GitHub検索クエリ filename:CLAUDE.md "## Development Commands" が一つのセクションとして成立するほど、コマンド集は定番の構成要素になっている。AI が手探りでコマンドを推測せずに済む。
第四に、アンチパターンの明示だ。「やってはいけないこと」を禁止事項として書く。直接 main に push しない、特定のディレクトリを触らない、といった制約を明文化すると、AI の暴走を未然に防げる。本サイトの CLAUDE.md にも「やらないこと」セクションがあり、この型は実運用で広く採られている。
この4要素はチェックリストではなく、観察された頻出パターンだ。すべてを盛り込む必要はなく、プロジェクトの性格に応じて重みが変わる。ライブラリなら規約とAPIの明示が厚くなり、複雑なアプリならコンテキスト共有が厚くなる。
自前プロジェクトに取り込む手順
リストを眺めるだけで終わらせず、自分の CLAUDE.md に落とすには、次の流れが実用的だ。
性格を特定
言語・規模・用途] --> B[近い実例を
リストから選ぶ
Top Picks or フィルタ] B --> C[元リポジトリで
本物のCLAUDE.mdを読む
分析文と照合] C --> D[構成要素を抽出
コンテキスト/規約/
コマンド/禁止事項] D --> E[自プロジェクトに移植
固有名詞・パスを
自分のものへ改変] E --> F[Claude Codeで検証
誤読・過不足を
見て調整]
最初に、自分のプロジェクトの性格を言語・規模・用途で特定する。TypeScript の小規模ツールなのか、Python の大規模AIシステムなのかで、参考にすべき実例が変わる。
次に、近い実例をリストから選ぶ。判断に迷うなら Top Picks の Essential から入り、言語別・用途別フィルタで自分のスタックに寄せる。一つに絞らず、2〜3件を見比べると共通する型が浮かぶ。
選んだら、必ず元リポジトリで本物の CLAUDE.md を開く。awesome-claude-md に載るのは分析文であって CLAUDE.md そのものではないからだ。分析文が「なぜ優れているか」を指すので、本物と照らして読むと意図が掴める。
そこから構成要素を抽出し、自分のプロジェクトに移植する。固有名詞・パス・コマンドは当然すべて自分のものに置き換える。丸ごとコピーしても他人のアーキテクチャの説明にしかならないので、骨格だけ借りて中身は書き直す。
最後に Claude Code で実際に動かし、AI が誤読する箇所や、書きすぎ・書き足りない箇所を見て調整する。CLAUDE.md は一度で完成させるものではなく、AI の振る舞いを見ながら削り足す対象だ。
具体的にイメージすると、たとえば Python の小さな CLI ツールを書いているなら、まず getting-started や developer-tooling から近い規模の例を2件選ぶ。一方が「アーキテクチャを3行で要約し、残りはコマンド一覧に振っている」構成で、もう一方が「禁止事項を箇条書きで先頭に置いている」構成だったとする。自分のツールには複雑なアーキテクチャがないので前者の比率を借り、main への直接 push を避けたいので後者の禁止事項の型を足す、という具合に部品を組み合わせる。丸ごと真似るのではなく、実例を部品の供給源として扱うと、自分のプロジェクトに過不足なく収まる。
移植した CLAUDE.md は、Claude Code に簡単なタスクを投げて挙動を観察すると質を確かめやすい。指示したはずの規約が守られないなら書き方が曖昧か埋もれている合図で、逆に毎回同じ確認を AI が繰り返すなら、その情報が CLAUDE.md に足りていない。awesome-claude-md の実例は、この調整の到達点としての「完成形」を見せてくれる存在でもある。
類似リソースとの比較
CLAUDE.md の学び方には複数の入り口がある。awesome-claude-md の位置づけを、隣接するリソースと比べて整理する。
| リソース | 性格 | 得意 | 苦手・限界 |
|---|---|---|---|
| awesome-claude-md | 実例カタログ | 有名プロジェクトの実装を横断比較できる | 原則の体系的な説明は薄い |
| Anthropic公式 Memory ドキュメント | 仕様書 | 階層・読み込み順など正確な仕様の根拠 | 「何を書くか」の中身は委ねられる |
| CLAUDE.md 書き方ガイド（解説記事） | 原則・設計論 | セクション設計や失敗パターンを体系化 | 個別スタックの具体実装は読者任せ |
| awesome-harness-engineering | 周辺ツール集 | CLAUDE.md を含む足回り全体のOSSを俯瞰 | CLAUDE.md 単体の実例は少ない |
| CLAUDE.md 生成ツール（sourcebook 等） | 自動生成 | コードベースから下書きを自動作成 | プロジェクト固有の意図は補えない |
これらは競合ではなく分担だ。仕様の根拠は公式ドキュメント、書き方の原則は解説記事、具体的な実装は awesome-claude-md、という順で参照すると無駄がない。CLAUDE.md は AI エージェントの足回り全体の一部でもあり、メモリ・MCP・権限などを含む広い文脈は awesome-harness-engineeringの歩き方 で扱っている。
awesome-claude-md 自身も Tools & Ecosystem セクションで生成ツールを紹介する。複数マシン間で CLAUDE.md を同期する claude-brain（MIT）、コードベースの規約や git 履歴から CLAUDE.md を生成する sourcebook（BSL-1.1）などだ。実例で型を学び、生成ツールで下書きを作り、手で意図を足す、という組み合わせも成り立つ。
コントリビューション方法
awesome-claude-md はプルリクエストを歓迎するコミュニティリストだ。良い CLAUDE.md を見つけたら、次の手順で追加できる。
最初に GitHub検索で候補を探す。CONTRIBUTING は filename:CLAUDE.md "## Architecture" や filename:CLAUDE.md org:microsoft のようなクエリを例示する。特定のセクションを持つ CLAUDE.md を絞り込むと、質の高い候補に当たりやすい。
次に60点以上の基準を満たすかを自分で見立て、満たすなら分析文を書く。何が優れているか、どんなパターンを示しているかを言葉にして、README の該当カテゴリに1行追記し、プルリクエストを送る。
ここで守るべき倫理ガイドラインがある。CLAUDE.md を直接コピーしない、常に元ソースへリンクする、出典とライセンス情報を明記する、公開され許諾されたファイルだけを参照する。リストが他者のドキュメントを転載せずリンクと分析で構成されているのは、この方針の帰結だ。自分のプロジェクトを推薦する場合も同じで、提出するのはリンクと分析であってファイルの中身ではない。
リンク切れの修正や分類の改善、既存分析への技術的な補足といった小さな貢献も受け付けている。awesomeリスト共通の、フォークして追記してプルリクエスト、という流れで参加できる。
制限事項・注意点
実例カタログとして便利な一方、使うときに意識しておきたい限界がある。
第一に、LICENSE ファイルが置かれていない点だ（2026-06-17時点）。リスト本文は他者の CLAUDE.md を転載していないため、各実例の利用条件はリンク先リポジトリそれぞれのライセンスに従う。実例を自分のプロジェクトに取り込むときは、骨格だけ借りるとはいえ、リンク先の条件を個別に確認するのが安全だ。
第二に、収録はスナップショットである点だ。元リポジトリの CLAUDE.md は更新され続けるが、awesome-claude-md の分析文が常に追随するとは限らない。分析が書かれた時点と現在で本物の中身が変わっている可能性があるので、必ずリンク先で現在の中身を直接読む。
第三に、英語圏のプロジェクトに偏る点だ。収録例はほぼ英語の CLAUDE.md で、日本語で書く際の言い回しや、日本語プロジェクト特有の事情は別途考える必要がある。構成や型は言語を問わず流用できるが、文面そのものは参考にとどまる。
第四に、「良い CLAUDE.md」の評価は文脈依存である点だ。100点満点の採点は明確だが、ある実例が自分のプロジェクトにそのまま効くとは限らない。大規模AIシステム向けの厚い CLAUDE.md を小さなツールに移植すれば、過剰でノイズになる。リストは候補を示すが、取捨選択は読み手の仕事だ。
まとめ
awesome-claude-md は、CLAUDE.md を「どう書けばいいか分からない」段階の開発者に、108件の実例という出発点を与える。スター数をほとんど見ない採点で中身本位に選ばれた実例が、公式の標準から人格のにじむ規約、機械で強制する境界まで、CLAUDE.md の振れ幅を見せてくれる。
使い方は単純だ。自分のプロジェクトの性格を特定し、近い実例を選び、元リポジトリで本物を読み、骨格を移植して Claude Code で調整する。公式ドキュメントで仕様を、解説記事で原則を、このリストで実装を、と役割分担で参照すれば、空のファイルを前に悩む時間を実例から逆算する作業に置き換えられる。まずは Top Picks を開き、自分のスタックに一番近い1件を読むところから始めてほしい。
関連記事として、セクション設計の原則を学ぶ CLAUDE.mdの書き方、Claude Code の全体像を押さえる Claude Code 2026年版・実装手引き も合わせて参照してほしい。
参照ソース
・josix/awesome-claude-md（公式リポジトリ・README） — 本記事の一次情報。README・カテゴリ構成・採点基準・倫理ガイドライン
・Awesome Claude.md（GitHub Pages サイト） — リストのWeb版
・GitHub API: josix/awesome-claude-md — ★数・作成日・更新日時の実測値
・Anthropic公式 Claude Code — Manage Claude’s memory — CLAUDE.md のメモリ階層と読み込み仕様
・Josix（作者 GitHub プロフィール）
