はじめに：設定ファイルは「アーキテクチャ」として設計する

CLAUDE.mdは書いている。でも.claude/ディレクトリ全体を「設定のアーキテクチャ」として設計している人はまだ少ない。

この記事では、.claude/ディレクトリを構成するCLAUDE.md・hooks・カスタムコマンド・settingsを連携させ、ソロ開発からモノレポ大規模構成まで対応する3つの設計パターンを紹介します。読み終わる頃には、あなたのプロジェクトに最適な.claude/構成が見えているはずです。

環境・前提条件

Claude Code: 最新版（CLI）
Node.js: 18以上（hooks内でlint/type-checkを動かす場合）
OS: macOS / Linux（Windowsでも概ね同様）
Claude Code のプロジェクトルートに.claude/ディレクトリを配置できる状態

前提：.claude/ディレクトリ構成の全体像

まず、.claude/ディレクトリに配置できるファイル群とその役割を整理します。

ファイル / ディレクトリ	役割
`CLAUDE.md`（プロジェクトルート）	Claude Codeが最初に読み込むプロジェクトコンテキスト。コーディング規約・技術スタック・禁止事項などを記述
`.claude/settings.json`	プロジェクトスコープの設定（許可するツール等）
`.claude/commands/`	カスタムスラッシュコマンドの定義ファイル（`.md`形式）
`.claude/hooks/`	Claude Code の各ライフサイクルイベントに対応するスクリプト群
サブディレクトリの`CLAUDE.md`	親のCLAUDE.mdに追加・上書きするコンテキスト（モノレポ向け）

全体像：ファイル構成と動作フェーズの関係

各ファイルがどのフェーズに影響するかを意識して配置することが、設定アーキテクチャの第一歩です。

パターン①：ソロ開発向けミニマル構成

一人で開発するプロジェクトなら、最小限の構成で十分です。

project-root/
├── CLAUDE.md
└── .claude/
    └── commands/
        ├── review.md
        ├── test-gen.md
        └── doc.md

CLAUDE.md の記述例（ミニマル版）

# プロジェクト概要
個人ブログのNext.js + TypeScriptプロジェクト。

# 技術スタック
- Next.js 15 (App Router)
- TypeScript 5.x
- Tailwind CSS v4

# コーディング規約
- 関数コンポーネントのみ使用
- `any`型は禁止
- ファイル名はkebab-case

ポイント： ソロ開発では「自分の記憶にないこと」だけ書けば十分です。技術スタックとファイル命名規則、禁止事項を3〜5項目に絞りましょう。カスタムコマンドを3つ用意しておけば、日常作業のほとんどはカバーできます。

パターン②：チーム開発向け標準構成

チーム開発では、メンバー間で暗黙知になりがちなルールをCLAUDE.mdに明文化し、settings.jsonで危険な操作をガードします。

project-root/
├── CLAUDE.md
└── .claude/
    ├── settings.json
    ├── commands/
    │   ├── review.md
    │   ├── test-gen.md
    │   ├── doc.md
    │   └── migration-check.md
    └── hooks/
        └── PostToolUse/
            └── lint-check.sh

CLAUDE.md の記述例（チーム版）

# プロジェクト概要
BtoB SaaSのバックエンドAPI。チーム4名で開発中。

# 技術スタック
- Go 1.23 / Echo v4
- PostgreSQL 16
- Docker Compose で開発環境構築

# コーディング規約
- エラーハンドリング: 必ず errors.Wrap でスタックトレースを付与
- DB操作: Repositoryパターンを使用（直接SQLを書かない）
- API レスポンス: 共通レスポンス構造体を使う（pkg/response参照）

# レビュー基準
- テストカバレッジ: 新規コードは80%以上
- N+1クエリの検出を最優先で確認

# 禁止操作
- mainブランチへの直接push禁止
- マイグレーションファイルの手動編集禁止
- 本番環境の環境変数をコード中にハードコード禁止

settings.json の設定例

{
  "permissions": {
    "allow": [
      "Bash(go build:*)",
      "Bash(go test:*)",
      "Bash(go vet:*)",
      "Bash(docker compose:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push origin main:*)",
      "Bash(DROP TABLE:*)"
    ]
  }
}

settings.jsonで破壊的コマンドを明示的にブロックしておくと、Claude Codeが誤って危険な操作を実行するリスクを減らせます。

パターン③：モノレポ大規模構成

モノレポでは、サブディレクトリごとにCLAUDE.mdを配置して、技術スタックの違いをClaude Codeに正確に伝えます。

monorepo-root/
├── CLAUDE.md                          # 共通ルール
├── .claude/
│   ├── settings.json
│   ├── commands/
│   │   ├── review.md
│   │   ├── test-gen.md
│   │   └── deploy-check.md
│   └── hooks/
│       └── PostToolUse/
│           └── lint-and-typecheck.sh
├── apps/
│   ├── web/
│   │   ├── CLAUDE.md                  # フロントエンド固有ルール
│   │   └── ...
│   └── api/
│       ├── CLAUDE.md                  # バックエンド固有ルール
│       └── ...
└── packages/
    └── shared/
        ├── CLAUDE.md                  # 共有パッケージのルール
        └── ...

子ディレクトリのCLAUDE.mdはルートのCLAUDE.mdに追加される形で読み込まれます。 ルートには全サブプロジェクト共通のルール（Gitコミット規約、CI設定など）を書き、各サブディレクトリには技術スタック固有のルールだけを書きましょう。

サブディレクトリCLAUDE.md例（apps/web/）

# フロントエンド固有ルール

このディレクトリはNext.js App Routerのフロントエンドアプリです。

# 技術スタック
- Next.js 15 (App Router)
- React 19
- Tailwind CSS v4
- Storybook 8

# コーディング規約
- コンポーネントはserver componentをデフォルトにする
- "use client"は最小限のコンポーネントにのみ付与
- 状態管理はnuqsを使用（useStateの直接利用は限定的に）
- スタイリングはTailwind CSSのみ（styled-components等は禁止）

# ディレクトリ構造
- app/ → ルーティング・ページ
- components/ → 再利用可能コンポーネント
- lib/ → ユーティリティ関数

hooks活用術：PostToolUseでlint・type-checkを自動パイプ

Claude Code の hooks 機能を使うと、コード編集後に自動でlint・type-checkを実行し、問題があればClaude Codeにフィードバックできます。

hooks の設定（settings.json 内）

hooks は .claude/settings.json のトップレベルに設定します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": ".claude/hooks/lint-and-typecheck.sh $CLAUDE_FILE_PATH"
      }
    ]
  },
  "permissions": {
    "allow": [
      "Bash(npm run lint:*)",
      "Bash(npx tsc:*)"
    ]
  }
}

lint-and-typecheck.sh の実装例

#!/bin/bash
# .claude/hooks/lint-and-typecheck.sh
# PostToolUse (Write|Edit) で呼ばれるスクリプト

FILE_PATH="$1"

# ファイル拡張子に応じた処理
case "$FILE_PATH" in
  *.ts|*.tsx)
    echo "=== TypeScript type-check ==="
    npx tsc --noEmit --pretty 2>&1 | head -30

    echo "=== ESLint ==="
    npx eslint "$FILE_PATH" --format compact 2>&1 | head -20
    ;;
  *.go)
    echo "=== Go vet ==="
    go vet ./... 2>&1 | head -20

    echo "=== golangci-lint ==="
    golangci-lint run "$FILE_PATH" 2>&1 | head -20
    ;;
esac

exit 0

hooksのstdoutに出力された内容はClaude Codeにフィードバックされます。 エラーがあればClaude Codeが自動的に修正を試みるため、「書く→チェック→直す」のループが自動化されます。

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

.claude/commands/ にMarkdownファイルを配置すると、/project: プレフィックス付きのカスタムスラッシュコマンドとして使えます。

/project:review（コードレビュー）

.claude/commands/review.md:

以下のファイルのコードレビューを行ってください。

## レビュー観点
1. **バグリスク**: null/undefined チェック漏れ、境界値処理、エラーハンドリング
2. **パフォーマンス**: N+1クエリ、不要な再レンダリング、メモリリーク
3. **セキュリティ**: SQLインジェクション、XSS、認証/認可の漏れ
4. **可読性**: 命名の適切さ、関数の責務分離、コメントの過不足

## 出力フォーマット
- 重大度: 🔴 Critical / 🟡 Warning / 🔵 Suggestion
- 各指摘には修正案のコード例を含めてください

対象: $ARGUMENTS

使い方：/project:review src/services/user-service.ts

/project:test-gen（テスト自動生成）

.claude/commands/test-gen.md:

指定されたファイルのユニットテストを生成してください。

## テスト方針
- テストフレームワーク: このプロジェクトで使われているものを自動検出
- カバレッジ目標: 分岐網羅（Branch Coverage）を重視
- テストケース: 正常系2〜3件、異常系2〜3件、境界値1〜2件
- モック: 外部依存は適切にモック化

## 命名規則
- テストファイル: `対象ファイル名.test.{ts,go}` として同階層に配置
- テスト名: 「何を」「どういう条件で」「どうなるか」が分かる名前

対象: $ARGUMENTS

/project:doc（ドキュメント生成）

.claude/commands/doc.md:

指定された対象のドキュメントを生成してください。

## ドキュメント種類（$ARGUMENTSの内容から判断）
- ファイル指定 → JSDoc/GoDoc コメントを追加
- ディレクトリ指定 → README.md を生成
- API指定 → OpenAPI 形式のスキーマを生成

## スタイル
- 日本語で記述
- コード例を必ず含める
- 「なぜそうしているか」の設計意図も記述

対象: $ARGUMENTS

$ARGUMENTS にはスラッシュコマンド実行時に続けて入力したテキストが展開されます。

アンチパターン：CLAUDE.mdに書きすぎると精度が下がる

CLAUDE.mdは強力ですが、情報を詰め込みすぎると逆効果です。

❌ よくある失敗パターン

アンチパターン	問題
CLAUDE.mdが500行以上	コンテキストウィンドウを圧迫し、肝心のコードへの注意力が下がる
自明なルールの列挙（「変数名は意味のある名前にする」等）	ノイズが増え、重要なルールが埋もれる
コード例を大量に貼り付け	CLAUDE.mdの役割は「方針」であり、「教科書」ではない
矛盾するルールの併存	Claude Codeがどちらを優先すべきか判断できず不安定に

✅ 最適な情報量の目安

ルート CLAUDE.md: 100〜200行以内
サブディレクトリ CLAUDE.md: 30〜80行以内
ルールの数: 1つのCLAUDE.mdにつき15項目以内
判断基準: 「このルールがないとClaude Codeが間違った判断をするか？」をセルフチェック

迷ったら削る方向で調整してください。Claude Codeは一般的なベストプラクティスをすでに知っています。あなたのプロジェクト固有の「普通と違うルール」だけを書くのが最適解です。

テンプレートリポジトリ：すぐ使える.claude/スターター構成

以下は、すぐにコピーして使えるスターター構成です。プロジェクトの規模に応じて選んでください。

ミニマル版（ソロ開発）

.claude/
└── commands/
    ├── review.md       # コードレビュー
    ├── test-gen.md     # テスト生成
    └── doc.md          # ドキュメント生成
CLAUDE.md               # 50〜100行

スタンダード版（チーム開発）

.claude/
├── settings.json       # 許可/拒否リスト
├── commands/
│   ├── review.md
│   ├── test-gen.md
│   ├── doc.md
│   └── migration-check.md
└── hooks/
    └── PostToolUse/
        └── lint-check.sh
CLAUDE.md                # 100〜200行

モノレポ版

.claude/
├── settings.json
├── commands/
│   ├── review.md
│   ├── test-gen.md
│   ├── doc.md
│   └── deploy-check.md
└── hooks/
    └── PostToolUse/
        └── lint-and-typecheck.sh
CLAUDE.md                           # 共通ルール（100行以内）
apps/web/CLAUDE.md                  # FE固有（50行以内）
apps/api/CLAUDE.md                  # BE固有（50行以内）
packages/shared/CLAUDE.md           # 共有ライブラリ固有（30行以内）

これらの構成をベースに、自分のプロジェクトのワークフローに合わせてカスタマイズしていくのがおすすめです。

まとめ

.claude/ディレクトリは「設定のアーキテクチャ」として設計する。 CLAUDE.md単体ではなく、settings.json・commands・hooksを組み合わせて、初期化から後処理まで一貫した制御を行いましょう。
プロジェクト規模に応じて3段階の構成パターンを選択する。 ソロ開発ならCLAUDE.md+コマンド3つで十分。チーム開発ではsettings.jsonで安全策を、モノレポではサブディレクトリCLAUDE.mdで文脈を分割しましょう。
CLAUDE.mdは「引き算」で最適化する。 プロジェクト固有の「普通と違うルール」だけを書く。100〜200行を上限の目安にして、書きすぎによる精度低下を防ぎましょう。

参考リンク