Claude Code를 사용하기 시작하면, 처음에 약간 "아깝다"고 느껴지는 순간이 있습니다.

그것은 바로, 세션을 열 때마다 프로젝트의 전제 조건을 처음부터 다시 설명하고 있을 때입니다.

"이 프로젝트의 테스트는 npm test로 실행해", "빌드는 이 명령어로 해", "명명 규칙은 이래"…… 어제도 말했던 것 같은 내용을 오늘도 또 입력하고 있습니다. 왠지 이게 은근히 소모적이라는 생각이 들거든요.

Claude Code에는 이러한 "매번 반복되는 설명"을 줄이기 위한 장치가 제대로 마련되어 있습니다. 그 입구가 되는 것이 오늘 주인공인 ** /init 이라는 단 하나의 명령어**입니다.

이 기사에서는 /init만에 집중하여 다음과 같이 진행합니다.

• 애초에 /init은 무엇을 해주는가
• 사용 전 준비 (설치부터 첫 실행까지)
• 실제로 /init을 입력하여 10분 만에 첫 성공을 체험하기
• 생성된 파일 확인과 그 이후의 활용 방법
• 빠지기 쉬운 함정과 자주 묻는 질문

상정하고 있는 독자는 "Claude Code라는 이름은 들어봤지만 아직 접해보지 않은 사람", "터미널(Terminal)에 익숙하지 않은 사람"입니다. 전문 용어는 처음 등장할 때마다 하나씩 풀어서 설명하므로 사전 지식은 필요 없습니다. 처음에는 누구나 헤매는 법이니 천천히 가봅시다.

참고로, 이 기사의 명령어는 Claude Code의 공식 문서를 실제로 읽고 확인한 것입니다 (참고 링크는 마지막에 모아두었습니다). 필자의 환경에서 실행 결과까지 확인하지 못한 것은 "동작 미확인"이라고 명시합니다.

/init 이야기를 하기 전에, /init이 만들어 주는 CLAUDE.md라는 파일에 대해서만 먼저 한마디로 짚고 넘어가겠습니다.

CLAUDE.md(클로드 엠디)는 Claude Code에게 매번 읽히고 싶은 "프로젝트 취급 설명서"를 적어두는 메모 파일입니다.

Claude Code의 공식 문서에는 이렇게 적혀 있습니다. "Each Claude Code session begins with a fresh context window (Claude Code의 세션은 매번 완전히 새로운 상태로 시작된다)". 인간으로 치면 매일 아침 기억이 리셋되는 동료와 같습니다. 유능하지만 어제 했던 회의는 기억하지 못하죠.

그 동료가 매일 아침 제대로 일할 수 있도록 책상 위에 놓아두는 메모, 그것이 CLAUDE.md입니다. 빌드 명령어, 테스트 실행 방법, 코딩 규약, 폴더 구성, "항상 이렇게 해줘"라는 규칙. 이러한 매 세션마다 유지했으면 하는 사실을 적어두면, Claude Code는 기동 시에 그것을 읽어 들인 후 업무를 시작합니다.

여기서 용어를 하나 보충하겠습니다.

• CLI (Command Line Interface, 명령줄 인터페이스) = 터미널(검은 화면)에 글자를 입력하여 조작하는 방식을 말합니다. Claude Code는 이 CLI로서 동작합니다.
• 리포지토리 (Repository, repo) = 대략적으로 말하면 "하나의 프로젝트 폴더"입니다. Git으로 관리하는 코드의 저장소 정도로 이해해도 오늘은 충분합니다.

그런데 이 CLAUDE.md를 수기로 처음부터 만드는 것은 조금 부담스럽습니다. 무엇을 써야 할지도 모르겠고요.

그 부분을 대신해 주는 것이 /init입니다.

공식 문서의 표현을 그대로 빌려오면, /init의 역할은 다음과 같습니다.

Run /init to generate a starting CLAUDE.md automatically. Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers.

일본어로 번역하면, **" /init을 실행하면, Claude가 현재 있는 프로젝트의 코드를 스스로 읽고, 빌드 명령어·테스트 절차·발견한 프로젝트 관습을 정리한 CLAUDE.md의 초안을 자동으로 만들어 준다"**는 뜻입니다.

커맨드 레퍼런스(Command Reference) 쪽에도 "First session in a repo. Run /init to generate a starter CLAUDE.md"라고 되어 있습니다.

「(리포지토리에서 첫 세션을 시작하면, /init으로 스타터 CLAUDE.md를 생성한다)」라고 적혀 있습니다. 즉, /init은 새로운 프로젝트에서 Claude Code를 처음 접했을 때, 가장 먼저 입력하면 기분이 좋아지는 명령어입니다.

여기서 안심해도 될 포인트가 하나 있습니다.

이미 CLAUDE.md가 있는 경우, /init은 그것을 덮어쓰지 않습니다. 공식 문서에는 다음과 같이 명시되어 있습니다. "If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it (이미 CLAUDE.md가 있다면, /init은 상위가 아니라 개선을 제안한다)". 직접 키워온 메모가 명령어 한 번에 날아가 버리는... 그런 사고는 일어나지 않도록 설계되어 있습니다. 이 부분은 사소해 보이지만 매우 중요한 지점이죠.

'사용법'으로 들어가기 전에, Claude Code 자체가 아직 설치되지 않은 분들을 위해 최단 경로의 준비 과정을 거쳐 가겠습니다. 여기는 /init을 위한 사전 준비 단계이므로 가볍게 넘어가겠습니다.

macOS / Linux / WSL의 경우, 터미널에서 이것을 실행합니다 (공식 네이티브 설치).

curl -fsSL https://claude.ai/install.sh | bash

Homebrew를 사용하는 Mac이라면, 이것으로도 설치 가능합니다.

brew install --cask claude-code

Windows의 PowerShell의 경우, 다음과 같습니다.

irm https://claude.ai/install.ps1 | iex

claude --version

공식 문서에 따르면, 이 명령어는 버전 번호 뒤에 (Claude Code)라고 표시됩니다. 그렇게 나온다면 설치 성공입니다.

작업하려는 프로젝트 폴더로 이동하여 claude라고 입력하기만 하면 됩니다.

cd /path/to/your/project
claude

/path/to/your/project는 자신의 작업 폴더 경로로 바꿔주세요. 처음에는 브라우저 로그인을 요청받습니다. Claude 구독(Pro / Max / Team / Enterprise)이나 Console 계정 등으로 로그인할 수 있습니다 (요금제 상세 내용은 공식 가격 페이지가 1차 정보입니다. 여기서는 깊게 다루지 않겠습니다).

실행되면 버전, 사용 중인 모델, 작업 디렉토리가 상단에 표시된 상태로 입력 대기 프롬프트가 나타납니다. 여기까지 왔다면 드디어 본론입니다.

보충: 위의 설치 관련 명령어는 공식 문서에서 인용한 것이며, 필자의 해당 환경에서의 실행 결과로서 동작 여부는 확인되지 않았습니다. 에러가 발생할 경우, 공식 'Troubleshoot installation' 페이지에 에러별 대처법이 정리되어 있습니다.

준비가 되었다면 해야 할 일은 정말 딱 하나뿐입니다. 실행된 Claude Code의 입력창에 다음과 같이 입력합니다.

/init

이것뿐입니다. 그러면 Claude가 현재 있는 프로젝트의 코드를 읽으러 가서 CLAUDE.md의 초안을 만들어 줍니다.

여기서 이 기사의 '10분 만의 첫 성공'을 체험해 봅시다. 갑자기 중요한 실무 프로젝트에서 시도하는 것이 불안하다면, 연습용 작은 폴더를 하나 만드는 것을 추천합니다.

# 연습용 폴더를 만들고 Git 리포지토리로 만들기
mkdir claude-init-practice
cd claude-init-practice
...

실행 후 프롬프트에서 /init을 실행합니다. 잠시 후 폴더 안에 CLAUDE.md 파일이 하나 생성되어 있을 것입니다. 내용을 들여다보면 README나 폴더 구조를 통해 Claude가 추측한 '이 프로젝트에 대한 설명'이 마크다운(Markdown) 형식으로 작성되어 있습니다.

"AI가 내 프로젝트를 위한 설명서를 알아서 써주었다" —— 이 경험이 목표입니다. 여기까지 10분이면 충분히 도달할 수 있습니다.

만들기만 하고 끝내면 조금 아쉽습니다. Claude Code에 제대로 읽혀졌는지까지 확인해야 비로소 '효과가 있는' 상태가 됩니다.

확인에 사용하는 것이 /context입니다. 세션 중에 다음과 같이 입력합니다.

/context

이것은 현재 Claude Code의 컨텍스트(Context, 즉 Claude가 가지고 있는 전제 정보의 집합)에 무엇이 들어있는지 목록으로 보여주는 명령어입니다. 공식 문서에도 "Run /context in a session and check the list under Memory files"라고 명시되어 있으며, 이 목록의 "Memory files" 항목에 방금 만든 CLAUDE.md의 이름이 나타난다면 제대로 읽어 들였다는 신호입니다.

생성 → /context로 읽기 확인. 이 2단계까지 완료하면 "대충 만들었다"에서 "효과가 있음을 스스로 확인했다"로 바뀝니다.

CLAUDE.md는 배치하는 위치에 따라 "어디까지 적용되는지(Scope, 범위)"가 달라집니다. 전부 외울 필요는 없으며, 우선 이 표만 머릿속에 넣어두세요.

/init이 만드는 것은 기본적으로 프로젝트용 CLAUDE.md입니다. 읽어 들이는 순서는 "넓은 범위 → 좁은 범위" 순이며, 좁은 쪽(프로젝트 고유 설정)이 나중에 온다고 기억해 두면 오늘은 충분합니다.

/init은 어디까지나 **초안(Draft)**입니다. Claude가 스스로 찾아내지 못한 내용은 당연히 그곳에 포함되지 않습니다.

여기서 등장하는 것이 /memory입니다. 커맨드 레퍼런스에 "Run /init ... then /memory to refine it (/init을 실행한 후, /memory로 다듬기)"라고 적혀 있듯이, CLAUDE.md를 나중에 수정하기 위한 입구입니다.

예를 들어, 다음과 같이 "Claude가 추측해서 작성할 수 없는 것"들을 추가하면 효과적입니다.

## 테스트
- 단위 테스트(Unit Test)는 `npm test`
- E2E는 `npm run test:e2e` (먼저 로컬 서버 실행 필요)
...

한 가지 팁을 드리자면, 공식적으로는 CLAUDE.md를 200행 미만으로 유지할 것을 권장합니다. 이유는 CLAUDE.md가 매 세션마다 통째로 읽히기 때문에, 그만큼 컨텍스트(Context)를 소비하기 때문입니다. 이것저것 너무 많이 담으면 오히려 지시 사항이 잘 지켜지지 않을 수 있습니다. "매번 가지고 있어야 할 사실"만 짧게. 이것이 효과적인 CLAUDE.md 작성법입니다.

공식 문서에는 /init의 대화형(Interactive) 새로운 플로우도 소개되어 있습니다. 환경 변수를 설정하여 활성화하는 것으로, 다음과 같이 적혀 있습니다.

CLAUDE_CODE_NEW_INIT=1

이 모드에서 /init은 "CLAUDE.md, skills, hooks 중 무엇을 준비할까요?"라고 물어보며, 서브 에이전트(Sub-agent, 즉 백그라운드에서 동작하는 작은 담당 Claude)가 코드베이스를 탐색하고, 부족한 정보는 추가 질문으로 채우며, 실제로 파일을 쓰기 전에 확인 가능한 제안(Reviewable proposal)을 보여줍니다.

다만, 이는 환경 변수에 의존하는 동작이므로 환경에 따라 모습이 달라질 수 있습니다. 필자의 환경에서는 동작을 확인하지 못했으므로, 우선은 **순수한(Vanilla) /init**으로 익숙해진 뒤에 관심이 생기면 시도해 보는 정도의 느낌으로 진행해도 괜찮습니다.

Q. /init을 입력해도 파일이 생성되지 않아요

먼저, Claude Code 세션이 실행 중인 상태에서 입력하고 있는지 확인하세요.

/init은 터미널의 일반적인 명령어가 아니라, **Claude Code 내부에서 입력하는 슬래시 명령어(Slash command)**입니다.

claude로 실행한 후의 입력창에 입력해야 합니다.

Q. 이미 CLAUDE.md가 있는데, 삭제되지는 않나요?

삭제되지 않습니다. 기존의 CLAUDE.md가 있을 때, /init은 덮어쓰기가 아니라 "개선 제안"을 해준다고 공식적으로 명시되어 있습니다. 안심하고 실행하셔도 됩니다.

Q. CLAUDE.md는 어디에 위치하나요?

/init이 생성하는 위치는 기본적으로 프로젝트 루트 디렉토리(./CLAUDE.md 또는 ./.claude/CLAUDE.md)입니다. 제대로 로드되었는지는 /context의 "Memory files"에서 확인할 수 있습니다.

Q. 내용을 수정하고 싶어요

/memory로 열어서 직접 수정할 수 있습니다. 생성된 문장에서 "어?" 싶은 부분이 있다면 주저하지 말고 고쳐도 괜찮습니다. 오히려 거기서부터 자신의 언어로 키워나가는 것이 본래의 사용법입니다.

Q. CLAUDE.md에 적으면 Claude가 반드시 그 규칙을 지키나요?

이 부분은 솔직하게 말씀드리겠습니다. 공식 문서에서는 "Claude treats them as context, not enforced configuration (CLAUDE.md는 문맥(context)일 뿐, 강제 설정(enforced configuration)이 아니다)"라고 명시하고 있습니다. 즉, 강력한 지시이기는 하지만 100%의 강제력을 가진 것은 아닙. 만약 반드시 기계적으로 차단해야 하는 작업이 있다면, CLAUDE.md가 아니라 hooks라는 별도의 메커니즘을 사용하라고 공식 가이드에서 안내하고 있습니다.

편리한 /init이지만, 언제나 만능인 것은 아닙니다. 이 점은 솔직하게 짚고 넘어가겠습니다.

기밀 정보가 많은 리포지토리 (Repository): /init은 코드를 읽고 설명을 작성합니다. 생성된 CLAUDE.md에 외부로 유출하고 싶지 않은 정보가 섞여 있지 않은지, 커밋(Commit) 전에 반드시 직접 눈으로 리뷰하세요.

거대한 코드베이스 (Codebase): 자동 생성된 추측이 빗나갈 수도 있습니다. 생성물을 무조건 믿지 말고, 틀린 부분은 /memory로 수정한다는 전제하에 사용하세요.

애초에 수명이 짧은 일회용 폴더: 몇 분 만에 버릴 작업에 굳이 CLAUDE.md를 준비할 필요는 없습니다.

요컨대, /init은 "초안을 순식간에 준비해 주는 파트너"이지, "최종 판단을 내려주는 사람"이 아닙. 마지막에 읽고, 수정하고, 책임을 지는 것은 본인입니다. 이 정도의 거리감을 유지하며 사용하는 것이 딱 적당합니다.

해야 할 일을 다시 한번 짧게 요약합니다.

• 프로젝트 폴더에서 claude를 실행한다
• /init을 입력한다 → CLAUDE.md 초안이 생성된다
• /context의 "Memory files"에서 로드 여부를 확인한다
• /memory를 통해 자신만이 쓸 수 있는 내용을 조금씩 추가해 나간다

단 한 번의 명령이지만, 이것을 해두면 내일부터 반복되는 "매번 다시 설명해야 하는 번거로움"이 훨씬 가벼워질 것입니다. 우선 연습용 폴더에서 한 번 해보시고, 그 다음에 실제 프로젝트에서 /init을 실행하여 생성된 CLAUDE.md에 자신의 언어로 딱 한 줄만 추가해 보세요. 거기서부터 당신만의 설정이 시작됩니다.

• Claude Code — How Claude remembers your project (CLAUDE.md / /init / auto memory): https://code.claude.com/docs/en/memory
• Claude Code — Commands (/init ・ /memory ・ /context 목록): https://code.claude.com/docs/en/commands
• Claude Code — Quickstart (설치 ・ claude --version ・ 실행): https://code.claude.com/docs/en/quickstart

생성형 AI 활용 엔지니어 & 세 아이의 아빠. AI × 개발의 실전 지식을 매일 발신하고 있습니다 → X: https://x.com/akira_papa_AI