Contents
see ListClaude Code는 Anthropic이 출시한 CLI 기반 AI 코딩 에이전트로, 터미널에서 직접 코드를 읽고, 수정하고, 실행하며, git 작업까지 수행할 수 있다. 기존 AI 코드 어시스턴트와 달리 실제 파일 시스템에 접근하여 프로젝트 전체를 이해하고 작업한다. 이 글에서는 Claude Code의 설치, 설정, 고급 활용법을 다룬다.
설치 및 시작
# npm으로 설치 (Node.js 18+ 필요)
npm install -g @anthropic-ai/claude-code
# 프로젝트 디렉토리에서 시작
cd ~/projects/my-app
claude
# 바로 명령 실행 (비대화형)
claude -p "이 프로젝트의 구조를 설명해줘"
# 파이프로 입력 전달
cat error.log | claude -p "이 에러 로그를 분석해줘"
CLAUDE.md로 프로젝트 규칙 설정
프로젝트 루트에 CLAUDE.md 파일을 생성하면 Claude Code가 프로젝트의 컨벤션과 규칙을 이해한다.
# CLAUDE.md 예시
# 프로젝트 규칙
## 기술 스택
- Backend: Spring Boot 3.3 + Java 21
- Frontend: React 18 + TypeScript
- DB: PostgreSQL 17
- Cache: Redis 7
## 코딩 컨벤션
- Java: Google Java Style Guide 준수
- 변수명은 camelCase, 상수는 UPPER_SNAKE_CASE
- API 응답은 항상 ResponseEntity로 래핑
- 모든 public 메서드에 Javadoc 작성
## 테스트 규칙
- 단위 테스트 필수 (JUnit 5 + Mockito)
- 테스트 메서드명: 한글로 행위_결과 형식
- 커버리지 80% 이상 유지
## Git 규칙
- 커밋 메시지: Conventional Commits 형식
- feat: 새 기능 / fix: 버그 수정 / refactor: 리팩토링
일상적인 개발 작업
코드 리뷰 및 리팩토링
# 프로젝트 진입 후
claude
# 코드 리뷰 요청
> src/service/UserService.java 파일을 리뷰해줘.
성능, 보안, 가독성 관점에서 개선점을 알려줘.
# 리팩토링 실행
> UserService에서 중복 코드를 제거하고
공통 로직을 별도 메서드로 추출해줘.
# 특정 패턴 적용
> 이 프로젝트의 Repository 클래스들에
QueryDSL 동적 쿼리 패턴을 적용해줘.
버그 수정
# 에러 메시지로 버그 추적
> NullPointerException이 OrderService.processOrder에서 발생해.
원인을 찾고 수정해줘.
# 테스트 실패 해결
> npm test 실행하면 UserList 컴포넌트 테스트가 실패해.
원인을 찾고 수정해줘.
# 로그 분석
> logs/error.log를 분석해서 최근 반복되는 에러 패턴을 정리해줘.
새 기능 구현
# API 엔드포인트 추가
> 상품 검색 API를 추가해줘.
- GET /api/products/search?q=keyword&category=electronics&page=0&size=20
- 키워드로 상품명, 설명 검색 (Full-text search)
- 카테고리 필터링
- 페이지네이션
- Controller, Service, Repository, DTO 모두 생성
# 프론트엔드 컴포넌트
> 상품 검색 결과를 표시하는 React 컴포넌트를 만들어줘.
- 검색 입력폼 (디바운스 적용)
- 무한 스크롤
- 로딩/에러 상태 처리
- TypeScript 타입 정의
고급 기능
에이전트(Sub-Agent) 활용
# .claude/agents/ 디렉토리에 에이전트 정의
# .claude/agents/deploy.md
# 배포 에이전트
## 역할
프로덕션 배포를 수행하는 에이전트
## 절차
1. 모든 테스트 실행 및 통과 확인
2. 빌드 수행
3. Docker 이미지 생성 및 태깅
4. 배포 실행
5. 헬스체크 확인
6. 결과 보고
스케줄 작업 설정
// workspace/schedules.json - 크론 작업 정의
{
"daily-report": {
"cron": "0 9 * * *",
"prompt": "오늘의 프로젝트 상태 리포트를 생성해줘"
},
"test-runner": {
"cron": "0 */6 * * *",
"prompt": "전체 테스트를 실행하고 실패가 있으면 알려줘"
}
}
Git 워크플로우
# 커밋
> 현재 변경사항을 커밋해줘
# Claude Code가 변경 내용을 분석하고 적절한 커밋 메시지 생성
# PR 생성
> 현재 브랜치로 PR을 생성해줘.
변경 내용을 요약해서 description에 넣어줘.
# PR 리뷰
> gh pr view 123을 확인하고 코드 리뷰를 해줘.
settings.json 설정
// .claude/settings.json
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git *)",
"Bash(docker *)"
],
"deny": [
"Bash(rm -rf /)",
"Bash(sudo *)"
]
},
"hooks": {
"preCommit": {
"command": "npm run lint && npm test"
}
}
}
CLI 플래그
# 모델 지정
claude --model claude-sonnet-4-20250514
claude --model claude-opus-4-20250514
# 비대화형 모드 (스크립트에서 사용)
claude -p "package.json의 의존성을 분석해줘" --output-format json
# 특정 파일 참조
claude -p "이 파일의 버그를 찾아줘" --file src/utils.ts
# 세션 이어가기
claude --continue # 마지막 세션 이어서
claude --resume SESSION_ID # 특정 세션 복원
# 최대 토큰 설정
claude --max-turns 50
효과적인 활용 팁
- CLAUDE.md를 상세하게 작성: 프로젝트 규칙, 기술 스택, 디렉토리 구조를 명시하면 결과 품질이 크게 향상된다
- 작은 단위로 요청: 한 번에 큰 변경보다 단계별로 요청하면 정확도가 높다
- 컨텍스트 제공: 관련 파일 경로나 에러 메시지를 함께 제공하면 더 정확한 결과를 얻는다
- 확인 후 진행: 큰 변경 전에 계획을 먼저 보여달라고 요청하고, 확인 후 실행을 지시한다
- git 활용: 변경 전 커밋해두면 Claude Code의 수정이 마음에 들지 않을 때 쉽게 되돌릴 수 있다
Claude Code는 단순한 코드 자동완성을 넘어, 프로젝트 전체를 이해하고 실제 개발 작업을 수행하는 AI 개발 동료다. CLAUDE.md로 프로젝트 맥락을 충분히 제공하고, 명확한 지시를 내리면 일상적인 개발 작업의 상당 부분을 위임할 수 있다.