CLAUDE.mdはシンプルでいい。
目次として使って詳細は別ファイルに分ける設計にした話

AI開発

はじめに

前回の記事（バイブコーディングで静的サイトを作った話）で、CLAUDE.mdというファイルを最初に作ったと書きました。

Claude CodeはこのファイルをAIが作業前に自動で読んでくれるので、毎回「このプロジェクトはこういう構成で、こういうルールで…」とゼロから説明しなくて済む。

今回はそのCLAUDE.mdを実際にどう書いているかを見せます。

最初は全部詰め込もうとして失敗した

最初にモックを作っていたとき、CLAUDE.mdにいろんなルールを書き込んでいきました。

  • 技術スタックのルール
  • 事例ページのHTMLレイアウト規約
  • SEOのmetaタグテンプレート
  • セキュリティヘッダーの設定
  • ファイル命名規則
  • カテゴリーの定義
  • …

書いていくうちに行数がどんどん膨れていって、見返したときに「これ、どこに何が書いてあるかわからない」という状態になりました。

これは没にして、設計を考え直しました。

解決策：CLAUDE.mdは「目次」として使う

気づいたのは、CLAUDE.mdに全部書こうとしなくていいということです。

CLAUDE.mdの役割を「このプロジェクトのルール一覧と、詳細はどのファイルに書いてあるかを伝える目次」に絞りました。詳細なルールはテーマごとに別ファイルに分けて、CLAUDE.mdからはそちらを参照させる。

イメージはこんな感じです。

CLAUDE.md（目次）
  ├── architecture.md（サイト構成・技術スタック）
  ├── design.md（デザイン方針・カラー）
  ├── example-page.md（事例ページのレイアウト規約）
  ├── security-seo.md（SEO・セキュリティ）
  └── ...

AIはCLAUDE.mdを読んで「詳細はこっちを見ればいい」とわかる。作業に必要なファイルだけを参照してくれるので、全部を一度に読み込ませるより動きが安定します。

実際のCLAUDE.mdを見せます

このサイト（コピペ de UI）で使っているCLAUDE.mdの中身です。だいたいこんな感じです。

# コピペ de UI — Claude.md

このファイルはAIアシスタント（Claude等）がプロジェクトを理解・支援するための指示書です。
作業前に必ずこのファイルと doc/ 配下のMDファイルを参照してください。

## プロジェクト概要

- サービス名: コピペ de UI
- キャッチコピー: Webで使えるUIコンポーネントをコピペで即実装
- 目的: Webアプリ開発者向けUIコンポーネント事例集サイト
- 提供物: 動くデモ・サンプルソース（HTML/CSS/JS）・AI用プロンプトの3点セット
- 形態: 静的サイト（Static Site）
- 運営者: shun@AI Builder

## ドキュメント構成

| ファイル                   | 内容                                            |
|---|---|
| doc/architecture.md        | サイト構成・ディレクトリ構造・技術スタック        |
| doc/design.md              | デザイン方針・カラー・レイアウトルール            |
| doc/pages.md               | 各ページの仕様・ルール                            |
| doc/example-page.md        | 事例ページの共通レイアウト仕様（HTML構造）        |
| doc/example-spec-rules.md  | 事例スペックMDの作成ルール                        |
| doc/categories.md          | 事例カテゴリー定義と一覧                          |
| doc/security-seo.md        | セキュリティ対策・SEO対策方針                     |
| doc/article-page.md        | 記事ページの共通レイアウト仕様                    |
| doc/examples/*.md          | 各事例のスペックMD（1事例につき1ファイル）        |

## AIへの作業指示ルール

1. コード生成時は architecture.md の技術スタックに従う
2. デザイン変更時は design.md のカラー・スタイルガイドを遵守する
3. 事例ページ（HTML）追加時は example-page.md のレイアウト仕様に従う
4. 事例スペックMD追加・編集時は必ず example-spec-rules.md を読んでから作業する
5. 新カテゴリー追加時は categories.md を更新する
6. セキュリティ・SEOに関わる変更は security-seo.md を参照する
7. 記事ページ（HTML）追加時は article-page.md のレイアウト仕様に従う
8. サンプルソースはバニラJS（フレームワーク不使用）で記述する
9. 外部ライブラリはCDN経由で読み込む（npmビルド不要の静的サイト前提）
10. コードはコピペですぐ動くことを最優先とする

これだけです。実際のファイルはこの内容で完結しています。

短くてびっくりするかもしれないですが、「AIへの作業指示ルール」の各行が別ファイルを参照するように書いてあるので、詳細はそちらに全部ある。CLAUDE.md自体はスリムなままです。

別ファイルはどんな内容？

参考までに、各ファイルがどういう役割かをさらっと紹介します。

architecture.md

技術スタック（HTML/CSS/バニラJS）、ディレクトリ構成、ファイル命名規則など。ここで一番大事にしたのが「このサイトは静的サイトで、フレームワークは使わない」という宣言です。

なぜわざわざ書くかというと、書かないとAIがNext.jsやReact前提のコードを書いてくることがあるからです。AIは「モダンな構成」を勝手に判断するので、明示的に縛ってあげる必要がある。

ちなみに静的サイトを選んだ理由は単純で、このサイトの目的はUIコンポーネントの事例を公開することなので、それを達成するには静的サイトで十分でした。Next.jsを使いこなす学習コストを払ってまで運営するメリットが感じられなかったし、正直複雑にしすぎて継続できなくなる方が怖かった。シンプルに保つことが長続きの条件だと思っています。

example-page.md / security-seo.md など

残りのファイルは前回の記事でも少し触れたので詳細は省きますが、「事例ページの構成ルール」「SEOのチェックリスト」といった内容が各ファイルに入っています。どれも「AIに毎回説明しなくて済むようにする」という目的で作っています。

まとめ

CLAUDE.mdは短くていいと思っています。

長くしようとすると「どこに何を書くか」の管理が大変になるし、AIも長い指示より短くて明確な指示の方が動きやすい。目次として使って、詳細は別ファイルに任せる構造にしてから、作業の安定感がだいぶ上がりました。

ただ、これはあくまで自分がこのプロジェクトで試行錯誤した結果の構成です。プロジェクトの規模や用途によって最適な書き方は変わると思いますし、世の中にはもっとうまい構成もあると思います。「こういうやり方もあるんだな」くらいの参考にしていただければ。

こういう設計の考え方を体系的に身につけたい方には、オンラインで学べるAI開発系のスクールも選択肢のひとつです。多くのスクールで無料カウンセリングを受け付けているので、独学の前にどんな学習ができるか話だけ聞いてみるのもありだと思います。

次回は、事例ページを作るときに「スペックMDを先に書く」という流れを紹介する予定です。CLAUDE.mdの別ファイル参照がさらに具体的にどう機能しているかが見えてくると思います。

written by shun@AI Builder