Claude Codeのプロジェクト設定（.claude/）完全ガイド

プロジェクト設定の全体像

Claude Codeは、プロジェクトごとにカスタマイズされた設定を持つことができます。これにより、プロジェクトの規約や制約をClaude Codeに自動的に理解させ、チーム全体で統一的な開発体験を実現できます。

設定は主に2つの仕組みで管理されます。

2つの設定メカニズム

仕組み	ファイル	主な用途
CLAUDE.md	プロジェクトルートの `CLAUDE.md`	プロジェクトの文脈、ルール、ガイダンスを自然言語で記述
.claude/ディレクトリ	`.claude/settings.json` 等	権限設定、ツール制御などを構造化データで記述

CLAUDE.md ― プロジェクトの「説明書」

CLAUDE.mdとは

CLAUDE.mdは、プロジェクトルートに配置するマークダウンファイルです。Claude Codeはセッション開始時にこのファイルを自動的に読み込み、プロジェクトの文脈を理解します。

CLAUDE.mdに書くべき内容

1. プロジェクト概要

# CLAUDE.md

## プロジェクト概要
ECサイトのバックエンドAPI。
Next.js 14 App Router + Prisma + PostgreSQL構成。

2. 技術スタック

## 技術スタック
- フレームワーク: Next.js 14 (App Router)
- 言語: TypeScript 5.x (strict mode)
- ORM: Prisma
- DB: PostgreSQL 16
- テスト: Vitest + Testing Library
- CI: GitHub Actions

3. コーディング規約

## コーディング規約
- 関数コンポーネントとReact Hooksを使用
- classコンポーネントは使用しない
- エラーハンドリングにはResult型パターンを使用
- 日本語コメントを推奨
- ファイル名はkebab-caseを使用

4. ディレクトリ構成

## ディレクトリ構成
src/
  app/          # Next.js App Routerのルート
  components/   # 共通コンポーネント
  lib/          # ユーティリティ・ヘルパー
  services/     # ビジネスロジック
  types/        # 型定義
prisma/         # Prismaスキーマとマイグレーション
tests/          # テストファイル

5. 重要な注意事項

## 重要な注意事項
- .envファイルは絶対にコミットしない
- DBマイグレーションは必ずレビューを通す
- main ブランチへの直接pushは禁止
- テストカバレッジ80%以上を維持

/init コマンドで自動生成

/initコマンドを使うと、Claude Codeがプロジェクトを分析してCLAUDE.mdの雛形を自動生成してくれます。

使用方法

# Claude Codeのセッション内で
/init

自動生成された内容をベースに、プロジェクト固有のルールや規約を追加・修正していくのがおすすめです。

.claude/ディレクトリ ― 構造化された設定

ディレクトリ構成

.claude/
├── settings.json        # プロジェクト共有設定（Gitにコミット）
├── settings.local.json  # 個人ローカル設定（.gitignore対象）
└── worktrees/           # ワークツリー用ディレクトリ

settings.json ― プロジェクト共有設定

チーム全体で共有する設定を記述します。このファイルはGitにコミットして共有します。

settings.jsonの例

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run build)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(npm publish)"
    ]
  }
}

settings.local.json ― 個人設定

個人的な設定のカスタマイズに使用します。.gitignoreに追加してGit管理から除外すべきファイルです。

settings.local.jsonの例

{
  "permissions": {
    "allow": [
      "Edit",
      "Write",
      "Bash(docker *)"
    ]
  }
}

グローバル設定

すべてのプロジェクトに適用されるグローバル設定は、ホームディレクトリの~/.claude/settings.jsonに配置します。

グローバル設定の例

# ~/.claude/settings.json
{
  "permissions": {
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf /)"
    ]
  }
}

設定の優先順位

設定は以下の順序で適用されます（上位が優先）

コマンドライン引数（--allowedTools 等）
.claude/settings.local.json（個人ローカル設定）
.claude/settings.json（プロジェクト共有設定）
~/.claude/settings.json（グローバル設定）
デフォルト設定

deny（拒否）ルールはallow（許可）ルールより常に優先されます。つまり、上位レベルで許可されていても、下位レベルで拒否されていれば、そのツールは使用できません。

メモリ機能 ― セッション横断の情報共有

Claude Codeには/memoryコマンドでアクセスできるメモリ機能があります。これはCLAUDE.mdとは別の仕組みで、ユーザーごとの作業メモを保存できます。

メモリの活用例

# セッション中に/memoryを実行すると、
# 以下のような情報を記録・参照できます

## デプロイ手順
1. npm run build を実行
2. tests が全パスすることを確認
3. staging環境にデプロイ

## 既知の問題
- ログインページのCSS崩れ（Issue #42）
- APIレスポンスのキャッシュ問題（調査中）

チーム開発でのベストプラクティス

推奨セットアップ

CLAUDE.md: プロジェクトの規約・構成・注意事項を記載し、Gitにコミット
.claude/settings.json: チーム共通の権限設定を記載し、Gitにコミット
.claude/settings.local.json: 個人の追加設定用。.gitignoreに追加
.gitignore: .claude/settings.local.json と .claude/worktrees/ を除外
/init: 新しいプロジェクトの初期設定に活用
/memory: 個人の作業メモや手順を保存