CLAUDE.md 작성법 7가지 원칙 — 안티패턴 4가지와 Spring Boot SI 템플릿 전문

클로드 코드(Claude Code)를 팀에 도입하면서 가장 많이 고친 파일이 CLAUDE.md였습니다. 처음엔 "자세할수록 좋다"고 믿고 길게 썼는데, 결과는 반대였습니다. 이 글은 그 시행착오 끝에 정리한 작성 원칙 7가지와, 금융권 Spring Boot SI 프로젝트용 템플릿 전문입니다. 앞 글 금융권 망분리 환경 도입 5가지의 후속입니다.

CLAUDE.md는 문서가 아니라 지시문입니다

클로드 코드는 세션을 시작할 때 다음 위치의 CLAUDE.md를 찾아 컨텍스트에 넣습니다.

• ~/.claude/CLAUDE.md — 개인 전역 (모든 프로젝트에 적용)
• 프로젝트 루트 CLAUDE.md — 팀 공용, git 커밋 대상
• 하위 폴더의 CLAUDE.md — 그 폴더의 파일을 다룰 때 추가로 로드 (모노레포에서 유용)
• CLAUDE.local.md — 개인용, .gitignore에 넣음

핵심은 두 번째입니다. 프로젝트 루트 CLAUDE.md 하나가 팀 전체에 같은 규칙을 강제합니다. 이 파일을 읽는 대상은 사람이 아니라 모델이라는 점을 잊지 마세요. 서술문이 아니라 명령문으로, 배경 설명이 아니라 규칙으로 씁니다.

잘 쓰는 CLAUDE.md의 7가지 원칙

1. 짧게. 300줄을 넘기지 않는다

길어질수록 모델이 각 규칙에 주는 가중치가 떨어집니다. 정확히 말하면 길이 자체보다 모든 규칙을 같은 우선순위로 한꺼번에 읽히게 만드는 것이 문제입니다. 상세 내용은 docs/로 빼고 링크만 둡니다. 루트에는 자주 틀리는 치명 규칙과 실행 명령만 남깁니다.

2. "하지 말 것"이 "할 것"보다 중요하다

모델은 기본적으로 뭐든 해 보려 합니다. 금지 목록이 사고를 막습니다. 아래 템플릿마다 "절대 하지 말 것" 섹션이 있는 이유입니다. 그중 정말 치명적인 것(운영 설정 파일 수정, force push, 테스트 삭제)은 CLAUDE.md에 적는 것으로 끝내지 말고 permissions.deny와 훅으로도 강제합니다. 문서는 잊혀도 훅은 안 잊힙니다.

3. 명령어는 복사-실행 가능한 형태로

"테스트를 실행하세요"가 아니라 ./gradlew test --tests "[패키지].*"처럼 씁니다. 모델이 추측으로 다른 명령을 만들어 내는 것을 막고, 매번 "어떻게 빌드하나요?"라고 묻지 않게 합니다.

4. 이유보다 규칙

"성능을 위해 N+1을 피하세요"보다 "루프 안에서 Mapper 호출 금지"가 잘 지켜집니다. 이유는 한 줄 괄호로 충분합니다.

5. 작업 방식(프로세스)을 명시한다

"3개 파일 이상 수정 시 계획 먼저", "수정 후 컴파일 결과 보고" 같은 절차가 있으면 결과 품질이 눈에 띄게 안정됩니다. 특히 테스트가 없는 레거시에서는 "요청받지 않은 리팩터링 금지, 영향 범위 표로 보고"가 사고를 막습니다.

6. 프로젝트 고유 관례를 적는다

커밋 메시지 형식, 티켓 키, 변경 주석 관례처럼 "우리 팀만 아는 것"이 가장 가치 있는 내용입니다. "깨끗한 코드를 작성하세요" 같은 일반 상식은 지면 낭비입니다. 코드 컨벤션은 설명 50줄보다 예시 코드 5줄이 낫습니다. 예시 하나가 설명 여러 문단보다 오래 살아남습니다.

7. 살아 있는 파일로 관리한다

리뷰에서 반복되는 지적, 훅이 막은 사례, 회고에서 나온 규칙을 CLAUDE.md에 추가합니다. CLAUDE.md 변경도 PR 리뷰를 거칩니다. 세션 중에 #으로 시작하는 메시지를 보내면 바로 추가할 수도 있습니다.

안티패턴 4가지

• 회사 소개, 시스템 역사 같은 서술문 — 토큰만 씁니다.
• "항상 최선을 다해 주세요" 류의 정서적 지시 — 효과 없음.
• 모든 코딩 컨벤션을 전부 나열 — 린터가 할 일입니다. 린터 명령만 적으세요.
• 시크릿, 내부 IP, 계정 정보 — CLAUDE.md도 컨텍스트로 전송됩니다. 절대 넣지 않습니다.

템플릿 전문: Spring Boot / Java SI 프로젝트

금융권·공공 SI에서 가장 많이 쓰는 스택 기준입니다. [대괄호]는 프로젝트에 맞게 채우세요.

# CLAUDE.md — Spring Boot / Java SI 프로젝트

## 프로젝트 개요
- 시스템명: [예: 카드 승인 정산 시스템]
- 역할: [예: 승인 내역 집계 → 정산 파일 생성 → 대외기관 전송]
- 스택: Java 17, Spring Boot 3.2, Spring Batch, MyBatis, Oracle 19c, Redis
- 빌드: Gradle 8 (`./gradlew clean build -x test` 로 컴파일만 확인)
- 배포: Jenkins → Nexus → OpenShift (dev / stg / prd)

## 명령어 (항상 이 명령을 사용)
- 컴파일: `./gradlew compileJava`
- 단위 테스트: `./gradlew test --tests "[패키지].*"`
- 로컬 실행: `./gradlew bootRun --args='--spring.profiles.active=local'`
- 린트: `./gradlew checkstyleMain spotlessCheck`

## 코드 규칙
- 레이어: Controller → Service → Mapper. Controller에서 Mapper 직접 호출 금지.
- 트랜잭션: Service 계층 public 메서드에만 `@Transactional`. readOnly 명시.
- 예외: 비즈니스 예외는 `BizException(errorCode)`. RuntimeException 직접 throw 금지.
- 로그: `log.info` 에 개인정보(카드번호, 주민번호, 계좌번호) 절대 출력 금지. 마스킹 유틸 `MaskUtil` 사용.
- DTO: Lombok `@Getter @Builder`. Setter 사용 금지. Entity를 Controller 밖으로 반환 금지.
- SQL: MyBatis XML에 작성. `${}` 바인딩 금지(SQL Injection). 반드시 `#{}`.
- 날짜: `LocalDate/LocalDateTime` 사용. `java.util.Date` 신규 사용 금지.
- 신규 API는 `docs/api/[도메인].md` 에 요청/응답 예시 추가.

## 절대 하지 말 것
- `application-prd.yml`, `*.pem`, `*.jks`, `.env*` 파일 읽기/수정/커밋 금지.
- 운영 DB 연결정보를 코드나 테스트에 하드코딩 금지.
- 기존 공개 API의 요청/응답 필드 삭제·이름 변경 금지 (하위 호환). 추가만 허용.
- `git push --force`, `git reset --hard` 금지.
- 테스트를 통과시키기 위해 테스트를 삭제하거나 `@Disabled` 처리 금지.

## 작업 방식
1. 변경 전 관련 Service/Mapper/XML을 먼저 읽고 영향 범위를 한 줄로 요약한다.
2. 3개 파일 이상 수정하는 작업은 계획을 먼저 제시하고 승인 후 진행한다.
3. 수정 후 `./gradlew compileJava` 와 관련 테스트를 실행해 결과를 보고한다.
4. 커밋 메시지: `[JIRA-키] 요약` 형식. 예) `[PAY-123] 정산 파일 생성 시 소수점 처리 수정`

## 참고 문서
- 아키텍처: `docs/architecture.md`
- 배치 잡 목록: `docs/batch-jobs.md`
- 코드 리뷰 체크리스트: `docs/review-checklist.md`

이 템플릿에서 눈여겨볼 곳은 세 군데입니다. 첫째, 로그에 개인정보 출력 금지와 ${} 바인딩 금지 — 금융권 보안 심사에서 반드시 걸리는 항목입니다. 둘째, "테스트를 통과시키기 위해 테스트를 삭제 금지" — 이 한 줄이 없으면 실제로 벌어집니다. 셋째, 작업 방식 2번의 "3개 파일 이상이면 계획 먼저" — 대형 변경이 조용히 진행되는 것을 막습니다.

다른 프로젝트 유형은?

Python 데이터 파이프라인(PII 컬럼 명시, 운영 테이블 DELETE 금지), Terraform(apply 금지·plan만, prd 읽기 전용), Kubernetes GitOps 리포("이 리포 변경 = 배포" 경고, kubectl 변경 금지), React/TS(any 금지, zod 파싱), RAG/LLM 서비스(프롬프트 파일 관리, 변경 시 평가 세트 필수, 폐쇄망 규칙), 테스트 없는 레거시(요청 밖 리팩터링 금지, Java 8 문법 제한), 모노레포(루트/하위 CLAUDE.md 분리)까지 8종을 같은 형식으로 만들어 클로드 코드 실무 세팅 킷에 넣었습니다. 훅 스크립트 4종, 슬래시 커맨드 6종, Kubernetes 읽기전용 RBAC 포함 MCP 설정 4종, 보안 거버넌스 체크리스트, 27쪽 가이드 PDF가 함께 들어 있습니다.

▶ 킷 보기: https://www.latpeed.com/products/uKSp6 (런칭 기간 12,900원, 정가 19,900원)

여러분 CLAUDE.md는 몇 줄인가요. 300줄이 넘는다면 이 글의 1번부터 다시 보시길 권합니다. "우리 팀은 이런 규칙이 효과 있었다"는 사례는 댓글로 남겨 주세요.