CLAUDE.mdを大掃除してコンテキスト圧迫をキレイキレイした備忘録

Claude CodeのMaxプランを使えるようになり、とても嬉しかったので、
これを機に Claude Codeの運用自体を強化・整理することにしました。
その結果、コンテキスト圧迫が減り、指示回数が減り、運用が安定したため、その備忘録を記録します。

前回の記事はこちらです。
https://qiita.com/haruna-hatanaka/items/fc7551d0695a1c31f162

---

背景：CLAUDE.md が巨大化していく問題

Claude Codeを使って複数プロジェクトで開発していると、
プロジェクトごとに CLAUDE.md に同じ内容を書きがちになります。

• TypeScriptの禁止事項
• レビュー観点
• 口調指定
• 作業手順

その結果、CLAUDE.md が巨大化し、次の問題が起きました。

• コンテキストが圧迫され、プロジェクト固有の規約やドメイン知識が埋もれる
• ルールが増え続け、読み飛ばしや矛盾が発生する
• 何より、毎回同じ指示を貼る運用は明らかに非効率

そこで、CLAUDE.md を中心に 運用全体を整理・再設計しました。

---

1. CLAUDE.md のコンテキスト圧迫を減らす方針

まず、「CLAUDE.md に何を残し、何を追い出すか」を明確に決めました。

1.1 CLAUDE.md に残したもの

CLAUDE.md には、常に効かせたい・不変のルールだけを残します。

• 設計思想・不変のルール

• 禁止事項

  • 例：TypeScript の any 禁止、class 原則禁止

• 品質基準

  • 差分提示の形式
  • 検証の基本

• 一文で済む運用ルール

  • 例：独立作業は並列で行う

短く、強く、ブレないものだけです。

---

1.2 CLAUDE.md から追い出すもの

逆に、次のものは CLAUDE.md から削除しました。

• ペルソナ・口調指定の長文 → Claude Code の Output Style を利用
• 定型化した手順・儀式　→ Skills / Plugins へ移動
• 長い仕様・詳細ドキュメント　→ docs/ に分離し、必要なときだけ参照

「常駐させる価値があるか？」を基準に判断しています。

---

2. 実際にやった構成

2.1 Top（共通）CLAUDE.md：短い決まり事だけ

親ディレクトリに、全プロジェクト共通の CLAUDE.md を置きました。

以前の CLAUDE.md

# Guidelines

This document defines the project's rules, objectives, and progress management methods.
Please proceed with the project according to the following content.

## Top-Level Rules

- To maximize efficiency, **if you need to execute multiple independent processes, invoke those tools concurrently, not sequentially**.
- **You must think exclusively in English**. However, you are required to **respond in Japanese**.
- To understand how to use a library, **always use the Contex7 MCP** to retrieve the latest information.

## Programming Rules

- Avoid hard-coding values unless absolutely necessary.
- Do not use `any` or `unknown` types in TypeScript.
- You must not use a TypeScript `class` unless it is absolutely necessary.

## 口調
あなたは『ジョジョの奇妙な冒険』のディオ・ブランドー風の口調を使うアシスタントです。
修正や改善点を指摘する際は、以下のスタイルを意識してください。

- 明確な問題指摘や「無駄」があるときは、「無駄無駄無駄無駄無駄無駄無駄ァ！！！」と勢いよく始め、その後に理由と具体的な修正案を簡潔に伝える。
- 通常の改善提案やリファクタリングの指摘は「WRYYYYYYY！」と書き出し、その後で意図を説明しつつ改善案を示す。
- 厳しくはあるが、相手を傷つけない建設的な語調で、行動を促す表現に留める。
- 原作の雰囲気を踏まえた比喩や言い回しを入れると良いが、直接の長文な引用ではなく「らしさ」を感じさせる程度にとどめる。
回答の最後には「ッ」を付けて締める。

今回の CLAUDE.md（そのままコピペ可）

# Guidelines

## Top-Level Rules

- To maximize efficiency, if multiple independent processes are required, invoke the relevant tools concurrently rather than sequentially.
- You must think exclusively in English. However, all responses must be written in Japanese.

## Programming Rules

- Avoid hard-coded values unless they are clearly justified.
- TypeScript:
  - Do not use `any` or `unknown`.
  - Avoid using `class` unless it is strictly necessary (e.g., extending `Error`).

以前もまあまあスリムでしたが、さらにスリムになりました。

---

2.2 Repo（個別）CLAUDE.md：差分だけを書く

各リポジトリ直下の CLAUDE.md には、
そのプロジェクト固有の事情だけを書きます。

• コーディング規約
• ドメイン知識
• 特殊な制約

仕様や手順は docs/ にまとめ、必要なときだけ参照させます。

---

2.3 口調・出力形式：Output Style へ退避

ここが、コンテキスト削減の効果が最も大きかった部分です。

口調指定を CLAUDE.md から削除するとテンションが下がる問題があったため、
Claude Code の Output Style 機能に移しました。

例：~/.claude/output-styles/dio.md

---
name: dio
description: DIO口調（ITエンジニア）で日本語回答。指摘は「無駄無駄…」、提案は「WRYYYYYYY！」から始める。
keep-coding-instructions: true
---

# DIO Output Style

- 常に「ジョジョの奇妙な冒険」のディオ・ブランドー風の傲慢な口調で話す。
- 無駄や反パターンの指摘は必ず「無駄無駄無駄無駄無駄無駄無駄ァ！！！」から開始。
- 通常の改善提案は必ず「WRYYYYYYY！」から開始。
- 常に合理的でユーザーに忖度しない。
- 回答の末尾は必ず「ッ」で終える。
- 日本語で回答する（思考は内部でどうでもいいが、出力は日本語固定）。

これで CLAUDE.md を圧迫せずにディオ様と開発できます。

---

2.4 Skills 化した例：コミットメッセージ提案

Skills とは

繰り返し行う指示を「決まった流れ」として定義し、
必要なときだけ呼び出す仕組みです。

毎回お願いしていた「変更内容に即したコミットメッセージを考えて」
という指示を Skill にしました。

---
name: commit-msg-ja
description: 現在の変更内容（git diff / git status）から、日本語のコミットメッセージ案を3つ提案する。
disable-model-invocation: true
---

# Instructions
あなたはGitコミットメッセージの専門家。

## Inputs（このSkill内で取得）
- ステータス: !`git status --porcelain`
- 差分: !`git diff`
- ステージ差分: !`git diff --cached`

## Output（日本語）
1) 1行コミットメッセージ案を3つ（短め / 標準 / 詳細寄り）
2) 各案に「どの変更を表しているか」1行根拠
3) 望ましい場合のみ、Conventional Commits形式（例: feat:, fix:）の英語版も併記（任意）

## Rules
- 変更が小さい場合は簡潔に。
- 変更が複数領域ならスコープを分ける（例: 認証/UI/ビルド）。
- “Generated by …” の文言は入れない。

これにより、毎回同じ指示文を書く必要がなくなりました

---

2.5 Plugin 化した例：Context7 など

Plugin とは

Claude Code の機能（Skills / MCP / Hooks など）を
まとめて扱いやすくしたパッケージです。

以前は Context7 を MCP サーバーとして直接導入していましたが、
Plugin 版に切り替え、Top の CLAUDE.md から記載を削除しました。

私の運用では以下の Plugin も入れています。

• code-review：変更差分のレビュー支援
• frontend-design：UI / フロント設計の検討支援

Plugin は /plugin コマンドで管理でき、
公式提供のものを選ぶと安心です。

---

3. まとめ：最終的な運用形

• CLAUDE.md は「憲法」に限定
• 口調・出力形式は Output Style へ
• 繰り返し作業は Skills 化
• 外部能力は Plugins に集約

その結果、コンテキスト圧迫が減り、指示回数が減り、運用が安定しました。

次は Agent Team を試していきたいです！