improve-claude-md

ユーザーが CLAUDE.md ファイルを提示した場合（または改善を依頼した場合）は、以下の原則と構成に従って書き直してください。

根本的な問題

Claude Code は、CLAUDE.md ごとに次のシステムリマインダーを挿入します。

「このコンテキストはタスクに関連する場合もしない場合もあります。タスクに非常に関連する場合を除き、このコンテキストに応答しないでください。」

そのため、Claude は無関係だと判断した CLAUDE.md の内容を無視します。現在のタスクに当てはまらない内容が増えるほど、重要な内容も含めてすべてを無視する可能性が高くなります。

解決策：<important if="condition"> ブロック

CLAUDE.md のうち、条件によって関連性が変わるセクションを <important if="condition"> XML タグで囲みます。これは Claude Code のシステムプロンプト自体で使われているのと同じ XML タグのパターンを活用し、「関連する場合もしない場合もある」という枠組みを超えて、モデルに明確な関連性のシグナルを与えます。

原則

1. 基本的なコンテキストはそのままにし、ドメイン固有のガイダンスはタグで囲む

すべてを <important if> ブロックに入れる必要はありません。プロジェクトの概要、プロジェクトの構成、技術スタックなど、ほぼすべてのタスクに関連するコンテキストは、ファイルの冒頭に通常の Markdown として記載します。これはエージェントが常に必要とする導入時のコンテキストです。

テストのパターン、API の規約、状態管理、i18n など、特定のタスクでのみ必要となるドメイン固有のガイダンスは、対象を絞った条件を付けて <important if> ブロックで囲みます。

判断の目安：タスクの 90％以上に関連する内容はそのまま記載します。特定の種類の作業に関連する内容はタグで囲みます。

2. 条件は具体的で、対象を絞ったものにする

悪い例 — あらゆるものに当てはまる広すぎる条件：

<important if="you are writing or modifying any code">
- Use absolute imports
- Use functional components
- Use camelCase filenames
</important>

良い例 — 各ルールに、それぞれ対象を絞ったトリガーを設定する：

<important if="you are adding or modifying imports">
- Use `@/` absolute imports (see tsconfig.json for path aliases)
- Avoid default exports except in route files
</important>

<important if="you are creating new components">
- Use functional components with explicit prop interfaces
</important>

<important if="you are creating new files or directories">
- Use camelCase for file and directory names
</important>

3. 簡潔に保ち、段階的な情報開示は控えめにする

エージェントが情報を見つけるためにツールを呼び出す必要がある別ファイルへ分割しないでください。非常に長大または複雑なコンテキストを扱う場合は例外です。

<important if> ブロックの目的は、すべての内容をインラインに置きつつ、条件に応じて重み付けすることです。エージェントは全体を確認し、条件に合致する内容にだけ注目します。

ファイルは簡潔に保つことを優先してください。

4. 少ないほどよい

• 最先端のモデルは、数百件程度の指示であれば確実に従えます。Claude Code のシステムプロンプトとツールだけですでに約 50 件を使用しています。CLAUDE.md はできる限り簡潔にしてください。
• リンター、フォーマッター、またはプレコミットフックで強制できる指示は削除します。
• 既存のコードパターンからエージェントが把握できる指示は削除します。LLM はコンテキスト内で学習するため、コードベース全体で一貫して使われているパターンがあれば、数回検索するだけでそれに従うようになります。
• コードスニペットは削除します。古くなりやすく、ファイルを肥大化させるためです。代わりにファイルパスを参照します（例：「パターンについては src/utils/example.ts を参照してください」）。

5. コマンドはすべて残す

元のファイルにあるコマンドを削除しないでください。コマンドの一覧は基本的な参照情報です。一部のコマンドを使う頻度が低くても、エージェントが利用可能なコマンドを把握できるようにする必要があります。

出力構成

CLAUDE.md を書き直す場合は、次の構成で作成します。

# CLAUDE.md

[one-line project identity — what it is, what it's built with]

## Project map
[directory listing with brief descriptions]

<important if="you need to run commands to build, test, lint, or generate code">
[commands table — all commands from the original]
</important>

<important if="<specific trigger for rule 1>">
[rule 1]
</important>

<important if="<specific trigger for rule 2>">
[rule 2]
</important>

... more rules, each with their own block ...

<important if="<specific trigger for domain area 1>">

[guidance]

</important>

... more domain sections ...

適用方法

既存の CLAUDE.md を改善する場合：

1. プロジェクトの概要を特定する — これが何であるかを説明する1文を抜き出します。先頭にそのまま記載します。
2. ディレクトリマップを抜き出す — そのまま記載します（<important if> で囲みません）。これは基礎となるコンテキストです。
3. 技術スタックを抜き出す — 記載があれば、そのまま先頭付近に記載します。1〜2行にまとめます。
4. コマンドを抜き出す — 元のファイルにあるコマンドをすべて残します。1つの <important if> ブロックで囲みます。
5. ルールを分割する — ルールのリストは、それぞれ個別の条件を指定した <important if> ブロックに分割します。ルールをまとめてもかまいませんが、関連のないルールを1つの大まかな条件の下にまとめてはいけません。
6. ドメイン別のセクションを囲む — テスト、API パターン、状態管理、i18n などはそれぞれ個別のブロックにし、その知識が必要となる状況を条件として記載します。
7. リンターの対象範囲を削除する — スタイルガイドライン、フォーマットルール、ツールで強制できる内容を削除します。pre-push または pre-commit フックへの置き換えを提案します。
8. コードスニペットを削除する — ファイルパスへの参照に置き換えます。
9. 曖昧な指示を削除する — 「X エージェントを活用する」や「ベストプラクティスに従う」など、具体的で実行可能ではない指示を削除します。

例

入力：

# CLAUDE.md

This is an Express API with a React frontend in a Turborepo monorepo.

## Commands

| Command | Description |
|---|---|
| `turbo build` | Build all packages |
| `turbo test` | Run all tests |
| `turbo lint` | Lint all packages |
| `turbo dev` | Start dev server |
| `turbo storybook` | Start Storybook |
| `turbo db:generate` | Generate Prisma client |
| `turbo db:migrate` | Run database migrations |
| `turbo analyze` | Bundle analyzer |

## Project Structure

- `apps/api/` - Express REST API
- `apps/web/` - React SPA
- `packages/db/` - Prisma schema and client
- `packages/ui/` - Shared component library
- `packages/config/` - Shared configuration

## Coding Standards

- Use named exports
- Use functional components with TypeScript interfaces for props
- Use camelCase for variables, PascalCase for components
- Prefer `const` over `let`
- Always use strict equality (`===`)
- Use template literals instead of string concatenation
- Write JSDoc comments for all public functions
- Use barrel exports in index.ts files

## API Development

- All routes go in `apps/api/src/routes/`
- Use Zod for request validation
- Use Prisma for database access
- Error responses follow RFC 7807 format
- Authentication via JWT middleware

## Testing

- Jest + Supertest for API tests
- Vitest + Testing Library for frontend
- Test fixtures in `__fixtures__/` directories
- Use `createTestClient()` helper for API integration tests
- Mock database with `prismaMock` from `packages/db/test`

## State Management

- Zustand for global client state
- React Query for server state
- URL state via `nuqs`

出力：

# CLAUDE.md

Express API + React frontend in a Turborepo monorepo.

## Project map

- `apps/api/` - Express REST API
- `apps/web/` - React SPA
- `packages/db/` - Prisma schema and client
- `packages/ui/` - Shared component library
- `packages/config/` - Shared configuration

<important if="you need to run commands to build, test, lint, or generate code">

Run with `turbo` from the repo root.

| Command | What it does |
|---|---|
| `turbo build` | Build all packages |
| `turbo test` | Run all tests |
| `turbo lint` | Lint all packages |
| `turbo dev` | Start dev server |
| `turbo storybook` | Start Storybook |
| `turbo db:generate` | Regenerate Prisma client after schema changes |
| `turbo db:migrate` | Run database migrations |
| `turbo analyze` | Bundle analyzer |
</important>

<important if="you are adding or modifying imports or exports">
- Use named exports (no default exports)
</important>

<important if="you are creating new components">
- Use functional components with TypeScript interfaces for props
</important>

<important if="you are adding or modifying API routes">

- All routes go in `apps/api/src/routes/`
- Use Zod for request validation
- Use Prisma for database access
- Error responses follow RFC 7807 format
- Authentication via JWT middleware
</important>

<important if="you are writing or modifying tests">

- API: Jest + Supertest
- Frontend: Vitest + Testing Library
- Test fixtures in `__fixtures__/` directories
- Use `createTestClient()` helper for API integration tests
- Mock database with `prismaMock` from `packages/db/test`
</important>

<important if="you are working with state management, stores, or URL parameters">

- Zustand for global client state
- React Query for server state
- URL state via `nuqs`
</important>

削除した内容とその理由：

• camelCase／PascalCase、const と let の使い分け、厳密等価演算子、テンプレートリテラル、JSDoc、バレルエクスポート — リンターやフォーマッターの対象、または既存のコードパターンから判断できるため
• 「コーディング規約」セクションをまとめた内容 — 条件ごとに対象を絞ったブロックに分割したため

削除しなかった内容：

• すべてのコマンドを維持（dev、storybook、analyze を含む）
• プロジェクトマップはそのまま記載（基礎となるコンテキストであり、すべてのタスクに関連するため）