CLAUDE.mdファイルの究極ガイド: Claude Codeの生産性を10倍にする方法

CLAUDE.mdファイルとは何で、なぜ重要なのか

CLAUDE.mdファイルなしでClaude Codeを使用している場合、そのパワーの大部分を活用できていません。

CLAUDE.mdは、すべてのセッションの開始時にClaude Codeが自動的に読み込むMarkdown設定ファイルです。プロジェクトのアーキテクチャ、コーディング標準、優先ツール、テストパターン、ワークフロールールについてClaudeに伝えます。すべての会話で同じ指示を繰り返す代わりに、一度書けば、毎回Claudeがそれに従います。

会社について何も知らない請負業者を雇うのと、エンジニアリングハンドブック全体を読んだ人を雇うのとの違いと考えてください。CLAUDE.mdファイルがそのハンドブックです。

なぜCLAUDE.mdが繰り返しプロンプティングに勝るのか

トークン節約だけでも大きいです。会話ごとにコンテキスト設定で500トークンを費やし、1日20会話なら、毎日10,000トークン — モデルによって1日約$0.15〜$0.75です。1か月で、CLAUDE.mdファイルは$4.50〜$22.50の生のAPIコストを節約しながら、より良い結果を生み出します。

Anthropicクレジット | AWSクレジット | Google Cloudクレジット

---

Claude CodeがCLAUDE.mdファイルを読む方法

Claude Codeは特定の優先順位でCLAUDE.mdファイルを検索します。この階層を理解することは、指示を効果的に整理するために不可欠です。

ファイル読み込み順序

Claude Codeは適用可能なすべてのファイルをマージします。グローバルファイルに「2スペースインデントを使用」、プロジェクトファイルに「4スペースタブを使用」と書かれている場合、そのプロジェクトではプロジェクトファイルが勝ちます。

何をどこに

グローバルCLAUDE.md(~/.claude/CLAUDE.md) — どこでも適用される設定:

# Global Preferences
- Always use TypeScript over JavaScript when possible
- Prefer functional components over class components in React
- Write concise commit messages under 72 characters
- Use ESM imports, never CommonJS require()

プロジェクトCLAUDE.md(プロジェクトルート) — このコードベースに固有のすべて:

# Project: Acme Dashboard
## Tech Stack
- Next.js 15 with App Router
- TypeScript 5.x strict mode
- Tailwind CSS 4.0
- Prisma ORM with PostgreSQL
- Jest + React Testing Library for tests

## Architecture
- /app — Next.js routes (App Router only, no Pages Router)
- /components — reusable UI components
- /lib — business logic and utilities
- /prisma — database schema and migrations

---

最初のCLAUDE.mdファイルを作成する

Claude CodeとCLAUDE.mdファイルを適切に設定するためのステップバイステップセットアップ。

ステップ1: Claude Codeをインストール

npm install -g @anthropic-ai/claude-code

ステップ2: プロジェクトルートにCLAUDE.mdを作成

touch CLAUDE.md

ステップ3: 基本設定を追加

この最小テンプレートから始めて、必要に応じて拡張:

# Project: [Your Project Name]

## Tech Stack
- [Language/Framework]
- [Database]
- [Key libraries]

## Coding Standards
- [Indentation preference]
- [Naming conventions]
- [Import ordering]

## Rules
- Always write tests for new functions
- Never commit directly to main
- Use conventional commit messages

ステップ4: Claude Codeを実行

claude

Claude Codeは自動的にCLAUDE.mdファイルを検出して読み込みます。セッション出力に確認が表示されます。

---

CLAUDE.mdテンプレート: スターター、上級、チーム

テンプレート1: シンプルなプロジェクト(20行)

ソロ開発者、サイドプロジェクト、小規模コードベースに最適。

# My App

## Stack
- Python 3.12, FastAPI, SQLAlchemy, PostgreSQL
- pytest for testing

## Rules
- Use type hints on all function signatures
- Write docstrings for public functions
- Keep functions under 30 lines
- Use async/await for all database operations
- Format with black, lint with ruff

## Patterns
- Repository pattern for data access
- Pydantic models for request/response validation
- Dependency injection via FastAPI Depends()

テンプレート2: 上級フルスタックプロジェクト(80行以上)

複数の開発者と複雑なアーキテクチャを持つ本番アプリケーション向け。

# Acme SaaS Platform

## Tech Stack
- Frontend: Next.js 15, TypeScript 5.x, Tailwind CSS 4.0
- Backend: Node.js 22, tRPC, Prisma ORM
- Database: PostgreSQL 16, Redis 7
- Infrastructure: Vercel (frontend), Railway (backend)
- Testing: Vitest, Playwright, MSW

## Architecture
All code follows Clean Architecture principles:
- /packages/web — Next.js frontend (App Router only)
- /packages/api — tRPC backend
- /packages/shared — shared types and utilities
- /packages/db — Prisma schema and client

## Coding Standards
- Strict TypeScript: no any, no ts-ignore
- All components must be functional with hooks
- Server Components by default, "use client" only when needed
- All API routes must have Zod input validation
- Database queries go through repository layer, never raw SQL

## Testing Requirements
- Minimum 80% coverage for new code
- Unit tests for all business logic
- Integration tests for API endpoints
- E2E tests for critical user flows
- Use MSW for API mocking, never mock fetch directly

## Git Workflow
- Conventional commits: feat:, fix:, chore:, docs:
- All PRs require passing CI before merge
- Squash merge to main
- Branch naming: feature/TICKET-123-description

## Security Rules
- NEVER hardcode secrets or API keys
- Always use environment variables for config
- Sanitize all user input
- Use parameterized queries (Prisma handles this)
- NEVER expose internal error details to clients

テンプレート3: チーム設定(Git経由で共有)

すべてのメンバー間で一貫したClaude Code動作を望むチーム向け。

# Team Engineering Standards — Acme Corp

## Overview
This file ensures Claude Code follows our team's engineering
standards. Committed to Git so all engineers get identical behavior.

## Code Review Checklist (Claude must follow before suggesting code)
1. Does this change have tests?
2. Are error cases handled?
3. Is the function documented?
4. Does it follow our naming conventions?
5. Are there any security implications?

## Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with use prefix (useAuth.ts)
- Utils: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE (MAX_RETRIES)
- Database tables: snake_case (user_profiles)
- API routes: kebab-case (/api/user-settings)

## Forbidden Patterns
- DO NOT use console.log in production code (use our logger)
- DO NOT use any TypeScript escape hatches (any, @ts-ignore)
- DO NOT install new dependencies without justification
- DO NOT modify database schema without migration file
- DO NOT use default exports (use named exports only)

## Preferred Libraries (do not suggest alternatives)
- State management: Zustand (not Redux)
- Forms: React Hook Form + Zod (not Formik)
- HTTP client: native fetch (not Axios)
- Date handling: date-fns (not Moment.js)
- Animation: Framer Motion (not React Spring)

---

比較: CLAUDE.md vs .cursorrules vs .github/copilot-instructions.md

AIコーディングツールを評価している場合、それぞれが設定をどう扱うかを理解することが重要です。

Claude Codeの主要な差別化要因は、CLAUDE.md周辺のエコシステムです — フック、カスタムコマンド、MCPサーバー、マルチエージェントサポートが、設定ファイルから完全な自動化フレームワークに変えます。

---

フック: Claude Codeワークフローの自動化

フックは、CLAUDE.md自体ではなく、.claude/settings.jsonで設定します。Claude Codeイベントの前後にシェルコマンドを自動的に実行します。

フック設定構造

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo 'File about to be modified'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ],
    "PreCommit": [
      {
        "command": "npm run lint && npm run test:changed"
      }
    ]
  }
}

最も有用なフックパターン

実用的なフック例

すべてのファイル編集後の自動フォーマット:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

変更されたファイルのテスト実行:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx vitest run --reporter=verbose --changed"
      }
    ]
  }
}

---

カスタムスラッシュコマンド

スラッシュコマンドを使うと、単一の/コマンドでトリガーする再利用可能なプロンプトテンプレートを作成できます。

スラッシュコマンドの作成方法

1. プロジェクトに.claude/commands/ディレクトリを作成
2. Markdownファイルを追加 — 各ファイルがコマンドになる
3. 動的入力のプレースホルダーとして$ARGUMENTSを使用

例: .claude/commands/review.md

Review the following code for:
1. Security vulnerabilities
2. Performance issues
3. Missing error handling
4. Test coverage gaps

Code to review: $ARGUMENTS

Provide a severity rating (low/medium/high/critical) for each finding.

Claude Codeでの使用:

/project:review src/auth/login.ts

有用なスラッシュコマンドのアイデア

---

MCPサーバー: Claude Codeの機能を拡張

MCP(Model Context Protocol)サーバーは、Claude Codeを外部ツールやサービスに接続します。適切に設定されると、Claude Codeはデータベースをクエリし、Webを閲覧し、ファイルを管理し、GitHubとやり取りでき、コーディングセッション内からはるかに多くのことができます。

MCPサーバーの設定方法

MCPサーバーは.claude/settings.jsonでセットアップします:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

開発者向けの最も人気のあるMCPサーバー

CLAUDE.mdでMCPを参照する

CLAUDE.mdは、接続されたMCPサーバーをいつどう使うかをClaude Codeに指示できます:

## Available Tools
- Use the postgres MCP to check schema before writing migrations
- Use the github MCP to create PRs after completing feature branches
- Use the memory MCP to track progress on multi-step tasks

---

バイラルな27エージェントセットアップ: Googleエンジニアが80%の作業を自動化した方法

2026年初頭、GoogleエンジニアのTwitterスレッドがバイラルになり、ワークフローの異なる部分を処理するために27の専門Claude Codeエージェントをセットアップした方法を説明しました。各エージェントは狭く焦点を絞った指示を持つ独自のCLAUDE.mdを持っていました。

中核的な洞察

すべてを行おうとする1つの汎用Claude Codeセッションの代わりに、彼は作業を専門の役割に分解しました。各エージェントは:

• ドメイン固有の知識を持つ専用CLAUDE.md
• 制限されたツールアクセス(そのエージェントが必要なものだけ)
• 何を扱うべきで何を扱うべきでないかの明確な境界
• 特定の出力フォーマットと品質標準

エージェントの内訳の例

このセットアップを複製する方法

このパターンの恩恵を受けるために27エージェントは必要ありません。3〜5の専門設定から始めましょう:

1. 役割ごとに別々のCLAUDE.mdファイルを作成:

.claude/agents/frontend.md
.claude/agents/backend.md
.claude/agents/testing.md

2. 特定の設定でClaude Codeを起動:

# Use different profiles by combining global + agent-specific context
claude --profile frontend

3. 明確なハンドオフポイントを定義:

メインCLAUDE.mdは、いつエージェントを切り替えるかを参照できます:

## Agent Workflow
- Frontend changes: use the frontend agent profile
- API changes: use the backend agent profile
- After any code change: run the test agent
- Before merging: run the review agent

なぜこれが機能するのか

27エージェントアプローチが機能するのは、AI生産性の基本原則によるものです:狭いコンテキストは広いコンテキストよりも良い出力を生み出します。 フロントエンド、バックエンド、DevOps、テスト、ドキュメンテーションに関する400行の指示を読み込んだClaude Codeセッションは、関連する50行を読み込んだものよりも、どのタスクでもパフォーマンスが悪くなります。

---

一般的なCLAUDE.mdの間違い(と修正方法)

間違い1: あいまいすぎる

悪い例:

Write good code that follows best practices.

良い例:

- Use TypeScript strict mode, no implicit any
- All functions must have JSDoc comments
- Error handling: wrap async operations in try/catch
- Max function length: 30 lines

間違い2: 指示で過負荷

500行以上の指示を入れると、Claude Codeは重要なルールを優先順位を下げます。CLAUDE.mdを焦点を絞ったままにしましょう。

間違い3: CLAUDE.mdをバージョン管理しない

CLAUDE.mdはGitにコミットすべきです。これにより以下が保証されます:

• チームの一貫性
• 変更履歴と説明責任
• 指示が問題を引き起こす場合の簡単なロールバック
• 指示の変更のPRレビュー

間違い4: セキュリティセクションを無視する

常にCLAUDE.mdにセキュリティルールを含めましょう:

## Security (CRITICAL — never ignore)
- NEVER hardcode API keys, tokens, or passwords
- NEVER commit .env files
- ALWAYS use parameterized database queries
- ALWAYS validate and sanitize user input
- NEVER expose stack traces or internal errors to users

間違い5: 技術スタックの言及を忘れる

Claude Codeはコードからスタックを推測できますが、明示的な宣言で間違った仮定を防ぎます:

## Stack (authoritative — do not infer differently)
- Runtime: Node.js 22 (NOT Deno, NOT Bun)
- Framework: Next.js 15 App Router (NOT Pages Router)
- ORM: Prisma (NOT Drizzle, NOT TypeORM)
- Package manager: pnpm (NOT npm, NOT yarn)

---

Claude Codeのベストプラクティス: パワーユーザーのヒント

ヒント1: 条件付き指示を使う

## Environment-Specific Rules
- In development: use verbose logging, skip minification
- In production: no console.log, enable all optimizations
- In CI: run full test suite, fail on any warning

ヒント2: 出力フォーマットを定義する

## When I ask for a code review, respond with:
1. **Summary** (1-2 sentences)
2. **Issues found** (bulleted, severity-tagged)
3. **Suggested fixes** (with code snippets)
4. **Overall grade** (A/B/C/D/F)

ヒント3: 依存関係に境界を設定する

## Dependency Rules
- NEVER install packages with fewer than 1,000 weekly downloads
- NEVER install packages with known CVEs
- Prefer built-in Node.js APIs over third-party packages
- Always check bundle size impact before adding frontend deps

ヒント4: 長いプロジェクトにメモリファイルを使う

## Memory
- Track all completed features in .claude/memory/features.md
- Log all architecture decisions in .claude/memory/decisions.md
- Update progress after each session

ヒント5: CI/CDと統合する

CLAUDE.mdは、Claude CodeにCIパイプラインを尊重するよう指示できます:

## Before pushing any code:
1. Run `pnpm lint` — fix all errors
2. Run `pnpm test` — all tests must pass
3. Run `pnpm build` — build must succeed
4. Check bundle size — must not exceed 250KB

---

Claude Codeのコストはどれくらい?(そしてクレジットを取得する方法)

Claude CodeはAPIクレジットを使用するため、コストは使用するモデルと、それに与えるコンテキストの量に依存します。

Claude Codeコストの内訳

一般的な重いClaude Codeの日は500K〜2Mトークンを使用し、モデル選択によって$2〜$30のコストがかかります。よく設定されたCLAUDE.mdは、繰り返しのコンテキストを排除することでトークン使用量を削減します。

Claude Codeの無料クレジットを取得する

Claude Codeの使用を資金提供する最良の方法は、クレジットプログラムを通じてです:

積み重ね可能なクレジット合計: すべてのプログラムで最大$230,000以上

Anthropicクレジット | AWSクレジット | Google Cloudクレジット | Azureクレジット

1つのCLAUDE.mdファイルと$5,000〜$25,000のスタートアップクレジットの組み合わせで、3〜6か月の集中的なClaude Code開発をゼロコストで実現できます。資格のあるものを見つけるには、ClaimAICreditsで利用可能なすべてのクレジットプログラムを閲覧してください。

---

クイックリファレンス: CLAUDE.mdチートシート

---

今日始める

CLAUDE.mdファイルは、AI支援開発のためにセットアップできる最高のレバレッジ設定です。このガイドのシンプルなテンプレートから始めて、リポジトリにコミットし、ワークフローで機能するものに基づいて反復しましょう。

Claude Codeから最も価値を得ているエンジニアは、より良いプロンプトを書いているわけではありません — より良いCLAUDE.mdファイルを書いています。バイラルな27エージェントセットアップは、思慮深い設定が毎回ブルートフォースプロンプティングに勝つことを証明しています。

Claude CodeのAPIコストがマルチエージェントワークフローなどの高度なセットアップの実験を妨げている場合は、ClaimAICreditsを通じて利用可能な無料クレジットプログラムを探索してください。Anthropic、AWS、Google Cloudのクレジットを積み重ねれば、CLAUDE.md設定を完成させるための数か月の無料開発時間が得られます。