チーム開発用CLAUDE.mdテンプレート

なぜチーム開発用のCLAUDE.mdが必要か

個人開発と異なり、チームでClaude Codeを使う場合には「全員が同じ方向を向いているか」が重要になります。チームメンバーAが const を使い、チームメンバーBが let を使い、Claudeが生成するコードがさらに別のスタイルになる——これは実際によく起きる問題です。

チーム共有のCLAUDE.mdをリポジトリに置くことで、全員のClaude Codeが同じルールで動きます。これはチーム用のESLint設定ファイルをコミットするのと同じ考え方です。

※CLAUDE.md: プロジェクトのルートに置くClaude Code専用の設定ファイル。プロジェクト固有のルールやコンテキストを記述する。※リポジトリ: Gitでコードと変更履歴を管理するフォルダ。GitHubなどのサービスで共有できる。※コミット: Gitでファイルの変更を履歴として記録する操作。

テンプレート本体

# [プロジェクト名] 開発ガイド

このファイルはClaude Codeに読み込まれるプロジェクト設定ファイルです。
チーム全員が同じ設定で作業できるよう、リポジトリにコミットして管理します。

最終更新: 2026年XX月XX日
管理者: [チームリーダー名]

## プロジェクト概要

[プロジェクトの簡単な説明。何をするサービスか、誰が使うか。]

## チーム体制

- エンジニア: X名
- デザイナー: X名
- PM: X名
- Claudeは「チームメンバーの一人」として作業する

## ブランチ戦略

GitHub Flowを採用しています。

main（常にデプロイ可能） └── feature/[機能名] └── fix/[バグ名] └── chore/[雑務名]

### ブランチ命名規則

```bash
# 機能追加
git checkout -b feature/user-authentication

# バグ修正
git checkout -b fix/login-redirect-bug

# リファクタリング
git checkout -b refactor/extract-auth-service

# ドキュメント・設定変更
git checkout -b chore/update-dependencies

※リファクタリング: 外部から見た動作を変えずに、コードの内部構造を整理・改善すること。※ブランチ: Gitでコードの変更履歴を分岐させる仕組み。本番コードに影響を与えずに新機能を開発できる。※デプロイ: 開発したコードを本番サーバーに公開・適用すること。

コミットメッセージ規約

Conventional Commitsを採用しています。

<type>(<scope>): <description>

[optional body]

[optional footer]

typeの種類

type	用途
feat	新機能追加
fix	バグ修正
refactor	リファクタリング
test	テスト追加・修正
docs	ドキュメント
chore	ビルド・ツール設定変更
style	フォーマット変更（動作に影響なし）

# ✅ 良い例
git commit -m "feat(auth): ソーシャルログイン機能を追加"
git commit -m "fix(cart): 数量0のとき合計金額が不正になるバグを修正"
git commit -m "refactor(api): fetch処理をカスタムフックに切り出し"

# ❌ 悪い例
git commit -m "修正"
git commit -m "wip"
git commit -m "Claude がコード生成した"

Pull Request ルール

PRテンプレート

PRを作成する際は以下のテンプレートを使ってください：

## 変更内容

[何を変更したか、簡潔に]

## 変更理由

[なぜ変更したか]

## 動作確認

- [ ] ローカルで動作確認済み
- [ ] テストが通っている
- [ ] レビュアーが確認すべき箇所を指摘した

## スクリーンショット（UIの変更がある場合）

[before/after のスクリーンショット]

マージの条件

レビュアー2名以上の Approve
CIがグリーン（lint + test）
コンフリクトが解消されている

※マージ: Gitで別ブランチの変更を現在のブランチに統合すること。

コードレビューの基準

レビューは以下の観点で行います：

必須確認事項（ブロッカー）

セキュリティの問題（SQLインジェクション、XSS等）
パフォーマンスの明らかな問題（N+1、不要なループ等）
テストがない
意図が読み取れない命名

推奨事項（提案）

もっとシンプルに書ける箇所
将来のメンテナンス性を高める提案

コメントの書き方

# ブロッカー（必ず修正）
[MUST] セキュリティリスクがあるため修正してください

# 提案（議論の余地あり）
[NIT] こちらのほうがシンプルかもしれません
[SUGGEST] 将来的に○○が必要になった場合、このほうが拡張しやすいです

コーディング規約

命名規則

// ファイル名
UserProfile.tsx          // コンポーネント: PascalCase
useUserProfile.ts        // カスタムフック: use + PascalCase
userProfile.utils.ts     // ユーティリティ: camelCase + ドット記法
user-profile.types.ts    // 型定義: kebab-case + ドット記法

// 変数・関数
const userId = '123';                    // camelCase
const MAX_RETRY_COUNT = 3;              // 定数: UPPER_SNAKE_CASE
function calculateTotalPrice() {}       // 動詞から始める
const isLoading = false;               // boolean: is/has/can から始める

// コンポーネント
export function UserProfileCard() {}   // PascalCase

禁止事項

console.log をコミットしない（デバッグ用は logger を使う）
TODO: コメントはIssue番号とセットにする（例: // TODO: #123 ここを最適化する）
ハードコードされたURLや認証情報は禁止（環境変数を使う）
マジックナンバーは定数として名前をつける

※環境変数: APIキーやデータベース接続情報など、コードに直接書きたくない値をOSやサーバーに設定する仕組み。

テスト方針

カバレッジ目標

ユニットテスト: 80%以上
E2Eテスト: 主要ユーザーフローをカバー

テストの優先度

ビジネスロジック（Service層）: 必ずテストする
APIエンドポイント: 正常系・異常系ともにテストする
UIコンポーネント: インタラクションのあるものをテストする
ユーティリティ関数: エッジケースを含めてテストする

※エンドポイント: APIにアクセスするためのURL。例: `/api/users` や `/api/posts/123` など。※E2Eテスト: End-to-End テストの略。ユーザー操作を再現してブラウザ全体の動作を検証するテスト手法。※API: Application Programming Interface の略。外部サービスとプログラム間でデータをやりとりするための接続口。

開発環境セットアップ

# リポジトリをクローン
git clone [リポジトリURL]
cd [プロジェクト名]

# 依存関係インストール
npm install

# 環境変数設定
cp .env.example .env.local
# .env.local を編集

# データベースセットアップ
npm run db:setup

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

※npm: Node.jsのパッケージ管理ツール。`npm install` でライブラリをインストールする。

コンフリクト解決のルール

コンフリクトはブランチ作成者が解決する責任を持つ
解決が難しい場合は、コンフリクト箇所の担当者に相談する
<<<<<<< HEAD などのマーカーを残したままコミットしない

セキュリティ規約

API Keyや秘密情報は絶対にコミットしない
.env ファイルは .gitignore に含まれているか確認する
外部ライブラリ追加時はセキュリティアドバイザリを確認する
ユーザー入力は必ずバリデーションとサニタイズを行う

Claudeへのお願い

このプロジェクトで作業する際は以下を守ってください：

ブランチ名・コミットメッセージは上記の規約に従う
新しいファイルを作成する前に、既存のファイルで対応できないか確認する
既存のコードスタイルに合わせる
テストを書かずに「完成」としない
セキュリティに関わる変更は必ずコメントを残す

## 各セクションの説明

**ブランチ戦略**: Claudeが新しい作業を開始するとき、どのブランチを作るかが定義されます。これがないと、Claudeが `main` ブランチに直接コミットしようとすることがあります。

**コミットメッセージ規約**: Claudeが生成するコミットメッセージも統一されます。Conventional Commitsに従ったメッセージが自動的に生成されるようになります。

**コードレビューの基準**: Claudeに「このPRをレビューして」と頼んだとき、どの観点でレビューするかが定まります。

**Claudeへのお願いセクション**: CLAUDE.mdの最後に、Claudeへの直接的な指示をまとめています。これは特に効果的なパターンです。

## カスタマイズのポイント

1. **スクラムチームの場合**: スプリント・ストーリーポイントに関するセクションを追加してください。

2. **リリースフロー**: Gitフロー（develop ブランチあり）を使う場合はブランチ戦略を更新してください。

3. **CI/CD**: GitHub Actionsの設定や、どのチェックが必須かを記述するとより効果的です。

:::note
チーム用CLAUDE.mdは「生きたドキュメント」として扱ってください。チームの合意でルールが変わったら、CLAUDE.mdも同時に更新する文化を作ることが重要です。
:::

※GitHub Actions: GitHubが提供するCI/CDサービス。コードのプッシュをトリガーにテスト・ビルド・デプロイを自動実行できる。※CI/CD: Continuous Integration / Continuous Delivery の略。コード変更を自動でテスト・本番環境にデプロイする仕組み。