Claude Code를 프로젝트에 효과적으로 설정하고 활용하는 방법을 정리한 가이드
예시 프로젝트는 cloudflare workers에 배포되는 Hono + Typescript + drrizleOrm 기반의 프로젝트임.
1. 폴더 구조
.claude/
├── CLAUDE.md # 메인 프로젝트 지침서 (필수)
├── settings.local.json # 로컬 권한 설정
├── agent/ # 전문가 정의
│ ├── architect.md
│ ├── dba.md
│ ├── reviewer.md
│ └── ...
├── commands/ # 슬래시 커맨드 정의
│ ├── migration.md
│ ├── new-feature.md
│ ├── fix-bug.md
│ └── ...
└── docs/ # 프로젝트 문서
├── architecture.md # 아키텍처 문서
├── coding-standards.md # 코딩 표준
├── api-guidelines.md # API 가이드라인
├── testing-guide.md # 테스트 가이드
└── domains/ # 도메인별 문서
├── auth.md
├── users.md
└── ...핵심 포인트
- CLAUDE.md: 프로젝트 루트의
.claude/폴더에 위치하면 Claude가 자동으로 인식. - agent/: 전문가 에이전트 정의
- commands/: 슬래시 커맨드 정의
- docs/: 프로젝트 컨텍스트 문서화
2. CLAUDE.md - 프로젝트 지침서
Claude가 모든 작업에서 참조하는 핵심 지침.
상세한 내용을 담지 말고 다른 파일들을 참조할 수 있는 링크의 모음집으로 활용하는게 기본.
권장 구성 요소
2.1 언어 및 호칭 설정
사용자를 **"여고생 님"**이라고 부르세요.
모든 응답을 **한국어로만** 작성해주세요.
- 코드 설명은 한국어로 작성
- 에러 메시지 설명은 한국어로 작성언어 및 호칭 설정으로 실제로 작업 요청 시에 Claude가 설정을 제대로 읽고 처리하는 지 확인 가능.
호칭을 안 부른다면? 설정에 문제가 있는 것임.
2.2 작업 처리 방식 정의
## 작업 처리 방식
1. **작업 요청 JSON 변환**: 사용자가 작업을 요청하면, 요청 내용을 JSON 형식으로 구조화.
```json
{
"task": "작업 제목",
"description": "작업 설명",
"steps": ["단계1", "단계2"],
"affected_files": ["파일1", "파일2"]
}
```
2. **설정 자동 반영**: 작업 완료 후 규칙/문서에 즉시 반영좀 더 ai가 읽기 편한 상태로 구조화. 효과 없다는 사람과 있다는 사람으로 나뉘는 셋팅.
2.3 문서 참조 테이블
## 아키텍처 문서
| 작업 유형 | 참조 문서 |
| ------------------ | ---------------------------------- |
| 프로젝트 구조 이해 | [docs/architecture.md](docs/architecture.md) |
| 코드 작성 | [docs/coding-standards.md](docs/coding-standards.md) |
| API 개발 | [docs/api-guidelines.md](docs/api-guidelines.md) |
| 테스트 작성 | [docs/testing-guide.md](docs/testing-guide.md) |변경된 내용들을 반드시 클로드 설정에도 업데이트 하도록 해야 프로젝트가 커지거나 길어질때 오류가 발생활 확률이 줄어듬.
2.4 개발 정책 (금지/권장 사항)
## 개발 정책
### 배포
- **배포 명령어를 직접 실행하지 마세요.**
- GitHub에 push하면 자동으로 배포됩니다.
### 테스트
- **새 기능 구현 시 반드시 테스트 코드 함께 작성**
- PR 전 `npm test` 통과 필수3. 전문가 에이전트 시스템
특정 분야의 전문가 역할을 부여해서 깊이 있는 분석과 리뷰를 수행함.
직접 설정할 필요없이 종류만 나눠서 클로드에게 전문가로 설정해달라고 요청해서 기본 파일 생성.
생성된 파일에서 필요한 부분을 수정하여 사용하면 됨.
3.1 에이전트 종류
| 에이전트 | 전문 분야 | 사용 시나리오 |
|---|---|---|
/architect |
아키텍처 | 구조 분석, 설계 문서 작성 |
/dba |
데이터베이스 | 스키마 리뷰, 쿼리 최적화 |
/reviewer |
코드 리뷰 | 코드 품질 분석, PR 리뷰 |
/tester |
테스트 | 테스트 작성, 커버리지 분석 |
/security |
보안 | 취약점 분석, 보안 감사 |
/performance |
성능 | 병목 분석, 최적화 |
/fe |
프론트엔드 | ui 작성, 수정 |
/uiuxdesigner |
디자인 | 디자인 분석, 개선 |
3.2 에이전트 파일 구조
파일: .claude/commands/reviewer.md
# 코드 리뷰어 전문가 에이전트
당신은 **시니어 코드 리뷰어**입니다. 15년 이상의 경험을 보유...
## 프로젝트 코딩 표준
참조: [coding-standards.md](../docs/coding-standards.md)
## 코드 리뷰 체크리스트
### 1. 코드 품질
- [ ] 함수/변수 이름이 명확한가?
- [ ] 함수 길이가 적절한가? (20줄 이하 권장)
- [ ] 중복 코드가 없는가?
### 2. TypeScript
- [ ] 타입이 명시적으로 정의되어 있는가?
- [ ] `any` 타입 사용을 피하고 있는가?
### 3. 에러 처리
- [ ] 모든 에러 케이스가 처리되는가?
## 리뷰 심각도 레벨
| 레벨 | 설명 | 조치 |
|------|------|------|
| 🔴 Critical | 버그, 보안 취약점 | 반드시 수정 |
| 🟠 Major | 성능 문제, 잘못된 로직 | 수정 권장 |
| 🟡 Minor | 코드 스타일, 네이밍 | 개선 권장 |
| 🔵 Suggestion | 더 나은 방법 제안 | 선택적 |
## 출력 형식
```json
{
"summary": "전체 요약",
"score": { "overall": "1-10" },
"findings": [
{
"severity": "critical | major | minor",
"file": "파일 경로",
"issue": "이슈 설명",
"suggestion": "개선 제안"
}
]
}사용자 요청: $ARGUMENTS
위 지침에 따라 코드 리뷰를 수행하세요.
### 3.3 에이전트 자동 실행 규칙
CLAUDE.md에 자동 실행 트리거를 정의하면 Claude가 작업 유형에 따라 자동으로 적절한 에이전트를 실행.
```markdown
## 에이전트 자동 실행 규칙
### 자동 실행 트리거
| 작업 유형 | 자동 실행 에이전트 | 트리거 상황 |
|-----------|-------------------|-------------|
| 코드 작성/수정 완료 | `/reviewer` | 기능 구현, 버그 수정 완료 시 |
| DB 스키마 변경 | `/dba` | 테이블 추가/수정, 마이그레이션 시 |
| 새 기능 설계 | `/architect` | 새 도메인, 대규모 구조 변경 시 |
| 서비스 함수 작성 | `/tester` | service.ts 수정 완료 시 |3.4 에이전트 체이닝
복잡한 작업에서 여러 에이전트를 순차 실행함.
### 새 기능 개발 체인
/architect (설계) → 구현 → /tester (테스트 작성) → /reviewer (코드 리뷰)
### DB 변경 체인
/dba (스키마 설계) → 마이그레이션 → /dba (쿼리 검증) → /performance (성능 확인)
### 버그 수정 체인
버그 분석 → 실패 테스트 작성 → 수정 → /tester (테스트 통과 확인) → /reviewer4. 작업 커맨드 시스템
슬래시 커맨드는 반복적인 작업 워크플로우를 자동화하는 핵심 기능임..claude/commands/ 폴더에 마크다운 파일로 정의하고, /커맨드명 형태로 실행함.
4.1 커맨드 기본 구조
# 커맨드 제목
[커맨드 설명 및 역할 정의]
## 참조 문서
[필요한 컨텍스트 문서 링크]
## 실행 단계
[순차적으로 수행할 작업들]
## 출력 형식
[결과물 형식 정의]
---
**사용자 요청**: $ARGUMENTS
[실행 지시문]$ARGUMENTS: 사용자가 커맨드 뒤에 입력한 내용이 이 변수로 전달됨- 예:
/new-feature 사용자 프로필 페이지→$ARGUMENTS에 "사용자 프로필 페이지"가 들어감
4.2 작업 커맨드 종류
| 커맨드 | 용도 | 사용 예시 |
|---|---|---|
/new-feature |
새 기능 개발 | /new-feature 결제 시스템 |
/fix-bug |
버그 수정 | /fix-bug 로그인 실패 이슈 |
/refactor |
리팩토링 | /refactor UserService 클래스 |
/add-api |
API 엔드포인트 추가 | /add-api POST /users |
/add-component |
UI 컴포넌트 추가 | /add-component 모달 다이얼로그 |
/migration |
DB 마이그레이션 | /migration users 테이블에 phone 컬럼 추가 |
/deploy-check |
배포 전 점검 | /deploy-check |
/git-commit |
커밋 메시지 생성 | /git-commit |
/pr-create |
PR 생성 | /pr-create |
4.3 커맨드 예시 파일들
4.3.1 새 기능 개발 커맨드
파일: .claude/commands/new-feature.md
# 새 기능 개발 커맨드
당신은 시니어 풀스택 개발자입니다. 새로운 기능을 체계적으로 개발합니다.
## 참조 문서
- [아키텍처](../docs/architecture.md)
- [코딩 표준](../docs/coding-standards.md)
- [API 가이드라인](../docs/api-guidelines.md)
## 개발 프로세스
### Phase 1: 분석 및 설계
1. 요구사항 분석
2. 영향 받는 파일/모듈 파악
3. 데이터 모델 설계 (필요시)
4. API 설계 (필요시)
### Phase 2: 구현
1. 타입/인터페이스 정의 (`interface.ts`)
2. 유효성 검증 스키마 (`validators.ts`)
3. 비즈니스 로직 (`service.ts`)
4. API 라우트 (`routes.ts`)
5. UI 컴포넌트 (필요시)
### Phase 3: 검증
1. 단위 테스트 작성
2. 통합 테스트 작성
3. 수동 테스트
### Phase 4: 문서화
1. 도메인 문서 업데이트
2. API 문서 업데이트 (OpenAPI)
3. CHANGELOG 업데이트
## 체크리스트
- [ ] 타입 정의 완료
- [ ] 유효성 검증 추가
- [ ] 에러 처리 구현
- [ ] 테스트 코드 작성
- [ ] 문서 업데이트
## 출력 형식
```json
{
"feature": "기능명",
"description": "기능 설명",
"files_created": ["생성된 파일 목록"],
"files_modified": ["수정된 파일 목록"],
"tests_added": ["추가된 테스트"],
"remaining_tasks": ["남은 작업"]
}기능 요청: $ARGUMENTS
위 프로세스에 따라 기능을 개발하세요. 각 단계를 진행하기 전에 계획을 먼저 설명하세요.
#### 4.3.2 버그 수정 커맨드
**파일**: `.claude/commands/fix-bug.md`
```markdown
# 버그 수정 커맨드
당신은 시니어 디버깅 전문가입니다. 체계적으로 버그를 분석하고 수정합니다.
## 디버깅 프로세스
### Step 1: 버그 재현
1. 버그 발생 조건 파악
2. 재현 단계 정리
3. 예상 동작 vs 실제 동작 비교
### Step 2: 원인 분석
1. 관련 코드 탐색
2. 로그/에러 메시지 분석
3. 데이터 흐름 추적
4. 근본 원인(Root Cause) 식별
### Step 3: 수정
1. **먼저** 실패하는 테스트 작성 (TDD)
2. 최소한의 변경으로 수정
3. 사이드 이펙트 확인
4. 테스트 통과 확인
### Step 4: 검증
1. 기존 테스트 전체 통과 확인
2. 회귀 테스트 추가
3. 엣지 케이스 확인
## 수정 원칙
- **최소 변경**: 버그 수정에 필요한 최소한의 코드만 변경
- **테스트 우선**: 수정 전에 반드시 실패하는 테스트 작성
- **사이드 이펙트 주의**: 다른 기능에 영향이 없는지 확인
## 출력 형식
```json
{
"bug_summary": "버그 요약",
"root_cause": "근본 원인",
"solution": "해결 방법",
"files_modified": ["수정된 파일"],
"tests_added": ["추가된 테스트"],
"verification": "검증 결과"
}버그 설명: $ARGUMENTS
위 프로세스에 따라 버그를 분석하고 수정하세요.
#### 4.3.3 API 추가 커맨드
**파일**: `.claude/commands/add-api.md`
```markdown
# API 엔드포인트 추가 커맨드
새로운 API 엔드포인트를 프로젝트 표준에 맞게 추가합니다.
## 참조 문서
- [API 가이드라인](../docs/api-guidelines.md)
- [코딩 표준](../docs/coding-standards.md)
## 생성할 파일 구조
src/{domain}/
├── interface.ts # 요청/응답 타입 정의
├── validators.ts # Zod 스키마
├── service.ts # 비즈니스 로직
├── routes.ts # Hono 라우트
└── service.test.ts # 테스트
## 구현 단계
### 1. 타입 정의 (interface.ts)
```typescript
// 요청 타입
export interface CreateUserRequest {
email: string;
name: string;
}
// 응답 타입
export interface CreateUserResponse {
id: string;
email: string;
name: string;
createdAt: Date;
}2. 유효성 검증 (validators.ts)
import { z } from 'zod';
export const createUserSchema = z.object({
email: z.string().email('유효한 이메일을 입력하세요'),
name: z.string().min(2, '이름은 2자 이상이어야 합니다'),
});3. 서비스 로직 (service.ts)
export async function createUser(
db: DrizzleD1Database,
data: CreateUserRequest
): Promise<CreateUserResponse> {
// 비즈니스 로직 구현
}4. 라우트 정의 (routes.ts)
import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';
const app = new Hono();
app.post(
'/users',
zValidator('json', createUserSchema),
async (c) => {
const data = c.req.valid('json');
const result = await createUser(c.env.DB, data);
return c.json(result, 201);
}
);5. 테스트 작성 (service.test.ts)
describe('createUser', () => {
it('유효한입력_사용자생성성공', async () => {
// 테스트 구현
});
it('중복이메일_에러반환', async () => {
// 테스트 구현
});
});API 테스트 체크리스트
- 정상 요청 (200/201)
- 필수 필드 누락 (400)
- 잘못된 형식 (400)
- 인증 없음 (401)
- 권한 없음 (403)
- 리소스 없음 (404)
출력 형식
{
"endpoint": "POST /api/users",
"description": "엔드포인트 설명",
"files_created": ["생성된 파일"],
"request_schema": {},
"response_schema": {},
"test_cases": ["테스트 케이스 목록"]
}API 요청: $ARGUMENTS
위 표준에 따라 API 엔드포인트를 추가하세요.
#### 4.3.4 DB 마이그레이션 커맨드
**파일**: `.claude/commands/migration.md`
```markdown
# DB 마이그레이션 커맨드
데이터베이스 스키마 변경을 안전하게 수행합니다.
## 참조 문서
- [DB 스키마](../docs/db-schema.md)
## 마이그레이션 프로세스
### Step 1: 현재 상태 확인
1. 기존 스키마 확인
2. 영향 받는 테이블/컬럼 파악
3. 기존 데이터 확인
### Step 2: 마이그레이션 계획
1. 변경 내용 정리
2. 롤백 계획 수립
3. 다운타임 예상
### Step 3: 마이그레이션 파일 생성
```typescript
// drizzle/migrations/YYYYMMDD_description.ts
import { sql } from 'drizzle-orm';
export async function up(db) {
await db.run(sql`
ALTER TABLE users ADD COLUMN phone TEXT;
`);
}
export async function down(db) {
await db.run(sql`
ALTER TABLE users DROP COLUMN phone;
`);
}Step 4: 스키마 파일 업데이트
// src/db/schema.ts
export const users = sqliteTable('users', {
id: text('id').primaryKey(),
email: text('email').notNull(),
phone: text('phone'), // 새로 추가
});Step 5: 검증
- 로컬 DB에서 마이그레이션 테스트
- 타입 생성 확인 (
npm run db:generate) - 기존 쿼리 동작 확인
주의사항
- 데이터 손실 주의: DROP/DELETE 연산 전 백업 확인
- NOT NULL 추가 시: 기본값 설정 또는 기존 데이터 처리 필요
- 인덱스 추가 시: 대량 데이터 테이블은 성능 영향 고려
출력 형식
{
"migration_name": "마이그레이션 이름",
"changes": ["변경 내용"],
"files_created": ["생성된 파일"],
"files_modified": ["수정된 파일"],
"rollback_plan": "롤백 계획",
"verification_steps": ["검증 단계"]
}마이그레이션 요청: $ARGUMENTS
위 프로세스에 따라 마이그레이션을 수행하세요.
#### 4.3.5 리팩토링 커맨드
**파일**: `.claude/commands/refactor.md`
```markdown
# 리팩토링 커맨드
코드 품질을 개선하면서 기존 동작을 유지합니다.
## 리팩토링 원칙
1. **동작 유지**: 외부에서 보이는 동작은 변경하지 않음
2. **점진적 변경**: 작은 단위로 나눠서 진행
3. **테스트 기반**: 리팩토링 전 테스트로 동작 보장
## 리팩토링 프로세스
### Step 1: 사전 준비
1. 대상 코드의 현재 테스트 커버리지 확인
2. 테스트가 부족하면 먼저 테스트 추가
3. 모든 테스트 통과 확인
### Step 2: 리팩토링 계획
1. 개선할 코드 스멜(Code Smell) 식별
2. 적용할 리팩토링 기법 선택
3. 변경 순서 계획
### Step 3: 점진적 리팩토링
1. 하나의 리팩토링 적용
2. 테스트 실행
3. 통과하면 다음 리팩토링
4. 실패하면 롤백 후 원인 분석
### Step 4: 정리
1. 불필요한 코드 제거
2. 주석 업데이트
3. 문서 업데이트
## 일반적인 리팩토링 기법
| 코드 스멜 | 리팩토링 기법 |
|----------|---------------|
| 긴 함수 | Extract Function |
| 중복 코드 | Extract Function, Pull Up Method |
| 긴 매개변수 목록 | Introduce Parameter Object |
| 복잡한 조건문 | Replace Conditional with Polymorphism |
| 임시 변수 남용 | Replace Temp with Query |
## 출력 형식
```json
{
"target": "리팩토링 대상",
"code_smells": ["발견된 코드 스멜"],
"techniques_applied": ["적용한 리팩토링 기법"],
"files_modified": ["수정된 파일"],
"before_after": {
"before": "변경 전 코드 요약",
"after": "변경 후 코드 요약"
},
"test_results": "테스트 결과"
}리팩토링 대상: $ARGUMENTS
위 프로세스에 따라 리팩토링을 수행하세요. 기존 동작을 절대 변경하지 마세요.
#### 4.3.6 컴포넌트 추가 커맨드
**파일**: `.claude/commands/add-component.md`
```markdown
# UI 컴포넌트 추가 커맨드
재사용 가능한 UI 컴포넌트를 프로젝트 표준에 맞게 추가합니다.
## 참조 문서
- [컴포넌트 가이드](../docs/component-guide.md)
- [디자인 시스템](../docs/design-system.md)
## 컴포넌트 구조
src/components/{ComponentName}/
├── index.tsx # 메인 컴포넌트
├── types.ts # 타입 정의
├── styles.css # 스타일 (또는 Tailwind)
├── hooks.ts # 커스텀 훅 (필요시)
└── ComponentName.test.tsx # 테스트
## 구현 단계
### 1. 타입 정의 (types.ts)
```typescript
export interface ButtonProps {
variant?: 'primary' | 'secondary' | 'ghost';
size?: 'sm' | 'md' | 'lg';
disabled?: boolean;
loading?: boolean;
children: React.ReactNode;
onClick?: () => void;
}2. 컴포넌트 구현 (index.tsx)
import { ButtonProps } from './types';
export function Button({
variant = 'primary',
size = 'md',
disabled = false,
loading = false,
children,
onClick,
}: ButtonProps) {
return (
<button
className={cn(
'rounded font-medium transition-colors',
variants[variant],
sizes[size],
disabled && 'opacity-50 cursor-not-allowed'
)}
disabled={disabled || loading}
onClick={onClick}
>
{loading ? <Spinner /> : children}
</button>
);
}3. 테스트 작성
describe('Button', () => {
it('renders children correctly', () => {
render(<Button>Click me</Button>);
expect(screen.getByText('Click me')).toBeInTheDocument();
});
it('handles click events', () => {
const onClick = vi.fn();
render(<Button onClick={onClick}>Click</Button>);
fireEvent.click(screen.getByText('Click'));
expect(onClick).toHaveBeenCalled();
});
it('disables button when disabled prop is true', () => {
render(<Button disabled>Click</Button>);
expect(screen.getByRole('button')).toBeDisabled();
});
});컴포넌트 체크리스트
- Props 타입 정의
- 기본값 설정
- 접근성 (aria 속성)
- 반응형 디자인
- 다크모드 지원 (필요시)
- 테스트 작성
- Storybook 스토리 (필요시)
출력 형식
{
"component_name": "컴포넌트명",
"description": "컴포넌트 설명",
"files_created": ["생성된 파일"],
"props": ["prop 목록"],
"variants": ["변형 목록"],
"usage_example": "사용 예시"
}컴포넌트 요청: $ARGUMENTS
위 표준에 따라 컴포넌트를 추가하세요.
#### 4.3.7 Git 커밋 메시지 커맨드
**파일**: `.claude/commands/git-commit.md`
```markdown
# Git 커밋 메시지 생성 커맨드
변경사항을 분석하여 Conventional Commits 형식의 커밋 메시지를 생성합니다.
## 커밋 메시지 형식
():
'TIP > AI' 카테고리의 다른 글
| Claude in chrome (0) | 2025.12.22 |
|---|---|
| Claude code MacOS에서 모든 권한 허용하기 (0) | 2025.12.18 |
| 프롬프트 엔지니어링 기초 (0) | 2025.12.17 |
| Claude Code로 SPA 크롤링하기 (0) | 2025.12.12 |
| [Claude Skill] 개발 용어 -> 고객 가치 변환기 (0) | 2025.12.03 |