Claude Code를 처음 열었을 때, 대부분은 바로 “코드 짜줘”부터 시작한다. 그게 자연스럽다. 그런데 이 순서가 틀렸다. claude 초기 설정을 제대로 하지 않으면 Claude는 프로젝트의 맥락을 모르는 채로 작업하고, 같은 실수를 반복하고, 매번 설명을 다시 들어야 한다. 처음 세팅에 10분을 쓰면, 이후 수십 시간의 작업 품질이 달라진다.
이 글에서는 claude 초기 설정의 핵심 3가지를 순서대로 다룬다. /init으로 프로젝트 구조를 Claude에게 읽히고, Plan Mode로 방향을 먼저 맞추고, CLAUDE.md로 Claude의 장기 기억을 설계하는 방법이다.
claude 초기 설정, 첫 번째 선택이 왜 중요한가
Claude Code는 대화가 끝나면 기억이 사라진다. 새 세션을 열 때마다 Claude는 백지 상태다. 이 구조적 한계를 해결하는 것이 claude 초기 설정의 핵심이다.
초기 설정 없이 작업하면 생기는 문제는 세 가지다. 첫째, Claude가 프레임워크나 폴더 구조를 매번 새로 파악해야 한다. 둘째, 팀 컨벤션이나 금지 규칙을 모른 채 코드를 생성한다. 셋째, 방향이 맞지 않는 코드를 수정하다 시간을 낭비한다. 반대로 설정이 잘 된 프로젝트에서 Claude는 처음부터 규칙을 알고, 구조를 파악한 상태에서 시작한다.
/init — 프로젝트 구조를 Claude에게 읽히는 법
/init은 Claude Code의 슬래시 명령어다. 실행하면 Claude가 현재 프로젝트 디렉토리를 스캔하고, 분석 결과를 바탕으로 CLAUDE.md 초안을 자동 생성한다.
Claude Code를 실행한 상태에서 아래처럼 입력하면 된다.
/init
분석이 끝나면 Claude가 생성한 CLAUDE.md 초안을 보여준다. 검토 후 확인하면 파일이 프로젝트 루트에 저장된다. /init이 읽어내는 내용은 아래와 같다.
| 항목 | 내용 |
|---|---|
| 빌드/테스트 명령어 | npm run dev, npm run test 등 실행 명령어 자동 감지 |
| 아키텍처 패턴 | 프레임워크, 라우터 구조, 상태 관리 방식 |
| 코드 컨벤션 | 네이밍 패턴, 파일 구조, 임포트 스타일 |
| 핵심 의존성 | 어떤 라이브러리를 쓰는지, 왜 쓰는지 |
한 가지 주의할 점이 있다. /init은 터미널에서 직접 실행하는 명령어가 아니다. Claude Code 인터랙티브 모드 안에서, 즉 Claude Code를 열고 대화창에 입력해야 동작한다.
/init만으론 부족한 이유 — 시작 단계의 진실
/init의 한계를 정확히 알아야 제대로 쓸 수 있다. /init은 현재 상태를 읽는다. 분석할 코드가 있어야 제대로 된 CLAUDE.md를 만든다.
프로젝트를 막 시작한 단계, 폴더 구조만 잡혀 있는 상태라면 /init이 만들어주는 건 껍데기에 가깝다. package.json이나 requirements.txt 정도는 읽어내지만, 프로젝트의 의도나 방향은 코드에서 읽어낼 수 없다.
이 경우 순서가 달라진다.
| 상황 | 권장 순서 |
|---|---|
| 코드가 어느 정도 쌓인 기존 프로젝트 | /init 먼저 → CLAUDE.md 검토 및 보완 |
| 프로젝트 시작 단계 | CLAUDE.md 직접 작성 → /init으로 보완 |
| 오픈소스 클론 후 빠른 파악 | /init 먼저 → Plan Mode로 방향 확인 |
시작 단계라면 기술 스택, 팀 컨벤션, 절대 규칙(예: .env 수정 금지, 마이그레이션 파일 삭제 금지)을 직접 써두는 것이 /init보다 강력하다. Claude한테 “이 프로젝트 어떻게 돼 있어?”를 설명하는 게 아니라, “이 프로젝트는 이렇게 해야 해”를 못 박는 것이기 때문이다.
Plan Mode — 방향을 먼저 맞추고 코드를 짜라
Plan Mode는 Claude Code의 실행 모드 중 하나다. 이 모드에서 Claude는 파일을 수정하거나 명령어를 실행하지 않는다. 대신 무엇을 할지 먼저 설명하고, 승인을 받은 후에 움직인다.
VS Code 확장에서는 프롬프트 박스 하단의 모드 셀렉터 버튼으로 전환할 수 있다. 터미널에서는 Shift + Tab으로 모드를 순환하거나, 대화창에 /plan을 입력해 진입한다.
| 모드 | 동작 방식 |
|---|---|
| Normal | 파일 편집 전마다 허락을 구함 |
| Plan | 아무것도 건드리기 전에 전체 계획을 먼저 제시 |
| Auto-accept | 변경사항 자동 적용 |
Plan Mode가 특히 강력한 상황은 초기 설정 단계다. Claude가 /init으로 구조를 파악한 상태에서 Plan Mode로 전환하면, 막연한 질문 대신 구체적인 질문이 나온다.
“인증은 JWT로 처리할까요, 세션 기반으로 할까요?” “API 응답 래퍼를 공통으로 쓸 구조인가요?”
이 대화를 통해 초반에 아키텍처 방향을 못 박을 수 있다. 나중에 방향을 틀면 코드 전체를 뒤집어야 하기 때문에, 이 단계를 건너뛰면 비용이 커진다. claude 초기 설정에서 Plan Mode는 설계 검토 도구로 쓰는 것이 맞다.
Ctrl + G를 누르면 Claude가 만든 플랜을 에디터에서 직접 수정할 수 있다. 대화로 수정 사항을 설명하는 것보다 훨씬 빠르다.
/init + Plan Mode 조합이 강력한 이유
둘을 따로 쓰면 각각의 한계가 있다.
/init 단독으로는 “현재 상태”만 읽는다. Plan Mode 단독으로는 컨텍스트가 없어서 일반적인 질문만 던진다. 그런데 /init으로 구조를 파악시킨 뒤 Plan Mode로 전환하면, Claude는 이미 프로젝트 구조를 아는 상태에서 의도를 확인한다. 질문의 밀도가 달라진다.
실전에서 쓰는 순서는 이렇다.
1단계: 기본 폴더 구조 세팅
2단계: /init 실행 → CLAUDE.md 초안 생성
3단계: Plan Mode 진입 → 아키텍처·방향 질문 주고받기
4단계: 대화에서 나온 결정사항을 CLAUDE.md에 추가
5단계: 이후 작업은 CLAUDE.md를 베이스로 진행
이 흐름이 자리잡히면 새 세션을 열어도 Claude는 처음부터 프로젝트를 이해한 상태에서 시작한다.
CLAUDE.md — Claude의 장기 기억을 설계하는 법
CLAUDE.md는 Claude Code가 세션 시작마다 자동으로 읽는 파일이다. 여기에 쓴 내용은 매 대화의 시작점이 된다. claude 초기 설정에서 가장 직접적인 효과를 내는 파일이기도 하다.
형식은 자유롭다. 중요한 건 짧고 명확하게 쓰는 것이다. 너무 길면 Claude가 중요한 규칙을 노이즈 속에서 놓친다.
실제로 효과적인 CLAUDE.md 구조는 아래와 같다.
## Project Overview
Next.js 기반 쇼핑몰. Supabase로 인증/DB, Tailwind CSS 사용.
## Commands
- npm run dev # 개발 서버
- npm run test # Jest 테스트
- npm run lint # ESLint
## Rules
- 절대 .env 파일 수정 금지
- 마이그레이션 파일 삭제 금지
- API 응답은 무조건 ApiResponse<T> 래퍼 사용
## Architecture
- App Router (Next.js), Pages Router 아님
- 모든 API 호출은 /lib/api/ 경로를 통해서만
업데이트 타이밍은 단순하다. 아키텍처 결정을 내렸을 때, 새 컨벤션을 추가했을 때, 그리고 Claude가 같은 실수를 두 번 반복했을 때다. 같은 걸 두 번 수정했다면 그 내용은 CLAUDE.md에 들어가야 한다.
CLAUDE.md 계층 구조 — 폴더별로 나눠 관리하는 법
CLAUDE.md는 프로젝트 루트 하나만 쓸 필요가 없다. 계층 구조로 나눠 관리할 수 있다.
| 위치 | 적용 범위 |
|---|---|
~/.claude/CLAUDE.md | 개인 설정 — 모든 프로젝트에 공통 적용 |
./CLAUDE.md | 프로젝트 루트 — 팀 공유, git 커밋 대상 |
./src/CLAUDE.md | 서브디렉토리 — 해당 폴더 작업 시 자동 로드 |
모노레포처럼 프론트엔드와 백엔드가 같은 레포에 공존하는 경우 이 구조가 빛난다.
project/
├── CLAUDE.md ← 전체 공통 규칙 (기술스택, 금지사항)
├── frontend/
│ └── CLAUDE.md ← React/TS 전용 규칙
└── backend/
└── CLAUDE.md ← Django/Python 전용 규칙
상위 디렉토리의 CLAUDE.md는 자동으로 함께 로드된다. 하위 디렉토리의 CLAUDE.md는 해당 폴더 파일을 작업할 때 Claude가 자동으로 읽어온다. 공통 규칙은 루트에, 세부 규칙은 각 폴더에 두는 것이 관리하기 가장 깔끔하다.
팀 협업이라면 루트 CLAUDE.md는 반드시 git에 커밋한다. 팀원 모두가 동일한 Claude 경험을 갖게 되고, 신규 입사자 온보딩 문서로도 활용할 수 있다.
핵심 요약
claude 초기 설정은 세 가지 도구로 완성된다.
| 도구 | 역할 | 언제 |
|---|---|---|
/init | 프로젝트 구조를 자동 분석해 CLAUDE.md 초안 생성 | 코드가 어느 정도 있을 때 |
| Plan Mode | 실행 전 계획을 먼저 제시, 방향 정렬 | 아키텍처 결정이 필요한 초반 |
| CLAUDE.md | 세션마다 자동 로드되는 Claude의 장기 기억 | 항상 |
처음부터 완벽할 필요는 없다. /init으로 초안을 만들고, Plan Mode로 방향을 잡고, 작업하면서 CLAUDE.md를 채워가면 된다. 중요한 건 이 세 가지가 연결되어 있다는 것이다. 설정이 쌓일수록 Claude는 더 정확해진다.
[링크 제안]
claude 초기 설정을 마쳤다면, 다음 질문은 “Claude Code를 어떻게 프로덕션 수준으로 쓸 것인가”다.
Claude Code를 쓰기 전에 마크다운 문법을 잡아두면 CLAUDE.md 작성 품질이 달라진다.
공식 문서에서 더 깊은 내용을 확인할 수 있다: Claude Code 공식 문서
