Implementing Environment Variable Management Best Practices: Claude Code 활용 가이드

환경 변수관리が重要な理由

애플리케이션개발では、APIキーや데이터베이스接続情報などの機密情報を安全に관리해야 합니다。환경 변수は그基本手段ですが、타입安全性や유효성 검사が不足しがちです。Claude Code를 활용하면 堅牢な환경 변수관리の仕組みを빠르게구축할 수 있습니다。

타입安全な환경 변수の로딩

> 환경 변수をzodで유효성 검사して타입安全に読み込む모듈を作って。
> 必須・任意の区別と、デフォルト値の설정もできるようにして。

import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'staging', 'production']).default('development'),
  PORT: z.coerce.number().int().positive().default(3000),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional(),
  API_KEY: z.string().min(1, 'API_KEYは必須です'),
  JWT_SECRET: z.string().min(32, 'JWT_SECRETは32文字以上必要です'),
  CORS_ORIGINS: z.string().transform((s) => s.split(',')).default('http://localhost:3000'),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});

export type Env = z.infer<typeof envSchema>;

function loadEnv(): Env {
  const result = envSchema.safeParse(process.env);

  if (!result.success) {
    const formatted = result.error.format();
    console.error('環境変数のバリデーションエラー:');
    for (const [key, value] of Object.entries(formatted)) {
      if (key !== '_errors' && value && '_errors' in value) {
        console.error(`  ${key}: ${(value as any)._errors.join(', ')}`);
      }
    }
    process.exit(1);
  }

  return result.data;
}

export const env = loadEnv();

.env파일の템플릿관리

> .env.exampleを自動생성するスクリプトを作って。
> 実際の値は含めず、説明댓글付きで。

import fs from 'fs';
import path from 'path';

function generateEnvExample(envPath: string, outputPath: string) {
  const envContent = fs.readFileSync(envPath, 'utf-8');
  const lines = envContent.split('\n');

  const exampleLines = lines.map((line) => {
    if (line.startsWith('#') || line.trim() === '') return line;

    const [key] = line.split('=');
    const descriptions: Record<string, string> = {
      DATABASE_URL: '# データベース接続URL (例: postgresql://user:pass@localhost:5432/db)',
      API_KEY: '# APIキー (本番環境では安全に管理してください)',
      JWT_SECRET: '# JWT署名用シークレット (32文字以上)',
    };

    const comment = descriptions[key?.trim()] || '';
    return `${comment}\n${key?.trim()}=`;
  });

  fs.writeFileSync(outputPath, exampleLines.join('\n'));
}

環境ごとの설정전환

> 環境ごとに異なる설정を관리するConfig클래스を作って。
> development, staging, productionの3環境に대응して。

interface AppConfig {
  database: { pool: number; ssl: boolean };
  cache: { ttl: number; enabled: boolean };
  logging: { level: string; format: string };
}

const configs: Record<string, AppConfig> = {
  development: {
    database: { pool: 5, ssl: false },
    cache: { ttl: 60, enabled: false },
    logging: { level: 'debug', format: 'pretty' },
  },
  production: {
    database: { pool: 20, ssl: true },
    cache: { ttl: 3600, enabled: true },
    logging: { level: 'warn', format: 'json' },
  },
};

export function getConfig(): AppConfig {
  const nodeEnv = env.NODE_ENV;
  return configs[nodeEnv] ?? configs.development;
}

シークレットのローテーション대응

機密情報のローテーションを安全に行うため、複数バージョンのシークレットを同時に保持する仕組みも구축할 수 있습니다。

class SecretManager {
  private secrets: Map<string, string[]> = new Map();

  register(key: string, ...values: string[]) {
    this.secrets.set(key, values.filter(Boolean));
  }

  getCurrent(key: string): string {
    const values = this.secrets.get(key);
    if (!values || values.length === 0) {
      throw new Error(`Secret not found: ${key}`);
    }
    return values[0];
  }

  verify(key: string, token: string, verifyFn: (secret: string, token: string) => boolean): boolean {
    const values = this.secrets.get(key) ?? [];
    return values.some((secret) => verifyFn(secret, token));
  }
}

const secrets = new SecretManager();
secrets.register('JWT_SECRET', env.JWT_SECRET, process.env.JWT_SECRET_PREVIOUS ?? '');

정리

Claude Code를 활용하면 zod에 의한타입安全な유효성 검사、環境別설정、シークレット관리まで、환경 변수관리の仕組みを一貫して구축할 수 있습니다。보안の基本로서인증구현가이드도 참고하세요.테스트の자동화에 대해서는테스트戦略の글で詳しく解説しています。

zod의 상세 정보는Zod공식 문서를 확인하세요.환경 변수관리の보안에 대해서는OWASP Configuration Guide도 참고가 됩니다.