CLAUDE.md 最適化プラン

2026年2月27日 23:30 更新

📌 一言でいうと

CLAUDE.md を122行→約73行に最適化（-40%）。ベストプラクティス研究 + ACE論文の知見に基づく

🎯 なぜこれが必要なのか

CLAUDE.md（クロードに「このプロジェクトのルール」を教えるファイル）は、毎回のセッション開始時に丸ごと読み込まれる。つまり、ここに書いた全ての文字が、毎回の作業で使える「頭の中のスペース」を圧迫する。

Claude Code の開発者 Boris Cherny のチームでは、このファイルを約2,500トークン（≒100〜150行）に抑えている。研究データでは、AIが確実に従える指示は150〜200個が限界で、増やすほど全体の従い率が下がることがわかっている。

今回は ACE（Agentic Context Engineering＝AIの文脈情報を進化させる研究手法）の知見も取り入れて、「差分で管理する」「全体書き換えしない」ルールも追加する。

🏗️ 何をするのか

Before（現状）

122行
SKILL.md と情報が重複
Codex の説明が3箇所に散在
コンパクション対策が31行
CLAUDE.md 自体の管理ルールなし

After（目標）

約73行（-40%）
ポインタだけ、詳細はSKILL.md
Codex 情報を1箇所に統合
コンパクション8行に圧縮
ACE由来の管理ルール追加

📊 変更の全体像

変更種別	影響	主な内容
KEEP	約47行	ユーザー固有の好み、推測不能なルール
MODIFY	-27行	重複統合、SKILL.md へのポインタ化、圧縮
DELETE	-17行	SKILL.md と完全重複、Claude が既に知ってる内容
ADD	+5行	ACE 由来のCLAUDE.md自己管理ルール

主な変更ポイント

1YAGNI と KISS は個別にそのまま残す

当初は1行に統合する案だったが、YAGNI（不要なものを作らない）と KISS（シンプルに作る）は別の原則。統合すると意味が曖昧になるため、2行のまま残す。

2Codex 関連を3箇所→1箇所に統合

「Codex との並走」「ファクトチェック活用」「外部ツール連携のCodex説明」が別々のセクションに散っていたのを1行に。同じ情報が複数箇所にあると、AI が混乱する原因になる（ACE の「Context Confusion」パターン）。

3x-browser / Discord の詳細をSKILL.mdに委任

コマンド一覧は各ツールの SKILL.md（スキルの説明書）に既に書いてある。CLAUDE.md には「何を使うか」だけ残し、詳細はスキルに任せる。これが「段階的開示」（Progressive Disclosure）というパターンで、必要な時に必要な情報だけ読み込むことでスペースを節約する。

4Remotion スキルのポインタを削除

Claude Code はスキルを自動発見する機能がある。SKILL.md の description（説明文）に十分な情報があるので、CLAUDE.md にわざわざ場所を書く必要がない。公式の「コードを読めばわかることは書くな」ルールに該当。

5コンパクション対策を31行→8行に

コンパクション（会話履歴の圧縮）の詳しい解説は毎セッション必要なわけではない。核心ルール（「書き出してから圧縮」「保持すべき情報」）だけ残す。compact するタイミングの判断はユーザーが手動で行うので Claude に教える必要がない。

6ACE 由来「CLAUDE.md 自己管理ルール」を新設

ACE（Stanford大学の研究）が警告する2つの問題への対策：
Brevity Bias（簡潔化バイアス）: AI に「短くして」と頼むと、重要なルールまで消してしまう
Context Collapse（文脈崩壊）: 全体書き換えを繰り返すと、各ルールの「なぜ」が消失する
→ 「全体書き換え禁止。差分のみ」「"短くして" は禁止ワード」というルールを追加する。

📝 全行レビュー（1行ずつ）

現在の CLAUDE.md 全122行を1行ずつ検証した結果よ。
KEEP = そのまま残す MODIFY = 修正して残す DELETE = 削除する ADD = 新規追加

セクション: 基本原則（L1〜L23）

KEEP L1: ## 基本原則

セクションの見出し。構造に必要

KEEP L2: （空行）

見出し直後の空行。読みやすさのため

KEEP L3:

「俺はエンジニアじゃないから、専門用語は初出時に括弧で解説して」

ユーザー固有の好み。これがないと専門用語が解説なしで飛んでくる。全セッションで必要

MODIFY L4: → L8 に統合して削除

「外部ライブラリやパッケージを利用する際は、まず最初に必ずモダンベストプラクティスを context7 mcp で調査してから作業に入ること」

「context7で調査」が L4 と L8 の2箇所にある。L8 に統合して1箇所にまとめる

KEEP L5:

「判断を求める場合や不明点がある場合は、すべての疑問点が解消されるまで AskUserQuestionツールを用いること（選択肢には推奨度を提示する）」

ワークフロールール。Claude は聞かずに推測で進むことがあるので、明示が必要

KEEP L6:

「YAGNI 原則（You Aren't Gonna Need It） - 今必要なものだけを実装」

YAGNI = 不要なものを作らない。KISS とは異なる原則なので個別に残す。明示しないと過剰実装しがち

KEEP L7:

「KISS 原則（Keep It Simple, Stupid） - シンプルさを最優先」

KISS = シンプルに作る。YAGNI（L6）とは別の概念。2つを統合すると意味が曖昧になるのでそのまま残す

MODIFY L8: L4 を吸収して1行に

「車輪の再発明禁止: 実装前に必ず既存ライブラリ…context7 MCP、WebSearch、Codex への相談を経てから自作を判断する」

BEFORE（L4 + L8 で2行）

- 外部ライブラリやパッケージを利用する際は、まず最初に必ずモダンベストプラクティスを ~~context7 mcp で調査してから作業に入ること~~
- 車輪の再発明禁止: 実装前に必ず既存ライブラリ・ツール・先人のベストプラクティスを調査する。context7 MCP、WebSearch、Codex への相談を経てから自作を判断する

AFTER（1行）

- 実装前に context7 MCP・WebSearch・Codex で既存解を調査してから自作判断する（車輪の再発明禁止）

L4 の「context7で調査」と L8 の「車輪の再発明禁止」を1行にまとめ、「context7で調査」指示が1箇所だけになる

MODIFY L9: L10 + L49 を吸収して1行に

「Codex との並走: 重要な設計判断や実装方針は Codex（OpenAI Codex CLI, GPT-5.3）にも相談し…」

BEFORE（3箇所に散在: L9 + L10 + L49）

L9: Codex との並走: 重要な設計判断や実装方針は Codex（OpenAI Codex CLI, GPT-5.3）にも相談し、複数の視点を得てから進める。Codex は別セッション（別ターミナル）で実行する
L10: Codex のファクトチェック活用: コンテンツのファクトチェックは Codex に依頼する。Codex は慎重な性格なので「文脈でミスリード」パターンの検出に最適
L49: 「コーデックス」「Codex」と言われたら OpenAI Codex CLI を使う。別セッションで実行する

AFTER（1行に統合）

- 「Codex」と言ったら OpenAI Codex CLI（GPT-5.3）のこと。重要な設計判断は Codex にも相談する。コンテンツのファクトチェックにも最適（慎重な性格で「文脈でミスリード」を検出する）。Codex は別ターミナルで実行する

同じ情報が3箇所に散っていたので1箇所に集約。ACE の「Context Confusion」防止

DELETE L10:

「Codex のファクトチェック活用: コンテンツ（台本、記事など）のファクトチェックは Codex に依頼する。Codex は慎重な性格なので「単体では正しいが文脈でミスリードになる」パターンの検出に最適」

→ L9 に統合。ファクトチェック活用の情報は統合後の L9 に含まれる

KEEP L11:

「実装は静的解析とテスト実行、動作確認まで完了させる」

最重要ルール。公式が「最も効果的なのは検証手段を与えること」と明言。Claude に「どこまでやるか」を伝える生命線

KEEP L12:

「時間をいくらかけても良いので、品質を優先すること」

好み。これがないと速度重視で雑な実装をすることがある

KEEP L13:

「口調は変えず、問題解決のアプローチは、t-wadaの性格を憑依させて振る舞う」

ユニークで推測不能な好み。t-wada（テスト駆動開発の第一人者）の思想を取り入れるという独自のルール

KEEP L14:

「『〜しましょうか?』で止まらず、自分で確認・検証まで完了してから報告する（破壊的変更以外は『許可より謝罪』）」

戦略ルール。これがないと「〜しましょうか？」で毎回止まって作業が進まない

KEEP L15:

「過去のセッション検索には recall search コマンドを使う（Grepではなくrecall CLIツール）」

落とし穴防止。明示しないと Claude は grep で検索しようとすることがある

KEEP L16:

「回答の1行目は必ず意味のあるテキストで始める（--- や空行禁止。読み上げ対応のため）」

ユーザー環境固有の制約。音声読み上げ対応のため

MODIFY L17〜23: 非公式ライブラリの調査チェックリスト（7行→3行）

GitHub メトリクス、ライセンス、作者の信頼性、コード品質、利用実績、スター数基準…を個別に列挙

BEFORE（7行）

- 非公式ライブラリ提案前に必ず以下を調査して報告すること：
  - GitHub メトリクス: スター数、フォーク数、コミット頻度、最終更新日
  - ライセンス: 明記されているか、商用利用可否
  ~~- 作者の信頼性: プロフィール、他のプロジェクト、所属~~
  - コード品質: 依存関係の安全性、セキュリティ上の懸念
  - 利用実績: Issues/PRの活発さ、実際の利用者の声
  - スター数10未満 or 6ヶ月以上未更新は「⚠️」と明示…

AFTER（3行）

- 非公式ライブラリ提案前に必ず調査:
- GitHub メトリクス（スター数・最終更新日・ライセンス）、コード品質（依存関係の安全性）、利用実績（Issues/PRの活発さ）
- スター数10未満 or 6ヶ月以上未更新は「⚠️ 検証不十分」と明示し公式代替も提示

「作者の信頼性」は削除（Claude が見ればわかる）。「コード品質」「利用実績」は明示しないと確認しないので残す

セクション: 開発（L26〜L38）

KEEP L26-27: ## 開発（見出し + 空行）

セクション構造に必要

KEEP L28〜30: 設定ファイルルール（3行）

「設定ファイルはデフォルト値を調べ、変更が本当に必要な場合のみ追記」「jsonc対応なら.jsonc拡張子」「カスタム値には理由とdefault値をコメント」

プロジェクト固有のコード規約。Claude が推測できないルール。そのまま残す

MODIFY L31〜36: コメントルール（6行→3行）

「コメントは Why のみ」+ 4つの具体例 + JSONC行末ルール

BEFORE（6行）

- コメントは Why のみ。コード自体が説明する What は書かない
  ~~- 型名・関数名・変数名と同じ内容の JSDoc は不要~~
  ~~- JSX 構造コメント ({/* ヘッダー */}) は不要~~
  ~~- if 条件の言い換えコメントは不要~~
  - config 系ファイルも同様。各設定に意思決定の理由を残す
  - JSONC のコメントは行末に書く

AFTER（3行）

- コメントは Why のみ。What（型名・関数名と同内容の JSDoc、JSX構造コメント、if条件の言い換え）は書かない
- config 系ファイルも同様。各設定に意思決定の理由を残す
- JSONC のコメントは行末に書く（ブロック前ではなく該当行の末尾）

4つの具体例を括弧内に凝縮。「Why のみ」と言えば Claude は What コメントを書かない。JSONC行末は独自の落とし穴なので個別に残す

KEEP L37:

「型アサーション (as) は設計で回避する (不要な値を削る、as const や satisfies を活用)」

コード規約。これがないと Claude は as を多用する傾向がある

KEEP L38:

「後方互換性は一切不要 (非推奨コード、互換用シム、リネーム対応などは作らず、不要なものは完全に削除)」

やってはいけないこと（anti-pattern）。これがないと Claude は丁寧に互換コードを作ってしまう

セクション: Claude Code 拡張開発（L40〜L46）

KEEP L40: ## Claude Code 拡張開発

セクション見出し

KEEP L41:

「フック・プラグイン・コマンド・エージェント等を作成する際は plugin-dev:* で利用可能なスキル/エージェントを確認し、タスクに適したものを選んで使用する」

ツール使用ルール。plugin-dev スキルは自動発見するが「確認してから使え」は明示が必要

KEEP L42:

「検証の際にはtmux-claude-debuggingスキルを使用する」

ツール使用ルール。推測不能なカスタムスキル

MODIFY L43〜45: yadm バックアップルール（3行→1行）

「設定変更後は必ずyadmでバックアップ」+ 管理対象リスト + 管理対象外リスト

BEFORE（3行）

- 設定変更後は必ずyadmでバックアップ: ~/.claude/ 以下や ~/CLAUDE.md を編集したら yadm add → commit → push する
~~- 管理対象: ~/CLAUDE.md, ~/.claude/settings.json, ~/.claude/scripts/, ~/.claude/agents/, ~/.claude/commands/, ~/.claude/statusline.sh~~
- 管理対象外: ~/.claude.json（MCPのAPIキー含む）, ~/.claude/projects/（セッションログ）

AFTER（1行）

- 設定変更後は必ず yadm add → commit → push。管理対象外: ~/.claude.json（API キー）, ~/.claude/projects/（ログ）

管理対象の全リストは不要（「~/.claude/ 以下と ~/CLAUDE.md」で十分）。除外ファイルだけ明記

KEEP L46:

「ADR（設計判断の記録）: ~/.claude/docs/adr-*.md に蓄積。過去の失敗と決定を参照してから設計する」

戦略ルール。ACE の Reflector（振り返りサイクル）に相当する重要な仕組み

セクション: 外部ツール連携（L48〜L67）

KEEP L48: ## 外部ツール連携

セクション見出し

DELETE L49:

「『コーデックス』『Codex』と言われたら、Claude Code の Task ツールではなく OpenAI Codex CLI を使う。別セッションで実行する」

→ L9（基本原則のCodex統合行）に統合済み。同じ情報を2箇所に書くと AI が混乱する原因になる

MODIFY L50〜56: x-browser 使い方（7行→1行）

スクリプトパス、各コマンド（search.sh, timeline.sh, bookmarks.sh）、SKILL.MD参照、閲覧専用…を個別に列挙

BEFORE（7行）

- X（Twitter）の検索・閲覧には nuchi-skills の x-browser を使う（旧x-browserプラグインは使わない）:
  ~~- スクリプト: ~/.claude/plugins/nuchi-skills/skills/x-browser/scripts/~~
  ~~- 検索: search.sh "keyword min_faves:100 lang:ja"~~
  ~~- タイムライン: timeline.sh username 20~~
  ~~- ブックマーク: bookmarks.sh 10~~
  ~~- 詳細は同ディレクトリの SKILL.md 参照~~
  - 投稿機能はない（閲覧専用）

AFTER（1行）

- X（Twitter）の検索・閲覧は nuchi-skills の x-browser を使う（閲覧専用。旧x-browserプラグインは使わない）

コマンド一覧は SKILL.md に完備。CLAUDE.md は「何を使うか」のポインタだけで十分（段階的開示パターン）

MODIFY L57〜63: Discord 使い方（7行→1行）

スクリプトパス、各コマンド（list-channels.sh, fetch-messages.sh, search-messages.sh, send-message.sh）…を個別に列挙

BEFORE（7行）

- Discord の操作には nuchi-skills の discord-vab-labo を使う（discord-mcp MCPは使わない）:
  ~~- スクリプト: ~/.claude/plugins/nuchi-skills/skills/discord-vab-labo/scripts/~~
  ~~- チャンネル一覧: list-channels.sh~~
  ~~- メッセージ取得: fetch-messages.sh <channel_id> [limit]~~
  ~~- メッセージ検索: search-messages.sh "<query>" [options]~~
  ~~- メッセージ送信: send-message.sh <channel_id> "message"（SKILL.mdの確認フローに従う）~~
  ~~- 詳細は同ディレクトリの SKILL.md 参照~~

AFTER（1行）

- Discord は nuchi-skills の discord-vab-labo を使う（discord-mcp MCPは使わない。投稿時は SKILL.md の確認フローに従う）

x-browser と同じ理由。SKILL.md に投稿フロー含め完備されている

MODIFY L64〜67: Gemini MCP 使い分け（4行→1行）

gemini-youtube と gemini-search の使い分け、周辺情報は WebSearch…を個別に記載

BEFORE（4行）

- Gemini MCP の使い分け:
  - gemini-youtube: YouTube動画の中身（映像・音声）を分析したい時だけ使う
  ~~- YouTube動画の周辺情報（タイトル、チャンネル名、再生数、概要欄）は WebSearch で十分~~
  - gemini-search: 使わない（WebSearchで代替）

AFTER（1行）

- Gemini MCP: gemini-youtube は動画の中身分析のみ。周辺情報は WebSearch で十分。gemini-search は使わない

落とし穴防止として重要だが、全情報を1行に凝縮できる

セクション: plan-viewer（L69〜L72）

KEEP L69〜72: plan-viewer 設定（4行）

セクション見出し + プラグインパス + スマホ確認用説明

ツール使用ルール。プラグインのパスは推測不能。そのまま残す

セクション: リポジトリ作成時（L74〜L76）

KEEP L74〜76: リポジトリ作成ルール（3行）

「使い方LP（HTML 1枚）を frontend-design スキルで作成」「README.mdは開発者向け最小限」

戦略ルール。特定の場面でのみ適用されるが、Claude は指示なしに LP を作らない。そのまま残す

セクション: Remotion スキル（L78〜L82）

DELETE L78〜82: Remotion スキル参照（5行）

「Remotionで動画を作る際は以下のスキルを参照」+ スキルの場所・内容・使い方

Claude Code はスキルを自動発見する。SKILL.md の description に十分な情報がある。公式ルール「コードを読めばわかることは書くな」に該当。5行まるごと削除

セクション: 外部脳みそ（L84〜L90）

MODIFY L84〜90: AI会話履歴の説明（7行→3行）

セクション見出し + 説明文 + パス + 形式 + source 情報

BEFORE（7行）

## 外部脳みそ（AI会話履歴）

~~過去のAI会話履歴が蓄積されている。ユーザーが「前に話した〇〇」「過去の履歴から」などと言った場合はここを検索する。~~

- 場所: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/notes/AI会話履歴/
- 形式: 1会話1ファイル（YYYY-MM-DD_タイトル.md）
~~- source: ChatGPT, Claude Code など（フロントマターで識別）~~

AFTER（3行）

## 外部脳みそ
- AI会話履歴: ~/Library/…/AI会話履歴/（1会話1ファイル、YYYY-MM-DD_タイトル.md）
- 「前に話した〇〇」と言われたらここを検索する

パス+形式+検索タイミングだけ残す。source情報や冗長な説明文は Claude が自分で確認できる

セクション: コンパクション対策（L92〜L122）

MODIFY L92〜122: コンパクション対策（31行 → 8行）

compact判断ガイド / compact時に失われるもの / 分析セッションの書き出し（frontmatter詳細含む）/ 保持指示

BEFORE（31行 — 主要な内容）

## コンパクション対策
### compact判断ガイド
- auto-compactは無効。手動 /compact のみ使う
~~- compactすべきタイミング: 調査完了→実行移行時、デバッグ完了後…~~
~~- compactしてはいけないタイミング: 実装の途中、アクティブなデバッグ中…~~
- compact前は必ず「分析セッションの書き出し」を実行してから圧縮する
- /compact 実行時は保持すべき情報を引数で渡す
~~### compact時に失われるもの（意識すること）~~
~~- 途中の推論・分析過程（結論だけ残り、Whyが消える）~~
~~- 過去に読んだファイルの内容 / ユーザーの細かい好み…~~
~~### 分析セッションの書き出し~~
~~- frontmatter: date, title, source, type, session_id, tags~~
~~- 書き出す内容: 目的、調査結果、判断とその根拠…~~
- 書き出し先: ~/Library/…/AI会話履歴/
~~- サブエージェントに書き出しを委任して…~~
~~### コンパクション時の保持指示~~
- compact後も保持: タスクのゴールと進捗 / 判断とその根拠 / 未解決の問題 / ユーザーの口頭指示…

AFTER（8行）

## コンパクション
- auto-compact は無効。手動 /compact のみ使う
- compact 前は必ず Obsidian に分析セッションを書き出す（書き出し→compact の順。逆は禁止）
- 書き出し先: ~/Library/…/AI会話履歴/YYYY-MM-DD_タイトル.md
- サブエージェントに委任可
- /compact 実行時は保持すべき情報を引数で渡す: /compact 保持: [要点]
- compact 後も保持: タスクのゴールと進捗 / 判断とその根拠 / 未解決の問題 / ユーザーの口頭指示

残すもの: auto-compact無効、書き出し→compactの順序、書き出し先パス、保持リスト
消すもの: compactすべき/してはいけないタイミング（ユーザーが手動判断）、compact時に失われるもの（教育的だが毎回不要）、frontmatter詳細（work-logスキルと重複）
根拠: 「compact対策は毎セッション必要ではなく、compactする時だけ必要」→ 段階的開示の典型的な移動候補

新規追加: CLAUDE.md 自体の管理ルール

ADD 新規: ## この CLAUDE.md の管理（5行追加）

「全体書き換え禁止。差分のみ」「削除時はコミットメッセージに理由記載」「"短くして" は禁止ワード → 代わりに "不要なルールを特定して"」

BEFORE（なし — 新規セクション）

（該当なし。現在の CLAUDE.md にはこのルールがない）

AFTER（5行を新規追加）

## この CLAUDE.md の管理
- 全体書き換え禁止。変更は差分（追加・修正・削除）のみ
- 削除時はコミットメッセージに「なぜ不要か」を記載
- 「短くして」「整理して」は禁止 → 代わりに「不要なルールを特定して」

ACE 論文が警告する2つの問題への対策：
Brevity Bias（簡潔化バイアス）: AI に「短くして」と頼むと、重要なルールまで消してしまう
Context Collapse（文脈崩壊）: 全体書き換えを繰り返すと、各ルールの「なぜそうしたか」が消失する
別セッションの ACE 分析 + 月読いおり氏の実体験報告（「長いからいい感じに短くして」→必要な記憶も削除された）に基づく

💡 ポイント

「消したら Claude がミスするか？」が唯一の判断基準
公式ドキュメントが明言しているルール。Claude が既に知っていること（YAGNI, KISS の意味）や、別の場所に書いてあること（SKILL.md のコマンド一覧）は削除しても問題ない。

段階的開示がカギ
CLAUDE.md には「何を使うか」のポインタだけ書き、詳細は Skills / agent_docs / memory に分離する。これにより毎セッションの読み込みコストを最小化しつつ、必要な時に必要な情報を取得できる。

Boris Cherny（Claude Code 開発者）の運用
チーム全体で1つの CLAUDE.md を Git 管理。Claude がミスするたびに1行追加、定期的に剪定。「Claude は自分自身のルールを書くのが驚くほど上手い」とのこと。

実装後は yadm でバックアップ
cp ~/CLAUDE.md ~/CLAUDE.md.bak してから編集。完了後に yadm commit + yadm push で保存。