Claude Code의 두뇌를 설계하다CLAUDE.md와 Skills 완벽 가이드
Claude Code를 설치하고 바로 코드를 짜달라고 하면, 잘 해준다. 근데 매번 "우리 프로젝트는 Tailwind 쓰고, 컴포넌트는 Server Component 기본이고, 커밋은 feat: 접두사 쓰고..." 이런 말을 반복하고 있다면, 뭔가 잘못되고 있는 거다.
.gitignore 없이 node_modules를 커밋하는 사람은 없다. 2026년에 CLAUDE.md 없이 Claude Code를 쓰는 것도 비슷한 상황이다.
CLAUDE.md가 뭔데?
CLAUDE.md는 AI에게 주는 온보딩 문서다. 새 팀원이 들어오면 "우리 프로젝트는 이렇게 돌아가고, 이런 규칙이 있고, 이 명령어를 쓰면 된다"고 알려주듯이, Claude Code에게도 같은 걸 해주는 파일이다.
CLAUDE.md = 프로젝트의 규칙 + 구조 + 명령어를 Claude에게 알려주는 마크다운 파일
세션이 시작될 때마다 자동으로 로드된다. 한 번 써놓으면 매 대화에서 반복 설명할 필요가 없다.
없으면 어떻게 되나?
CLAUDE.md가 없으면 매번 이런 일이 벌어진다:
나: "컴포넌트 하나 만들어줘"
Claude: *inline style로 만듦*
나: "아 우리 Tailwind 쓴다고..."
Claude: *수정함*
나: "다크모드도 지원해야 해, CSS 변수 써야 하고..."
Claude: *또 수정*
나: "커밋 메시지도 feat: 접두사 붙여야..."
CLAUDE.md가 있으면:
나: "컴포넌트 하나 만들어줘"
Claude: *Tailwind + CSS 변수 + 다크모드 + feat: 커밋까지 한 번에*
3초면 시작할 수 있다
claude
> /init
/init 명령어를 실행하면 Claude가 프로젝트 구조를 분석해서 초안을 자동 생성한다. package.json, 설정 파일, 디렉토리 구조를 읽고 빌드 명령어, 테스트 방법, 코딩 컨벤션을 정리해준다.
이게 시작점이다. 여기서 수정하고 덧붙이면서 프로젝트에 맞게 다듬으면 된다.
CLAUDE.md 계층 구조 — 어디에 뭘 넣을까
CLAUDE.md는 하나만 있는 게 아니다. 계층 구조로 동작한다. 가장 넓은 범위(전체 프로젝트)에서 가장 좁은 범위(특정 디렉토리)까지 단계별로 설정할 수 있다.
📁 ~/.claude/
│ └── CLAUDE.md ← 🔵 User: 모든 프로젝트에 적용
│
📁 my-project/
│ ├── CLAUDE.md ← 🟢 Project: 팀 전체 공유 (git에 커밋)
│ ├── CLAUDE.local.md ← 🟡 Local: 나만의 설정 (gitignore됨)
│ └── .claude/
│ ├── CLAUDE.md ← 🟢 Project (대안 위치)
│ └── rules/
│ ├── code-style.md ← 🟢 모듈화된 규칙
│ ├── testing.md
│ └── security.md
│
📁 my-project/packages/frontend/
└── CLAUDE.md ← 🔴 Directory: 이 폴더 전용 규칙
각 레벨을 정리하면 이렇다:
| 레벨 | 위치 | 용도 | 공유 대상 |
|---|---|---|---|
| User | ~/.claude/CLAUDE.md | 개인 선호 설정 | 나만 (모든 프로젝트) |
| Project | ./CLAUDE.md | 팀 규칙, 프로젝트 구조 | 팀 전체 (git 커밋) |
| Local | ./CLAUDE.local.md | 개인 프로젝트 설정 | 나만 (자동 gitignore) |
| Rules | .claude/rules/*.md | 주제별 모듈화 규칙 | 팀 전체 |
| Directory | 하위폴더/CLAUDE.md | 특정 디렉토리 전용 | 팀 전체 |
우선순위: 더 구체적인 것이 이긴다. 프로젝트 레벨 설정이 유저 레벨보다 우선하고, 디렉토리 레벨이 프로젝트 레벨보다 우선한다.
.claude/rules/로 모듈화하기
CLAUDE.md가 길어지면 .claude/rules/ 디렉토리로 분리할 수 있다. 주제별로 나누면 관리가 훨씬 편하다:
.claude/rules/
├── code-style.md # 코딩 스타일 규칙
├── testing.md # 테스트 컨벤션
├── api-design.md # API 설계 규칙
└── frontend/
├── react.md # React 패턴
└── styling.md # CSS/Tailwind 규칙
특정 파일에만 적용되는 규칙은 paths 프론트매터로 스코프를 지정할 수 있다:
---
paths:
- "src/components/**/*.tsx"
---
# React 컴포넌트 규칙
- Server Component 기본. useState/useEffect 필요할 때만 'use client'
- Props 타입은 인터페이스로 정의
이렇게 하면 src/components/ 하위의 .tsx 파일 작업할 때만 이 규칙이 로드된다.
잘 쓴 CLAUDE.md vs 못 쓴 CLAUDE.md
못 쓴 예시
# 프로젝트 가이드
이 프로젝트는 Next.js를 사용하는 웹 애플리케이션입니다. React와 TypeScript를
기반으로 하며, Tailwind CSS를 스타일링에 사용합니다. 데이터베이스는 PostgreSQL
이고, ORM은 Prisma를 사용합니다. 배포는 Vercel에서 하고 있으며, CI/CD는
GitHub Actions로 구성되어 있습니다. 테스트는 Jest와 Testing Library를
사용하고 있습니다. 코드 스타일은 ESLint와 Prettier로 관리합니다.
상태 관리는 Zustand를 사용하고 있으며, 폼 처리는 React Hook Form을
사용합니다. 인증은 NextAuth.js를 사용하고, 이메일 발송은...
(계속 장문으로 이어짐)
문제점: 장황하고, 구조가 없고, 실행 가능한 명령어도 없다.
잘 쓴 예시
# MyApp
## Stack
Next.js 14 (App Router), TypeScript, Tailwind CSS, Prisma + PostgreSQL
## Commands
npm run dev # localhost:3000
npm run build # Production build (exit 0 = pass)
npm test # Jest + Testing Library
npx prisma studio # DB GUI
## Rules
1. Server Components 기본. 'use client'는 꼭 필요할 때만.
2. 스타일은 Tailwind만. inline style 금지.
3. 커밋: feat: / fix: / refactor: 접두사.
4. 새 패키지 설치 전 확인 필요.
## Structure
src/app/ # 라우트
src/components/ # UI 컴포넌트
src/lib/ # 유틸, 훅
prisma/schema.prisma # DB 스키마
핵심 원칙 3가지:
- 간결하게 — 150줄 이내가 이상적. Claude는 약 150~200개의 지시를 안정적으로 따를 수 있는데, 시스템 프롬프트가 이미 50개 정도를 쓴다.
- 실행 가능하게 — "코드를 잘 짜세요" 대신 "Tailwind만 쓰고, inline style 금지"처럼 구체적으로.
- Progressive Disclosure — 모든 걸 다 적지 말고, 세부 정보는 별도 파일로 분리해서
@import로 연결.
@import로 문서 분리하기
CLAUDE.md가 길어지면 @path/to/file 문법으로 외부 파일을 가져올 수 있다:
# MyApp
프로젝트 개요는 @README.md 참고.
사용 가능한 명령어는 @package.json 참고.
## 상세 규칙
- API 설계 규칙: @docs/api-conventions.md
- Git 워크플로우: @docs/git-workflow.md
이렇게 하면 CLAUDE.md 자체는 짧게 유지하면서, 필요한 맥락은 언제든 참조할 수 있다.
Skills — CLAUDE.md의 확장팩
CLAUDE.md가 "이 프로젝트는 이런 곳이야"라면, Skills는 **"이런 일은 이렇게 해"**다.
Skill이란?
Skill은 SKILL.md 파일로 정의하는 재사용 가능한 지시 세트다. CLAUDE.md에 모든 걸 넣으면 너무 길어지니까, 특정 작업(블로그 작성, 코드 리뷰, 배포 등)에 대한 상세 지침을 별도 파일로 분리한 것이다.
.claude/skills/
├── code-review/
│ └── SKILL.md # 코드 리뷰 규칙
├── deploy/
│ └── SKILL.md # 배포 프로세스
└── blog-writer/
├── SKILL.md # 블로그 작성 규칙
├── tone-guide.md # 톤 가이드 (참고 파일)
└── examples/
└── sample.md # 예시 포스트
SKILL.md는 두 부분으로 구성된다:
---
name: code-review
description: PR 코드를 리뷰하고 개선점을 제안합니다.
---
# 코드 리뷰 규칙
## 확인 항목
1. TypeScript any 타입 사용 여부
2. 에러 핸들링 누락
3. 보안 취약점 (SQL injection, XSS 등)
4. 성능 이슈 (불필요한 re-render, N+1 쿼리)
## 리뷰 포맷
- 심각도: 🔴 Critical / 🟡 Warning / 🟢 Suggestion
- 각 항목에 수정 방법 제시
YAML 프론트매터(위쪽 --- 사이)에서 이름과 설명을 정의하고, 아래 마크다운에서 구체적인 지시를 적는다.
자동 호출 vs 수동 호출
Skills는 두 가지 방식으로 작동한다:
| 방식 | 설정 | 동작 |
|---|---|---|
| 자동 호출 | 기본값 | Claude가 대화 맥락에 맞으면 알아서 로드 |
| 수동 호출 | disable-model-invocation: true | /skill-name으로 직접 실행해야만 동작 |
---
name: deploy
description: 프로덕션 배포
disable-model-invocation: true # 수동으로만 실행
---
# 배포 절차
1. 테스트 스위트 실행
2. 빌드
3. Vercel에 배포
배포처럼 부작용이 있는 작업은 disable-model-invocation: true로 설정해서 Claude가 멋대로 실행하지 못하게 막는 게 좋다. 코딩 컨벤션이나 스타일 가이드처럼 참고용 Skill은 자동 호출이 편하다.
어디에 저장하나?
| 위치 | 적용 범위 |
|---|---|
~/.claude/skills/ | 모든 프로젝트 (개인용) |
.claude/skills/ | 이 프로젝트만 (팀 공유) |
개인적으로 항상 쓰는 Skill(코드 리뷰, 커밋 등)은 ~/.claude/skills/에, 프로젝트 전용 Skill(블로그 작성, 특정 API 규칙 등)은 .claude/skills/에 넣으면 된다.
Skill에 인자 전달하기
$ARGUMENTS 또는 $0, $1 같은 플레이스홀더로 인자를 받을 수 있다:
---
name: fix-issue
description: GitHub 이슈를 수정합니다
disable-model-invocation: true
---
GitHub 이슈 #$ARGUMENTS 수정:
1. 이슈 내용 확인
2. 코드 수정
3. 테스트 작성
4. feat: 또는 fix: 커밋
> /fix-issue 42
# → "GitHub 이슈 #42 수정:" 으로 실행됨
실전: 내 프로젝트에서 이렇게 쓰고 있다
이론은 여기까지. 실제로 어떻게 쓰는지 보여주겠다.
내 포트폴리오 사이트(White Place)는 Next.js 14 + TypeScript + Tailwind CSS로 만들어졌다. 블로그, 포트폴리오, AI 뉴스, 데스크 리뷰 등 11개 라우트가 있고, 컴포넌트는 28개가 넘는다.
CLAUDE.md 구조
# White Place
## Project Context
Next.js 14 App Router developer portfolio and blog system.
- Tech Stack: React, TypeScript, Tailwind CSS, React Three Fiber
## Category System (2-Tier)
| category | subcategory | 설명 |
|----------|-------------|------|
| "ai" | "ai-news" | AI 뉴스 |
| "dev" | "web-dev" | 웹 개발 |
| "cs" | "tutorial" | 튜토리얼 |
## Global Rules
1. No hardcoded colors — CSS 변수만 사용
2. No unapproved packages
3. SSG first
4. Images = next/image
## Commands
npm run dev / npm run build / npx tsc --noEmit
## Agent Routing ← 이게 핵심
| Skill | Trigger Keywords |
|-------|-----------------|
| A Blog Writer | blog, post, article |
| B Feature Dev | feature, component, page |
| D Design System | style, css, tailwind |
| F AI News Writer | ai news, LLM, Claude |
핵심은 맨 아래 Agent Routing 테이블이다. 대화 주제에 따라 어떤 Skill을 참조할지 명시해놓으면, Claude가 알아서 관련 Skill 파일을 읽고 그 규칙을 따른다.
7개 Skill 라우팅 시스템
.claude/skills/
├── A-blog-writer.md # 블로그 포스트 작성 규칙
├── B-feature-dev.md # 기능 개발 워크플로우
├── C-portfolio-manager.md # 포트폴리오 관리
├── D-design-system.md # 디자인 시스템 (CSS 변수, Tailwind)
├── E-youtube-curator.md # YouTube 영상 큐레이션
├── F-ai-news-writer.md # AI 뉴스 작성 (웹 서칭 + 팩트체크)
└── H-3d-specialist.md # Three.js / R3F 3D 작업
각 Skill이 서로 라우팅 규칙을 갖고 있다. 예를 들어 Skill A(블로그 작성) 중에 3D 관련 작업이 필요하면 Skill H로 넘기고, CSS 변경이 필요하면 Skill D를 참조한다.
카테고리 시스템 문서화 사례
블로그에 2단계 카테고리 시스템을 쓰는데, 이걸 CLAUDE.md에 명시해놓으니까 포스트 작성할 때 카테고리를 잘못 넣는 일이 사라졌다:
# 프론트매터 예시
---
title: "포스트 제목"
date: "2026-02-23"
category: "dev" # 상위: ai | dev | cs
subcategory: "web-dev" # 하위: ai-news | web-dev | dev-env | tutorial | algorithm
tags: ["next.js", "react"]
---
이 구조를 CLAUDE.md에 한 번 적어놓으면, 이후 모든 포스트에서 일관된 카테고리를 자동으로 적용한다. 문서화가 곧 자동화다.
시작하는 법 (3분 셋업)
Step 1: 초안 생성
claude
> /init
프로젝트 구조를 분석해서 CLAUDE.md 초안을 만들어준다.
Step 2: 핵심 규칙 추가
생성된 파일을 열고, 최소한 이것들은 넣어라:
- 빌드/테스트 명령어 — Claude가 검증할 때 쓸 수 있도록
- 코딩 컨벤션 — 스타일, 네이밍, 패턴
- 프로젝트 구조 — 어디에 뭐가 있는지
- 금지 사항 — 하면 안 되는 것 (예: inline style 금지)
Step 3: 대화하면서 보완
작업 중에 Claude가 틀린 방식으로 하면, # 키를 눌러서 바로 CLAUDE.md에 규칙을 추가할 수 있다:
# 키 → "항상 Server Component 기본으로 만들고, useState 쓸 때만 'use client' 추가해"
→ CLAUDE.md에 자동 저장
이게 가장 자연스러운 방법이다. 한 번에 완벽한 문서를 만들려고 하지 말고, 실제 작업하면서 필요할 때마다 추가하면 된다.
추천 초기 설정 체크리스트
-
/init으로 CLAUDE.md 생성 - 빌드/테스트 명령어 확인
- 코딩 컨벤션 3~5개 추가
- 프로젝트 구조 간략하게 명시
- 자주 쓰는 Skill 1개 만들어보기 (코드 리뷰 추천)
- 팀 프로젝트라면 git에 커밋
CLAUDE.md는 살아있는 문서다. 완벽할 필요 없다. 쓰면서 계속 다듬으면 된다. 중요한 건 지금 당장 시작하는 것이다.
참고