Claude Code로 환경 변수와 시크릿을 관리하는 실전 가이드

실수로 API 키를 GitHub에 커밋해서 식은땀을 흘려본 경험 — 개발자라면 누구나 있을 겁니다. 시크릿 유출의 90%는 사람 실수입니다. Claude Code를 연동하면 .env 셋업부터 탐지, 로테이션, 사고 대응까지 기계적으로 안전을 강제할 수 있습니다.

1. .env 셋업 자동화

새 개발자는 환경 변수를 모으는 것부터 고생합니다. .env.example에서 생성하게 하세요.

claude -p "
Read .env.example and interactively create a .env for this project.

For each variable:
1. What it's for
2. Where to get it (with URLs)
3. Recommended local dev value
4. Required or optional

Confirm .env is gitignored before saving.
"

신규 개발자 온보딩 속도를 극적으로 끌어올립니다.

2. Pre-Commit으로 실수 커밋 차단

누군가 git commit을 실행하는 그 순간 시크릿을 잡아냅니다.

claude -p "
Create .husky/pre-commit.

Requirements:
- Check staged files for:
  - AWS access keys: AKIA[0-9A-Z]{16}
  - Stripe: sk_live_[0-9a-zA-Z]{24}
  - GitHub PAT: ghp_[0-9a-zA-Z]{36}
  - Generic API-key-looking strings
- Reject commit and show file/line on detection
- Allow // secrets-ignore comment for false positives

Also compare with trufflehog and gitleaks, and
recommend a team-friendly setup.
"

gitleaks는 업계 표준입니다 — Claude Code와 결합하면 탐지된 항목을 자동으로 조치할 수도 있습니다.

3. 기존 커밋 히스토리 감사

과거의 유출이 여전히 남아 있는지 확인합니다.

claude -p "
Scan the entire commit history for secrets:

1. Run gitleaks detect --source . --no-git
2. Categorize findings (active / already revoked / false positive)
3. For active leaks, show immediate rotation steps
4. Git history purge steps (git filter-branch or BFG Repo Cleaner)

Output to docs/security/secret-audit.md (treat as confidential).
"

:::message alert 유출된 시크릿 = 즉시 폐기하고 로테이션

히스토리를 정리해도 포크와 캐시에는 이미 남아 있다고 가정해야 합니다. :::

4. .env.example 싱크 유지

.env가 바뀌면 .env.example도 자동으로 업데이트합니다.

claude -p "
Compare .env and .env.example:

1. Vars in .env but not .env.example → add with placeholders
2. Vars in .env.example but not .env → propose removal if obsolete
3. Improve comments (purpose docs)
4. Confirm secret values remain as placeholders

Save .env.example in a git-diff-reviewable state.
"

5. 프로덕션 시크릿을 Secrets Manager로 마이그레이션

프로덕션 시크릿을 .env에서 AWS Secrets Manager / Cloudflare Secrets / Doppler로 옮깁니다.

claude -p "
Migrate 10 production secrets from .env to AWS Secrets Manager:

1. aws secretsmanager create-secret commands
2. Least-privilege IAM read policy
3. App-side fetch code (with caching)
4. Deploy procedure (cut over from .env)
5. Rollback plan

Output Terraform definitions too.
"

최종 상태: 코드와 저장소 어디에도 프로덕션 시크릿이 존재하지 않음.

6. 정기 시크릿 로테이션 스케줄링

90일마다, 자동으로 로테이션.

claude -p "
Design a script to auto-rotate API keys for Stripe, OpenAI, Resend every 90 days:

1. Issue new keys via each service's API
2. Save to Secrets Manager / Cloudflare Secrets
3. Trigger deploy to pick up new keys
4. Revoke old keys
5. Append to docs/security/rotation-log.md

Provide a monthly GitHub Actions schedule YAML.
"

90일 로테이션은 컴플라이언스 요건이기도 한 경우가 많습니다.

7. 유출 사고 대응 플레이북

사고가 터져도 당황하지 않도록 준비해 두세요.

claude -p "
Write docs/security/incident-playbook.md for:

Scenario: AWS access key accidentally committed to a public GitHub repo

0-15 min:
- Revoke key in AWS Console
- Make the repo private

15 min - 1 hour:
- Check CloudTrail for unauthorized use
- Remove key from git history (git filter-branch)
- Issue new key, register in Secrets Manager

1 hour+:
- Notify security team
- Decide on customer disclosure

Include exact commands and designated owners.
"

CLAUDE.md에 보안 규칙 박아두기

Claude Code 자체의 행동을 제약합니다.

## Secret Handling Rules

### Forbidden
- Hardcoding .env values in source code
- Logging API keys (including console.log)
- Putting secrets in comments
- Putting secrets in README / docs

### Required
- Update .env.example whenever API keys change
- Register new external service keys in Secrets Manager
- Pre-commit secret scan must pass

### AI Instructions
- Always use process.env.XXX for key values in generated code
- Never copy .env contents elsewhere
- Route secret-related changes through human review

이렇게 하면 Claude Code가 실수로 키를 하드코딩할 확률이 줄어듭니다.

안티패턴

❌ .env.example을 방치해 괴리 발생

새 팀원이 앱을 실행하지 못해 혼란이 벌어집니다. 둘을 반드시 싱크로 유지하세요.

❌ Slack / Zoom에서 API 키 공유

히스토리에 영원히 남습니다. 시크릿 공유 도구(1Password / Doppler)를 사용하세요.

❌ 민감 데이터 로깅

console.log(req.headers)는 Authorization 헤더를 노출합니다. 공격적으로 마스킹하세요.

❌ “아무도 모를 거야” 가정

봇은 5초 안에 키를 탐지해 악용합니다. 모든 커밋을 공개 커밋이라고 생각하세요.

결론

• .env를 인터랙티브하게 셋업
• Pre-commit으로 시크릿 유출 탐지
• 과거 커밋 감사
• .env.example 싱크 유지
• 프로덕션 시크릿은 Secrets Manager로 이전
• 90일 로테이션 자동화
• 사고 대응 플레이북 준비
• CLAUDE.md로 AI 행동 제약

시크릿 관리는 시스템적 문제입니다. Claude Code를 쓰면 임기응변 점검에서 기계적 안전망으로 전환할 수 있습니다.

관련 글: 보안 감사 / 웹 보안 헤더 / Hooks 가이드

공식 문서: Anthropic Claude Code / gitleaks