CLAUDE.md実践ガイド - プロジェクト別設定パターン¶

🆕 2025年8月最新機能

階層メモリシステム: Enterprise・Project・User・Local の4階層メモリ管理
Memory import: @path/to/import による追加メモリファイル読み込み
ショートカット対応: # でクイック追加、/memory で直接編集
Project Memory統合: チーム共有プロジェクト設定の正式対応

この記事の対象者

CLAUDE.mdの基本を理解している方
チーム開発でメモリ管理を活用したい方
Claude Codeの最新機能を使いたい方

この記事で学べること¶

2025年最新の階層メモリシステム活用
プロジェクトタイプ別の設定パターン
メモリimport機能の効果的な使い方
チーム開発での階層管理手法
実際のプロジェクト例とテンプレート

前提知識¶

Claude Code (@anthropic-ai/claude-code) がインストール済み
基本的なプロジェクト構造の知識

🧠 2025年最新：階層メモリシステム¶

階層構造の理解¶

Claude Codeは4つの階層でメモリを管理します：

graph TD
    A[Enterprise Policy] --> B[Project Memory]
    B --> C[User Memory]  
    C --> D[Local Project Memory - 廃止予定]

Enterprise Policy: 組織全体のルール（システムレベル）
Project Memory: チーム共有のプロジェクト設定
User Memory: 個人設定（全プロジェクト共通）
~~Local Project Memory~~: 廃止予定

Memory Import機能¶

# CLAUDE.md メインファイル

## プロジェクト基本設定
基本的な開発ルールとコマンド

## 詳細設定の読み込み
@docs/detailed-coding-standards.md
@docs/api-guidelines.md  
@.github/team-workflows.md

ショートカット活用¶

# クイックメモリ追加
# Claude Code起動中に # を使用

# 直接編集
/memory

# メモリ確認
claude memory --list

Auto Memory（自動学習）について¶

Claude Codeは作業履歴から文脈や決定事項を ~/.claude/projects/<project>/memory/ に自動保存します。MEMORY.md（インデックス）は 最初の200行のみロードされる点に注意してください。詳しい仕組みと無効化方法はコマンドリファレンス > Auto Memory制御を参照してください。

`.claude/rules/` による条件付きルールのモジュール化¶

CLAUDE.md にすべての指示・制約（コーディングスタイル、テスト方針、デプロイ手順など）を詰め込むと、トークン消費が激しくなり、不要なコンテキストが増長します。これを回避するため、CLAUDE.md 内に全てを書かず、.claude/rules/ ディレクトリに用途ごとのルールファイルを分割し、CLAUDE.md から@import またはリンク経由で必要に応じて呼び出す運用が2026年のベストプラクティスです。

.claude/rules/
├── code-style.md   # 【TypeScriptの書き方】変更時のみ確認される
├── security.md     # 【認証・認可】セキュリティ関連ファイル編集時に確認
└── frontend/
    └── testing.md  # 【フロントのテスト戦略】テストコード作成時に参照

これにより、CLAUDE.md は「常に意識すべきコアシステム（人間だけが知っている暗黙知）」のみに保たれ、スマートなエージェント運用が可能になります。

プロジェクトタイプ別設定パターン¶

1. Webアプリケーション (React/Next.js)¶

## リポジトリ概要

このプロジェクトは [主要技術スタック] で構築された [プロジェクトタイプ] です。

### 主要機能
- 機能1: 説明
- 機能2: 説明
- 機能3: 説明

### 対象ユーザー
- メイン: [主要ユーザー層]
- サブ: [副次的ユーザー層]

### 開発状況
- 現在のフェーズ: [開発フェーズ]
- バージョン: [バージョン番号]
- 安定性: [安定性レベル]

2. 技術スタックと依存関係¶

## 技術スタック

### フロントエンド
- フレームワーク: React 18.2 with TypeScript
- UIライブラリ: Material-UI v5
- 状態管理: Redux Toolkit
- ビルドツール: Vite

### バックエンド
- ランタイム: Node.js 18 LTS
- フレームワーク: Express.js
- データベース: PostgreSQL 15
- ORM: Prisma

### インフラ
- ホスティング: AWS (EC2, RDS, S3)
- CI/CD: GitHub Actions
- 監視: DataDog
- コンテナ: Docker

3. 開発ガイドライン¶

## 開発ガイドライン

### コードスタイル
- **言語**: TypeScript（strictモード）
- **Lint**: ESLint（Airbnb設定）
- **フォーマット**: Prettier（2スペースインデント）
- **命名規則**:
  - コンポーネント: PascalCase（例: `UserProfile`）
  - 関数: camelCase（例: `getUserData`）
  - 定数: UPPER_SNAKE_CASE（例: `API_BASE_URL`）
  - ファイル: kebab-case（例: `user-profile.tsx`）

### Gitルール
- **ブランチ**: feature/*, bugfix/*, hotfix/*
- **コミット**: Conventional Commits形式
  - feat: 新機能
  - fix: バグ修正
  - docs: ドキュメント
  - style: コードスタイル
  - refactor: リファクタリング
  - test: テスト更新
  - chore: ビルド・ツール更新

### テスト要件
- 単体テスト: Jest（カバレッジ80%以上）
- 結合テスト: Cypress（主要フロー）
- パフォーマンス: Lighthouseスコア > 90

4. ワークフローとコマンド¶

## よく使うコマンド

### 開発
```bash
# 依存関係のインストール
npm install

# 開発サーバー起動
npm run dev

# テスト実行
npm test

# プロダクションビルド
npm run build

# ステージングデプロイ
npm run deploy:staging

# 本番デプロイ
npm run deploy:prod

データベース操作¶

# マイグレーション実行
npx prisma migrate dev

# Prismaクライアント生成
npx prisma generate

# テストデータ投入
npm run db:seed

# データベースリセット
npm run db:reset

コード品質¶

# Lint実行
npm run lint

# Lint自動修正
npm run lint:fix

# 型チェック
npm run type-check

# 全チェック実行
npm run check:all

## チェックリストの効果的な活用

### 機能開発チェックリスト

```markdown
## タスクチェックリスト

### 機能開発チェックリスト
- [ ] **要件確認**: 機能要件を理解する
- [ ] **デザイン確認**: UI/UXデザインをレビュー
- [ ] **実装計画**: 実装アプローチを策定
- [ ] **コード実装**: 機能コードを記述
- [ ] **単体テスト**: 網羅的な単体テストを作成
- [ ] **結合テスト**: 結合テストを追加
- [ ] **ドキュメント**: 関連ドキュメントを更新
- [ ] **コードレビュー**: PRを提出し承認を得る
- [ ] **QAテスト**: QAチームのテスト完了を確認
- [ ] **デプロイ**: 本番環境にデプロイ

### バグ修正チェックリスト
- [ ] **再現確認**: バグの再現手順を確認
- [ ] **根本原因分析**: 原因を特定
- [ ] **修正実装**: 修正を実装
- [ ] **回帰テスト**: 再発防止テストを追加
- [ ] **修正検証**: 修正で問題が解決されたことを確認
- [ ] **関連調査**: 類似の問題がないか確認
- [ ] **ドキュメント**: 必要に応じて更新
- [ ] **デプロイ**: 修正をリリース

### コードレビューチェックリスト
- [ ] **機能**: コードが意図通り動作する
- [ ] **テスト**: 十分なテストカバレッジ
- [ ] **パフォーマンス**: 性能劣化がない
- [ ] **セキュリティ**: セキュリティ脆弱性がない
- [ ] **スタイル**: コーディング規約に準拠
- [ ] **ドキュメント**: コードが適切に文書化されている
- [ ] **依存関係**: 不要な依存関係がない
- [ ] **破壊的変更**: 特定し文書化されている

実際のプロジェクト例¶

1. 技術ブログサイトの CLAUDE.md¶

# CLAUDE.md - 技術ブログ

## プロジェクト概要
Next.js + MDX で構築した技術ブログサイト。

## 記事作成ワークフロー

### 執筆前
- [ ] トピックを徹底的にリサーチ
- [ ] 既存の類似コンテンツを確認
- [ ] ターゲット読者を定義
- [ ] 記事のアウトラインを作成

### 執筆
- [ ] MDXファイルを作成
- [ ] コード例を追加
- [ ] OGP画像を生成
- [ ] 関連記事リンクを追加

### 品質確認
- [ ] 文法・誤字チェック
- [ ] 全コード例をテスト
- [ ] 全リンクを検証
- [ ] モバイル表示を確認

### デプロイ
- [ ] git add, commit, push
- [ ] Vercelプレビューで確認
- [ ] 本番デプロイを確認
- [ ] 検索インデックスを確認

## よく使うコマンド

```bash
# ローカル開発
npm run dev

# プロダクションビルド
npm run build

# ビルド済みサイトをプレビュー
npm run start

### 2. API プロジェクトの CLAUDE.md

```markdown
# CLAUDE.md - REST APIプロジェクト

## アーキテクチャ概要

src/ ├── controllers/ # リクエストハンドラ ├── services/ # ビジネスロジック ├── models/ # データモデル ├── middleware/ # Expressミドルウェア ├── utils/ # ヘルパー関数 └── config/ # 設定ファイル

## API開発ガイドライン

### エンドポイント命名規則
- 動詞ではなく名詞を使用
- コレクションは複数形
- 複合語はkebab-case

例:
- GET /api/users
- GET /api/users/:id
- POST /api/users
- GET /api/user-profiles

### レスポンスフォーマット
```json
{
  "success": true,
  "data": {},
  "error": null,
  "metadata": {
    "timestamp": "2024-01-01T00:00:00Z",
    "version": "1.0.0"
  }
}

エラーハンドリング¶

// 常にこのエラー形式を使用
throw new AppError('エラーメッセージ', 400, 'ERROR_CODE');

テスト要件¶

全エンドポイントに以下が必要: 1. ビジネスロジックの単体テスト 2. APIエンドポイントの結合テスト 3. 性能重要エンドポイントの負荷テスト

セキュリティチェックリスト¶

全エンドポイントで入力バリデーション
認証必須（公開エンドポイントを除く）
レートリミット実装済み
SQLインジェクション対策
XSS対策

CORS適切に設定済み

### 3. フロントエンドプロジェクトの CLAUDE.md

```markdown
# CLAUDE.md - Reactアプリケーション

## コンポーネント開発

### コンポーネント構成
```typescript
// components/UserProfile/UserProfile.tsx
import React from 'react';
import { UserProfileProps } from './UserProfile.types';
import { useUserProfile } from './UserProfile.hooks';
import styles from './UserProfile.module.css';

export const UserProfile: React.FC<UserProfileProps> = ({ userId }) => {
  const { user, loading, error } = useUserProfile(userId);

  // コンポーネントロジック
};

状態管理ルール¶

UIのみの状態はローカルuseState
コンポーネント間の状態はContext
グローバルなアプリケーション状態はRedux
サーバー状態はReact Query

パフォーマンスガイドライン¶

高コストコンポーネントにReact.memoを使用
長いリストには仮想スクロールを実装
ルートと重いコンポーネントはレイジーロード
画像は次世代フォーマットで最適化

アクセシビリティ要件¶

全コンポーネントに必須: - [ ] 適切なARIAラベル - [ ] キーボードナビゲーション対応 - [ ] WCAG 2.1 AA準拠 - [ ] 自動a11yテスト合格 - [ ] スクリーンリーダーテスト済み

CSSガイドライン¶

/* CSS Modulesを使用 */
.container {
  /* モバイルファーストアプローチ */
  padding: 1rem;

  @media (min-width: 768px) {
    padding: 2rem;
  }
}

/* CSS変数でテーマ管理 */
.button {
  background-color: var(--primary-color);
  color: var(--text-on-primary);
}

## 💡 ベストプラクティス

### 1. 明確で実行可能な指示

```markdown
# Good ✅
## ファイル命名規則
- コンポーネント: PascalCase（例: UserProfile.tsx）
- ユーティリティ: camelCase（例: formatDate.ts）
- テスト: *.test.ts または *.spec.ts

# Bad ❌
## ファイル命名規則
ファイルは適切に命名してください。

2. 具体的なコード例¶

# Good ✅
## エラーハンドリングパターン
```typescript
try {
  const result = await apiCall();
  return { success: true, data: result };
} catch (error) {
  logger.error('API呼び出し失敗', { error, context });
  return { success: false, error: error.message };
}

Bad ❌¶

エラーハンドリング¶

エラーを適切に処理してください。

### 3. チェックリストの活用

```markdown
# Good ✅
## PRチェックリスト
- [ ] ローカルでテスト合格
- [ ] console.logが残っていない
- [ ] ドキュメント更新済み
- [ ] Changelogエントリ追加済み
- [ ] パフォーマンス影響を評価済み

# Bad ❌
## PR要件
提出前に全体を確認してください。

🔧 よくある問題とトラブルシューティング¶

❌ "Claude CodeがCLAUDE.mdを認識しない"¶

原因と解決策:

# 1. ファイル名確認（最も多い原因）
ls -la CLAUDE.md      # ✅ 正しい
ls -la calude.md      # ❌ スペルミス
ls -la claud.md       # ❌ スペルミス  
ls -la claude.md      # ⚠️ 小文字（環境によっては動作しない）

# 2. ファイル権限確認
chmod 644 CLAUDE.md

# 3. 文字エンコーディング確認
file CLAUDE.md        # UTF-8になっているか確認

❌ "日本語文字化け"¶

解決策:

# UTF-8で保存されているか確認
file -i CLAUDE.md

# BOM無しUTF-8で再保存
# VS Code: 右下の「UTF-8」→「UTF-8 with BOM」→「UTF-8」に戻す

❌ "ファイルが長すぎて効果がない"¶

解決策:

# ❌ 悪い例：すべてを1ファイルに詰め込む
CLAUDE.md (5000行)

# ✅ 良い例：参照パターンを使用
CLAUDE.md (簡潔) → docs/detailed-guide.md (詳細)

❌ "チーム間で内容が異なる"¶

解決策:

# Git管理で統一
git add CLAUDE.md
git commit -m "Standardize CLAUDE.md across team"

# 定期的な同期確認
git log --oneline CLAUDE.md

🔍 CLAUDE.md認知度向上のために¶

検索でよく間違われるパターン¶

間違い	正しい	原因
`calude.md`	`CLAUDE.md`	文字順序ミス
`claud.md`	`CLAUDE.md`	最後の"E"抜け
`claude .md`	`CLAUDE.md`	スペース挿入
`claude.md`	`CLAUDE.md`	大文字小文字

プロジェクトでの認知度向上施策¶

# README.mdに明記
## 📋 プロジェクト設定ファイル
このプロジェクトでは `CLAUDE.md` ファイルでAI支援を最適化しています。

# プルリクエストテンプレートに追加
## チェックリスト
- [ ] CLAUDE.mdの内容を更新（必要に応じて）

# VS Code設定での認識向上
# .vscode/settings.json
{
  "files.associations": {
    "CLAUDE.md": "markdown"
  }
}

🔄 継続的な改善¶

1. 定期的なレビュー¶

## メンテナンススケジュール

### 毎週
- タスクチェックリストのレビューと更新
- 古い依存関係の確認
- エラーログのレビュー

### 毎月
- ドキュメントの更新
- ガイドラインのレビューと改善
- コードメトリクスの分析

### 四半期ごと
- メジャー依存関係の更新
- アーキテクチャレビュー
- パフォーマンス監査

2. フィードバックの収集¶

## フィードバック収集

### 開発者フィードバック
- どのガイドラインが不明確か？
- どのタスクが繰り返し作業か？
- どのツールが不足しているか？

### AIパフォーマンス
- 成功完了率を追跡
- よくあるミスを特定
- 時間削減を測定

### 改善アイデア
- [ ] コード例を追加
- [ ] 動画チュートリアルを作成
- [ ] カスタムツールを構築

📋 よく使われるCLAUDE.mdテンプレート集¶

🔥 最小構成テンプレート（初心者向け）¶

cat << 'EOF' > CLAUDE.md
# CLAUDE.md

## プロジェクト概要
- プロジェクト名: [名前]
- 技術スタック: [技術]
- 開発ルール: [ルール]

## よく使うコマンド
```bash
npm run dev    # 開発サーバー
npm test       # テスト実行
npm run build  # ビルド

EOF

### ⚡ React/Next.js テンプレート

```bash
cat << 'EOF' > CLAUDE.md
# CLAUDE.md

## プロジェクト概要
Next.js 14 + TypeScript + Tailwind CSS プロジェクト

## 開発ガイドライン
- TypeScript strict モード使用
- コンポーネント名: PascalCase
- ファイル名: kebab-case
- CSS: Tailwind CSS使用（inline style禁止）

## コマンド
```bash
npm run dev        # 開発サーバー (http://localhost:3000)
npm run build      # プロダクションビルド
npm run lint       # ESLint実行
npm run type-check # TypeScript型チェック

ディレクトリ構成¶

src/
├── components/    # 再利用可能コンポーネント
├── pages/        # Next.jsページ
├── hooks/        # カスタムフック
├── utils/        # ユーティリティ関数
└── types/        # TypeScript型定義

EOF

### 🛠️ API/バックエンド テンプレート

```bash
cat << 'EOF' > CLAUDE.md
# CLAUDE.md

## プロジェクト概要
Node.js + Express + PostgreSQL REST API

## 開発ガイドライン
- エラーハンドリング必須実装
- 全エンドポイントにvalidation追加
- レスポンス形式統一
- JWT認証使用

## API設計規則
```typescript
// 成功レスポンス
{ "success": true, "data": {...} }

// エラーレスポンス  
{ "success": false, "error": "message", "code": "ERROR_CODE" }

コマンド¶

npm run dev        # 開発サーバー
npm run test       # テスト実行
npm run db:migrate # DB マイグレーション
npm run db:seed    # テストデータ投入

EOF

### 📱 Vue.js テンプレート

```bash
cat << 'EOF' > CLAUDE.md
# CLAUDE.md

## プロジェクト概要
Vue 3 + Composition API + Pinia + TypeScript

## 開発ガイドライン
- `<script setup>` 構文使用
- Composition API推奨
- Pinia でグローバル状態管理
- Vue Router でルーティング

## コンポーネント規則
- Props: TypeScriptインターフェース定義
- Events: defineEmitsで明示的定義
- ファイル名: PascalCase.vue

## コマンド
```bash
npm run dev     # 開発サーバー
npm run build   # プロダクションビルド  
npm run test    # Vitest実行
npm run lint    # ESLint + Prettier

EOF ```

🎓 学習リソース¶

推奨記事¶

外部リソース¶

🚀 次のステップ¶

既存プロジェクトへの適用: 現在のプロジェクトに CLAUDE.md を追加
チームでの共有: チームメンバーと内容をレビュー
継続的な改善: 使用しながら内容を洗練
効果測定: 生産性向上を定量的に測定

CLAUDE.md実践ガイド - プロジェクト別設定パターン¶

この記事で学べること¶

前提知識¶

🧠 2025年最新：階層メモリシステム¶

階層構造の理解¶

Memory Import機能¶

ショートカット活用¶

Auto Memory（自動学習）について¶

.claude/rules/ による条件付きルールのモジュール化¶

プロジェクトタイプ別設定パターン¶

1. Webアプリケーション (React/Next.js)¶

2. 技術スタックと依存関係¶

3. 開発ガイドライン¶

4. ワークフローとコマンド¶

データベース操作¶

コード品質¶

実際のプロジェクト例¶

1. 技術ブログサイトの CLAUDE.md¶

エラーハンドリング¶

テスト要件¶

セキュリティチェックリスト¶

状態管理ルール¶

パフォーマンスガイドライン¶

アクセシビリティ要件¶

CSSガイドライン¶

2. 具体的なコード例¶

Bad ❌¶

エラーハンドリング¶

🔧 よくある問題とトラブルシューティング¶

❌ "Claude CodeがCLAUDE.mdを認識しない"¶

❌ "日本語文字化け"¶

❌ "ファイルが長すぎて効果がない"¶

❌ "チーム間で内容が異なる"¶

🔍 CLAUDE.md認知度向上のために¶

検索でよく間違われるパターン¶

プロジェクトでの認知度向上施策¶

🔄 継続的な改善¶

1. 定期的なレビュー¶

2. フィードバックの収集¶

📋 よく使われるCLAUDE.mdテンプレート集¶

🔥 最小構成テンプレート（初心者向け）¶

ディレクトリ構成¶

コマンド¶

🎓 学習リソース¶

推奨記事¶

外部リソース¶

🚀 次のステップ¶

`.claude/rules/` による条件付きルールのモジュール化¶