# Claude CLI 완전 가이드 v8: Project Memory (CLAUDE.md) 활용

## Project Memory란?

Project Memory는 `CLAUDE.md` 파일에 저장되는 프로젝트별 지식입니다. Claude가 세션 시작 시 자동으로 읽어 프로젝트 컨텍스트를 이해합니다.

### 핵심 가치

- **팀 공유**: Git으로 버전 관리, 팀 전체가 동일한 컨텍스트
- **일관성**: 세션마다 동일한 규칙 적용
- **효율성**: 반복적인 설명 불필요

---

## CLAUDE.md 위치

두 위치 중 하나에 생성:

```
./CLAUDE.md              # 프로젝트 루트
./.claude/CLAUDE.md      # .claude 디렉토리 내
```

---

## 빠른 시작

### 초기화

```
/init
```

기본 템플릿으로 CLAUDE.md를 생성합니다.

### 편집

```
/memory
```

CLAUDE.md를 편집 모드로 엽니다.

### 확인

```
#
```

현재 CLAUDE.md 내용을 표시합니다.

---

## CLAUDE.md 구조

### 권장 섹션

```markdown
# 프로젝트 이름

## 개요
프로젝트 설명

## 기술 스택
사용 기술 목록

## 프로젝트 구조
디렉토리 구조 설명

## 코딩 규칙
팀 코딩 스타일

## 빌드 & 테스트
주요 명령어

## 주의사항
특별히 주의할 점
```

---

## 실전 CLAUDE.md 예제

### 웹 프론트엔드 프로젝트

```markdown
# E-Commerce Frontend

## 개요
React 기반 이커머스 프론트엔드 애플리케이션

## 기술 스택
- React 18 + TypeScript
- Zustand (상태 관리)
- TanStack Query (서버 상태)
- Tailwind CSS
- Vite

## 프로젝트 구조
```
src/
├── components/     # UI 컴포넌트
│   ├── common/     # 공통 컴포넌트
│   ├── layout/     # 레이아웃
│   └── features/   # 기능별 컴포넌트
├── hooks/          # 커스텀 훅
├── services/       # API 서비스
├── stores/         # Zustand 스토어
├── types/          # TypeScript 타입
└── utils/          # 유틸리티 함수
```

## 코딩 규칙
- 함수형 컴포넌트만 사용
- Props는 interface로 정의 (ComponentNameProps)
- 커스텀 훅은 use 접두사
- 2칸 들여쓰기
- 세미콜론 필수
- ESLint/Prettier 설정 준수

## 명령어
| 작업 | 명령어 |
|------|--------|
| 개발 서버 | `npm run dev` |
| 빌드 | `npm run build` |
| 테스트 | `npm test` |
| 린트 | `npm run lint` |
| 타입 체크 | `npm run typecheck` |

## 컴포넌트 패턴
```typescript
// 표준 컴포넌트 구조
interface ButtonProps {
  variant: 'primary' | 'secondary';
  children: React.ReactNode;
  onClick?: () => void;
}

export const Button = ({ variant, children, onClick }: ButtonProps) => {
  return (
    <button className={styles[variant]} onClick={onClick}>
      {children}
    </button>
  );
};
```

## API 연동
- 기본 URL: `process.env.VITE_API_URL`
- 인증: Bearer 토큰 (localStorage에 저장)
- 에러 처리: TanStack Query의 onError 활용

## 주의사항
- `components/legacy/`는 마이그레이션 중, 수정 금지
- 새 컴포넌트는 반드시 Storybook 스토리 작성
- 상태 관리는 가능한 서버 상태(TanStack Query)로
```

### Node.js API 서버 프로젝트

```markdown
# Order Management API

## 개요
주문 관리를 위한 RESTful API 서버

## 기술 스택
- Node.js 20 LTS
- Express.js
- PostgreSQL + Prisma ORM
- Redis (캐싱)
- Jest (테스트)

## 프로젝트 구조
```
src/
├── controllers/    # 요청 핸들러
├── services/       # 비즈니스 로직
├── repositories/   # 데이터 접근
├── middlewares/    # 미들웨어
├── validators/     # 입력 검증
├── utils/          # 유틸리티
└── types/          # 타입 정의
prisma/
└── schema.prisma   # DB 스키마
```

## 아키텍처 규칙
- Controller → Service → Repository 레이어 구조
- Controller: 요청/응답 처리만
- Service: 비즈니스 로직
- Repository: DB 쿼리

## 명령어
| 작업 | 명령어 |
|------|--------|
| 개발 서버 | `npm run dev` |
| 빌드 | `npm run build` |
| 테스트 | `npm test` |
| DB 마이그레이션 | `npm run db:migrate` |
| DB 시드 | `npm run db:seed` |
| Prisma Studio | `npm run db:studio` |

## API 응답 형식
```json
// 성공
{
  "success": true,
  "data": { ... }
}

// 에러
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "에러 메시지"
  }
}
```

## 환경 변수
- `DATABASE_URL`: PostgreSQL 연결 문자열
- `REDIS_URL`: Redis 연결 문자열
- `JWT_SECRET`: JWT 서명 키
- `.env.example` 참조

## 주의사항
- 모든 엔드포인트는 `validators/`에 검증 스키마 필수
- DB 변경 시 반드시 마이그레이션 사용
- 프로덕션 DB 직접 쿼리 금지
```

---

## 효과적인 작성 패턴

### 1. 구체적으로 작성

**나쁜 예:**
```markdown
## 코딩 규칙
코드를 깔끔하게 작성하세요.
```

**좋은 예:**
```markdown
## 코딩 규칙
- 2칸 들여쓰기 (탭 금지)
- 세미콜론 필수
- 줄 길이 최대 100자
- Prettier 설정: `.prettierrc` 참조
```

### 2. 불릿 포인트 활용

```markdown
## 데이터베이스 규칙
- 테이블명: snake_case, 복수형 (예: `user_orders`)
- 컬럼명: snake_case (예: `created_at`)
- PK: `id` (bigint, auto increment)
- 타임스탬프: `created_at`, `updated_at` 필수
```

### 3. 명령어 테이블

```markdown
## 자주 사용하는 명령어
| 작업 | 명령어 |
|------|--------|
| 개발 서버 | `npm run dev` |
| 프로덕션 빌드 | `npm run build` |
| 테스트 | `npm test` |
| 테스트 (watch) | `npm run test:watch` |
| 커버리지 | `npm run test:coverage` |
```

### 4. 코드 예시 포함

```markdown
## 에러 처리 패턴
```typescript
// 올바른 패턴
try {
  const result = await service.process(data);
  return res.json({ success: true, data: result });
} catch (error) {
  logger.error('Processing failed', { error, data });
  return res.status(500).json({
    success: false,
    error: { code: 'PROCESSING_ERROR', message: 'Failed to process' }
  });
}
```
```

### 5. 주의사항 강조

```markdown
## 주의사항

### 🚨 절대 금지
- 프로덕션 DB 직접 수정
- `.env` 파일 커밋
- `node_modules/` 커밋

### ⚠️ 주의 필요
- `legacy/` 코드 수정 시 팀 리더 확인 필요
- 외부 API 호출 시 rate limit 고려
```

---

## 외부 파일 Import

`@` 문법으로 다른 파일 참조:

```markdown
# CLAUDE.md

## 개요
프로젝트 설명

## 상세 문서
@docs/architecture.md
@docs/api-spec.md
@docs/database-schema.md
```

### 개인 설정 분리

팀 공유 내용과 개인 설정 분리:

```markdown
# CLAUDE.md (Git에 포함)

## 프로젝트 규칙
...

## 개인 설정
@~/.claude/my-preferences.md
```

---

## 팀 협업 활용

### Git 워크플로우

```bash
# CLAUDE.md 추가
git add CLAUDE.md
git commit -m "Add project memory for Claude Code"

# 업데이트
git add CLAUDE.md
git commit -m "Update coding conventions in CLAUDE.md"
```

### PR 템플릿에 포함

`.github/PULL_REQUEST_TEMPLATE.md`:

```markdown
## 변경 사항

## CLAUDE.md 업데이트 필요?
- [ ] 아니오
- [ ] 예 (업데이트 완료)
```

### 정기 검토

월간/분기별로 CLAUDE.md 검토:

- 오래된 정보 업데이트
- 새로운 패턴/규칙 추가
- 사용하지 않는 내용 제거

---

## CLAUDE.md vs 다른 설정

| 파일 | 용도 |
|------|------|
| `CLAUDE.md` | 프로젝트 지식 및 규칙 |
| `.claude/settings.json` | Claude Code 동작 설정 |
| `.claude/commands/` | 커스텀 슬래시 명령어 |
| `.claude/skills/` | Skills 정의 |
| `.mcp.json` | MCP 서버 설정 |

---

## 고급 활용

### 조건부 내용

```markdown
## 환경별 설정

### 개발 환경
- API URL: `http://localhost:3000`
- DB: 로컬 PostgreSQL

### 스테이징
- API URL: `https://staging-api.example.com`
- DB: 읽기 전용 복제본 사용
```

### 체크리스트

```markdown
## 배포 전 체크리스트
- [ ] 모든 테스트 통과
- [ ] 타입 에러 없음
- [ ] 린트 에러 없음
- [ ] 환경 변수 확인
- [ ] 마이그레이션 검토
```

### 트러블슈팅 가이드

```markdown
## 자주 발생하는 문제

### 빌드 실패
1. `node_modules` 삭제 후 재설치
2. TypeScript 버전 확인 (5.x 필요)
3. `.env` 파일 확인

### DB 연결 오류
1. PostgreSQL 서비스 상태 확인
2. `.env`의 `DATABASE_URL` 확인
3. `npm run db:migrate` 실행
```

---

## 다음 단계

v8에서는 Project Memory의 활용법을 다뤘습니다.

**다음 v9에서는**:
- 보안 아키텍처
- 권한 설정 방법
- Permission 모드
- 보안 베스트 프랙티스

를 상세히 알아봅니다.

---

## 빠른 참조

```
CLAUDE.md 관리:
  /init       초기화 (새 파일 생성)
  /memory     편집 모드
  #           내용 표시

파일 위치:
  ./CLAUDE.md
  ./.claude/CLAUDE.md

권장 섹션:
  # 프로젝트명
  ## 개요
  ## 기술 스택
  ## 프로젝트 구조
  ## 코딩 규칙
  ## 명령어
  ## 주의사항

외부 파일 참조:
  @docs/file.md
  @~/.claude/personal.md

베스트 프랙티스:
  - 구체적으로 작성
  - 불릿 포인트 활용
  - 명령어는 테이블로
  - 코드 예시 포함
  - 정기적으로 업데이트
```

---

*Claude CLI 완전 가이드 시리즈 v8/10*