Claude Code 초보자 튜토리얼 파트 2 — CLAUDE.md 설정부터 실전 프로젝트·고급 팁까지
파트1에서 Claude Code를 설치하고 처음 실행에 성공한 뒤, 저는 한동안 멍하니 터미널 화면을 바라봤습니다. "됐다, 이제 뭘 시키지?" 막상 쓰려고 하니 어떤 지시를 어떻게 해야 할지 막막했습니다. "코드 짜줘"라고 하면 되는 건지, 더 구체적으로 써야 하는 건지, 어디서부터 시작해야 하는지 감이 오지 않았습니다. 설치보다 오히려 이 단계가 더 어렵게 느껴지더군요.
그러다 CLAUDE.md라는 파일을 만들면 Claude Code가 매번 프로젝트 정보를 기억한다는 걸 알게 됐습니다. 반신반의하며 직접 만들어봤습니다. 프로젝트 설명 한 줄, 제가 선호하는 방식 몇 가지를 적어넣었더니 다음 세션부터 Claude가 맥락을 바로 이해하고 일을 시작하는 게 느껴졌습니다. "아, 이게 핵심이구나" 싶었습니다. 매번 처음부터 설명하지 않아도 된다는 게 이렇게 편할 줄 몰랐습니다.
파트2는 이런 제 경험에서 출발합니다. 설치는 성공했는데 막막한 분, CLAUDE.md가 뭔지는 들어봤는데 어떻게 써야 할지 모르는 분을 위한 내용입니다. 어떤 지시를 어떻게 해야 Claude Code가 제대로 일하는지, 실수 없이 큰 작업을 진행하는 Plan Mode는 어떻게 쓰는지, 직접 써보면서 깨달은 것들을 순서대로 정리했습니다.
Claude Code는 매 세션을 시작할 때 이전 대화 내용을 전혀 기억하지 못합니다. 코드 스타일 선호도도, 테스트 실행 방법도, 프로젝트 구조도 처음부터 다시 파악해야 합니다. 이 문제를 해결하는 것이 바로 CLAUDE.md 파일입니다. 프로젝트 최상위 폴더에 이 파일 하나를 만들어두면, Claude Code가 매 세션 시작 시 자동으로 읽어들여 프로젝트의 맥락을 즉시 파악합니다.
CLAUDE.md 빠르게 만드는 법 — /init 명령어
프로젝트 폴더에서 Claude Code를 실행한 뒤 아래 명령어를 입력하면 AI가 프로젝트 구조를 분석해 CLAUDE.md 초안을 자동 생성합니다.
자동 생성된 파일을 그대로 두는 것보다 불필요한 줄을 절반 정도 줄이는 것이 좋습니다. 모든 줄은 Claude의 주의(attention)를 경쟁적으로 소비하기 때문에, 지침이 많을수록 중요한 내용의 효과가 희석됩니다. 업계 경험상 150~200개 이상의 지침부터 준수율이 떨어지기 시작한다고 합니다. (출처: libretto.co.kr, 2026년)
CLAUDE.md에 반드시 담아야 할 4가지
| 항목 | 내용 | 예시 |
|---|---|---|
| 프로젝트 개요 | 이 프로젝트가 무엇인지 한 줄 설명 | Next.js 기반 쇼핑몰, Stripe 결제 연동 |
| 코드 스타일 | 언어·포맷·네이밍 규칙 | TypeScript strict 모드, 화살표 함수 통일 |
| 주요 명령어 | 빌드·테스트·실행 방법 | npm run dev, npm run test |
| 주의 사항 | 건드리면 안 되는 파일·특이 로직 | auth 모듈 직접 수정 금지, env 파일 커밋 금지 |
CLAUDE.md 실제 작성 예시
Next.js 14 기반 개인 블로그. Markdown 파일로 글을 관리합니다.
## 코드 스타일
- TypeScript 사용, strict 모드
- 컴포넌트는 화살표 함수로 작성
- CSS는 Tailwind CSS만 사용
## 주요 명령어
- 개발 서버: npm run dev
- 빌드: npm run build
- 테스트: npm run test
## 주의 사항
- .env.local 파일은 절대 수정하거나 커밋하지 마세요
- /pages/api 폴더는 변경 전 반드시 확인을 받으세요
Claude Code는 강력하지만, 복잡한 작업을 지시하면 AI가 예상치 못한 방향으로 파일을 수정할 수도 있습니다. 이를 방지하는 것이 Plan Mode(계획 모드)입니다. Plan Mode에서는 Claude가 파일을 직접 수정하지 않고 "이렇게 진행하겠습니다"라는 계획만 먼저 제시합니다. 사용자가 계획을 확인하고 승인하면 그때 실제 작업을 진행합니다. (출처: code.claude.com 공식 모범 사례 문서)
Plan Mode를 사용하는 방법은 간단합니다. 작업 지시 앞에 "먼저 계획만 세워줘, 실행하지 말고"라고 추가하면 됩니다.
먼저 계획만 세워줘, 실행하지 말고.
사용자 로그인 기능을 이 프로젝트에 추가하려고 해.
어떤 파일을 어떻게 수정해야 할지 설명해줘.
계획을 확인한 뒤 "좋아, 진행해줘" 또는 "3번 단계는 빼고 진행해줘"처럼 수정 지시를 내릴 수 있습니다. 대규모 리팩토링, 여러 파일이 동시에 바뀌는 기능 추가, 처음 해보는 작업이라면 반드시 Plan Mode를 먼저 사용하는 습관을 들이세요. 또한 Claude가 예상치 못한 방향으로 진행할 때는 Esc 키로 즉시 중단할 수 있습니다. 컨텍스트는 보존되므로 방향을 수정한 뒤 이어서 진행하면 됩니다. (출처: code.claude.com 공식 모범 사례 문서)
아래 시나리오들은 Claude Code에 실제로 입력하면 바로 작동하는 자연어 지시문입니다. 코드 지식이 없어도 복사해서 내 상황에 맞게 수정해 사용할 수 있습니다.
| 시나리오 | Claude Code에 입력할 지시문 |
|---|---|
| 프로젝트 파악 | "이 프로젝트의 전체 구조를 분석하고, 주요 파일과 기능을 한국어로 설명해줘." |
| 버그 수정 | "로그인 버튼을 클릭하면 [에러 메시지]가 나와. 원인을 찾아서 수정해줘." |
| 새 기능 추가 | "회원가입 시 이메일 인증 기능을 추가하고 싶어. 먼저 계획만 세워줘." |
| 코드 리뷰 | "auth.js 파일을 리뷰해줘. 보안 취약점이나 개선할 점이 있으면 알려줘." |
| Git 커밋 | "지금까지 수정한 내용을 정리해서 Git 커밋 메시지를 작성하고 커밋해줘." |
(참고: blog.highoutputclub.com·code.claude.com 공식 문서, 2026년 기준 실전 활용 시나리오.)
지시할 때 한 가지 팁이 있습니다. "think hard"라는 표현을 앞에 붙이면 Claude가 더 깊이 생각해서 결과물을 냅니다. 예를 들어 "think hard about the edge cases in our authentication flow"처럼 사용합니다. 복잡하거나 중요한 작업일수록 이 표현을 활용하면 품질이 눈에 띄게 달라진다고 하네요. (출처: tech.hyperithm.com 클로드 코드 사용 가이드)
MCP(Model Context Protocol)는 Claude Code가 외부 서비스와 직접 소통할 수 있게 연결해 주는 프로토콜입니다. MCP를 활용하면 Claude Code 안에서 Slack 메시지를 보내거나, Notion 페이지를 생성하거나, Jira 티켓을 처리하는 것이 가능해집니다.
MCP 서버 추가하는 방법
터미널에서 Claude Code를 실행한 상태에서 아래처럼 명령합니다. (Notion 연동 예시)
claude mcp add notion-mcp
# 추가된 MCP 서버 목록 확인
claude mcp list
MCP 연동 후에는 자연어로 바로 지시할 수 있습니다. "오늘 작업한 내용을 Notion 개발 일지 페이지에 정리해줘" 또는 "팀 Slack #개발 채널에 배포 완료 메시지를 보내줘" 같은 방식으로 업무 자동화가 가능해집니다. 초보자 단계에서는 MCP 없이도 충분히 활용할 수 있으므로, 기본 사용에 익숙해진 뒤 단계적으로 도입하는 것을 더 추천합니다.
자주 하는 실수 TOP 3
실수 1 — /clear 없이 새 작업 시작하기. 이전 작업의 컨텍스트가 누적된 채로 새 작업을 지시하면 Claude가 혼동해 엉뚱한 파일을 수정하거나 불필요한 토큰을 소모합니다. 새 작업을 시작할 때는 반드시 /clear를 먼저 입력하세요.
실수 2 — 너무 큰 작업을 한 번에 지시하기. "쇼핑몰 전체를 만들어줘"처럼 범위가 너무 큰 지시는 방향을 잃기 쉽습니다. 작업을 작은 단위로 쪼개서 "먼저 메인 페이지 레이아웃만 만들어줘", "그 다음 상품 목록 컴포넌트를 추가해줘"처럼 순서대로 진행하는 것이 훨씬 정확합니다.
실수 3 — Claude의 결과물을 확인 없이 커밋하기. AI가 생성한 코드는 반드시 실제로 실행해보고 확인한 뒤 버전 관리에 등록하세요. Claude가 논리적으로 맞는 코드를 작성했더라도 실제 환경과 맞지 않는 경우가 있을 수 있습니다.
비용 절약 실전 팁
| 방법 | 효과 |
|---|---|
| 일상 작업은 Sonnet 모델 사용 | 복잡한 작업만 Opus로 전환해 토큰 절약 |
| 작업 간 /clear 습관화 | 불필요한 컨텍스트 누적 방지 |
| /cost 명령어로 수시 확인 | 현재 세션 토큰 사용량 실시간 파악 (API 사용자) |
| CLAUDE.md 간결하게 유지 | 지침 줄일수록 작업 지시에 집중되는 토큰 증가 |
| claude doctor 진단 명령어 활용 | 연결·설치 문제를 조기에 발견해 낭비 방지 |
(출처: blog.highoutputclub.com·jackerlab.com·tech.hyperithm.com, 2026년 기준 종합.)
마지막으로 유용한 진단 명령어를 소개합니다. Claude Code가 이상하게 느껴질 때 아래 명령어를 실행하면 설치 상태와 연결을 자동으로 점검해 줍니다.
claude doctor
# 수동 업데이트
claude update
파트 1의 설치·기본 사용에서 이번 파트 2의 CLAUDE.md 설정, Plan Mode, 실전 시나리오, MCP 연동, 비용 절약까지 마쳤습니다. Claude Code는 처음 접하면 낯설지만, 이 두 편의 가이드를 통해서 코딩 경험 없이도 실제 프로젝트에서 AI의 도움을 받을 수 있으셨으면 좋겠네요.😉 가장 중요한 것은 직접 써보는 것입니다. 오늘 바로 연습용 폴더 하나를 만들고, "간단한 할 일 목록 앱을 만들어줘"라고 입력하며 시작해 보세요. 🙌
Q. CLAUDE.md 파일은 어떤 폴더에 만들어야 하나요?
A. 프로젝트 최상위 폴더(루트)에 만들면 됩니다. 예를 들어 내 프로젝트 폴더가 ~/my-blog라면 ~/my-blog/CLAUDE.md로 저장합니다. Claude Code는 실행 시 현재 폴더를 기준으로 CLAUDE.md를 자동으로 찾아 읽습니다. /init 명령어를 사용하면 올바른 위치에 자동 생성됩니다.
Q. Claude Code와 Cursor 중 어떤 것이 초보자에게 더 적합한가요?
A. 용도에 따라 다릅니다. 일상적인 코드 자동완성과 VS Code 같은 익숙한 편집기 환경이 필요하다면 Cursor가 편합니다. 프로젝트 전체를 이해하고 여러 파일을 동시에 수정하는 대규모 작업이 주라면 Claude Code가 유리합니다. 실무에서는 Cursor 에디터 안에서 Claude Code를 통합해 사용하는 하이브리드 방식이 가장 많이 채택되고 있습니다.
Q. Claude Code가 실수로 중요한 파일을 삭제하거나 망가뜨릴 수 있나요?
A. Claude Code는 파일을 수정하거나 삭제하기 전에 사용자에게 확인을 요청하는 것이 기본 동작입니다. 하지만 완전한 안전망은 아닙니다. 그래서 다음 세 가지 예방책을 병행하여 사용해 보세요. 첫째, 중요한 작업 전에는 항상 Plan Mode로 계획을 먼저 확인하세요. 둘째, Git으로 버전 관리를 해두면 언제든 이전 상태로 돌아갈 수 있습니다. 셋째, CLAUDE.md의 주의 사항에 "절대 수정하면 안 되는 파일"을 명시해두면 AI가 해당 파일을 건드리지 않습니다.
— Jin Jin
댓글
댓글 쓰기