Posted in人工知能

.claude/ディレクトリ構成ガイド：小規模から大規模プロジェクトまで

Artificial Intelligence tutorial - IT technology blog
Artificial Intelligence tutorial - IT technology blog

問題：Claudeはセッション間で何も「覚えていない」

約3ヶ月前からPythonプロジェクトでClaude Codeを使い始めました。最初は毎回ターミナルを開くたびに説明し直す必要がありました。「このプロジェクトはFastAPIを使っていて、データベースはPostgreSQL、命名規則はsnake_case、テストファイルは別途作らないで…」と。正直、疲れました。

数週間格闘してようやく気づいたのは、.claude/ディレクトリをまったく活用していなかったということ。このディレクトリはまさにこの問題を解決するために設計されたものです。

.claude/を適切に設定していない場合の典型的な症状：

  • 毎日同じコードスタイルのルールをClaudeに伝え直す必要がある
  • すでにプロジェクトに存在するライブラリの追加をClaudeが提案する
  • チームメンバーそれぞれが異なる方法でClaudeを使い、出力が一貫しない
  • テストの実行コマンドやビルド方法をClaudeが知らない

原因：Claude Codeはコンテキストベースで動作し、デフォルトでは「長期記憶」がない

Claude Codeは過去の会話を自動的に記憶しません。各セッションは白紙の状態から始まります。新しくチームに加わったエンジニアとは違います。彼らはREADMEを読んだり、同僚に聞いたりしながら徐々にプロジェクトを理解していけます。Claudeは毎セッションの最初から構造化された「ブリーフィング」が必要です。

ディレクトリ内で起動すると、Claude Codeは優先順位に従って設定ファイルを自動的に読み込みます：ホームのCLAUDE.md → プロジェクトルートのCLAUDE.md → .claude/内のファイル。コードの規約からよく使うコマンドまで、「長期記憶」はすべてここに格納されています。CLAUDE.mdがどのようにClaudeのプロジェクト把握を助けるかについて、より詳細な解説も参考にしてください。

.claude/の構成：シンプルから複雑まで

レベル1：個人プロジェクト（ソロ）

一人で開発するプロジェクトなら、ルートにCLAUDE.mdファイルを置くだけで十分です。Claudeはこのファイルを最初に、自動的に読み込みます。

# 最小構成
my-project/
├── CLAUDE.md          ← メインファイル、Claudeが自動的に読み込む
├── src/
└── ...

小規模プロジェクトのCLAUDE.mdの内容：

# Project Context

## Stack
- Python 3.11, FastAPI, SQLAlchemy 2.0
- PostgreSQL (local: localhost:5432/mydb)
- Alembic for migrations

## 規約
- 変数/関数名: snake_case
- クラス名: PascalCase
- `print()`は使わない — `logging`モジュールを使用
- すべてのAPIエンドポイントに完全な型ヒントが必要

## よく使うコマンド
- 開発サーバー起動: `uvicorn app.main:app --reload`
- テスト実行: `pytest tests/ -v`
- マイグレーション作成: `alembic revision --autogenerate -m "説明"`

簡潔ですが、Claudeが間違ったスタックを提案したり、規約外のコードを生成したりするのを防ぐには十分です。

レベル2：中規模プロジェクト（settingsとcommandsを追加）

より複雑なプロジェクトでは、Claudeの動作を制御するsettings.jsonと、カスタムスラッシュコマンドを保存するcommands/ディレクトリが必要になります。

# レベル2の構成
my-project/
├── CLAUDE.md
├── .claude/
│   ├── settings.json      ← パーミッション、フックの設定
│   └── commands/
│       ├── review.md      ← /project:review
│       └── deploy.md      ← /project:deploy

.claude/settings.jsonでClaudeが実行できる操作を制限できます：

{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(pytest:*)",
      "Bash(uvicorn:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ]
  }
}

.claude/commands/review.mdのカスタムコマンド：

---
description: コミット前にコード変更をレビューする
---

`git diff HEAD`の変更内容を以下の基準でレビューしてください：
1. 命名規約に違反していないか？
2. エラーハンドリングが不足している箇所はないか？
3. N+1クエリが発生していないか？
4. 型ヒントは完全に記述されているか？

実際の問題のみ報告し、不要なリファクタリングは提案しないこと。

Claude Codeで/project:reviewと入力するだけで呼び出せます。毎回すべての要件を入力し直す必要はありません。カスタムスラッシュコマンドでワークフローを最適化する方法についても詳しく解説しています。

レベル3：チームプロジェクト（複数環境・複数メンバー）

多くのチームが見落としているレベルです。これが原因で開発者間でClaudeの出力が一致しなくなります。

# チームスケールの構成
my-project/
├── CLAUDE.md                  ← チーム共通のコンテキスト（gitにコミット）
├── .claude/
│   ├── settings.json          ← 共有パーミッション（gitにコミット）
│   ├── settings.local.json    ← 個人用オーバーライド（.gitignoreに追加）
│   └── commands/
│       ├── review.md
│       ├── test.md
│       ├── migration.md
│       └── deploy-staging.md

重要なポイント：settings.jsonはチーム全員が共有するためgitにコミットします。settings.local.jsonは個人のマシン固有の設定（独自のAPIキー、パスなど）を他のメンバーに影響を与えずにオーバーライドできます。

# .gitignoreに追加
.claude/settings.local.json
.claude/memory/    # auto memoryを使用する場合

チーム向けのCLAUDE.mdには、明確なオンボーディングセクションを追加すべきです：

# Project: E-commerce Platform

## アーキテクチャ概要
- Backend: FastAPI (port 8000)
- Frontend: Next.js (port 3000)  
- Database: PostgreSQL + Redis
- Message queue: RabbitMQ

## 重要なルール
- データベーススキーマを勝手に変更しない — 必ずマイグレーションを作成
- 認証情報をハードコードしない — 環境変数を使用
- 新しいエンドポイントにはインテグレーションテストが必須
- PRはマージ前にCIを通過させること

## 環境
- Dev: `docker-compose up -d`
- Test: `pytest tests/ --cov=app --cov-report=term`
- Stagingデプロイ: `/project:deploy-staging`

## 連絡先
- DBスキーマの質問: Slackの@dbteamへ
- インフラ: docs/infrastructure.mdを参照

ベストプラクティス：段階的に.claude/を構築する

最初からフル構成をセットアップするのは得策ではありません。時間がかかる上に、本当に必要なものがわからないからです。以下の順序で進めるのがベターです：

  1. 1週目：スタックと最重要ルール3〜5個でCLAUDE.mdを作成。それだけでOK。
  2. 2〜3週間後：Claudeに繰り返し伝えていることに注目し、CLAUDE.mdに追加していく。
  3. よく使うパターンができたら：毎回手入力する代わりにカスタムコマンドを作成。
  4. チームが参加したら：settings.local.jsonを分離し、CLAUDE.mdにオンボーディングセクションを追加。

個人的によく使っているコツ：スプリントごとに10分かけて、Claudeがミスしたことや何度も指摘が必要だったことを振り返り、CLAUDE.mdをその場で更新する。このファイルはREADMEと同様に「生きたドキュメント」として扱うべきです。古くなればClaudeのパフォーマンスも低下します。

.claude/が機能しているか確認する

# ClaudeがCLAUDE.mdを読み込んでいるか確認
# Claude Codeで直接質問する：
"このプロジェクトはどんなスタックを使っていますか？テストの実行コマンドは？"

# Claudeが正しく答えた → CLAUDE.mdが読み込まれている
# Claudeが知らない → ファイルの場所とエンコーディングを確認（UTF-8必須）

よくあるミス

  • CLAUDE.mdが長すぎる：500行超でもClaudeは読めますが、コンテキストが薄まり重要な情報が埋もれます。重要な情報を先頭に置くことを優先してください。
  • 曖昧な表現を使う：「きれいなコードを書いて」は効果がありません。「関数は最大50行、各関数は1つのことだけを行う」のように具体的に書いてください。
  • .gitignoreへの追加を忘れる：settings.local.jsonには個人情報が含まれます。コミットすると情報が漏洩します。
  • CLAUDE.mdをバージョン管理しない：このファイルはプロジェクトとともに変化します。通常のコードと同様に履歴を追跡してください。

実際の成果

.claude/を適切にセットアップした後、毎セッションの「ブリーフィング」時間が5〜10分からほぼゼロに減りました。出力の一貫性も大幅に向上し、規約違反による修正が減り、プロジェクトのコンテキストと無関係な提案もほとんどなくなりました。

.claude/ディレクトリは小さなものです。時には数十行のmarkdownファイル1つだけのこともあります。しかし、そのファイルこそがClaude Codeを本当に役立つツールにするか、常に監視が必要なチャットボットのままにするかを決める存在です。カスタムスキルの作成でAIをプロジェクトに深く統合することで、さらに一歩進んだ活用も可能です。

Share:
Tags: