Claude Code 입문설치부터 CLAUDE.md, Skills, Plugin까지
ChatGPT나 Claude 웹에서 코드를 복사-붙여넣기 하고 있다면, 한 단계 더 있습니다. Claude Code는 터미널에서 직접 파일을 읽고, 수정하고, 빌드까지 돌리는 AI 코딩 도구입니다. 웹 채팅창에 코드를 붙여넣는 게 아니라, AI가 내 프로젝트 안에서 직접 작업합니다.
근데 설치하고 바로 쓰면, 매번 같은 말을 반복하게 됩니다. "Tailwind 쓰고, 커밋은 feat: 접두사 붙이고, 이 폴더에 파일 만들고..." CLAUDE.md를 쓰면 이 반복이 사라집니다. Skills를 추가하면 작업별 전문가를 만들 수 있습니다. Plugin을 쓰면 이 모든 걸 커뮤니티가 만들어둔 것으로 바로 시작할 수 있습니다.
Claude Code 설치하기
준비물
- Node.js 18 이상 — nodejs.org에서 LTS 버전을 설치합니다
- Anthropic 계정 — claude.ai에서 가입
Node.js가 설치되어 있는지 확인하려면:
node --version
# v18.x.x 이상이면 OK
설치
npm install -g @anthropic-ai/claude-code
-g는 글로벌 설치입니다. 어느 폴더에서든 claude 명령어를 쓸 수 있게 됩니다.
첫 실행
프로젝트 폴더로 이동한 뒤:
cd my-project
claude
처음 실행하면 인증 과정이 나옵니다. 브라우저가 열리면서 Anthropic 계정으로 로그인하라고 합니다. 로그인하면 터미널로 돌아와서 바로 대화를 시작할 수 있습니다.
Max 구독이 있으면 그대로 사용 가능하고, 없으면 API 키를 설정해야 합니다. API 키는 console.anthropic.com에서 발급받을 수 있습니다.
이게 웹 Claude랑 뭐가 다른데?
| 웹 Claude | Claude Code | |
|---|---|---|
| 작업 방식 | 채팅창에 코드 복사-붙여넣기 | 내 프로젝트 파일을 직접 읽고 수정 |
| 파일 접근 | 불가능 | 모든 파일 읽기/쓰기 가능 |
| 터미널 실행 | 불가능 | npm run build, git 등 직접 실행 |
| 프로젝트 맥락 | 매번 설명해야 함 | CLAUDE.md로 자동 로드 |
핵심 차이는 파일 시스템 접근입니다. 웹에서는 "이 파일 수정해줘"라고 하면 수정된 코드를 보여주고, 내가 직접 복사해서 붙여넣어야 합니다. Claude Code에서는 AI가 직접 파일을 열고 수정하고 저장합니다.
CLAUDE.md — AI에게 주는 온보딩 문서
CLAUDE.md는 Claude Code가 세션 시작할 때 자동으로 읽는 프로젝트 설명서입니다. 새 팀원한테 "우리 프로젝트는 이렇게 돌아가고, 이런 규칙이 있어"라고 알려주는 문서를 떠올리면 됩니다.
없으면 이렇게 됩니다
나: "컴포넌트 하나 만들어줘"
Claude: (inline style로 만듦)
나: "아 우리 Tailwind 쓴다고..."
Claude: (수정)
나: "다크모드도 지원해야 하고, CSS 변수 써야 하고..."
Claude: (또 수정)
나: "커밋 메시지도 feat: 접두사 붙여야..."
있으면 이렇게 됩니다
나: "컴포넌트 하나 만들어줘"
Claude: (Tailwind + CSS 변수 + 다크모드 + feat: 커밋까지 한 번에)
한 번 써놓으면 매 세션에서 자동으로 로드됩니다. 같은 말을 반복할 필요가 없습니다.
3분 만에 시작하기
claude
> /init
/init 명령어를 실행하면 Claude가 프로젝트 구조를 분석해서 CLAUDE.md 초안을 자동 생성합니다. package.json, 설정 파일, 디렉토리 구조를 읽고 기본 내용을 채워줍니다.
생성된 파일을 열어보면 이미 꽤 쓸만합니다. 여기서 4가지만 확인하고 추가하면 됩니다.
반드시 넣어야 할 4가지
1. 빌드/테스트 명령어
## Commands
npm run dev # 개발 서버
npm run build # 프로덕션 빌드
npm test # 테스트 실행
Claude가 코드를 수정한 뒤 스스로 검증할 수 있게 됩니다.
2. 코딩 컨벤션
## Rules
1. Tailwind CSS만 사용. inline style 금지.
2. Server Components 기본. useState 필요할 때만 'use client'.
3. 커밋 메시지: feat: / fix: / refactor: 접두사.
3. 프로젝트 구조
## Structure
src/app/ # 페이지 (App Router)
src/components/ # UI 컴포넌트
src/lib/ # 유틸리티
4. 금지 사항
## Don'ts
- 새 패키지 설치 전 반드시 물어보기
- <img> 태그 대신 next/image 사용
- any 타입 금지
AI에게 "하지 마라"고 명확하게 말하는 게 "잘 해라"보다 효과적입니다.
잘 동작하는지 확인하기
CLAUDE.md를 저장한 뒤 Claude Code를 다시 실행하면, 세션 시작 시 자동으로 읽힙니다.
확인하는 가장 쉬운 방법:
claude
> 이 프로젝트 기술 스택이 뭐야?
CLAUDE.md에 적어둔 내용을 바탕으로 대답하면 정상입니다. "Next.js 14를 쓰고 있고, Tailwind CSS를 사용합니다"처럼 답하면 제대로 로드된 겁니다.
작업 중에 규칙 추가하기 — # 키
Claude Code에서 대화 중에 # 키를 누르면, 메모리에 규칙을 바로 추가할 수 있습니다.
예를 들어, Claude가 컴포넌트를 만들 때 자꾸 export default function 대신 const를 쓴다면:
- 대화 중에
#키를 누릅니다 - "컴포넌트는 항상 export default function으로 선언" 이라고 입력합니다
- Enter를 누르면 CLAUDE.md에 자동으로 추가됩니다
이후 세션부터는 이 규칙을 자동으로 따릅니다. 완벽한 문서를 한 번에 만들려고 하지 마세요. 작업하면서 필요할 때 추가하는 게 가장 자연스러운 방법입니다.
계층 구조 — 어디에 뭘 넣을까
CLAUDE.md는 하나만 있는 게 아닙니다. 범위에 따라 여러 위치에 둘 수 있습니다.
~/.claude/
│ └── CLAUDE.md ← 모든 프로젝트에 적용 (내 개인 설정)
│
my-project/
│ ├── CLAUDE.md ← 이 프로젝트 전체 (팀과 공유, git에 커밋)
│ ├── CLAUDE.local.md ← 나만의 설정 (자동으로 gitignore됨)
│ └── .claude/rules/
│ ├── code-style.md ← 주제별로 분리한 규칙
│ └── testing.md
│
my-project/packages/frontend/
└── CLAUDE.md ← 이 폴더에서만 적용
| 레벨 | 위치 | 용도 | 누가 보나 |
|---|---|---|---|
| User | ~/.claude/CLAUDE.md | "나는 한국어로 대답해줘" 같은 개인 설정 | 나만 |
| Project | ./CLAUDE.md | 프로젝트 규칙 | 팀 전체 |
| Local | ./CLAUDE.local.md | 나만의 프로젝트 설정 | 나만 |
| Rules | .claude/rules/*.md | 주제별 규칙 파일 | 팀 전체 |
| Directory | 하위폴더/CLAUDE.md | 특정 폴더 전용 | 팀 전체 |
더 구체적인 설정이 이깁니다. 프로젝트 레벨이 User 레벨보다 우선하고, 디렉토리 레벨이 프로젝트 레벨보다 우선합니다.
처음에는 프로젝트 루트의 CLAUDE.md 하나만 있으면 충분합니다. 파일이 길어지면 그때 분리하세요.
Skills — 작업별 전문가 만들기
CLAUDE.md가 "이 프로젝트는 이런 곳이야"라면, Skills는 **"이런 작업은 이렇게 해"**입니다.
Skills가 필요한 이유
블로그 글을 쓸 때마다 이런 말을 반복한다고 가정합니다:
"프론트매터에 title, date, description, tags, category 넣어줘.
카테고리는 dev, ai, cs 중 하나고, 톤은 ~합니다체로,
이모지는 최대 2개까지만, AI 냄새 나는 표현 쓰지 마..."
이걸 Skill 파일 하나에 적어놓으면, 다음부터는 "블로그 글 써줘"만 하면 됩니다.
첫 번째 Skill 만들어보기
.claude/skills/ 폴더에 마크다운 파일을 만들면 됩니다.
mkdir -p .claude/skills
예시로 간단한 코드 리뷰 Skill을 만들어보겠습니다.
---
name: code-review
description: 코드를 리뷰하고 개선점을 제안합니다.
---
# 코드 리뷰 규칙
## 확인 항목
1. TypeScript any 타입 사용 여부
2. 사용하지 않는 import/변수
3. 에러 핸들링 누락
4. 보안 취약점 (XSS, SQL injection 등)
## 리뷰 형식
- 심각도 표시: [Critical] / [Warning] / [Suggestion]
- 모든 이슈에 파일명:라인번호 포함
- "looks good" 같은 모호한 리뷰 금지
이 파일을 .claude/skills/code-review/SKILL.md에 저장합니다.
파일 구조는 이렇게 됩니다:
.claude/skills/
└── code-review/
└── SKILL.md
자동 호출 vs 수동 호출
기본적으로 Skills는 자동 호출됩니다. Claude가 대화 맥락을 보고, 관련 Skill이 있으면 알아서 읽습니다. "코드 리뷰해줘"라고 하면 위에 만든 Skill을 자동으로 참조합니다.
배포나 삭제처럼 부작용이 있는 작업은 수동으로만 실행되게 설정할 수 있습니다:
---
name: deploy
description: 프로덕션 배포
disable-model-invocation: true # 수동으로만 실행
---
이렇게 하면 Claude가 멋대로 배포를 실행하지 않습니다. /deploy라고 직접 입력해야만 동작합니다.
| 작업 종류 | 추천 설정 | 이유 |
|---|---|---|
| 코딩 컨벤션, 스타일 가이드 | 자동 호출 | 항상 참고해야 하니까 |
| 블로그 작성, 코드 리뷰 | 자동 호출 | 맥락에 따라 알아서 적용 |
| 배포, 데이터 삭제 | 수동 호출 | 실수 방지 |
Skill에 인자 전달하기
$ARGUMENTS 플레이스홀더로 값을 받을 수 있습니다:
---
name: fix-issue
description: GitHub 이슈를 수정합니다
disable-model-invocation: true
---
GitHub 이슈 #$ARGUMENTS를 확인하고:
1. 이슈 내용 파악
2. 관련 코드 수정
3. 테스트 확인
4. fix: 커밋
> /fix-issue 42
# → "GitHub 이슈 #42를 확인하고:" 로 실행됨
어디에 저장하나
| 위치 | 범위 |
|---|---|
~/.claude/skills/ | 내 모든 프로젝트에서 사용 |
.claude/skills/ | 이 프로젝트에서만 사용 |
개인적으로 항상 쓰는 Skill(코드 리뷰, 커밋 규칙)은 ~/.claude/skills/에, 프로젝트 전용 Skill은 .claude/skills/에 넣으면 됩니다.
Plugin — 커뮤니티가 만든 확장팩
2026년 들어 Claude Code에 Plugin 시스템이 추가되었습니다. CLAUDE.md와 Skills를 직접 만드는 게 처음부터 만드는 것이라면, Plugin은 누군가가 만들어둔 걸 설치해서 쓰는 것입니다.
Plugin이 뭔가
Plugin은 CLAUDE.md 규칙, Skills, Hooks(자동 실행 스크립트)를 패키지로 묶은 것입니다. npm install처럼 한 줄로 설치하면, 해당 도구의 규칙과 워크플로우가 Claude Code에 자동으로 적용됩니다.
claude plugin add @anthropic/plugin-name
CLAUDE.md → Skills → Plugin 관계
CLAUDE.md 프로젝트 규칙 (직접 작성)
│
├── Skills 작업별 매뉴얼 (직접 작성)
│
└── Plugin CLAUDE.md + Skills + Hooks를 패키지로 묶은 것 (커뮤니티/팀이 배포)
- CLAUDE.md: 프로젝트에 맞는 기본 규칙
- Skills: 반복되는 작업을 자동화하는 지시 세트
- Plugin: 위 두 가지를 포함한 재사용 가능한 패키지
직접 만들어 쓰다가 "이거 다른 프로젝트에서도 쓰고 싶다" 싶으면 Plugin으로 패키징할 수 있습니다. 반대로, 커뮤니티에서 잘 만들어진 Plugin을 가져와서 바로 쓸 수도 있습니다.
claudeforge — Plugin 이전의 시도
Plugin 시스템이 공식 출시되기 전에, 커뮤니티에서는 이미 비슷한 시도가 있었습니다. 제가 만들었던 claudeforge도 그중 하나입니다.
claudeforge는 CLAUDE.md와 Skills 파일을 프로젝트 유형에 맞게 자동 생성해주는 도구였습니다. "Next.js 블로그 프로젝트야"라고 하면, 해당 스택에 맞는 규칙과 스킬 파일을 뼈대부터 만들어줬습니다.
이후 Anthropic이 Claude Code에 공식 Plugin 시스템을 도입하면서, claudeforge가 하던 역할의 상당 부분을 Plugin이 대체하게 됐습니다. 개인이 만든 도구가 플랫폼 기능으로 흡수되는 전형적인 패턴입니다.
지금은 Plugin 시스템이 공식으로 있으니, 새 프로젝트를 시작할 때는 Plugin부터 찾아보는 게 효율적입니다. 없으면 직접 만들고, 잘 되면 Plugin으로 배포하면 됩니다.
흔한 실수와 해결법
"CLAUDE.md를 만들었는데 안 읽히는 것 같아"
확인 1: 파일 위치가 프로젝트 루트인지 확인하세요. src/CLAUDE.md에 넣으면 안 됩니다. 프로젝트 최상위 폴더에 있어야 합니다.
확인 2: 파일명이 정확한지 확인하세요. Claude.md도, claude.md도 아닌 CLAUDE.md입니다. 대문자입니다.
확인 3: Claude Code를 새로 시작했는지 확인하세요. 이미 실행 중인 세션에서는 변경 사항이 바로 반영되지 않을 수 있습니다.
"규칙을 적었는데 Claude가 안 따라"
CLAUDE.md가 너무 길면 규칙이 묻힙니다. 150줄 이내가 이상적입니다. 정말 중요한 규칙은 앞쪽에 배치하세요.
"코드를 잘 짜세요" 같은 모호한 지시는 효과가 없습니다. "inline style 금지, Tailwind만 사용" 처럼 구체적으로 적어야 합니다.
"Skill 파일을 만들었는데 인식이 안 돼"
Skill 파일은 반드시 .claude/skills/ 아래에 있어야 합니다. 그리고 파일 안에 YAML 프론트매터(--- 사이의 name, description)가 있어야 합니다. 프론트매터가 없으면 일반 마크다운 파일로 취급됩니다.
---
name: my-skill # 이게 있어야 Skill로 인식됨
description: 설명
---
시작하는 순서
- Claude Code 설치 —
npm install -g @anthropic-ai/claude-code /init으로 CLAUDE.md 생성 — 초안을 자동으로 만들어줍니다- 4가지 확인 — 명령어, 컨벤션, 구조, 금지사항이 있는지 체크
- 작업하면서 보완 —
#키로 규칙을 하나씩 추가 - 반복 작업이 보이면 Skill로 분리 — 블로그 글쓰기, 코드 리뷰 등
- Plugin 검색 — 이미 만들어진 게 있는지 확인
완벽한 설정을 한 번에 만들 필요 없습니다. CLAUDE.md 하나 만들고, 빌드 명령어 3줄 적는 것만으로도 효과가 있습니다. 거기서부터 작업하면서 필요한 규칙을 하나씩 추가하면 됩니다. 가장 좋은 CLAUDE.md는 6개월 동안 계속 수정된 CLAUDE.md입니다.
