Claude Codeで開発環境を安全にセットアップする実践ガイド

新しいPCを買った日や、既存リポジトリに初めて入る日は、実装よりも先に環境構築で消耗しがちです。Node.jsのバージョンが違う、npm と pnpm が混ざる、.env が古い、Dockerのボリュームに前のデータが残る。Claude Codeを使うとこの作業は速くなりますが、ただ「セットアップして」と頼むだけでは危険です。

開発環境のセットアップは、速度よりも再現性が重要です。誰が実行しても同じ依存関係、同じ権限、同じ検証コマンドに到達できる状態を作ります。この記事では、Claude Codeに任せる部分と人間が固定するルールを分けて、Node、パッケージマネージャ、.env、CLAUDE.md、権限、hooks、Docker、失敗時の戻し方までまとめます。

公式情報は必ず一次情報で確認してください。インストールと認証はClaude Code setup、設定はClaude Code settings、権限はConfigure permissions、hooksはHooks guideが基準です。初回の操作に不安がある場合は、先にClaude Code入門ガイドとCLAUDE.mdベストプラクティスを読むと流れをつかみやすくなります。

flowchart TD
  A["ツールの前提確認"] --> B["Nodeとパッケージマネージャを固定"]
  B --> C["依存関係と.env.exampleを作成"]
  C --> D["CLAUDE.mdに作業手順を保存"]
  D --> E["settings.jsonで権限と機密ファイルを制限"]
  E --> F["hooksで危険コマンドをブロック"]
  F --> G["doctor、test、env checkで検証"]

まず決める方針

Claude Codeは、ターミナルの中でファイルを読み、コマンドを実行し、必要なら編集します。便利な反面、作業ディレクトリの中にある秘密情報や壊しやすい設定も見えてしまいます。そこで最初に「何を許可し、何を禁止するか」をプロジェクト側に置きます。

実務では次の順番が安定します。

項目	固定するもの	理由
実行環境	.nvmrc、packageManager、corepack	Nodeやpnpmの差で依存関係がずれないようにする
機密情報	.env.example、.gitignore、permissions.deny	APIキーや本番DBのURLを読ませない、コミットしない
作業手順	CLAUDE.md	参加者が変わっても同じ手順をClaude Codeが読める
権限	.claude/settings.json	危険なBash、.envの読み取り、git pushを制御する
自動チェック	hooks	LLMの判断に任せず、危険コマンドを機械的に止める
検証	doctor、check:env、test	「できた気がする」で終わらせない

hookは「エージェントの足場であるharnessの中で、特定のタイミングに必ず走る小さな処理」と考えると分かりやすいです。Claude Codeへのお願い文ではなく、設定ファイルとスクリプトで実行されるガードレールです。

コピペで作る最小セットアップ

次のスクリプトは、Git Bash、WSL、macOS、Linuxで動かす前提です。Windowsネイティブだけで作業する場合は、Git for Windowsを入れるか、同じファイルをPowerShellで手作業作成してください。claude コマンド、Node.js、Corepack、pnpmの状態を確認し、検証できる最小プロジェクトを作ります。

#!/usr/bin/env bash
set -euo pipefail

APP_DIR="${1:-claude-dev-lab}"
mkdir -p "$APP_DIR"
cd "$APP_DIR"

command -v node >/dev/null || { echo "Node.js is required"; exit 1; }
command -v claude >/dev/null || { echo "Claude Code CLI is required"; exit 1; }

corepack enable
corepack prepare [email protected] --activate

cat > package.json <<'JSON'
{
  "name": "claude-dev-lab",
  "private": true,
  "type": "module",
  "packageManager": "[email protected]",
  "scripts": {
    "doctor": "node --version && pnpm --version && claude --version",
    "check:env": "tsx src/env.ts",
    "test": "vitest run --passWithNoTests"
  },
  "dependencies": {
    "dotenv": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest",
    "vitest": "latest"
  }
}
JSON

mkdir -p src .claude/hooks .vscode
printf "22\n" > .nvmrc
cat > .gitignore <<'EOF'
node_modules
.env
.env.*
!.env.example
dist
coverage
EOF

cat > .env.example <<'EOF'
NODE_ENV=development
DATABASE_URL=postgresql://app:app@localhost:5432/app
REDIS_URL=redis://localhost:6379
EOF

cat > src/env.ts <<'TS'
import { config } from "dotenv";
import { z } from "zod";

config();

const Env = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional()
});

const parsed = Env.safeParse(process.env);
if (!parsed.success) {
  console.error(parsed.error.flatten().fieldErrors);
  process.exit(1);
}

console.log("env ok", {
  nodeEnv: parsed.data.NODE_ENV,
  hasRedis: Boolean(parsed.data.REDIS_URL)
});
TS

cat > CLAUDE.md <<'EOF'
# Project Instructions

## Environment Setup
- Use Node from `.nvmrc`.
- Use pnpm through Corepack. Do not switch to npm or yarn.
- Copy `.env.example` to `.env` locally, then edit values by hand.
- Never read, print, or commit `.env` or secret files.
- Before changing code, run `pnpm run doctor` and `pnpm run check:env`.
- After changing code, run the narrowest relevant test and record the command result.

## Work Rules
- Start with exploration and a short plan.
- Do not run destructive commands or deploy commands without explicit human approval.
- Keep setup changes reproducible in committed files, not in local terminal history.
EOF

cat > .claude/hooks/block-dangerous.mjs <<'JS'
import { readFileSync } from "node:fs";

const input = JSON.parse(readFileSync(0, "utf8") || "{}");
const command = String(input.tool_input?.command ?? "");

const blockedPatterns = [
  /rm\s+-rf\s+(\/|~|\$HOME)/,
  /git\s+push\b/,
  /curl\b.+\|\s*(bash|sh)/,
  /Invoke-WebRequest\b.+\|\s*iex/i
];

if (blockedPatterns.some((pattern) => pattern.test(command))) {
  console.log(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "危険なコマンドです。人間が目的と対象を確認してから実行してください。"
    }
  }));
} else {
  console.log("{}");
}
JS

cat > .claude/settings.json <<'JSON'
{
  "defaultMode": "plan",
  "permissions": {
    "allow": [
      "Read",
      "Bash(pnpm install)",
      "Bash(pnpm run *)",
      "Bash(git status *)",
      "Bash(claude --version)",
      "Bash(claude doctor)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push *)",
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "CLAUDE_CODE_SUBPROCESS_ENV_SCRUB": "1"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/block-dangerous.mjs"
          }
        ]
      }
    ]
  }
}
JSON

pnpm install
cp .env.example .env
pnpm run doctor
pnpm run check:env
pnpm test

このスクリプトの狙いは「すぐ実装に入れること」ではなく、「Claude Codeが安全に作業できる境界を先に作ること」です。defaultMode を plan にしておくと、最初は読み取りと調査を中心に進めやすくなります。編集を任せる段階で、必要なコマンドだけ許可します。

Windowsネイティブでは、最初に次を確認します。

winget install Anthropic.ClaudeCode
claude --version
claude doctor
node --version
corepack enable
pnpm --version

pnpm --version が通らない場合は、Nodeのインストール、Corepackの有効化、端末の再起動を順に確認してください。会社PCではプロキシや証明書で失敗することもあるため、その場合はエラーメッセージを保存してからClaude Codeに「この制約の中で原因候補を整理して」と頼みます。

Claude Codeに依頼する実用プロンプト

環境構築を任せるときは、作業範囲、禁止事項、検証条件を一つの依頼に含めます。

claude -p "
このリポジトリの開発環境セットアップを点検してください。

守ること:
- .env、.env.*、secrets配下は読まない
- npmやyarnに切り替えず、packageManagerに従う
- 破壊的なDocker volume削除やgit pushは提案だけにする

実行してよいこと:
- README、package.json、CLAUDE.md、.claude/settings.jsonを読む
- pnpm install、pnpm run doctor、pnpm run check:env、pnpm testを実行する

最後に、実行したコマンド、失敗した点、修正したファイル、残る手作業を箇条書きで報告してください。
"

この形式にしておくと、Claude Codeが勝手に「便利そうなこと」を広げにくくなります。特に.envは、値を作るファイルではなく、ローカルで人間が編集するファイルです。Claude Codeには.env.exampleの不足を見つけさせ、実値は読ませない運用にします。

3つ以上の具体的なユースケース

1. 新規SaaSのプロトタイプ

Next.js、API、DB、テストを最初から作る場合は、上の最小セットにDocker Composeを足します。PostgreSQLやRedisをコンテナ化すると、Masaが個人開発でよく遭遇した「自分のPCでは動くが、別PCではDB接続だけ失敗する」問題を減らせます。詳しいDocker構成はClaude Code Docker Composeガイドも参考になります。

2. 既存リポジトリへのオンボーディング

チームに入った初日は、実装前に README、package.json、CLAUDE.md、CI設定をClaude Codeに読ませ、セットアップ手順の抜けを洗い出します。ここで「実行したコマンドの証拠」を残させると、次の参加者向けの手順更新にも使えます。チーム運用はClaude Codeチーム開発ガイドにつながります。

3. コンテンツサイトや収益導線の保守

ブログ、LP、商品ページでは、開発環境の不安定さが収益導線の壊れにつながります。CTAリンク、計測イベント、OGP画像、AdSense用の表示確認をチェックリストに入れ、Claude Codeには「本文だけでなく収益導線を壊していないか」を確認させます。無料テンプレートはチートシートから、実務向けテンプレートは商品一覧、チーム導入は研修・導入相談にまとめています。

4. 社内ツールの再現可能な検証

社内ツールでは、DB、キュー、外部APIのモックを含むため、手順が口伝になりやすいです。.env.example、Docker Compose、pnpm run seed、pnpm testをセットにして、Claude Codeに「新しい開発者が30分で動かせるか」をレビューさせます。

失敗例と落とし穴

一番多い失敗は、パッケージマネージャの混在です。pnpm-lock.yamlがあるのにnpm installを実行すると、依存関係やlockfileが二重化します。packageManagerを置き、CLAUDE.mdに「npmへ切り替えない」と明記してください。

次に危険なのは、.envを読ませることです。Claude Codeに「設定を見て」と頼むと、広い検索で.envに触る可能性があります。permissions.denyと.gitignoreを両方使い、.env.exampleだけをレビュー対象にします。公式設定でも、機密ファイルはdeny設定で除外する方針が示されています。

Dockerのボリュームも落とし穴です。古いスキーマが残っていると、マイグレーションを直しても挙動が変わりません。ただし docker volume rm はデータを消す操作です。Claude Codeには「削除コマンドを実行して」ではなく「削除が必要か判断し、実行前に理由と対象を出して」と頼みます。

bypassPermissions は、隔離されたコンテナやVM以外では避けます。速く見えますが、.git、設定ファイル、IDE設定、デプロイ関連のファイルまで一気に変更される危険があります。普段はplanかdefaultで始め、必要なコマンドだけ許可します。

hooksにも注意が必要です。hookは自動実行されるため、信頼できないリポジトリの.claude/settings.jsonをそのまま信用しないでください。初回clone後は、Claude Codeを起動する前に.claude配下を人間が確認する運用が安全です。

再現性チェックリスト

• claude --version と claude doctor が通る
• .nvmrcまたは.node-versionがある
• packageManagerがpackage.jsonにある
• lockfileが1種類だけ存在する
• .env.exampleが最新で、.envはgitignoreされている
• CLAUDE.mdにセットアップ手順、禁止事項、検証コマンドがある
• .claude/settings.jsonで.env、secrets、git push、破壊的コマンドを制御している
• hooksの中身を人間が読める場所に置いている
• pnpm run doctor、pnpm run check:env、pnpm testの結果を最後に記録している

まとめ

Claude Codeで開発環境を作る価値は、単に作業が速いことではありません。環境の前提、権限、機密情報、検証手順をファイルとして残し、次の人も同じ順番で再現できることが本当の価値です。最初に.nvmrc、packageManager、.env.example、CLAUDE.md、.claude/settings.json、hooksを置けば、Claude Codeは「便利な自動化」から「監査できる共同作業者」に近づきます。

この記事で紹介した内容を実際に試した結果、最小プロジェクトでは pnpm install、pnpm run doctor、pnpm run check:env、pnpm test まで同じ順番で確認できました。特に効果が大きかったのは、.envを読ませない設定と、git pushや破壊的コマンドをhookで止める部分です。Masaの実運用でも、環境構築の失敗は「コマンドを知らない」より「前提が記録されていない」ことが原因になりやすいため、次回からはセットアップ自体を記事やテンプレートと同じ品質で管理します。