Claude Codeで環境変数とシークレットを安全に管理する実践ガイド

GitHub で API キーを誤ってコミットして大炎上——開発者なら一度は冷や汗をかいた経験があるはず。シークレット漏洩の 9割は人的ミス です。Claude Code を組み込めば、.env の管理からシークレット検出、定期ローテーションまで、機械的に安全を担保 できます。

1. .env のセットアップを自動化

新しい開発者が環境変数を揃えるのは面倒。.env.example から自動生成します。

claude -p "
.env.example を読んで、このプロジェクトの .env を対話形式で作成してください。

各変数について:
1. 用途の説明
2. どこで取得するか（URL 付き）
3. ローカル開発での推奨値
4. 必須かオプションか

作成した .env は .gitignore にあることを確認してから保存。
"

新人オンボーディングの速度が段違いに上がります。新人オンボーディング も参照。

2. 誤コミット検出を pre-commit で防ぐ

git commit の瞬間にシークレットを検出します。

claude -p "
.husky/pre-commit を作成してください。

要件:
- ステージ中のファイルに以下のパターンがないかチェック:
  - AWS アクセスキー: AKIA[0-9A-Z]{16}
  - Stripe: sk_live_[0-9a-zA-Z]{24}
  - GitHub PAT: ghp_[0-9a-zA-Z]{36}
  - 一般的な API キー風の文字列
- 検出したらコミットを拒否し、該当ファイル・行を表示
- false positive 用に // secrets-ignore コメントで除外可能に

trufflehog や gitleaks を使う選択肢も比較して、
チーム向けに推奨構成を提案してください。
"

gitleaks を導入するのが業界標準ですが、Claude Code と組み合わせて 検出内容の自動修正 までできると理想的です。

3. 既存コミット履歴のシークレット監査

過去に漏らしたシークレットが残っていないかチェック。

claude -p "
全コミット履歴をスキャンしてシークレットを検出:

1. gitleaks detect --source . --no-git を実行
2. 結果を分類（アクティブ / 既に無効化済み / 誤検知）
3. アクティブな漏洩は即ローテーションする手順を提示
4. .git 履歴から完全削除する手順（git filter-branch か BFG Repo Cleaner）

結果を docs/security/secret-audit.md に機密扱いで出力。
"

:::message alert 漏れたシークレットは即失効・再発行

履歴から消しても、フォーク・キャッシュで残っている前提で動くのが鉄則です。 :::

4. .env.example を常に最新に保つ

実 .env を更新したら .env.example も更新する——これを機械化。

claude -p "
.env と .env.example を比較:

1. .env にあって .env.example にない変数 → 追加（値はプレースホルダに）
2. .env.example にあって .env にない変数 → 不要なら削除提案
3. 各変数のコメント（用途説明）を整備
4. 機密値がプレースホルダになっているか確認

更新後、.env.example を git diff で確認できる状態で保存。
"

5. 本番シークレットを Secrets Manager に移行

ローカルの .env から、本番は AWS Secrets Manager / Cloudflare Secrets / Doppler 等へ。

claude -p "
.env にある本番用シークレット10個を AWS Secrets Manager に移行:

1. aws secretsmanager create-secret コマンドを生成
2. IAM ポリシー（読み取り権限の最小化）
3. アプリ側でのフェッチコード（キャッシュ付き）
4. デプロイ手順（既存の .env との切り替え）
5. ロールバック手順

Terraform 定義も出力してください。
"

本番のシークレットがコード/リポジトリに残らない状態を作ります。

6. シークレットローテーションの定期自動化

API キーを90日で必ず再発行する仕組み。

claude -p "
Stripe / OpenAI / Resend など外部サービスの API キーを
90日ごとに自動ローテーションするスクリプトを設計:

1. 各サービスの API 経由で新キー発行
2. Secrets Manager / Cloudflare Secrets に保存
3. デプロイをトリガーして新キーを反映
4. 旧キーの無効化
5. ローテーションログを docs/security/rotation-log.md に追記

GitHub Actions の schedule トリガーで月次実行する YAML も書いて。
"

90日ごとにローテーション はコンプライアンス要件でもあります。

7. 漏洩時のインシデントプレイブック

起きてから慌てない準備。

claude -p "
シークレット漏洩インシデント対応手順を docs/security/incident-playbook.md に:

前提: GitHub 公開リポジトリに AWS アクセスキーを誤コミット

0〜15分:
- AWS コンソールでキー無効化
- 該当リポジトリをプライベート化

15分〜1時間:
- CloudTrail でキーの不正利用確認
- git filter-branch で履歴からキー削除
- 新キーの発行と Secrets Manager 反映

1時間以上:
- セキュリティチーム報告
- 顧客通知要否の判断

各ステップのコマンドと担当者も明記。
"

CLAUDE.md にセキュリティルールを書く

Claude Code 自体が安全に振る舞うよう制約を設けます。

## シークレット取り扱いルール

### 禁止
- `.env` ファイルの内容をコードにハードコード
- API キーをログ出力（console.log 含む）
- シークレットをコメントに書く
- シークレットを README / docs に書く

### 必須
- API キー変更時は必ず .env.example も更新
- 新しい外部サービス追加時は Secrets Manager に登録
- pre-commit hook でシークレット検出を通す

### AI への指示
- コード生成時、APIキー類の値は必ず `process.env.XXX` に置き換える
- `.env` の内容を別の場所にコピーしない
- シークレット関連の変更は必ず人間のレビューを通す

これで Claude Code がうっかり鍵をハードコードするリスクを減らせます。

やってはいけないこと

❌ .env.example を .env と同期しない

新人が動かせない環境変数を見逃し、後で大混乱。必ず同期。

❌ Slack や Zoom で API キーを共有

履歴に永久保存されます。シークレット専用ツール（1Password / Doppler）経由で共有。

❌ ログに機密情報を混入

console.log(req.headers) は Authorization ヘッダを丸裸にします。マスキングを徹底。

❌ 「誰もこんなコミット見ない」と思う

bot が5秒で検出してマイニングします。公開前提で対策。

まとめ

• .env セットアップを対話形式で自動化
• pre-commit でシークレット誤コミットを検出
• 既存コミット履歴の監査
• .env.example を自動同期
• 本番は Secrets Manager に集約
• 90日ごとの自動ローテーション
• 漏洩時のプレイブックを事前整備
• CLAUDE.md で AI の振る舞いも制約

シークレット管理は 仕組みで解く問題。Claude Code があれば、属人的なチェックから機械的な安全網に切り替えられます。

関連記事: セキュリティ監査 / Web セキュリティヘッダー / Hooksガイド

公式ドキュメント: Anthropic Claude Code / gitleaks