技術
約3分で読めます
このサイトのCLAUDE.mdを半分以下に削減した方法
当ブログのCLAUDE.mdが273行まで膨らんでいた。テンプレートコードやマニュアル的な記述が増え、トークン効率が悪化していたので整理した。
問題点
- テンプレートコードの埋め込み: ページテンプレート（約80行）、HTMLスニペット等がそのまま記載されていた
- ガードレールとマニュアルの混在: 「Claudeが誤りやすい箇所」と「参考情報」が区別なく並んでいた
- トークン効率が悪い: 毎セッション、不要な詳細コードがコンテキストに読み込まれる
整理方針
前回の記事で書いた「ガードレール優先」の原則を自分のリポジトリに適用した。
- CLAUDE.mdには「Claudeが間違えやすい箇所」を中心に記載
- 詳細テンプレートは別ファイルに分離し、ポインタで参照
実施内容
1. テンプレートの分離
| 分離対象 | 対応 | 削減行数 |
|---|---|---|
| ページテンプレート（80行） | 既存ファイル参照に変更 | -80行 |
| HTMLスニペット（15行） | .claude/templates/ に分離 | -15行 |
| 埋め込みコード例（8行） | 自動処理なので説明不要、削除 | -8行 |
Before: テンプレートコードがそのまま埋め込まれていた
### ページテンプレート
`src/pages/example.astro` に作成:
---
import Layout from '@/layouts/Layout.astro';
// ... 80行のテンプレートコード
---After: 既存ファイルへのポインタに変更
### ページテンプレート
既存ファイルを参照: `src/pages/example.astro`2. ガードレールセクションの新設
Claudeが誤りやすい箇所を明確に分離した。
## Guardrails (Claudeが誤りやすい箇所)
### Styling: 動的生成コンテンツのCSS
フレームワークのスコープドCSSはJavaScriptで動的生成したDOM要素には適用されない。
→ グローバルCSSまたは外部CSSを使用すること。
### Markdown: 太字と日本語括弧
`**太字**` を日本語括弧と組み合わせると壊れることがある。
→ 日本語の「」で代用する。これにより「何を避けるべきか」「代わりに何をすべきか」が明確になった。
結果
| 項目 | Before | After |
|---|---|---|
| CLAUDE.md | 273行 | 121行 |
| 削減率 | - | 56%削減 |
学び
- テンプレートコードは「既存ファイル参照」で十分。Claudeは必要なときにファイルを読みに行ける
- ガードレール（誤りやすい箇所）とマニュアル（参考情報）を分離すると、重要な注意点が埋もれない
- 「避けるべきX」だけでなく「推奨はY」を併記すると、Claudeが正しい行動を取りやすい
今後の検証予定
整理はしたが、まだ実際にテンプレートを使うタスクで試していない（ブログなんでテンプレ用意させて手で打つとかの処理をしてる方が多いので）。次回、記事テンプレートや分離したスニペットを使う場面で以下を確認する予定：
- 分離したファイルが正しく参照されるか
- トークン消費が実際に減っているか
- コンテキスト圧縮が意図せず発生していないか
コンテキスト確認コマンド
Claude Code 1.0.86以降では /context コマンドでコンテキスト使用状況を詳細に確認できる：
- System prompt / System tools のトークン数
- MCP tools / Custom agents の消費量
- Memory files（CLAUDE.md等）の占有量
- Messages（会話履歴）の蓄積量
- Free space（残り容量）
CLAUDE.mdを削減した効果は、このコマンドの「Memory files」項目で確認できるはず。