はじめに#

Claude Code を個人プロジェクトで本格的に使い始めると、最初にぶつかるのが「毎回同じ文脈を口頭で説明するのがつらい」という問題です。
解決策としてリポジトリ直下に CLAUDE.md を置くのは既に定番ですが、プロジェクトが育つとこの 1 ファイルだけでは運用が破綻します。

本記事では、Claude Code が提供する CLAUDE.md / slash command / subagent / skill の 4 つのレイヤーを役割分担し、
プロジェクト文脈を構造的にエージェントへ渡す方法を、実際にこのブログで組んだ構成を例に紹介します。

なぜ CLAUDE.md だけでは足りないのか#

CLAUDE.md は Claude Code が毎セッションの先頭で必ず読み込む Markdown ファイルです。
プロジェクトのスタック・規約・よく使うコマンドをここに書いておくと、
毎回「この repo は Astro で、pnpm を使って、Biome で整形していて…」と説明しなくて済みます。
常時メモリとして非常に強力です。

しかし単体では 3 つの限界があります。

1. 全セッションの先頭で読まれる
   必ず読まれるため、大きくなるほど毎回のトークンを圧迫します。
   Claude Code のベストプラクティスでは 200 行以下が目安とされており、これを超えると「読まれているけれど守られない」状態になりがちです。
2. 手続き的なワークフローを書くには冗長
   「新規記事を作るときは、まずスラッグを決めて、次に雛形を生成して、フロントマターを書き換えて…」
   のような順序依存の作業は、自然言語で羅列しても実行順序を保証できません。
3. 専門的な知識は読み捨てになる危険性
   たとえば SEO レビューのような重いチェックリストを CLAUDE.md に書くと、
   SEO レビューをしない他のセッションでもトークンを消費してしまいます。

この 3 つを解決するために、残り 3 つのレイヤーを積み上げていきます。

4 層の役割分担#

ポイントは コンテキストの寿命と読まれる頻度 です。
CLAUDE.md は毎回全員が読む共有知識、skill は必要なときだけ特定のエージェントが読むニッチ知識、という使い分けを意識します。

実例: 個人ブログで組んだ構成#

今回実装した構成は次の通りです。

1
blog/
2
├── CLAUDE.md                          # 113 行。スタック・記事規約・コマンド
3
└── .claude/
4
    ├── settings.json                  # permission allowlist
5
    ├── commands/
6
    │   └── new-post.md                # /new-post <slug> で記事雛形を生成
7
    ├── agents/
8
    │   ├── post-planner.md            # 記事企画とアウトライン生成
9
    │   └── seo-reviewer.md            # 公開前の SEO レビュー
10
    └── skills/
11
        └── frontmatter-check/
12
            └── SKILL.md               # frontmatter の schema 検証

それぞれが「どの問いに答えるか」を 1 行で言えるように設計してあります。

• CLAUDE.md: このブログはどんな規約で書かれているか？
• /new-post: 新しい記事を始めるとき、どういう手順を踏むか？
• post-planner: このアイデアは記事として成立するか？ outline はどうなるか？
• seo-reviewer: この記事は公開に耐えるか？
• frontmatter-check: この YAML はスキーマに合っているか？

この 5 つを CLAUDE.md に詰め込もうとすると、確実に 500 行を超えます。
分割したことで CLAUDE.md は 110 行前後で安定し、各エージェントとスキルも 50〜60 行の手ごろなサイズに収まりました。

アイデアを「エージェントが読める形」で保つ#

もう 1 つ重要な気付きがあります。
プロジェクト文脈はコードだけではなく、計画や企画書も含まれる ということです。

このブログでは記事アイデアを docs/blog-post-plan/ 配下で以下のようなファネルで管理しています。

flowchart LR
      A["Inbox<br/>inbox.md"] -->
  B["Backlog<br/>spinoff-candidates.md"]
      B --> C["Active<br/>NN-*.md"]
      C --> D["Posts<br/>src/content/posts/"]

重要なのは、post-planner エージェントの定義ファイルに
「新規企画を受けたら、outline を書く前に必ず inbox.md と spinoff-candidates.md を grep して重複を確認せよ」
という義務を明記している点です。

1
## Inputs you should always gather
2

3
2. **Duplicate check (mandatory)**. Before producing any outline, grep
4
   both of these for overlapping keywords from the pitch:
5
   - docs/blog-post-plan/inbox.md
6
   - docs/blog-post-plan/spinoff-candidates.md
7
   If you find an overlapping entry, stop and report it before writing
8
   a new plan.

結果として、企画メモ自体が「エージェントが読みに行く構造化ドキュメント」になり、僕がアイデアの重複を手動でチェックする必要がなくなりました。
アイデア管理が 検索可能なコンテキスト に昇格した感覚です。

運用の勘所#

以下は実際に運用してみて効いたポイントです。

1. CLAUDE.md は 200 行を厳守する
   サイズが膨らんだ時点で、役割の切り分けに失敗している兆候です。
   特定ドメインに深入りした記述や「特定のケースでだけ役立つ手順」が混ざり始めたら、迷わずサブエージェントかスキルに切り出します。

2. コマンドとエージェントを混同しない
   「手順が決まっている」 → コマンド、「判断が必要」 → エージェント、と分けます。
   /new-post は決まったステップの実行なのでコマンドですが、SEO レビューは記事ごとの文脈判断が必要なのでエージェント（seo-reviewer）にしています。
   この区別を間違えると、エージェントがただの手順書になったり、コマンドが曖昧な判断を抱え込んだりします。

3. permission の allowlist を先に整える
   .claude/settings.json に pnpm lint、pnpm check、git status 等のコマンドを事前承認しておくと、エージェントが毎回承認を求めてきません。
   一方で git push --force のような破壊的コマンドは明示的に deny に入れておきます。
   これがないと、便利なエージェントほど承認プロンプトで作業が止まります。

4. Skill は呼ばれないと読まれない
   Claude Code の skill は description フィールドで自動判定されるか、
   エージェントが明示的に呼んだときに初めて SKILL.md の本文が読み込まれます。
   常に読んで欲しい知識は CLAUDE.md に、必要な時だけで十分な知識は skill に
   という分離の鉄則を守ると、全体のトークン効率が目に見えて良くなります。

まとめ#

• CLAUDE.md は「常時読まれる共有規約」、それ以外（commands / agents / skills）は「必要時だけ読まれる専門知識」という区別が設計の核心
• 企画書やアイデア帳のような人間向けドキュメントも、エージェントが grep できる構造にすると自動化の対象に引き上げられる
• 個人ブログ規模でもこの 4 層を分けるだけで、毎回のセッションで「最近何書いたっけ」を説明する必要がなくなる
• この仕組みは OGP 画像の自動生成のような別の自動化とも相性が良く、エージェントが規約を理解した上で実装を進められる

Claude Code のベストプラクティスは進化が速い領域なので、一度組んだ構成も定期的に見直す前提で運用するのがおすすめです。
まずは CLAUDE.md を 200 行以下に保ちつつ、/new-post のような .claude/commands/ を 1 つ作ってみるところから始めるのが最短です。
その 1 つが動いた瞬間に、このレイヤリング設計の意味が体感として腑に落ちるはずです。