完璧な CLAUDE.md ファイルの書き方 (2026年版)

2026年版：完璧な CLAUDE.md ファイルの書き方

CLAUDE.md ファイルは、Claude Code を使用するプロジェクトに追加できる最も効果的な要素です。これは、Claude がリポジトリでセッションを開始するたびに読み込む「永続的なシステムプロンプト」として機能します。適切に記述された CLAUDE.md は、間違いを劇的に減らし、コーディング標準を強制し、毎回説明しなくても Claude がプロジェクトのアーキテクチャを理解するのに役立ちます。

このガイドでは、効果的な CLAUDE.md ファイルの書き方について、テンプレートと実例を交えて解説します。

CLAUDE.md とは何か？

CLAUDE.md は、プロジェクトのルート（またはグローバル設定の場合は ~/.claude/CLAUDE.md）に配置される Markdown ファイルです。Claude Code がディレクトリ内で起動すると、自動的にこのファイルを読み取り、すべての対話のコンテキストとして使用します。

これは次のようなものだと考えてください：

人間の開発者ではなく、AI アシスタントのための README
セッションをまたいで維持される 永続的なシステムプロンプト
Claude が実際に従う コーディング標準ドキュメント

CLAUDE.md の配置場所

Claude Code は、以下の順序で CLAUDE.md ファイルを検索します：

場所	スコープ	ユースケース
`~/.claude/CLAUDE.md`	グローバル（全プロジェクト）	個人の好み、デフォルトの規約
`./CLAUDE.md`	プロジェクトルート	プロジェクト固有のコンテキストとルール
`./src/CLAUDE.md`	サブディレクトリ	モジュール固有の指示

見つかったすべてのファイルは結合され、より具体的なファイルの設定が優先されます。

必須セクション

優れた CLAUDE.md ファイルには、以下のセクションを含めるべきです。

1. プロジェクトの概要 (Project Overview)

プロジェクトの概要を 2〜3 文で伝えます。これにより、Claude が推測で動くのを防ぎます。

# Project Overview
This is a SaaS platform for AI media generation built with Next.js 14
(App Router), TypeScript, and Tailwind CSS. The backend uses Supabase
for auth and database, Stripe for payments, and a custom API layer
for AI model inference.

2. 技術スタック (Tech Stack)

主要なテクノロジー、フレームワーク、ライブラリをすべてリストアップします。バージョンは具体的に指定してください。

# Tech Stack
- Framework: Next.js 14.2 (App Router, NOT Pages Router)
- Language: TypeScript 5.4 (strict mode)
- Styling: Tailwind CSS 3.4 + shadcn/ui components
- Database: PostgreSQL via Supabase
- ORM: Prisma 5.x
- Auth: NextAuth.js v5 (Auth.js)
- Payments: Stripe (subscriptions + one-time)
- State: Zustand for client state
- Forms: React Hook Form + Zod validation
- Testing: Vitest + React Testing Library
- Package manager: pnpm (NOT npm or yarn)

3. プロジェクト構造 (Project Structure)

主要なディレクトリをマッピングして、Claude がどこに何があるか、あるいは配置すべきかを把握できるようにします。

# Project Structure
- src/app/ - Next.js App Router pages and layouts
- src/app/api/ - API route handlers
- src/app/[locale]/ - Internationalized routes
- src/components/ - Reusable React components
- src/components/ui/ - shadcn/ui base components (DO NOT EDIT)
- src/lib/ - Utility functions, API clients, helpers
- src/hooks/ - Custom React hooks
- src/types/ - TypeScript type definitions
- src/config/ - App configuration files
- prisma/ - Database schema and migrations
- content/ - MDX blog articles
- messages/ - i18n translation JSON files
- public/ - Static assets

4. コーディング規約 (Coding Conventions)

これは最も重要なセクションです。コーディング標準を明示的に指定してください。

# Coding Conventions

## General
- Use functional components with hooks (no class components)
- Prefer named exports over default exports
- Use absolute imports with @/ prefix (e.g., @/components/Button)
- All files use TypeScript (.ts/.tsx), never plain JavaScript

## Naming
- Components: PascalCase (e.g., UserProfile.tsx)
- Hooks: camelCase with "use" prefix (e.g., useAuth.ts)
- Utilities: camelCase (e.g., formatDate.ts)
- Types: PascalCase with descriptive names (e.g., UserProfile, ApiResponse)
- Constants: UPPER_SNAKE_CASE
- CSS classes: Use Tailwind utilities, avoid custom CSS

## Components
- One component per file
- Props interface defined above the component
- Use React.FC sparingly; prefer explicit return types
- Destructure props in the function signature
- Use "use client" directive only when necessary

## Error Handling
- Use try/catch in API routes and server actions
- Return structured error responses: { error: string, code: number }
- Never expose internal error details to the client
- Log errors server-side with console.error

## Imports Order
1. React/Next.js imports
2. Third-party library imports
3. Internal imports (@/)
4. Type imports
5. Relative imports

5. 重要なルールと制約 (Important Rules and Constraints)

Claude が決して破ってはならない厳格なルールを記述します。

# Important Rules
- NEVER modify files in src/components/ui/ (these are shadcn/ui generated)
- NEVER commit .env files or hardcode secrets
- ALWAYS use server actions for mutations, not API routes
- ALWAYS add "use client" when using hooks or event handlers
- ALWAYS run `pnpm lint` before considering a task complete
- Database migrations MUST be created with `pnpm prisma migrate dev`
- NEVER delete or modify existing migration files
- All user-facing text MUST use the i18n system (useTranslations)
- NEVER use `any` type; use `unknown` if the type is truly unknown

6. 共通コマンド (Common Commands)

ビルド、テスト、Lint 実行のために Claude が必要とするコマンドをリストアップします。

# Common Commands
- `pnpm dev` - Start development server
- `pnpm build` - Build for production
- `pnpm lint` - Run ESLint
- `pnpm typecheck` - Run TypeScript type checking
- `pnpm test` - Run test suite
- `pnpm test:watch` - Run tests in watch mode
- `pnpm prisma generate` - Regenerate Prisma client
- `pnpm prisma migrate dev` - Create and run migrations
- `pnpm prisma studio` - Open database browser

7. API とデータパターン (API and Data Patterns)

アプリケーション内でのデータフローをドキュメント化します。

# Data Patterns

## API Routes
API routes are in src/app/api/. They use the Next.js Route Handler format:
export async function POST(request: Request) { ... }

## Server Actions
Prefer server actions over API routes for mutations.
Server actions are in src/lib/actions/ and use "use server" directive.

## Database Queries
All database queries go through Prisma. The client is at src/lib/db.ts.
Never query the database directly from components.

## Authentication
Use the auth() helper from src/lib/auth.ts to get the current session.
Protected API routes should check auth at the top of the handler.

フルテンプレート

以下は、そのまま活用できる CLAUDE.md の完全版テンプレートです。

# Project Overview
[プロジェクトを説明する 2-3 文]

# Tech Stack
- Framework: [フレームワークとバージョン]
- Language: [言語とバージョン]
- Styling: [CSSのアプローチ]
- Database: [データベース]
- Auth: [認証ソリューション]
- Testing: [テストフレームワーク]
- Package manager: [pnpm/npm/yarn]

# Project Structure
- src/app/ - [説明]
- src/components/ - [説明]
- src/lib/ - [説明]
[必要に応じて追加]

# Coding Conventions
[コーディング標準]

# Important Rules
- NEVER [重要な制約]
- ALWAYS [必須のプラクティス]
[必要に応じて追加]

# Common Commands
- `[command]` - [説明]
[必要に応じて追加]

# Data Patterns
[アプリ内のデータフロー]

# Known Issues
[Claudeが留意すべき注意点]

高度なヒント

サブディレクトリでの CLAUDE.md 活用

モノリポジトリや複雑なプロジェクトの場合は、サブディレクトリに CLAUDE.md を追加します。

project/
  CLAUDE.md           # ルートレベルのプロジェクトコンテキスト
  packages/
    api/
      CLAUDE.md       # API固有の規約
    web/
      CLAUDE.md       # フロントエンド固有の規約

良いパターンの例を含める

規約を説明するだけでなく、実際に見せます。

# Example: Creating a New API Route

Here is the pattern for a new API route:

\`\`\`typescript
import { auth } from "@/lib/auth";
import { db } from "@/lib/db";
import { NextResponse } from "next/server";

export async function GET(request: Request) {
  const session = await auth();
  if (!session?.user) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  try {
    const data = await db.item.findMany({
      where: { userId: session.user.id },
    });
    return NextResponse.json(data);
  } catch (error) {
    console.error("Failed to fetch items:", error);
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 }
    );
  }
}
\`\`\`

重要なファイルを参照させる

Claude が読むべき重要なファイルを指示します。

# Key Files
- src/lib/auth.ts - Authentication configuration and helpers
- src/lib/db.ts - Database client and connection
- src/types/index.ts - Shared type definitions
- .env.example - Required environment variables

常に最新の状態に保つ

CLAUDE.md は生きているドキュメントとして扱ってください。規約を変更したときはファイルを更新します。Claude が間違いを犯したときは、それを防ぐためのルールを追加します。

避けるべきよくある間違い

曖昧すぎる: 「良いコーディングプラクティスを使う」では Claude に何も伝わりません。具体的に書いてください。
長すぎる: Claude にはコンテキストウィンドウがあります。500行以内に抑えましょう。
矛盾している: ある場所で「名前付きエクスポートを使う」と言いながら、例でデフォルトエクスポートを使わないでください。
否定的な指示を忘れる: すべきことだけでなく、してはいけないことも伝えてください。
技術スタックを省略する: Claude が誤ったフレームワークのバージョンを仮定する可能性があります。

効果の測定

CLAUDE.md を追加した後、以下の点を確認してください：

注意されなくても命名規則に従っているか
正しいディレクトリにファイルを配置しているか
適切なインポートとパターンを使用しているか
「重要なルール」に記載した間違いを避けているか
正しいビルド/Lintコマンドを実行しているか

もし Claude が同じ間違いを繰り返す場合は、より明示的なルールを CLAUDE.md に追加してください。

結論

適切に作成された CLAUDE.md ファイルがあるかどうかで、Claude Code が「一般的な AI アシスタント」になるか、「プロジェクトを深く理解した有能なチームメンバー」になるかが決まります。30分かけて良いものを作成すれば、その後の修正や再説明に費やす時間を何時間も節約できるでしょう。

画像、動画、音声、あるいは話すアバターなどの AI メディア生成機能を必要とするアプリケーションを構築しているなら、Hypereal AI がそれらすべてを単一の API で提供します。従量課金制、高速生成、クリエイティブな制作活動に対するコンテンツ制限なしという特徴を備えており、製品に AI メディアを統合する最も簡単な方法です。

2026年版：完璧な CLAUDE.md ファイルの書き方

このガイドでは、効果的な CLAUDE.md ファイルの書き方について、テンプレートと実例を交えて解説します。

CLAUDE.md とは何か？

これは次のようなものだと考えてください：

人間の開発者ではなく、AI アシスタントのための README
セッションをまたいで維持される 永続的なシステムプロンプト
Claude が実際に従う コーディング標準ドキュメント

CLAUDE.md の配置場所

Claude Code は、以下の順序で CLAUDE.md ファイルを検索します：

場所	スコープ	ユースケース
`~/.claude/CLAUDE.md`	グローバル（全プロジェクト）	個人の好み、デフォルトの規約
`./CLAUDE.md`	プロジェクトルート	プロジェクト固有のコンテキストとルール
`./src/CLAUDE.md`	サブディレクトリ	モジュール固有の指示

見つかったすべてのファイルは結合され、より具体的なファイルの設定が優先されます。

必須セクション

優れた CLAUDE.md ファイルには、以下のセクションを含めるべきです。

1. プロジェクトの概要 (Project Overview)

プロジェクトの概要を 2〜3 文で伝えます。これにより、Claude が推測で動くのを防ぎます。

# Project Overview
This is a SaaS platform for AI media generation built with Next.js 14
(App Router), TypeScript, and Tailwind CSS. The backend uses Supabase
for auth and database, Stripe for payments, and a custom API layer
for AI model inference.

2. 技術スタック (Tech Stack)

主要なテクノロジー、フレームワーク、ライブラリをすべてリストアップします。バージョンは具体的に指定してください。

# Tech Stack
- Framework: Next.js 14.2 (App Router, NOT Pages Router)
- Language: TypeScript 5.4 (strict mode)
- Styling: Tailwind CSS 3.4 + shadcn/ui components
- Database: PostgreSQL via Supabase
- ORM: Prisma 5.x
- Auth: NextAuth.js v5 (Auth.js)
- Payments: Stripe (subscriptions + one-time)
- State: Zustand for client state
- Forms: React Hook Form + Zod validation
- Testing: Vitest + React Testing Library
- Package manager: pnpm (NOT npm or yarn)

3. プロジェクト構造 (Project Structure)

主要なディレクトリをマッピングして、Claude がどこに何があるか、あるいは配置すべきかを把握できるようにします。

# Project Structure
- src/app/ - Next.js App Router pages and layouts
- src/app/api/ - API route handlers
- src/app/[locale]/ - Internationalized routes
- src/components/ - Reusable React components
- src/components/ui/ - shadcn/ui base components (DO NOT EDIT)
- src/lib/ - Utility functions, API clients, helpers
- src/hooks/ - Custom React hooks
- src/types/ - TypeScript type definitions
- src/config/ - App configuration files
- prisma/ - Database schema and migrations
- content/ - MDX blog articles
- messages/ - i18n translation JSON files
- public/ - Static assets

4. コーディング規約 (Coding Conventions)

これは最も重要なセクションです。コーディング標準を明示的に指定してください。

# Coding Conventions

## General
- Use functional components with hooks (no class components)
- Prefer named exports over default exports
- Use absolute imports with @/ prefix (e.g., @/components/Button)
- All files use TypeScript (.ts/.tsx), never plain JavaScript

## Naming
- Components: PascalCase (e.g., UserProfile.tsx)
- Hooks: camelCase with "use" prefix (e.g., useAuth.ts)
- Utilities: camelCase (e.g., formatDate.ts)
- Types: PascalCase with descriptive names (e.g., UserProfile, ApiResponse)
- Constants: UPPER_SNAKE_CASE
- CSS classes: Use Tailwind utilities, avoid custom CSS

## Components
- One component per file
- Props interface defined above the component
- Use React.FC sparingly; prefer explicit return types
- Destructure props in the function signature
- Use "use client" directive only when necessary

## Error Handling
- Use try/catch in API routes and server actions
- Return structured error responses: { error: string, code: number }
- Never expose internal error details to the client
- Log errors server-side with console.error

## Imports Order
1. React/Next.js imports
2. Third-party library imports
3. Internal imports (@/)
4. Type imports
5. Relative imports

5. 重要なルールと制約 (Important Rules and Constraints)

Claude が決して破ってはならない厳格なルールを記述します。

# Important Rules
- NEVER modify files in src/components/ui/ (these are shadcn/ui generated)
- NEVER commit .env files or hardcode secrets
- ALWAYS use server actions for mutations, not API routes
- ALWAYS add "use client" when using hooks or event handlers
- ALWAYS run `pnpm lint` before considering a task complete
- Database migrations MUST be created with `pnpm prisma migrate dev`
- NEVER delete or modify existing migration files
- All user-facing text MUST use the i18n system (useTranslations)
- NEVER use `any` type; use `unknown` if the type is truly unknown

6. 共通コマンド (Common Commands)

ビルド、テスト、Lint 実行のために Claude が必要とするコマンドをリストアップします。

# Common Commands
- `pnpm dev` - Start development server
- `pnpm build` - Build for production
- `pnpm lint` - Run ESLint
- `pnpm typecheck` - Run TypeScript type checking
- `pnpm test` - Run test suite
- `pnpm test:watch` - Run tests in watch mode
- `pnpm prisma generate` - Regenerate Prisma client
- `pnpm prisma migrate dev` - Create and run migrations
- `pnpm prisma studio` - Open database browser

7. API とデータパターン (API and Data Patterns)

アプリケーション内でのデータフローをドキュメント化します。

# Data Patterns

## API Routes
API routes are in src/app/api/. They use the Next.js Route Handler format:
export async function POST(request: Request) { ... }

## Server Actions
Prefer server actions over API routes for mutations.
Server actions are in src/lib/actions/ and use "use server" directive.

## Database Queries
All database queries go through Prisma. The client is at src/lib/db.ts.
Never query the database directly from components.

## Authentication
Use the auth() helper from src/lib/auth.ts to get the current session.
Protected API routes should check auth at the top of the handler.

フルテンプレート

以下は、そのまま活用できる CLAUDE.md の完全版テンプレートです。

# Project Overview
[プロジェクトを説明する 2-3 文]

# Tech Stack
- Framework: [フレームワークとバージョン]
- Language: [言語とバージョン]
- Styling: [CSSのアプローチ]
- Database: [データベース]
- Auth: [認証ソリューション]
- Testing: [テストフレームワーク]
- Package manager: [pnpm/npm/yarn]

# Project Structure
- src/app/ - [説明]
- src/components/ - [説明]
- src/lib/ - [説明]
[必要に応じて追加]

# Coding Conventions
[コーディング標準]

# Important Rules
- NEVER [重要な制約]
- ALWAYS [必須のプラクティス]
[必要に応じて追加]

# Common Commands
- `[command]` - [説明]
[必要に応じて追加]

# Data Patterns
[アプリ内のデータフロー]

# Known Issues
[Claudeが留意すべき注意点]

高度なヒント

サブディレクトリでの CLAUDE.md 活用

モノリポジトリや複雑なプロジェクトの場合は、サブディレクトリに CLAUDE.md を追加します。

project/
  CLAUDE.md           # ルートレベルのプロジェクトコンテキスト
  packages/
    api/
      CLAUDE.md       # API固有の規約
    web/
      CLAUDE.md       # フロントエンド固有の規約

良いパターンの例を含める

規約を説明するだけでなく、実際に見せます。

# Example: Creating a New API Route

Here is the pattern for a new API route:

\`\`\`typescript
import { auth } from "@/lib/auth";
import { db } from "@/lib/db";
import { NextResponse } from "next/server";

export async function GET(request: Request) {
  const session = await auth();
  if (!session?.user) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  try {
    const data = await db.item.findMany({
      where: { userId: session.user.id },
    });
    return NextResponse.json(data);
  } catch (error) {
    console.error("Failed to fetch items:", error);
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 }
    );
  }
}
\`\`\`

重要なファイルを参照させる

Claude が読むべき重要なファイルを指示します。

# Key Files
- src/lib/auth.ts - Authentication configuration and helpers
- src/lib/db.ts - Database client and connection
- src/types/index.ts - Shared type definitions
- .env.example - Required environment variables

常に最新の状態に保つ

避けるべきよくある間違い

曖昧すぎる: 「良いコーディングプラクティスを使う」では Claude に何も伝わりません。具体的に書いてください。
長すぎる: Claude にはコンテキストウィンドウがあります。500行以内に抑えましょう。
矛盾している: ある場所で「名前付きエクスポートを使う」と言いながら、例でデフォルトエクスポートを使わないでください。
否定的な指示を忘れる: すべきことだけでなく、してはいけないことも伝えてください。
技術スタックを省略する: Claude が誤ったフレームワークのバージョンを仮定する可能性があります。

効果の測定

CLAUDE.md を追加した後、以下の点を確認してください：

注意されなくても命名規則に従っているか
正しいディレクトリにファイルを配置しているか
適切なインポートとパターンを使用しているか
「重要なルール」に記載した間違いを避けているか
正しいビルド/Lintコマンドを実行しているか

もし Claude が同じ間違いを繰り返す場合は、より明示的なルールを CLAUDE.md に追加してください。

Hyperealで構築を始めよう

2026年版：完璧な CLAUDE.md ファイルの書き方

CLAUDE.md とは何か？

CLAUDE.md の配置場所

必須セクション

1. プロジェクトの概要 (Project Overview)

2. 技術スタック (Tech Stack)

3. プロジェクト構造 (Project Structure)

4. コーディング規約 (Coding Conventions)

5. 重要なルールと制約 (Important Rules and Constraints)

6. 共通コマンド (Common Commands)

7. API とデータパターン (API and Data Patterns)

フルテンプレート

高度なヒント

サブディレクトリでの CLAUDE.md 活用

良いパターンの例を含める

重要なファイルを参照させる

常に最新の状態に保つ

避けるべきよくある間違い

効果の測定

結論

関連記事

Claude Code 入門ガイド & ベストプラクティス (2026)

Claude Skills: カスタムな Claude Code Skill を作成する方法 (2026)

OpenRouterでClaude Codeを使用する方法 (2026年版)

今日から構築を開始

Hyperealで構築を始めよう

2026年版：完璧な CLAUDE.md ファイルの書き方

CLAUDE.md とは何か？

CLAUDE.md の配置場所

必須セクション

1. プロジェクトの概要 (Project Overview)

2. 技術スタック (Tech Stack)

3. プロジェクト構造 (Project Structure)

4. コーディング規約 (Coding Conventions)

5. 重要なルールと制約 (Important Rules and Constraints)

6. 共通コマンド (Common Commands)

7. API とデータパターン (API and Data Patterns)

フルテンプレート

高度なヒント

サブディレクトリでの CLAUDE.md 活用

良いパターンの例を含める

重要なファイルを参照させる

常に最新の状態に保つ

避けるべきよくある間違い

効果の測定

結論

関連記事

Claude Code 入門ガイド & ベストプラクティス (2026)

Claude Skills: カスタムな Claude Code Skill を作成する方法 (2026)

OpenRouterでClaude Codeを使用する方法 (2026年版)

今日から構築を開始