claude init으로 CLAUDE.md 파일 자동 생성하기 | Playbook Tip

새 프로젝트에 Claude Code를 붙이면 처음엔 컨텍스트가 없어서 엉뚱한 답변이 나오는 경우가 꽤 있어요. 파일 구조도 모르고, 어떤 프레임워크를 쓰는지도 모르니까요. 실밸개발자 채널 Claude Code 마스터 강의에서 이걸 해결하는 가장 간단한 방법을 알려줬는데, /init 명령어 하나예요.

/init을 실행하면 Claude가 프로젝트 디렉토리를 스캔해서 CLAUDE.md를 자동으로 만들어줘요. 이 파일 안에 프로젝트 구조, 주요 파일 경로, 기술 스택 같은 정보가 정리되고, 이후 대화에서 Claude가 이 파일을 컨텍스트로 읽어요. 진짜로 차이가 나더라고요. 설정 전후로 같은 질문을 던져보면 답변 정확도가 눈에 띄게 달라져요.

준비물

Claude Code CLI 설치 완료 (claude 명령어가 터미널에서 동작해야 해요)
Node.js 18 이상
세팅할 프로젝트 디렉토리

스텝

1. 프로젝트 루트로 이동

CLAUDE.md는 실행 위치 기준으로 생성돼요. 서브 디렉토리에서 실행하면 거기에 생기니까, 루트에서 시작하는 게 맞아요.

cd /path/to/your-project

2. Claude Code 실행

claude

터미널에 Claude Code 프롬프트가 뜨면 준비된 거예요.

3. /init 입력

Claude Code 프롬프트 안에서 아래를 입력해요.

/init

Claude가 프로젝트 파일들을 훑고 CLAUDE.md를 작성하기 시작해요. 프로젝트 규모에 따라 다르지만 보통 10-20초 안에 끝나요.

4. 생성된 파일 확인

cat CLAUDE.md

프로젝트 구조 요약, 주요 디렉토리 설명, 기술 스택 정보가 담긴 마크다운 파일이 생겨있을 거예요.

잘 됐는지 확인하는 방법

파일이 생성됐으면, Claude Code 프롬프트에서 프로젝트 관련 질문을 하나 던져봐요.

이 프로젝트의 주요 엔트리 파일이 어디에 있어요?

/init 전이라면 "확인이 필요해요" 같은 답이 나왔을 텐데, 이제는 실제 파일 경로를 짚어서 답해줘요. CLAUDE.md를 읽고 있다는 신호예요.

응용

자동 생성된 CLAUDE.md를 그대로 쓰기보다, 팀 컨벤션이나 코드 스타일 가이드를 직접 추가해두면 더 유용해요. 예를 들어 이런 섹션을 붙여두면 돼요.

## 코드 스타일
- 함수형 컴포넌트만 사용
- 상태 관리는 Zustand
- API 호출은 /src/api 디렉토리에만

Claude가 코드를 제안할 때 이 내용을 반영해서 답해줘요.

트러블슈팅

/init 입력 후 아무 반응이 없거나 에러가 나오면 Claude Code 버전을 확인해봐요.

claude --version

오래된 버전이면 /init을 지원하지 않을 수 있어요. npm update -g @anthropic-ai/claude-code로 업데이트하면 해결되는 경우가 많아요.

CLAUDE.md가 생성됐는데 내용이 너무 부실하다면, 프로젝트에 README.md나 package.json이 없어서 그럴 수 있어요. 기본 파일들이 있어야 Claude가 읽을 정보가 생겨요.

이 설정 하나로 매번 "이 프로젝트는 어떤 구조예요?"를 설명하는 수고를 덜 수 있게 돼요.

준비물

스텝