— CLAUDE.md 기반 실전 가이드 —
Claude Code는 LLM 기반 프로그래밍 에이전트로, 반복적인 개발 작업과 코드 생산성을 극대화할 수 있는 강력한 도구입니다. 하지만 AI에게 기대 이상의 결과를 얻기 위해서는 단순히 “코드를 작성해 달라”는 프롬프트를 주는 것만으로는 부족합니다.
이 글에서는 개인 글로벌 에이전트 가이드(CLAUDE.md)를 기반으로, Claude Code를 더 효과적으로 활용하는 방법을 공유하겠습니다.
1. 명확한 철학 세우기
Claude Code를 잘 쓰기 위해서는 개발 철학이 명확해야 합니다.CLAUDE.md의 핵심 신념은 다음과 같습니다.
- 대규모 변경보다 점진적 개선: 작고 안정적인 변경을 누적
- 기존 코드에서 배우기: 구현 전 반드시 분석과 계획
- 실용주의 우선: 이상적인 방법보다 프로젝트 현실에 맞춘 선택
- 코드는 명확하게: 영리함보다 읽기 쉬운 코드
2. 구현은 “계획 → 테스트 → 코드 → 리팩터링” 순서로
Claude Code를 시킬 때는 다음 프로세스를 따릅니다.
- 계획 수립 —
IMPLEMENTATION_PLAN.md에 단계별 목표와 성공 기준 작성 - 테스트 작성 — 코드 작성 전 테스트 케이스부터 정의 (TDD 접근)
- 최소한의 코드 구현 — 테스트를 통과하는 데 필요한 최소 코드 작성
- 리팩터링 — 코드 가독성과 구조 개선
- 커밋 — 변경 이유가 명확히 드러나는 메시지 작성
3. 3회 실패 규칙
Claude Code로 시도했는데 3번 연속 실패하면 바로 멈추고 재평가합니다.
- 실패 원인, 시도한 방법, 에러 메시지 기록
- 다른 구현 사례 2~3개 조사
- 추상화 수준 점검 및 문제 쪼개기
- 새로운 접근 방식 모색
이 규칙 덕분에 불필요한 반복 작업에 시간을 쓰지 않게 됩니다.
4. 아키텍처와 코드 품질 원칙
Claude Code가 생성하는 코드도 기본 품질 기준을 지켜야 합니다.
- 아키텍처: 상속보다 컴포지션, 싱글톤보다 인터페이스
- 품질: 모든 커밋은 컴파일·테스트 통과, 포맷팅·린팅 규칙 준수
- 에러 처리: 명확하고 빠른 실패, 예외 삼키지 않기
5. 의사결정 기준
여러 접근 방법이 있다면 다음 순서로 결정합니다.
- 테스트 용이성
- 가독성
- 일관성
- 단순성
- 가역성(변경 용이성)
6. 완료 정의(Definition of Done)
Claude Code 작업이 끝났다고 판단하려면 다음을 모두 충족해야 합니다.
- 테스트 작성 및 통과
- 프로젝트 규칙 준수
- 포맷터·린터 경고 없음
- 커밋 메시지 명확
- 계획과 일치하는 구현
- TODO에 반드시 이슈 번호 포함
7. 중요한 금기와 필수 사항
절대 하지 말 것:
--no-verify로 커밋 훅 우회- 테스트 비활성화
- 컴파일 안 되는 코드 커밋
- 근거 없는 추측
반드시 할 것:
- 작동하는 코드 점진적 커밋
- 계획 문서 지속 업데이트
- 기존 구현 참고
- 3회 실패 시 재평가
이 가이드는 Claude Code뿐만 아니라 모든 LLM 기반 코딩 에이전트를 효율적으로 사용하는 데 도움이 됩니다.
여러분도 자신의 개발 철학과 프로세스를 CLAUDE.md처럼 정리해 두면, AI와 협업할 때 훨씬 더 안정적이고 재현 가능한 결과를 얻을 수 있습니다.
2. CLAUDE.md(~/.claude/CLAUDE.md)
# 개발 가이드라인
## 철학
### 핵심 신념
- **대폭 변화보다 점진적 개선** — 컴파일되고 테스트 통과하는 작은 변경
- **기존 코드에서 배우기** — 구현 전에 분석과 계획
- **교조주의보다 실용주의** — 프로젝트 현실에 맞춰 조정
- **영리한 코드보다 명확한 의도** — 지루하고 명확한 코드 선택
### 단순함의 의미
- 함수/클래스당 단일 책임
- 섣부른 추상화 지양
- 기교 없는 선택 — 평범한 해법 선택
- 설명이 필요하다면 너무 복잡한 것
## 프로세스
### 1. 계획 & 단계 설정
복잡한 작업은 3~5단계로 나누고, `IMPLEMENTATION_PLAN.md`에 기록:
## Stage N: [단계명]
**목표**: [구체적 산출물]
**성공 기준**: [테스트 가능 결과]
**테스트**: [구체적 테스트 케이스]
**상태**: [Not Started|In Progress|Complete]
- 진행에 따라 상태 업데이트
- 모든 단계 완료 시 파일 삭제
### 2. 구현 흐름
1. 이해하기 — 기존 코드 패턴 분석
2. 테스트 작성 — 먼저 테스트 작성 (빨간불)
3. 구현 — 테스트 통과 최소 코드 작성 (초록불)
4. 리팩터링 — 테스트 통과 상태에서 코드 정리
5. 커밋 — 계획과 연결된 명확한 메시지 작성
### 3. 막혔을 때 (최대 3회 시도 후 중단)
- 실패 기록
- 대안 조사
- 기본 가정 점검
- 다른 각도 시도
## 기술 표준
### 아키텍처 원칙
- 상속보다 컴포지션
- 싱글톤보다 인터페이스
- 암묵성보다 명시성
- 가능하면 TDD
### 코드 품질
- 모든 커밋은 컴파일·테스트 통과
- 신규 기능 테스트 포함
- 포맷터/린터 준수
- 커밋 전 자가 검토
### 에러 처리
- 빠른 실패 + 명확한 메시지
- 디버깅 컨텍스트 포함
- 예외는 적절한 수준에서 처리
## 의사결정 기준
1. 테스트 용이성
2. 가독성
3. 일관성
4. 단순성
5. 가역성
## 프로젝트 통합
- 유사 기능 3개 찾기
- 패턴·규칙 파악
- 동일 라이브러리 활용
- 기존 테스트 패턴 준수
## 품질 게이트
- 테스트 작성 및 통과
- 규칙 준수
- 포맷터/린터 경고 없음
- 커밋 메시지 명확
- 계획과 일치
- TODO는 이슈 번호 포함
## 테스트 가이드라인
- 구현이 아닌 동작 테스트
- 가능한 한 테스트당 하나의 단언문
- 시나리오를 설명하는 테스트명
- 결정론적 테스트 작성
## 중요한 주의사항
**절대 하지 말 것**:
- `--no-verify` 사용
- 테스트 비활성화
- 컴파일 불가 코드 커밋
- 근거 없는 추측
**반드시 할 것**:
- 동작하는 코드 점진적 커밋
- 계획 문서 업데이트
- 기존 구현 참고
- 3회 실패 후 재평가
- Claude Code에서 최고의 결과를 얻는 방법
- Claude Code 설정
- 클로드 코드 시작하기
- Claude의 메모리 관리
- 일반적인 워크플로우
- Claude Code: 클로드 코드 실용 팁
- Claude Code: 에이전트형 코딩을 위한 모범 사례
- ✍️ Claude Code 시리즈 3편
- ✍️ Claude Code 시리즈 2편
- ✍️ 시리즈 1편: 중소기업도 AI 개발 비서를 둘 수 있다 – Claude Code 이야기
- Claude Code CLI로 개발하는 새로운 시대: 터미널 속 AI 팀원 활용 가이드
- 💡 Claude Code를 쓰면서도 무료 모델을?
