Claude Code for Front-end #2: .claude 디렉토리

모든 프로젝트에 적용되는 나만의 AI 환경 - 프로젝트를 넘나들며 일관성 유지하기

---

1️⃣ 들어가며

1편에서 프로젝트별 CLAUDE.md 작성법을 소개했습니다. 각 프로젝트에서 Claude Code가 의도를 정확히 이해하고 코드를 작성할 수 있게 되었습니다.

그런데 여러 프로젝트를 진행하면서 한 가지 패턴을 발견했습니다.

모든 CLAUDE.md에서 반복되는 내용이 존재합니다.

# 프로젝트 A의 CLAUDE.md
- TypeScript에서 `any` 타입 사용 금지
- TODO 주석 대신 완전한 구현
- Git feature branch 전략 사용
- 한국어로 응답

# 프로젝트 B의 CLAUDE.md
- TypeScript에서 `any` 타입 사용 금지 (또 쓴다...)
- TODO 주석 대신 완전한 구현 (또 쓴다...)
- Git feature branch 전략 사용 (또...)
- 한국어로 응답 (또...)

이런 규칙들은 프로젝트별이 아니라 개인의 코딩 철학입니다.

이를 해결하는 방법이 바로 ~/.claude/ 디렉토리입니다.

---

2️⃣ .claude 디렉토리란?

홈 디렉토리의 전역 설정

~/.claude/ 는 홈 디렉토리에 만드는 전역 설정 공간입니다.

# macOS/Linux
~/.claude/
└── CLAUDE.md

# Windows
C:\\\\Users\\\\[username]\\\\.claude\\\\
└── CLAUDE.md

설정 우선순위 체계

Claude Code는 다음 순서로 설정을 읽어옵니다:

1. Claude Code 기본 동작
   ↓
2. ~/.claude/CLAUDE.md (전역 설정)
   ↓
3. [프로젝트]/CLAUDE.md (프로젝트 설정)
   ↓
4. 대화 중 명시적 지시

중요한 점: 아래 단계가 위 단계를 덮어씁니다.

예시:

• 전역: "한국어로 응답"
• 프로젝트: "영어로 응답" (문서화 프로젝트)
• 결과: 해당 프로젝트에서는 영어로 응답

언제 전역으로 빼야 하는가?

전역으로 관리 (~/.claude/):

• 개인 코딩 철학 (any 금지, DRY 원칙)
• 선호하는 응답 언어
• Git 워크플로우
• 보편적인 품질 기준

프로젝트별 관리 (CLAUDE.md):

• 기술 스택 (Next.js, React, Vue)
• 디렉토리 구조
• 프로젝트 특화 패턴
• 개발 명령어

판단 기준: "다른 프로젝트에서도 똑같이 적용할 규칙인가?"

---

3️⃣ ~/.claude/CLAUDE.md 구조

전역 설정에서 제가 실제로 사용하는 규칙들을 소개합니다.

1. 언어 설정

# Language Preference

Always respond in Korean using formal language (존댓말).

효과: 모든 프로젝트에서 한국어로 대화할 수 있습니다. 영어 문서화가 필요한 프로젝트에서만 CLAUDE.md에서 재정의합니다.

2. TypeScript 규칙

## TypeScript Rules

### Type Safety
- **Never use `any` type** - Always use `unknown`, specific types, or generics
- Prefer interfaces over types for object shapes
- Always define return types for functions
- Use strict mode settings

### Examples

```typescript
// ❌ Bad
function fetchData(): any {
  return fetch('/api/data')
}

// ✅ Good
interface ApiResponse {
  data: User[]
  total: number
}

async function fetchData(): Promise<ApiResponse> {
  const response = await fetch('/api/data')
  return response.json()
}

효과: Claude Code가 절대 any 타입을 제안하지 않습니다.

3. 코드 품질 기준

## Code Quality Standards

### Implementation Rules
- **No TODO comments** - Implement completely or don't start
- **No magic numbers/strings** - Define as constants
- **No console.log** - Use proper logging utility
- **Maximum function length**: 30 lines
- **Maximum component length**: 150 lines

### Examples

```typescript
// ❌ Bad
function calculate(price: number) {
  // TODO: add tax calculation
  return price * 1.1  // Magic number
}

// ✅ Good
const TAX_RATE = 0.1

function calculate(price: number): number {
  return price * (1 + TAX_RATE)
}

효과: Claude Code가 항상 완전한 코드를 작성하며, magic number를 상수로 정의합니다.

4. Git 워크플로우

## Git Workflow

### Branch Strategy
- Always work on feature branches
- Never commit directly to `main` or `master`
- Use meaningful commit messages

### Commit Message Format
- feat: Add user authentication 
- fix: Resolve login redirect issue 
- refactor: Simplify API client logic

### Before Commit Checklist
1. Run linting: `npm run lint`
2. Run tests: `npm run test`
3. Review changes: `git diff`

효과: Claude Code가 Git 작업 시 항상 feature branch를 사용하고, 린트/테스트를 실행합니다.

5. 금지 패턴

## Prohibited Patterns

- ❌ **No `any` type**
- ❌ **No TODO comments**
- ❌ **No console.log** (use logger)
- ❌ **No inline styles** (use CSS/Tailwind)
- ❌ **No magic numbers** (define constants)
- ❌ **No partial implementations** (complete or don't start)

효과: 이런 패턴을 제안하면 즉시 거부하고 대안을 제시합니다.

---

4️⃣ 실제 적용 효과

Before: 반복 설명의 지옥

프로젝트 A에서:

나: "API 호출 함수 만들어줘"
Claude: [함수 생성]
나: "any 타입 쓰지 마"
Claude: [수정]
나: "console.log 빼고"
Claude: [수정]
나: "TODO 주석 말고 완전히 구현해"
Claude: [수정]

프로젝트 B로 이동:

나: "API 호출 함수 만들어줘"
Claude: [함수 생성]
나: "any 타입 쓰지 마" (또...)
Claude: [수정]
나: "console.log 빼고" (또...)
Claude: [수정]

After: 한 번 설정, 영원히 적용

~/.claude/CLAUDE.md 설정 후:

나: "API 호출 함수 만들어줘"
Claude: [any 없이, console.log 없이, 완전히 구현된 함수 생성]

모든 프로젝트에서 동일하게 적용됩니다.

---

5️⃣ 전역 vs 프로젝트별 분리 전략

제가 실제로 사용하는 분리 기준입니다.

전역 설정 (~/.claude/CLAUDE.md)

1. 언어 및 커뮤니케이션:

- 응답 언어 (한국어/영어)
- 응답 스타일 (formal/casual)
- 설명 상세도

2. 코딩 철학:

- TypeScript any 금지
- DRY (Don't Repeat Yourself) 원칙
- SOLID 원칙
- 완전 구현 원칙 (No TODO)

3. Git 워크플로우:

- Feature branch 전략
- Commit message 형식
- PR 전 체크리스트

4. 품질 기준:

- 함수 최대 길이
- 컴포넌트 최대 길이
- 네이밍 컨벤션 기본 원칙
- 금지 패턴

프로젝트별 설정 (CLAUDE.md)

1. 기술 스택:

- 프레임워크 (Next.js, React, Vue)
- 상태 관리 (Zustand, Redux, Recoil)
- 스타일링 (Tailwind, styled-components)

2. 프로젝트 구조:

- 디렉토리 구조
- 파일 명명 규칙
- Import 경로 (alias)

3. 개발 명령어:

- dev server 실행
- build 명령어
- 테스트 실행

4. 특화 패턴:

- API 호출 패턴
- 컴포넌트 템플릿
- 상태 관리 패턴

판단 플로우차트

규칙을 추가하려고 합니다
    ↓
이 규칙이 모든 프로젝트에 적용되나요?
    ↓
YES → ~/.claude/CLAUDE.md
NO → [프로젝트]/CLAUDE.md

---

6️⃣ 작성 팁

1. 점진적으로 추가하기

처음부터 완벽한 전역 설정을 만들 필요는 없습니다.

권장 방법:

1. 프로젝트 2-3개에서 CLAUDE.md 작성
2. 반복되는 규칙 발견
3. 전역으로 이동
4. 프로젝트별 CLAUDE.md에서 제거

예시:

# 프로젝트 A, B, C 모두에서 발견
"TypeScript any 금지"
→ ~/.claude/CLAUDE.md로 이동

# 프로젝트 A, B, C의 CLAUDE.md에서 제거
이제 각 프로젝트는 자신만의 특화 설정만 유지

2. 실제 사용 기반

이론이 아닌 실제 사용 패턴을 문서화합니다.

❌ 나쁜 예:

# 읽은 책의 모든 원칙을 나열
- SOLID 원칙
- GoF 디자인 패턴 23가지
- Clean Code 규칙 100가지

✅ 좋은 예:

# 실제로 자주 지적하는 것만
- any 타입 금지 (매번 지적함)
- TODO 주석 금지 (매번 지적함)
- console.log 금지 (매번 지적함)

3. 정기적 업데이트

워크플로우가 변경되면 설정도 함께 업데이트합니다.

업데이트 시점:

• 새로운 금지 패턴 발견 시
• 개발 프로세스 변경 시
• 새 프레임워크 도입 시

예시:

# 6개월 전: React Class Components 사용
## Component Rules
- Use class components with lifecycle methods
- Use HOCs (Higher-Order Components) for reusability
- Manage state with this.setState()

# 현재: React Hooks 전환 완료
## Component Rules
- Use functional components with Hooks
- Use custom hooks for reusability
- No class components (use hooks instead)
- Prefer useState and useEffect

---

7️⃣ 완성 템플릿

바로 복사해서 사용할 수 있는 ~/.claude/CLAUDE.md 템플릿입니다.

# Global Claude Code Configuration

This file contains my personal coding preferences applied to all projects.

## Language Preference

Always respond in Korean using formal language.

## TypeScript Rules

### Type Safety
- Never use `any` type - use `unknown`, specific types, or generics
- Prefer interfaces over types for object shapes
- Always define return types for functions

### Examples

```typescript
// ❌ Bad
function getData(): any {
  return fetch('/api/data')
}

// ✅ Good
interface ApiResponse {
  data: unknown
  status: number
}

async function getData(): Promise {
  const response = await fetch('/api/data')
  return response.json()
}
```

## Code Quality Standards

### Implementation Rules
- No TODO comments - implement completely or don't start
- No magic numbers/strings - define as constants
- No console.log - use proper logging utility
- Maximum function length: 30 lines
- Maximum component length: 150 lines

### Examples

```typescript
// ❌ Bad
function calculate(price: number) {
  // TODO: add tax calculation
  console.log(price)
  return price * 1.1
}

// ✅ Good
const TAX_RATE = 0.1

function calculate(price: number): number {
  logger.debug('Calculating price with tax', { price })
  return price * (1 + TAX_RATE)
}
```

## Git Workflow

### Branch Strategy
- Always work on feature branches
- Never commit directly to `main` or `master`
- Branch naming: `feature/feature-name`, `fix/bug-name`

### Commit Message Format
```
feat: Add new feature
fix: Resolve bug
refactor: Improve code structure
docs: Update documentation
test: Add or update tests
```

### Before Commit Checklist
1. Run linting
2. Run tests
3. Review changes with `git diff`

## Prohibited Patterns

- ❌ No `any` type
- ❌ No TODO comments
- ❌ No console.log
- ❌ No inline styles
- ❌ No magic numbers
- ❌ No partial implementations

## Naming Conventions

### General Rules
- **Constants**: UPPER_SNAKE_CASE
- **Functions**: camelCase
- **Classes/Components**: PascalCase
- **Files**: Match the export (PascalCase for components, camelCase for utilities)

### Examples

```typescript
// Constants
const API_BASE_URL = '<https://api.example.com>'
const MAX_RETRY_COUNT = 3

// Functions
function fetchUserData() {}
function calculateTotalPrice() {}

// Classes/Components
class UserService {}
function UserProfile() {}

// Files
UserProfile.tsx // Component file
apiClient.ts // Utility file
```

## Code Organization

### Import Order
1. External packages (react, next, lodash)
2. Internal absolute imports (@/components, @/lib)
3. Relative imports (./components, ../utils)

### File Structure
- Keep files under 300 lines
- One component per file
- Co-locate related files (component + styles + tests)

## Comments

### When to Comment
- ✅ Complex algorithms
- ✅ Business logic rationale
- ✅ Non-obvious workarounds

### When NOT to Comment
- ❌ Obvious code behavior
- ❌ TODO/FIXME (complete or create ticket)
- ❌ Commented-out code (use git history)

## Testing

### Test Coverage Goals
- Critical paths: 80%+
- Utilities: 90%+
- Components: 70%+

### Test Naming
```typescript
// ✅ Good
describe('UserService', () => {
  it('should return user data when user exists', () => {})
  it('should throw error when user not found', () => {})
})
```

---

8️⃣ 정리

핵심 포인트

전역 설정의 힘:

• 한 번 작성으로 모든 프로젝트 적용
• 반복 설명 제거
• 일관된 코드 품질 유지

분리 전략:

• 전역: 개인 철학, 언어, 워크플로우
• 프로젝트별: 기술 스택, 구조, 특화 패턴

작성 팁:

1. 점진적으로 추가
2. 실제 사용 기반
3. 정기적 업데이트

시작하기

# 1. ~/.claude 디렉토리 생성
mkdir ~/.claude

# 2. CLAUDE.md 생성
touch ~/.claude/CLAUDE.md

# 3. 위 템플릿 복사하여 시작
# 4. 프로젝트별 CLAUDE.md에서 중복 제거

체크리스트

• [ ] ~/.claude 디렉토리 생성
• [ ] CLAUDE.md 작성 (언어, TypeScript, 품질 기준)
• [ ] 프로젝트별 CLAUDE.md에서 중복 제거
• [ ] 새 프로젝트에서 테스트
• [ ] 정기적 업데이트 계획

효과

• 반복 설명 제거: 모든 프로젝트에 자동 적용
• 일관된 품질: 개인 기준 유지
• 시간 절약: 프로젝트 전환 시 재설명 불필요
• 팀 온보딩: 새 팀원이 규칙 이해 용이

베스트 프랙티스

1. 점진적 추가: 필요한 규칙부터 하나씩 추가
2. 실제 사용 기반: 이론이 아닌 실제 사용 패턴 문서화
3. 정기적 업데이트: 워크플로우 변화에 맞춰 수정
4. 플래그 활용: 상황에 맞는 플래그 조합 실험

.claude 디렉토리는 프로젝트를 넘나들며 일관성을 유지하는 핵심입니다. 지금 바로 ~/.claude/ 디렉토리를 만들고 나만의 AI 환경을 구축해보세요.