1. はじめに
目的と背景
Claude Codeでプロジェクトに取り組んでいると、「ルールをどこに書くか」で必ず迷います。CLAUDE.mdに書く、専用のスキル(SKILL.md)に書く、サブエージェント(.claude/agents/*.md)に書く、あるいはメモリに書く。選択肢が増えるほど「とりあえずCLAUDE.mdに全部書いておけば読んでくれるだろう」という誘惑も強くなります。
しかしCLAUDE.mdはすべてのセッション開始時に丸ごとコンテキストへ読み込まれるファイルです。書けば書くほど、会話のたびに消費されるトークンが増え、しかも公式ドキュメントには「長いファイルほど指示への追従性が下がる」とまで明記されています。つまりCLAUDE.mdへの書き込みすぎは、コンテキストの無駄遣いであると同時に、Claude自身の性能を下げる要因にもなり得ます。
試したことの概要
このブログ運用リポジトリ自体が、まさに「CLAUDE.mdを太らせない」ことを意識して育ててきたプロジェクトです。/blog-postというスキルを起点に、記事執筆・校正・勉強メモ作成・図解作成までを複数のスキル・サブエージェントに分割しており、今回はこのリポジトリの実際のファイル構成・行数を題材に、
- 何を
CLAUDE.mdに残し、何をスキル・サブエージェントに逃がすべきか - 実際に運用してみて起きた「指示通りに動かなかった」失敗と、その直し方
を具体的な数値付きで整理します。
2. 環境設定
使用したツールとバージョン
- Claude Code(CLI)
- このリポジトリ自体(
C:\Users\since\keitaro\projects\blog)。gitリポジトリではなく、静的サイトジェネレータ等のビルドパイプラインも持たない、Markdown執筆に特化したディレクトリ
初期設定と準備
特別なインストール作業は不要です。必要なのは以下のディレクトリ構成をプロジェクトルートに用意することだけです。
blog/
├── CLAUDE.md # ルールの正本(141行)
├── posts/ # 公開用記事
│ └── 2026-08-18-xxx.md
├── notes/ # 記事とは別の勉強メモ
│ └── 2026-08-18-xxx.md
├── images/ # 記事内で使うSVG図解
│ └── 2026-08-18-xxx/
│ └── architecture-overview.svg
└── .claude/
├── skills/
│ └── blog-post/
│ └── SKILL.md # オーケストレーター(40行)
└── agents/
├── trend-researcher.md # ネタ探し(29行)
├── proofreader.md # 校正(25行)
├── study-notes.md # 勉強メモ作成(27行)
├── diagram-illustrator.md # 図解作成(61行)
└── diagram-icons.svg # 共有アイコン素材(参照専用)
ポイントは、**CLAUDE.mdだけが「常にフルで読み込まれるファイル」で、それ以外(SKILL.md・.claude/agents/*.md)は「必要になったときだけ読み込まれるファイル」**という非対称性がある点です。この非対称性を意識してファイルを配置するのが、今回の整理術の核心です。
CLAUDE.mdとスキル・サブエージェントの読み込みタイミング。CLAUDE.mdは毎セッション全文ロードされ、SKILL.mdと4つのサブエージェント(trend-researcher, proofreader, study-notes, diagram-illustrator)は呼び出されたときだけ本文がロードされることを示す図
3. 実装手順
コードスニペットと説明
手順1: 「常時ロード」されるCLAUDE.mdには方針だけを書く
CLAUDE.mdには、ブログの目的(3行)と、ディレクトリ構成・各スキル・サブエージェントの役割一覧(基本1〜2文の短い説明)だけを書いています。実際の一覧部分(CLAUDE.mdの該当節をそのまま引用)は以下の通りです。
## ディレクトリ構成と執筆の自動化
-`posts/` … 公開用のブログ記事本文(例: `posts/2026-08-18-xxx.md`)。以下の章立てルールに沿って書く。
-`notes/` … ブログ記事とは別の勉強用メモ(技術的な深掘り、コマンド、つまずいた点など)。記事と同じスラッグで対応付ける(例: `notes/2026-08-18-xxx.md`)。公開記事の本文とは重複させない。
-`images/{記事と同じ日付-スラッグ}/` … 記事内で使う図解画像(SVG)置き場。記事と同じスラッグのディレクトリにまとめる(例: `images/2026-08-18-xxx/architecture-overview.svg`)。WordPressへの投稿時はこのファイルをメディアライブラリにアップロードする前に、手動でPNG等に変換する(WordPress標準設定はSVGアップロードを拒否する場合があるため)。
-`.claude/skills/blog-post/SKILL.md` … `/blog-post` スキル。ネタ探し→執筆→校正→勉強資料作成までを一連の流れで行うオーケストレーター。
-`.claude/agents/trend-researcher.md` … ネタ(トレンド)探し担当のサブエージェント。
-`.claude/agents/proofreader.md` … 誤字脱字・章立ての整合性チェック担当のサブエージェント(指摘のみ、自動修正はしない)。
-`.claude/agents/study-notes.md` … `notes/` 配下の勉強資料作成担当のサブエージェント。
-`.claude/agents/diagram-illustrator.md` … 記事内容をもとに`images/`配下へSVG図解を作成する担当のサブエージェント(`posts/`は編集しない)。指示された内容を作図する「指定モード」と、記事を通読して図解箇所自体を判断する「自己判断モード」を持つ。作図には共有アイコン素材`.claude/agents/diagram-icons.svg`を参照する。
執筆時はこの節にある構成・スキル・エージェントを使い、以下の章立てルール自体はここに転記せず本ファイルの該当節を都度参照すること。
各行はファイルパスと概要説明に留め、チェック観点や作図方針といった具体的な振る舞いのルールまでは書き込みません。notes/・images/・SKILL.md・diagram-illustratorのように補足の都合で2〜3文になっている行もありますが、それでも「何をするファイルか」という概要の域を出ず、判断基準やロジックの中身はスキル・サブエージェント側のファイルに書いています。詳細を書きたくなったら、それはCLAUDE.mdではなくスキル・サブエージェント側のファイルに書く、というルールを徹底しています。
手順2: 「オンデマンドロード」されるスキル・サブエージェントに詳細を逃がす
たとえば校正を担当するproofreaderサブエージェント(25行)は、チェック項目・出力形式・注意事項をすべて自分のファイル内で完結させています。
---
name: proofreader
description: ブログ記事の誤字脱字・表記ゆれ・章立ての整合性を、執筆時の文脈を引き継がないフレッシュな目でチェックする。記事執筆が完了した後、投稿前のレビュー段階で使う。
tools: Read, Grep
---
このようにtoolsフィールドで権限も絞っています(proofreaderはRead, GrepのみでWrite/Editを持たない)。これは今回の「コンテキストの無駄遣い」対策とは直接関係ありませんが、副次的に「サブエージェントの説明文(description)は常にすべてのサブエージェント名分だけ短く読み込まれ、本文はそのサブエージェントが実際に呼ばれたときだけ読み込まれる」という設計になっているため、サブエージェントの数が増えてもCLAUDE.mdのように線形にコンテキストを圧迫しません。
手順3: ルールの「正本」を1箇所に決め、他のファイルからは参照だけさせる
SKILL.md側には、章立てルールの中身を一切書いていません。
このスキルは、このディレクトリ(ブログ)で記事を1本作成するためのオーケストレーターです。
ルールの本体は `CLAUDE.md` にあるので、章立てや目的の具体的な内容はここには書かず、
必ず `CLAUDE.md` を読み込んで参照してください。
もし章立てルールをSKILL.mdにもコピーしてしまうと、後でCLAUDE.mdを更新したときにSKILL.md側が古いままになる、という不整合が起きやすくなります。「情報は1箇所に置き、他は参照する」というルールは、コンテキスト節約だけでなく保守性のためにも効きます。
ステップバイステップのガイド
- プロジェクトルートに
CLAUDE.mdを作り、方針・目的・ディレクトリ構成の一覧だけを書く(公式ドキュメントの目安は200行以内)。 - 繰り返し使う手順は
.claude/skills/{name}/SKILL.mdとしてスキル化し、CLAUDE.mdからは「このスキルを使う」という1行だけ参照する。 - 独立して実行でき、かつ「間違って本体ファイルを書き換えられたくない」処理(校正・調査など)は、
toolsを絞ったサブエージェント(.claude/agents/*.md)に切り出す。 - スキル・サブエージェントが増えたら、
CLAUDE.mdにはファイルパスと概要(基本は1〜2文)だけ追記する。diagram-illustratorのように呼び出しモードが複数あるものはモード名まで触れてよいが、モードの中身や判断基準までは書かない。詳細をここに書きたくなったら、それはそのスキル・サブエージェント側のファイルに書くべき内容だと考え直す。 - 定期的に
CLAUDE.mdの行数を数え、200行に近づいていたら「本当に常時必要な情報か」を見直す。
4. 結果
実行結果
このリポジトリの現在のファイル行数を実測すると、以下の通りです。
| ファイル | 行数 | ロードタイミング |
|---|---|---|
CLAUDE.md | 141行 | 毎セッション開始時に必ず全文ロード |
.claude/skills/blog-post/SKILL.md | 40行 | /blog-post実行時のみ |
.claude/agents/trend-researcher.md | 29行 | このサブエージェント呼び出し時のみ |
.claude/agents/proofreader.md | 25行 | このサブエージェント呼び出し時のみ |
.claude/agents/study-notes.md | 27行 | このサブエージェント呼び出し時のみ |
.claude/agents/diagram-illustrator.md | 61行 | このサブエージェント呼び出し時のみ |
もし仮に、1スキル+4サブエージェント分の本文(SKILL.md 40行 + trend-researcher 29行 + proofreader 25行 + study-notes 27行 + diagram-illustrator 61行 = 182行)をすべてCLAUDE.mdに直書きしていたら、CLAUDE.mdは141+182=323行になり、公式ガイドラインの「200行以内」を大幅に超えていた計算になります。ファイルを分けたことで、常時ロードされる分量を141行に抑えられているのが、今回の整理の直接的な効果です。
CLAUDE.mdの行数比較。現状のCLAUDE.md 141行と、1スキル+4サブエージェント分の本文をすべて直書きした場合の323行を比較し、公式ガイドラインの目安200行と対比した棒グラフ
成功例と失敗例
成功例: 「ルールの正本を1箇所にする」方針のおかげで、後からdiagram-illustratorサブエージェントを追加した際も、CLAUDE.mdへの変更は1行の追記だけで済みました。SKILL.md側の変更点(いつ・どう呼ぶか)はSKILL.md自身に、作図の詳細ルールはdiagram-illustrator.md自身に書いたため、変更の影響範囲が最小限に収まりました。
失敗例: ファイルを分けて「指示を書けば守られる」と思い込んでいたところ、diagram-illustratorサブエージェントに「共有アイコン素材<g id="icon-xxx">の中身をそのままコピーして使うこと」と明記していたにもかかわらず、実際の呼び出しではサブエージェントがその場でオリジナルのアイコンを描いてしまう、ということが起きました。ファイル分割自体は成功していても、書いた指示が字句通りに実行される保証はないという点は誤算でした。最終的には「そのままコピーしてもよいし、文脈に応じて描き直してもよい」という、実際の挙動に指示側を合わせる形に書き換えて決着しています。整理術は「どこに書くか」の問題であって、「書いた通りに動くか」は別の問題だと痛感しました。
5. まとめ
得られた知見と反省点
CLAUDE.mdは毎セッション全文ロードされるため、方針・目的・ファイル一覧だけに絞り、詳細はスキル・サブエージェントに逃がすと、コンテキストの無駄遣いと指示追従性の低下を同時に防げる。- スキル・サブエージェントは「呼ばれたときだけ本文がロードされる」ため、増やしてもコンテキスト消費が線形に増えにくい。
- ルールの重複を避け、「正本は1箇所、他は参照」を徹底すると、後からの追加・変更が1箇所の修正で済む。
- ただし、ファイルを適切な場所に分けても、書いた指示がサブエージェントに字句通り守られるとは限らない。実際の挙動を見てから指示を調整する前提で運用する必要がある。
今後の改善点
- 現状は
CLAUDE.mdとスキル・サブエージェントの2層構成だが、Claude Codeには特定のパス配下でだけ読み込まれる.claude/rules/のようなパススコープ付きルールの仕組みもあり、記事執筆時にしか使わない詳細ルールをさらに切り出せる余地がある。 CLAUDE.mdの行数を毎回目視で確認しているが、行数が閾値に近づいたら知らせてくれるような仕組み化はできていない。
