Claude Code プロジェクト初期化完全自動化ガイド — CLAUDE.md 設計から CI/CD セットアップまで

取り組みの背景：プロジェクト初期化の「負債」を解消する

新しいプロジェクトを立ち上げるたびに、同じ作業を繰り返していませんか？

package.json の初期設定、tsconfig のコピーペースト、ESLint・Prettier の設定、Git hooks の追加、CI/CD パイプラインの構築——ベテラン開発者でも 2〜3 時間かかるこの初期化作業を、Claude Code は 10 分以内 に完了させることができます。

しかも単なる「コピー」ではなく、プロジェクトの要件に応じて動的に最適化された構成を生成します。

対象読者:

Claude Code を使い始めて 1〜3 ヶ月の中級〜上級開発者
チームの開発環境統一に課題を感じているテックリード
新規プロジェクト立ち上げを効率化したいソロ開発者

1. CLAUDE.md 設計の原則と完全テンプレート

CLAUDE.md は Claude Code にとって「プロジェクトの設計書」です。適切に設計されたCLAUDE.mdは、AIが自律的に高品質なコードを生成するための羅針盤となります。

1-1. CLAUDE.md が機能するための3つの原則

原則1: 具体性 — 「何を」ではなく「どうやって」を記述する

悪い例:

# 技術スタック
- Next.js
- TypeScript
- Tailwind CSS

良い例:

# 技術スタック・実装規約
- Next.js 15 (App Router) — `src/app/` 配下を使用。`pages/` は使用禁止
- TypeScript strict モード — `tsconfig.json` の `"strict": true` は変更しない
- Tailwind CSS — インラインスタイル・CSS Modules は使用禁止。Tailwind のみ使用

原則2: 禁止事項の明示 — 避けるべきパターンを具体的に書く

Claude Code は禁止事項が明記されていない限り、慣例的な実装を選びます。特定のライブラリや設計パターンを避けたい場合は明示的に記述します。

原則3: コンテキスト階層 — ルートとサブディレクトリで分割する

大規模プロジェクトでは、ルートの CLAUDE.md にグローバルルールを、各ディレクトリに固有のルールを記述します。

project/
├── CLAUDE.md          ← グローバルルール（全体の方針）
├── src/
│   ├── CLAUDE.md      ← フロントエンド固有ルール
│   └── api/
│       └── CLAUDE.md  ← API 固有ルール
└── tests/
    └── CLAUDE.md      ← テスト規約

1-2. プロジェクト種別別 CLAUDE.md テンプレート

以下は実際に使用している完全テンプレートです。自プロジェクトに合わせてカスタマイズしてください。

① Next.js Web アプリケーション用テンプレート

# [プロジェクト名] — CLAUDE.md
 
## プロジェクト概要
[一言で何を作るプロジェクトか]
 
## 技術スタック
- Next.js 15 (App Router) + TypeScript strict
- Tailwind CSS + shadcn/ui
- Prisma + PostgreSQL（Supabase）
- Vitest（ユニットテスト）+ Playwright（E2E テスト）
- Vercel デプロイ
 
## ディレクトリ構成
src/
├── app/          ← Next.js App Router
├── components/   ← 共有UIコンポーネント
│   ├── ui/       ← shadcn/ui コンポーネント（直接編集禁止）
│   └── features/ ← 機能別コンポーネント
├── lib/          ← ユーティリティ・ヘルパー
├── hooks/        ← カスタムフック
└── types/        ← 型定義
 
## コーディング規約
- コンポーネント: PascalCase、`function` キーワード使用（アロー関数禁止）
- 変数・関数: camelCase
- 型定義: `interface` を優先（`type` は Union 型のみ）
- インポート順: Node.js → 外部ライブラリ → 内部（`@/` エイリアス使用）
- データフェッチ: Server Component でのみ行う（Client Component での fetch 禁止）
 
## Git 規約
- ブランチ: `feat/`, `fix/`, `docs/`, `refactor/`, `test/` プレフィックス
- コミットメッセージ: `feat: 機能説明` 形式（英語）
- PR: 必ず `main` ブランチへ、セルフレビュー後にマージ
 
## 禁止事項
- `any` 型の使用（`unknown` を使用）
- `console.log` の本番コードへの混入（`logger` ユーティリティを使用）
- `pages/` ディレクトリの作成
- インラインスタイル（`style={{}}` 属性）
- Client Component でのデータフェッチ

② Node.js/Express API サーバー用テンプレート

# [API名] — CLAUDE.md
 
## プロジェクト概要
[RESTful API / GraphQL API の説明]
 
## 技術スタック
- Node.js 22 + TypeScript strict
- Express 5 + Zod（バリデーション）
- Prisma + PostgreSQL
- Jest（テスト）+ Supertest（統合テスト）
- pino（ロギング）
 
## API 設計原則
- RESTful: リソース名は複数形（`/users`, `/posts`）
- レスポンス形式: `{ data: T, meta?: PaginationMeta, error?: ApiError }`
- エラーハンドリング: 必ず適切な HTTP ステータスコードを返す
- バリデーション: 全エンドポイントで Zod スキーマを使用
 
## セキュリティ必須事項
- 全エンドポイントに認証ミドルウェアを適用（公開エンドポイントは明示的に除外）
- Rate limiting: `/api/` 以下に一律適用
- CORS: 許可オリジンを環境変数で管理
 
## 禁止事項
- 環境変数の直接参照（`config/env.ts` 経由のみ）
- `req.body` の型アサーションなし使用
- トランザクションなしの複数テーブル更新

2. Claude Code によるスキャフォールディング自動化

CLAUDE.md が整ったら、実際にプロジェクトを自動生成します。

2-1. インタラクティブなスキャフォールディングプロンプト

以下のプロンプトをClaude Code に渡すことで、対話的にプロジェクト構造を生成できます。

# Claude Code を起動して以下のプロンプトを実行
claude

以下の仕様で Next.js プロジェクトを初期化してください。

## プロジェクト仕様
- プロジェクト名: my-saas-app
- 機能: ユーザー認証 + サブスクリプション管理 + ダッシュボード
- データベース: PostgreSQL（Supabase）
- 認証: NextAuth.js v5
- 決済: Stripe

## 実行してほしいこと
1. package.json を作成し、必要な依存関係を定義する
2. tsconfig.json を strict モードで設定する
3. src/ ディレクトリ構造を作成し、各ディレクトリに .gitkeep を配置する
4. 基本的な環境変数ファイル（.env.example）を作成する
5. ESLint + Prettier の設定ファイルを作成する
6. CLAUDE.md を上記の要件に基づいて生成する
7. 各ファイルの役割を説明するコメントを記述する

Sub-agent を並列実行して効率化してください。

2-2. Sub-agent 並列実行パターン

Claude Code は複数のサブエージェントを並列実行できます。プロジェクト初期化では以下のパターンが効果的です。

以下のタスクを Sub-agent を使って並列実行してください：

Agent 1: フロントエンド設定
- src/components/ ディレクトリ構造の作成
- shadcn/ui の初期コンポーネント（Button, Card, Input）の作成
- globals.css と Tailwind 設定の最適化

Agent 2: バックエンド設定
- src/lib/db.ts（Prisma クライアント）の作成
- src/lib/auth.ts（NextAuth.js 設定）の作成
- 初期 Prisma スキーマ（User, Session テーブル）の定義

Agent 3: 設定ファイル群
- .eslintrc.json の最適化
- prettier.config.js の作成
- .gitignore の最適化（Next.js + Prisma 対応）

全エージェントの作業が完了したら、各ファイルの整合性を確認してください。

この指示で Claude Code は3つのサブエージェントを同時起動し、通常の3倍速でファイルを生成します。

Sub-agent の詳細な活用パターンについては、[Claude Code 並列エージェント開発マスターガイド]/articles/claude-code/claude-code-parallel-development-mastery) で体系的に解説しています。

2-3. 自動化スクリプトによるワンコマンド初期化

繰り返し使用するプロジェクトテンプレートは、シェルスクリプトとして保存しておくと便利です。

#!/bin/bash
# init-project.sh — Claude Code によるプロジェクト自動初期化
 
set -euo pipefail
 
PROJECT_NAME="${1:-my-new-project}"
PROJECT_TYPE="${2:-nextjs}"  # nextjs | express | library
 
echo "🚀 プロジェクト初期化開始: ${PROJECT_NAME} (${PROJECT_TYPE})"
 
# 1. プロジェクトディレクトリを作成
mkdir -p "${PROJECT_NAME}"
cd "${PROJECT_NAME}"
 
# 2. Claude Code にプロンプトファイルを渡して初期化
PROMPT_FILE=$(mktemp /tmp/init_prompt_XXXXXX.txt)
 
cat > "${PROMPT_FILE}" << EOF
プロジェクト名「${PROJECT_NAME}」を ${PROJECT_TYPE} テンプレートで初期化してください。
 
要件:
1. package.json（TypeScript, ESLint, Prettier, Vitest を含む）
2. tsconfig.json（strict モード）
3. src/ ディレクトリ構造
4. .env.example（プロジェクト種別に応じた環境変数）
5. CLAUDE.md（このプロジェクト用）
6. .github/workflows/ci.yml（GitHub Actions CI）
7. README.md（セットアップ手順付き）
 
各ファイルは本番環境で使える品質で作成してください。
EOF
 
# 3. Claude Code で初期化実行
claude < "${PROMPT_FILE}"
 
# 4. クリーンアップ
rm -f "${PROMPT_FILE}"
echo "✅ プロジェクト初期化完了！"
echo "📁 cd ${PROJECT_NAME} && npm install"

# 使い方
chmod +x init-project.sh
./init-project.sh my-saas-app nextjs
./init-project.sh my-api express
./init-project.sh my-npm-lib library

3. Git hooks の自動設定

コード品質を自動的に担保する Git hooks を Claude Code で設定します。

3-1. husky + lint-staged の自動構成

現在のプロジェクトに以下の Git hooks を設定してください：

1. pre-commit フック
   - lint-staged で変更ファイルのみ ESLint + Prettier を実行
   - TypeScript の型チェック（tsc --noEmit）を実行
   - テストファイルが変更された場合は関連テストを実行

2. commit-msg フック
   - Conventional Commits 形式を強制
   - 許可するプレフィックス: feat, fix, docs, style, refactor, test, chore, ci

3. pre-push フック
   - フルテストスイートを実行
   - ビルドが成功することを確認

husky と lint-staged を package.json に設定し、.husky/ ディレクトリを作成してください。

Claude Code が生成する package.json の一部:

{
  "scripts": {
    "prepare": "husky",
    "lint": "eslint src/ --ext .ts,.tsx",
    "lint:fix": "eslint src/ --ext .ts,.tsx --fix",
    "format": "prettier --write src/",
    "type-check": "tsc --noEmit",
    "test": "vitest",
    "test:run": "vitest run"
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,yml}": [
      "prettier --write"
    ]
  }
}

3-2. commit-msg フックの実装

# .husky/commit-msg（Claude Code が生成）
#!/bin/bash
 
COMMIT_MSG_FILE="$1"
COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
 
# Conventional Commits パターン
PATTERN="^(feat|fix|docs|style|refactor|test|chore|ci)(\(.+\))?: .{1,72}$"
 
if ! echo "$COMMIT_MSG" | grep -qE "$PATTERN"; then
  echo "❌ コミットメッセージが Conventional Commits 形式に準拠していません。"
  echo ""
  echo "正しい形式: <type>(<scope>): <description>"
  echo ""
  echo "例:"
  echo "  feat: ユーザー認証機能を追加"
  echo "  fix(auth): ログアウト時のセッション削除バグを修正"
  echo "  docs: README にセットアップ手順を追加"
  echo ""
  echo "許可される type: feat, fix, docs, style, refactor, test, chore, ci"
  exit 1
fi
 
echo "✅ コミットメッセージ検証 OK"

4. CI/CD パイプラインの自動構築

4-1. GitHub Actions ワークフローの自動生成

以下の要件で GitHub Actions の CI/CD パイプラインを設定してください：

## CI ワークフロー（PR 時に実行）
- Node.js 20 と 22 でのクロスバージョンテスト
- 依存関係のキャッシュ（npm cache 利用）
- ESLint + TypeScript 型チェック
- Vitest によるユニットテスト + カバレッジレポート
- Playwright による E2E テスト（ヘッドレス）

## CD ワークフロー（main ブランチへのマージ時）
- Vercel への自動デプロイ
- デプロイ後のスモークテスト

並列実行を最大化してパイプライン時間を最小化してください。

CI/CD フローと Claude Code の HTTP Hooks 連携については Claude Code HTTP Hooks × GitHub Actions 完全統合ガイドも参考にしてください。

Claude Code が生成する .github/workflows/ci.yml:

name: CI
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
jobs:
  lint-and-type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - run: npm ci
      - run: npm run lint
      - run: npm run type-check
 
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: ['20', '22']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm run test:run -- --coverage
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage-${{ matrix.node-version }}
          path: coverage/
 
  e2e:
    runs-on: ubuntu-latest
    needs: [lint-and-type-check, test]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npm run build
      - run: npm run test:e2e
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL_TEST }}

4-2. 環境変数の自動管理

機密情報を安全に管理するための設定:

以下の環境変数管理ベストプラクティスをプロジェクトに実装してください：

1. src/config/env.ts を作成し、Zod で環境変数をバリデーション
2. .env.example を README に連動させる仕組み
3. GitHub Actions の secrets との連携設定

env.ts のサンプルも生成してください。

生成される src/config/env.ts:

import { z } from 'zod'
 
/**
 * 環境変数の型安全なバリデーション
 * Zod スキーマで全環境変数を定義・検証する
 */
const envSchema = z.object({
  // データベース
  DATABASE_URL: z.string().url('DATABASE_URL は有効なURLである必要があります'),
  
  // 認証
  NEXTAUTH_SECRET: z.string().min(32, 'NEXTAUTH_SECRET は32文字以上必要です'),
  NEXTAUTH_URL: z.string().url(),
  
  // 外部サービス
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
  STRIPE_WEBHOOK_SECRET: z.string().startsWith('whsec_'),
  
  // オプション
  SENTRY_DSN: z.string().url().optional(),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
})
 
// サーバーサイドのみで実行（Client Component からの参照はビルドエラーになる）
const parseEnv = () => {
  const parsed = envSchema.safeParse(process.env)
  
  if (!parsed.success) {
    console.error(
      '❌ 環境変数の検証に失敗しました:',
      parsed.error.flatten().fieldErrors
    )
    throw new Error('環境変数の設定が不正です。.env.example を確認してください。')
  }
  
  return parsed.data
}
 
export const env = parseEnv()

5. マルチプロジェクト環境での CLAUDE.md 管理

複数のプロジェクトを同時に管理する場合、CLAUDE.md の一元管理が重要です。

5-1. 共有ルールのテンプレートリポジトリ化

以下の構造で CLAUDE.md テンプレートリポジトリを作成してください：

templates/
├── base.md          ← 全プロジェクト共通ルール
├── nextjs.md        ← Next.js 固有ルール
├── express.md       ← Express 固有ルール
├── library.md       ← npm ライブラリ固有ルール
└── merge.sh         ← テンプレートを合成して CLAUDE.md を生成するスクリプト

merge.sh は引数でプロジェクト種別を受け取り、
base.md + [種別].md を結合して CLAUDE.md を出力します。

生成される merge.sh:

#!/bin/bash
# CLAUDE.md テンプレートマージスクリプト
 
TEMPLATE_DIR="${HOME}/.claude-templates"
PROJECT_TYPE="${1:-nextjs}"
OUTPUT="${2:-CLAUDE.md}"
 
if [ ! -f "${TEMPLATE_DIR}/${PROJECT_TYPE}.md" ]; then
  echo "❌ テンプレートが見つかりません: ${PROJECT_TYPE}"
  echo "利用可能: nextjs, express, library"
  exit 1
fi
 
# ベーステンプレート + 種別テンプレートを結合
{
  cat "${TEMPLATE_DIR}/base.md"
  echo ""
  echo "---"
  echo ""
  cat "${TEMPLATE_DIR}/${PROJECT_TYPE}.md"
} > "${OUTPUT}"
 
echo "✅ ${OUTPUT} を生成しました（テンプレート: ${PROJECT_TYPE}）"

5-2. プロジェクト間での CLAUDE.md 同期

# 共有ルールが更新された際の全プロジェクト同期スクリプト
#!/bin/bash
# sync-claude-md.sh
 
TEMPLATE_REPO="${HOME}/.claude-templates"
PROJECTS=(
  "${HOME}/projects/project-a"
  "${HOME}/projects/project-b"
  "${HOME}/projects/project-c"
)
 
for project in "${PROJECTS[@]}"; do
  if [ -f "${project}/CLAUDE.md" ]; then
    PROJECT_TYPE=$(grep -m1 "^## プロジェクト種別" "${project}/CLAUDE.md" | awk '{print $NF}')
    "${TEMPLATE_REPO}/merge.sh" "${PROJECT_TYPE:-nextjs}" "${project}/CLAUDE.md"
    echo "✅ ${project} の CLAUDE.md を更新しました"
  fi
done

6. よくあるエラーと対処法

エラー1: Claude Code がディレクトリ構造を無視する

原因: CLAUDE.md のディレクトリ定義が曖昧なため、Claude Code が独自判断で構成を変更しました。

対処: CLAUDE.md に「既存のディレクトリ構造は変更しない」を明記します。

## 重要制約
- `src/` 以下のディレクトリ構造は固定。新規ディレクトリの作成は事前確認が必要
- `components/ui/` は shadcn/ui 管理下。直接編集禁止（`npx shadcn-ui add` コマンドを使用）

エラー2: Sub-agent がファイルの競合を起こす

原因: 複数のサブエージェントが同一ファイルを編集しようとしました。

対処: タスク分割を明確にし、ファイルの所有権をエージェントごとに分ける。

Agent 1: src/components/ 以下のみを担当
Agent 2: src/lib/ 以下のみを担当（src/lib/components/ は触らない）
Agent 3: 設定ファイル（ルートディレクトリのみ）を担当

エラー3: GitHub Actions で環境変数が見つからない

原因: .env.example に定義した変数が GitHub Secrets に登録されていません。

対処: CI 失敗時のデバッグプロンプトを使います。

GitHub Actions の CI が失敗しています。以下のログを確認し、
どの環境変数が不足しているかを特定して、解決策を提示してください：

[ログを貼り付ける]

7. 応用編：AI ネイティブな開発ワークフロー

CLAUDE.md とスキャフォールディングが整ったら、日常の開発にも Claude Code を組み込みます。

マルチエージェントの詳細な実装については Claude Code のマルチエージェント機能を使いこなす実践ガイドを合わせてご覧ください。

7-1. 機能追加の標準化プロンプト

# 新機能追加テンプレート（CLAUDE.md に追記する）

## 新機能追加時のワークフロー
以下のステップで機能を実装してください：

1. src/types/ に型定義を追加
2. src/lib/ にビジネスロジックを実装（テスト付き）
3. src/components/features/ に UI コンポーネントを作成
4. src/app/ にページ/APIルートを追加
5. E2E テストを src/tests/e2e/ に追加
6. README のAPI仕様を更新

各ステップで既存のコードスタイルに合わせてください。

7-2. コードレビュー自動化との統合

# PR 作成時に Claude Code で自動レビューを実行
#!/bin/bash
# pre-push-review.sh
 
echo "🔍 Claude Code による自動コードレビューを実行中..."
 
# 変更されたファイルを取得
CHANGED_FILES=$(git diff --name-only origin/main...HEAD | grep -E "\.(ts|tsx)$")
 
if [ -z "$CHANGED_FILES" ]; then
  echo "TypeScript ファイルの変更なし。スキップします。"
  exit 0
fi
 
# Claude Code でレビュー実行
claude << EOF
以下のファイルをコードレビューしてください：
 
${CHANGED_FILES}
 
確認項目:
- CLAUDE.md のルール準拠
- TypeScript の型安全性
- セキュリティ上の問題
- パフォーマンス上の問題
- テストの網羅性
 
重大な問題があれば処理を中断し、修正提案を出力してください。
EOF

まとめ

CLAUDE.md の設計: 具体性・禁止事項・コンテキスト階層の3原則でAIの判断精度を高める
スキャフォールディング: Sub-agent の並列実行で初期化時間を1/3に短縮
Git hooks: husky + lint-staged でコード品質を自動担保
CI/CD: GitHub Actions ワークフローをワンプロンプトで生成
マルチプロジェクト管理: テンプレートリポジトリ化でチーム全体のルールを統一

この自動化ワークフローを導入することで、プロジェクト初期化にかかる時間を 2〜3 時間から 10 分以内 に短縮できます。浮いた時間を本質的な機能開発に集中させましょう。

さらに深く Claude Code の応用を