Claude Code는 매 세션 시작 시 저장소 루트에 있는 CLAUDE.md 파일을 읽습니다. 이것이 프로젝트 메모리 역할을 합니다. 여기에 작성된 내용은 반복하지 않아도 Claude가 기억하게 됩니다. 문제는 제가 보는 대부분의 CLAUDE.md 파일들이 '깨끗한 코드를 작성하라', '모범 사례를 따르라'와 같은 좋은 의도의 목록에 불과하며 아무것도 바꾸지 못한다는 것입니다.
실제로 작동하는, 비용을 지불할 위험이 있는 상황(Terraform을 사용한 인프라)에서 사용할 수 있는 파일을 작성해 보겠습니다.
1. 설명 대신 정확한 명령어
Claude는 명령어를 실행하게 됩니다. 안전하고 명확하며 구체적인 방법을 제시해야 합니다:
## 명령어 (안전하거나 읽기 전용, 또는 로컬)
- 형식: `terraform fmt -recursive`
- 검증: `terraform validate`
...
'코드를 검증하라(Validate)'는 모호합니다. terraform validate는 그렇지 않습니다. 만약 팀에서 OpenTofu를 사용한다면, 이를 tofu로 변경하세요. 명령어 자체는 동일합니다.
2. 모델이 추측할 수 없는 규칙
Claude는 이미 Terraform에 대해 알고 있습니다. 하지만 Claude가 모르는 것은 당신의 팀이 어떻게 사용하는지입니다. 오직 그것만을 작성하고, 규칙이 명확하지 않은 경우에는 그 이유를 추가하세요:
- `count` 대신 안정적인 키를 가진 `for_each` 사용 (count를 사용하면 목록 재정렬 시 리소스가 재생성됨).
- 리소스 이름을 변경하려면 삭제 및 재생성하는 대신 `moved {}` 블록을 사용.
- 민감한 변수는 `sensitive = true`로 설정하고, 비밀값은 시크릿 관리자(secret manager)에서 가져와 `.tfvars`에 절대 넣지 말 것.
괄호 안의 이유가 중요합니다. 이 설명을 통해 Claude는 목록에 작성하지 않은 경우에도 해당 아이디어를 적용할 수 있습니다.
3. 중단 지점이 있는 워크플로우
IaC(Infrastructure as Code)에서 핵심은 Claude의 작업이 어디서 끝나고 당신의 작업이 시작되는지 알려주는 것입니다:
## 워크플로우
1. 영향을 받는 모듈과 환경을 읽는다.
2. 최소한의 변경만 수행한다.
...
4단계는 300줄짜리 plan을 단 몇 분 안에 검토할 수 있는 요약본으로 변환하고, apply는 Claude가 할 일이 아님을 명확히 합니다.
4. '하지 말아야 할' 섹션
이것이 가장 중요하며 대부분의 사람들이 빠뜨리는 부분입니다:
금지 사항
- 명시적인 승인 없이
terraform apply, terraform destroy, -auto-approve, terraform state rm/mv, 또는 terraform import를 절대 실행하지 마세요.
...
참고: CLAUDE.md는 동작을 안내하지만 기술적 장벽은 아닙니다. 명령어를 실제로 차단하려면, .claude/settings.json의 권한 규칙(deny)과 또는 PreToolUse 훅(hook)을 결합해야 합니다. 두 계층 모두를 사용하는 것이 가장 좋습니다.
5. 간결하고 생동감 있게 유지하기
- 30~80줄을 목표로 하세요: 모든 내용이 세션마다 로드됩니다.
- Claude에게 같은 실수를 두 번 고쳐준다면, 그 수정 사항은
CLAUDE.md에 반영됩니다.
- 세션을 나가지 않고도 편집하려면 Claude Code 내에서
/memory를 사용하세요.
- 모노레포(monorepos)의 경우, 패키지별로
CLAUDE.md를 만드세요 (infra/CLAUDE.md, api/CLAUDE.md 등): Claude는 해당 폴더에서 작업할 때 이를 읽습니다.
간단한 테스트
작성 후, 새 세션을 열고 다음과 같이 요청해 보세요: "dev 환경에 로그용 S3 버킷을 추가해 줘." 만약 Claude가 계획(plan)을 형식화하고, 검증하며, 계획을 생성하고, 요약하여 보여준 뒤 적용하지 않고 멈춘다면, 당신의 CLAUDE.md는 제대로 작동하고 있는 것입니다.
도움이 되었나요? 이 예시는 **Claude Code용 스택별 CLAUDE.md 템플릿 15가지 (스페인어)**의 일부입니다: 원하시는 만큼, 최소 1 USD부터 결제할 수 있습니다. 더 많은 무료 자료는 GitHub에서 확인하세요.