Claude Code 모범 사례
읽는 시간: 10분 | 난이도: 중급자
Claude Code를 최대한 활용하기 위한 검증된 패턴과 팁을 소개합니다.
CLAUDE.md 파일 활용
CLAUDE.md는 Claude Code에게 프로젝트 컨텍스트를 제공하는 가장 중요한 도구입니다.
효과적인 CLAUDE.md 작성
# 프로젝트: MyApp
## 기술 스택
- Frontend: React 18, TypeScript, Tailwind CSS
- Backend: Node.js, Express, PostgreSQL
- 배포: Vercel (frontend), Railway (backend)
## 코딩 규칙
- 함수명: camelCase
- 컴포넌트명: PascalCase
- 테스트: Jest + Testing Library
- 항상 TypeScript strict 모드 사용
## 금지사항
- any 타입 사용 금지
- console.log를 프로덕션 코드에 남기지 말 것
## 자주 사용하는 명령어
- 개발 서버: `npm run dev`
- 테스트: `npm test`
- 빌드: `npm run build`
자세한 내용은 CLAUDE.md 설정 가이드를 참조하세요.
명확하고 구체적인 요청
모호한 요청
> 이 코드를 수정해줘
> 버그를 찾아줘
> 성능을 개선해줘
구체적인 요청
> src/api/users.ts의 getUserById 함수에서
사용자를 찾지 못할 때 null 대신
UserNotFoundError를 throw하도록 수정해줘
> 데이터베이스 쿼리가 1초 이상 걸리는
함수를 찾아서 인덱스 추가 방법을 제안해줘
> ProductList 컴포넌트의 리렌더링 횟수를 줄이기 위해
React.memo와 useCallback을 적절히 추가해줘
점진적 접근법
큰 작업을 작은 단계로 분해
한 번에 너무 많은 요청:
> 전체 인증 시스템을 JWT에서 OAuth2로
마이그레이션하고 UI도 전부 업데이트해줘
단계별 접근:
> 1단계: 현재 JWT 인증 구조를 분석해줘
> 2단계: OAuth2 마이그레이션 계획을 세워줘
> 3단계: 백엔드 인증 로직부터 변경해줘
> 4단계: 프론트엔드 로그인 UI를 업데이트해줘
컨텍스트 관리
새 작업 시작 시 컨텍스트 초기화
긴 대화는 성능 저하를 일으킬 수 있습니다:
# 현재 컨텍스트 초기화
/clear
# 또는 중요한 컨텍스트 유지하며 일부 초기화
/compact
관련 파일 명시적으로 언급
> @src/components/Cart.tsx 파일을 보고
장바구니 계산 로직의 버그를 찾아줘
검증 및 테스트
변경 후 항상 테스트 실행 요청
> 변경사항을 적용한 후 관련 테스트를 실행해줘
> 이 리팩토링 후 기존 테스트가 모두 통과하는지 확인해줘
단위 테스트 함께 작성
> calculateTax 함수를 구현하고
엣지 케이스를 포함한 단위 테스트도 작성해줘
코드 리뷰 활용
구현 전 설계 검토
> 이 기능을 구현하기 전에 접근 방식을 검토해줘:
- 사용자 권한 확인
- 데이터 유효성 검사
- 에러 처리 전략
어떤 문제점이 있을까?
보안 검토
> 이 코드에 SQL 인젝션이나 XSS 취약점이 있는지 검토해줘
> 사용자 입력을 처리하는 모든 함수의 보안을 검토해줘
Git 워크플로우
작은 단위로 커밋
> 각 기능 변경사항을 별도의 커밋으로 나눠서
의미있는 메시지와 함께 커밋해줘
커밋 전 확인
> 커밋하기 전에 변경된 파일 목록과
주요 변경사항을 요약해줘
반복 패턴 최적화
자주 사용하는 워크플로우를 슬래시 명령어로 저장
# .claude/commands/fix-types.md
TypeScript 타입 오류를 모두 찾아서 수정해줘.
strict 모드를 유지하되 any 타입 사용은 금지.
자세한 내용은 슬래시 명령어 가이드를 참조하세요.
대규모 코드베이스 처리
관련 부분만 집중
> authentication 모듈만 집중해서 분석해줘.
전체 코드베이스를 보지 말고
src/auth/ 디렉토리만 참조해줘.
점진적 리팩토링
> 전체 코드베이스를 한 번에 리팩토링하는 대신
Cart 컴포넌트 하나만 먼저 현대적인 패턴으로 변환해줘.
나머지는 이 패턴을 따라 순차적으로 처리할게.
에러 처리
에러 발생 시 컨텍스트 제공
> 다음 에러가 발생했어:
TypeError: Cannot read property 'map' of undefined
at ProductList (ProductList.tsx:45)
ProductList 컴포넌트를 확인하고 원인을 찾아줘.
products prop이 undefined인 경우도 처리해줘.
문서화
코드와 함께 문서 업데이트
> getUserProfile 함수를 구현하고
JSDoc 주석과 README 업데이트도 함께 해줘.
성능 최적화 팁
- 짧은 세션 선호: 긴 대화보다 목적이 명확한 짧은 세션이 효과적
- 파일 경로 명시:
@파일경로형식으로 특정 파일을 지정 - 출력 범위 제한: 불필요한 전체 파일 출력 요청 최소화
- 이전 결과 참조: "방금 만든 함수를 활용해서..." 방식으로 연속성 유지
다음 단계
- CLAUDE.md 설정 - 프로젝트 컨텍스트 최적화
- 슬래시 명령어 - 반복 작업 자동화
- 훅 시스템 - 자동화 워크플로우 구성