개발을 하다 보면 반복적인 코딩 작업이나 복잡한 로직 구현에 시간을 많이 쏟게 되죠. "이런 부분을 자동화할 수 있다면 얼마나 좋을까" 생각해 보셨다면? '클로드 코드'로 고민을 해결해 보세요. 이번 포스팅에서는 클로드 코드를 여러분만의 개발 어시스턴트로 만드는 실전 가이드를 알려드리겠습니다!

수동 편집하기

/init으로 만들어진 CLUADE.md가 내 의도를 잘 반영하고 있으면 괜찮지만, 혹시 미비한 부분이 있으면 검토 후 자동 생성된 CLAUDE.md를 프로젝트에 맞게 수정합니다. 자동 생성된 결과물은 출발점일 뿐이며, 실제 프로젝트 맥락과 팀의 규칙을 반영하는 과정이 중요합니다.

혹여나 직접 CLAUDE.md를 작성하기 부담스럽다면, 클로드 코드에게 작성을 요청해 보세요!

> 이 프로젝트에 최적화된 CLAUDE.md 파일을 작성해 줘.

프로젝트 정보:

- 카페 예약 시스템 개발

- React + TypeScript + Node.js

- 프로젝트 (3개월 예정)

- 팀 구성: 개발자 2명, 디자이너 1명


포함할 내용:

- 프로젝트 목표와 주요 기능

- 기술 스택과 개발 환경

- 코딩 컨벤션과 디렉터리 구조

- 자주 사용하는 명령어

- 팀 협업 규칙

클로드가 프로젝트에 맞는 상세한 CLAUDE.md를 생성해 주고, 우리는 필요한 부분만 수정하면 됩니다.

CLAUDE.md 메모리 스코프와 파일 위치

CLAUDE.md는 단일 파일 이상입니다. 프로젝트 전역에 걸친 규칙부터 개인 개발자의 선호까지 서로 다른 범위를 관리할 수 있으며, 이 구조 덕분에 팀 규칙과 개인 습관이 깔끔히 분리되면서도 함께 작동합니다.

클로드 코드는 두 가지 메모리 스코프를 통해 서로 다른 범위의 컨텍스트를 관리하는데요. 개발자 개인의 전역 설정부터 프로젝트별 팀 규칙, 그리고 로컬 환경의 개인적인 정보까지 체계적으로 분리하여 관리가 가능합니다.

CLAUDE.local.md라는 이름의 개인용 메모리가 있었으나 더 이상 지원되지 않습니다. 나중에 설명할 import를 대신 사용할 수 있습니다.

실제 활용 예시

실제 예시를 보면, User Scope와 Project Scope가 어떻게 서로 다른 맥락을 제공하고, 최종적으로 종합되는지 쉽게 이해할 수 있습니다.

1️. User Scope 예시(~/.claude/CLAUDE.md)

2️. Project Scope 예시 (~/proj/cafe_reservation_service/CLAUDE.md)

이러한 스코프는 조합하여 활용되는데, 클로드 코드는 두 가지 스코프를 자동으로 조합하여 최적의 컨텍스트를 제공합니다.

User Scope의 개인 설정이 기본 베이스가 됩니다.
Project Scope의 프로젝트 규칙이 개인 설정을 덮어씁니다.

예를 들어, 카페 예약 시스템에서 작업한다는 가정을 들어보겠습니다.

개인 선호 도구(VS Code, Tailwind CSS)는 User Scope에서
프로젝트 기술 스택(React + TypeScript)은 Project Scope에서 가져와 종합적인 컨텍스트를 구성합니다.

프롬프트 작성 팁

CLAUDE.md와 함께라면 기본적인 문맥은 이미 공유되지만, 프롬프트를 어떻게 작성하느냐에 따라 답변 품질이 크게 달라집니다. 따라서 구체성·맥락·단계적 접근이 필요해요. 클로드 코드와 효과적으로 대화하기 위해서는 아래 3가지 기본 팁을 참고해 보세요!

1) 구체적이고 명확한 요청 : 모호한 요청보다는 구체적인 요구사항을 제시

2) 컨텍스트 제공 : 프로젝트 상황, 기술 스택, 제약사항 등을 명시

3) 단계별 접근 : 복잡한 작업은 작은 단위로 나누어 진행

CLAUDE.md 작성 베스트 프랙티스

CLAUDE.md는 결국 AI에게 주는 가장 중요한 '작업 설명서'입니다. 너무 길고 장황하면 토큰을 낭비하고, 너무 짧으면 규칙이 빠질 수 있어요. 따라서 '간결하면서도 필요한 핵심을 빠짐없이' 담는 것이 원칙입니다!

CLAUDE.md 작성 원칙

간결성 우선 : 장황한 설명보다는 짧고 명확한 표현
선언적 형태 : 문장보다 점스타일 위주
토큰 효율성 : 불필요한 서술 제거
실시간 업데이트 : 프로젝트 진행에 따라 주기적으로 개선

CLAUDE.md 필수 포함 요소

최소한 다섯 가지 요소는 항상 포함되는 것이 좋아요!

1️. 기술 스택(Tech Stack)

# Tech Stack

- Next.js 14

- TypeScript 5.2

- Tailwind CSS 3.4

- Prisma ORM

- PostgreSQL 15

2️. 프로젝트 구조(Project Structure)

# Structure

- `src/app`: Next.js App Router pages

- `src/components`: Reusable React components

- `src/lib`: Utility functions

- `src/types`: TypeScript definitions

3️. 핵심 명령어 (Commands)

# Commands

- `npm run dev`: Start development server

- `npm run build`: Production build

- `npm run test`: Run Jest tests

- `npm run db:migrate`: Apply database migrations

4️. 코딩 스타일 (Code Style)

# Code Style

- Components: PascalCase

- Files: kebab-case

- Functions: camelCase

- Constants: UPPER_SNAKE_CASE

- Imports: Group external → internal → relative

5️. 저장소 규칙 (Respository Etiquette)

# Git Workflow

- Branches: feature/description, fix/description

- Commits: "type: description" (feat, fix, docs, style)

- Merge: Squash commits on main