[Claude Code 활용 4편] CLAUDE.md 완벽 작성 가이드 - DBA·운영자용 템플릿 3종
테스트 환경: Claude Code v2.x, Opus 4.7 / Sonnet 4.6
1편(입문), 2편(셸 스크립트), 3편(SQL·DBA)까지 Claude Code를 운영 업무에 활용하는 방법을 다뤘다면, 이번 4편은 그 모든 활용의 효율을 2~3배로 끌어올리는 도구 — CLAUDE.md 에 집중합니다.
CLAUDE.md는 Claude Code의 프로젝트 메모리 파일입니다. 모든 세션 시작 시 자동으로 로드되어 본인의 환경, 규칙, 표준을 Claude에게 매번 설명할 필요가 없게 해줍니다. 잘 만든 CLAUDE.md 한 장이 있으면:
- 매번 환경 설명 불필요 — "RHEL 8 환경이고 오라클 19c 운영 중인데..."를 매번 안 써도 됨
- 표준 준수 — 본인 회사의 명명 규칙, 코드 스타일을 자동 적용
- 위험 작업 차단 — 운영 DB 직접 수정 같은 위험 행동 사전 차단
- 응답 품질 향상 — Claude가 본인 환경에 맞춘 답변 생성
이번 글에서는 CLAUDE.md의 기본 원칙부터, DBA·서버 관리자가 그대로 복사해서 사용할 수 있는 3가지 템플릿, 그리고 운영 환경에서 자주 발생하는 함정까지 정리했습니다.
CLAUDE.md란 무엇인가
CLAUDE.md는 프로젝트 루트에 두는 마크다운 형식의 메모리 파일입니다. Claude Code는 세션 시작 시 이 파일을 자동으로 읽어 본인의 컨텍스트로 사용합니다.
동작 방식
cd ~/work/ops-scripts
ls -la
# CLAUDE.md ← 이 파일이 있으면 자동 로드
# backup.sh
# monitor.sh
claude
# Claude가 CLAUDE.md를 읽고 "RHEL 8, 오라클 19c 환경"임을 인지한 상태로 시작
CLAUDE.md vs Skill vs Hook
세 도구의 역할이 헷갈리기 쉬워서 비교표로 정리합니다.
도구 로드 시점 준수율 용도
| CLAUDE.md | 항상 (매 세션) | ~70% | 환경, 규칙, 표준 |
| .claude/rules/*.md | 경로 패턴 매칭 시 | ~70% | 특정 영역 상세 규칙 |
| Skill (.claude/skills/SKILL.md) | 작업 매칭 시 | 자동 | 도메인 지식 모음 |
| Hook (.claude/hooks/) | 도구 호출 시 | 100% | 절대 금지/강제 사항 |
핵심: CLAUDE.md는 가이드라인이고, Hook은 강제 규칙입니다. 절대 어겨선 안 되는 규칙(예: rm -rf 금지)은 CLAUDE.md가 아닌 Hook으로 처리해야 합니다.
첫 CLAUDE.md 만들기 - 3가지 방법
방법 1: /init 명령 (가장 빠름)
Claude Code 안에서:
> /init
Claude가 현재 폴더를 분석해서 자동으로 CLAUDE.md 초안을 생성합니다. 빌드 도구, 테스트 프레임워크, 코드 패턴을 인식해서 시작점을 제공합니다.
방법 2: # 명령으로 점진적 추가
작업 중에 메시지를 #로 시작하면 Claude가 그 지시를 자동으로 CLAUDE.md에 추가합니다.
> # 모든 셸 스크립트는 #!/bin/bash로 시작하고 set -e 옵션 사용
Claude가 이 규칙을 CLAUDE.md에 기록해서 다음 세션에도 적용됩니다. 운영 중에 발견한 규칙을 그때그때 누적하는 방식이라 매우 실용적입니다.
방법 3: 직접 작성
기본 템플릿(아래 섹션 참고)을 복사해서 시작하는 것이 가장 빠릅니다.
cd ~/work/ops-scripts
vi CLAUDE.md
★ 좋은 CLAUDE.md의 5가지 원칙
여러 시행착오를 거쳐 정리된 원칙입니다.
원칙 1: 짧게, 200줄 이하 ★ 가장 중요
CLAUDE.md는 매 세션 매 턴마다 컨텍스트 윈도우를 차지합니다. 길어질수록 Claude의 응답 품질이 측정 가능할 정도로 떨어집니다.
✅ 40줄짜리 정밀한 CLAUDE.md
❌ 400줄짜리 모든 것을 담은 CLAUDE.md
긴 내용은 .claude/rules/*.md로 분리하고 필요할 때만 로드되게 하세요.
원칙 2: 환경과 규칙 명시
Claude가 본인 환경을 모르면 일반론으로 답합니다. 환경 정보가 있으면 환경 특화 답변이 나옵니다.
# 환경
- OS: Oracle Linux 8.8
- DB: Oracle 19c (PRODDB, TESTDB)
- 셸: bash
- 시간대: Asia/Seoul
원칙 3: 금지 사항을 명확히
해야 할 것보다 하면 안 되는 것을 먼저 적으세요. 운영 환경에서 사고 예방 효과가 큽니다.
# 절대 금지
- 운영 DB(PRODDB)에 직접 DML/DDL 실행
- DROP TABLE, TRUNCATE 자동 실행
- shutdown, reboot 명령
- 비밀번호 평문 파일 저장
원칙 4: 점진적 개선
처음부터 완벽한 CLAUDE.md를 만들려고 하지 마세요. 작게 시작해서 운영하면서 개선하는 게 표준입니다.
Day 1: 환경 정보 + 기본 규칙 (20줄)
Week 1: 사고 사례 반영해서 금지 사항 추가 (40줄)
Month 1: 코드 스타일과 워크플로우 정착 (80줄)
원칙 5: 절대 룰은 Hook으로
CLAUDE.md는 약 70%만 준수됩니다. 절대 어겨선 안 되는 규칙은 Hook으로 강제하세요.
# .claude/hooks/pre-tool-use.sh 예시
# rm -rf / 같은 위험 명령 즉시 차단
★ DBA·운영자용 CLAUDE.md 템플릿 3종 (복붙 가능)
이번 글의 핵심입니다. 본인 환경에 맞춰 수정해서 바로 사용하세요.
템플릿 1: 셸 스크립트 / 운영 자동화용
2편(셸 스크립트)에서 다룬 작업 환경에 최적화된 템플릿입니다.
# 운영 자동화 작업 환경
## 환경 정보
- OS: Oracle Linux 8.8 (RHEL 8 호환)
- 셸: bash 4.4+
- 사용자: oracle, root (sudo)
- 시간대: Asia/Seoul
- 패키지 관리: dnf
## 주요 경로
- 스크립트: /home/oracle/scripts
- 백업: /backup
- 로그: /var/log/ops
- 오라클 진단: /u01/app/oracle/diag
## 셸 스크립트 작성 규칙
- 항상 `#!/bin/bash`로 시작
- `set -euo pipefail` 사용 (에러 시 즉시 종료)
- 변수는 대문자, 함수는 소문자
- 모든 작업은 /var/log/ops.log에 timestamp와 함께 기록
- 날짜 형식: YYYYMMDD_HHMMSS
## cron 등록 규칙
- 새벽 1~5시 사이는 백업/배치, 9~18시는 운영 시간
- 같은 시간대 동시 실행 작업 피할 것
- 모든 cron 출력은 로그 파일로 리다이렉트
## 절대 금지
- `rm -rf` 와일드카드 사용 금지 (구체 경로 지정)
- 운영 데이터 디렉토리(/u01/oradata) 직접 수정 금지
- root 사용자로 오라클 작업 금지
- 비밀번호 스크립트 평문 저장 금지 (Wallet 사용)
## 도구
- 백업: rman, expdp
- 모니터링: lsnrctl, tnsping, ps, top, sar
- 로그 분석: grep, awk, sed
템플릿 2: 오라클 SQL/DBA 작업용
3편(SQL·DBA)에서 다룬 작업에 최적화된 템플릿입니다.
# Oracle DBA 작업 환경
## DB 정보
- Oracle 19c (19.21)
- 인스턴스: PRODDB (운영), TESTDB (테스트)
- 캐릭터셋: AL32UTF8
- 멀티테넌트: 사용 (CDB$ROOT + PROD_PDB, TEST_PDB)
- 시간대: Asia/Seoul
## 주요 스키마
- APP_USER: 애플리케이션 메인 (운영)
- BATCH_USER: 배치 작업
- READ_ONLY_USER: 모니터링 전용
## SQL 작성 규칙
- 키워드는 대문자, 객체명은 소문자
- 들여쓰기 4 spaces
- JOIN은 ANSI 표준 (LEFT JOIN, INNER JOIN)
- 변수 바인딩은 :name 형식 (positional 안 됨)
- 주석은 단일 라인 `--`로, 블록 주석 `/* */` 지양
## 권한 / 객체 관리
- 직접 GRANT 우선 (PL/SQL에서 ROLE 권한 무효화)
- 시노님은 PUBLIC보다 PRIVATE + GRANT 조합 권장
- 새 테이블 생성 시 인덱스 + COMMENT 필수
## DBMS_SCHEDULER 작업 표준
- job_type은 PLSQL_BLOCK 기본
- repeat_interval에 BYHOUR/BYMINUTE/BYSECOND 모두 명시
- start_date에 명시적 타임존(Asia/Seoul) 지정
- 작업 등록 후 SAVE STATE 적용 (PDB 환경)
## 절대 금지
- 운영 DB(PRODDB)에 다음 명령 절대 실행 금지:
- `WHERE` 절 없는 UPDATE / DELETE
- `DROP TABLE`, `TRUNCATE`
- `ALTER SYSTEM` (DBA 매니저 사전 승인 필요)
- 비밀번호를 SQL 안에 평문으로 작성 금지
- 운영 DB 변경 작업은 항상 ROLLBACK SQL 함께 제시
## 자주 사용하는 진단 쿼리 위치
- ~/dba-toolkit/monitoring/ : 일상 점검
- ~/dba-toolkit/tuning/ : 성능 분석
- ~/dba-toolkit/troubleshoot/ : 장애 대응
템플릿 3: 통합 운영 환경 (가장 흔한 케이스)
위 두 가지를 통합한 본격 운영용입니다. 본인 환경에 가장 가까운 템플릿입니다.
# 통합 운영 작업 환경
## 환경
- OS: Oracle Linux 8.8 / Windows Server 2019 (혼합)
- DB: Oracle 19c PRODDB, Oracle 21c TESTDB
- 시간대: Asia/Seoul
- 사용자: oracle (DB), root (시스템)
## 작업 디렉토리 구조
- ~/work/scripts/ : 운영 자동화 스크립트
- ~/work/sql/ : SQL 파일과 점검 쿼리
- ~/work/reports/ : 일일/주간 점검 보고서
- ~/dba-toolkit/ : 자주 쓰는 진단 쿼리 모음
## 운영 표준
- 모든 변경 작업은 개발 → 테스트 → 운영 단계 거침
- 운영 변경은 변경 SQL + ROLLBACK SQL 함께 제시
- 백업 확인: RMAN 마지막 백업이 24시간 이내인지
- 작업 시간: 일과 시간 외 (또는 점검 시간 활용)
## 절대 금지 (사고 방지)
- 운영 DB의 DROP, TRUNCATE, 단독 UPDATE/DELETE
- shutdown, reboot, systemctl stop 자동 실행
- 비밀번호 평문 저장 (Wallet, 환경변수 활용)
- 모든 사용자 대상 비밀번호 정책 일괄 변경
## 자주 사용하는 도구
- 셸: bash (Linux), PowerShell (Windows)
- DB 접속: sqlplus, sqlplus64
- 모니터링: lsnrctl, top, vmstat, iostat
- 백업: rman, expdp/impdp
## 응답 스타일
- 명령어는 코드 블록으로
- 위험한 작업은 실행 전 영향 범위 설명 먼저
- 운영 DB 변경 시 항상 "이 작업은 운영 환경에 적용됩니다. 진행하시겠습니까?"로 확인
계층 구조 활용 - .claude/rules/ 디렉토리
CLAUDE.md를 200줄 이하로 유지하려면 상세 규칙을 별도 파일로 분리하세요. .claude/rules/ 폴더에 두면 경로 패턴 매칭으로 lazy 로드됩니다.
구조 예시
project/
├── CLAUDE.md ← 최소한의 환경/규칙 (40~80줄)
├── .claude/
│ └── rules/
│ ├── sql-style.md ← SQL 작성 상세 규칙
│ ├── backup-policy.md ← 백업 정책 상세
│ └── security.md ← 보안 정책 상세
└── scripts/
rules 파일 형식
---
paths: ["**/*.sql", "**/*.pls"]
---
# SQL 작성 상세 규칙
(SQL이나 PL/SQL 파일을 다룰 때만 이 내용이 로드됨)
## 인덱스 명명 규칙
- IDX_{테이블명_약자}_{컬럼명_약자}
- 유니크 인덱스는 UX_
## 트리거 작성 규칙
...
paths에 명시한 패턴에 매칭되는 파일을 다룰 때만 로드되어 컨텍스트를 절약합니다.
CLAUDE.md 점진적 개선 - 운영 사이클
처음 만든 CLAUDE.md를 어떻게 개선할지 단계별로 정리했습니다.
Week 1: 시작
기본 환경 정보 + 절대 금지 규칙 3~5개로 시작 (20~40줄).
Week 2~4: 사고/실수 반영
Claude가 본인 의도와 다르게 동작한 경우, # 명령으로 즉시 CLAUDE.md에 규칙 추가.
> # PL/SQL 작성 시 ROLE 통한 권한 의존 금지, 직접 GRANT 확인 후 작성
Month 1+: 코드 스타일 추가
자주 사용하는 패턴, 명명 규칙, 표준 절차를 누적.
Month 3+: 분리 시점
CLAUDE.md가 200줄을 넘으면 .claude/rules/로 영역별 분리 시작.
자주 발생하는 함정 5가지
함정 1: 너무 길게 작성
200~300줄 넘어가면 Claude의 응답 품질이 떨어집니다. 짧게 유지.
함정 2: 추상적 규칙
❌ "코드를 깨끗하게 작성하세요" ← 추상적
✅ "함수는 30줄 이하, 변수명은 snake_case" ← 구체적
구체적이고 측정 가능한 규칙이어야 Claude가 적용합니다.
함정 3: CLAUDE.md만 믿기
CLAUDE.md는 70% 준수입니다. 정말 중요한 규칙(보안, 운영 DB 보호)은 Hook으로 강제하세요.
함정 4: 한 번 만들고 방치
운영 환경은 계속 변합니다. 분기에 한 번 정도 CLAUDE.md를 리뷰하고 갱신하세요.
함정 5: 개인 사용자 레벨 누락
~/.claude/CLAUDE.md # 모든 프로젝트 공통 규칙
project1/CLAUDE.md # 프로젝트별 규칙
자주 사용하는 개인 표준은 ~/.claude/CLAUDE.md에 두면 모든 프로젝트에서 적용됩니다.
실전 점검 명령
본인의 CLAUDE.md 품질을 Claude에게 검토받을 수 있습니다.
> 현재 CLAUDE.md를 검토하고 다음을 평가해 줘:
1. 200줄 이하인가? 줄여야 할 영역은?
2. 추상적 규칙 → 구체적 규칙으로 바꿔야 할 것
3. 절대 금지 항목 중 Hook으로 옮겨야 할 것
4. DBA·운영자 관점에서 빠진 핵심 규칙
5. 개선 우선순위 TOP 5
이 점검을 분기에 한 번 정도 실행하면 CLAUDE.md가 자연스럽게 진화합니다.
시리즈 마무리
Claude Code 시리즈 4편에 걸쳐 DBA·서버 관리자가 Claude Code를 활용하는 방법을 다뤘습니다. 핵심을 한 번 더 정리하면:
- 1편: Claude Code는 운영자에게도 강력한 도구이며 5가지 핵심 활용이 가능
- 2편: 셸 스크립트와 운영 자동화에서 사이클을 한 곳에서 끝낼 수 있음
- 3편: SQL·DBA 업무에서 매일 1~2시간 절약 가능
- 4편 (이 글): CLAUDE.md가 모든 활용의 효율을 2~3배로 끌어올리는 핵심
CLAUDE.md는 단순한 메모리 파일이 아니라 본인의 운영 표준을 코드로 만든 자산입니다. 잘 만든 CLAUDE.md 하나가 매일의 작업 효율, 사고 예방, 표준 준수를 동시에 해결합니다.
본인 환경에 맞는 CLAUDE.md를 만들고 점진적으로 개선해 나가세요. 6개월 후 돌아보면 운영 노하우가 그대로 텍스트로 축적된 가장 가치 있는 파일이 되어 있을 것입니다.
비슷한 CLAUDE.md 활용 경험이나 더 좋은 템플릿이 있다면 댓글로 공유해 주세요. 다른 운영자들과 노하우를 함께 쌓아가면 좋겠습니다.