Claude Code 입문 — 설치부터 CLAUDE.md, Skills, Plugin까지
2026년 10월 기준으로 고침: 설치 방법, 로그인할 수 있는 계정, 작업 중에 CLAUDE.md에 규칙을 더하는 방법, Plugin 설치 명령, 하위 폴더 CLAUDE.md가 읽히는 시점을 지금 공식 문서에 맞췄습니다.
ChatGPT나 Claude 웹에서 코드를 복사-붙여넣기 하고 있다면, 한 단계 더 있습니다. Claude Code는 터미널에서 직접 파일을 읽고, 수정하고, 빌드까지 돌리는 AI 코딩 도구입니다. 웹 채팅창에 코드를 붙여넣는 게 아니라, AI가 내 프로젝트 안에서 직접 작업합니다.
근데 설치하고 바로 쓰면, 매번 같은 말을 반복하게 됩니다. "Tailwind 쓰고, 커밋은 feat: 접두사 붙이고, 이 폴더에 파일 만들고..." CLAUDE.md를 쓰면 이 반복이 사라집니다. Skills를 추가하면 작업별 전문가를 만들 수 있습니다. Plugin을 쓰면 이 모든 걸 커뮤니티가 만들어둔 것으로 바로 시작할 수 있습니다.
Claude Code 설치하기
준비물
- Claude 계정: Pro·Max·Team·Enterprise 구독이나 Claude Console 계정이 필요합니다. 무료 claude.ai 플랜으로는 Claude Code를 쓸 수 없습니다
- 지원 OS: macOS 13.0 이상, Windows 10 1809 이상, Ubuntu 20.04 이상 등. 전체 목록은 공식 설치 문서에 있습니다
기본 설치에는 Node.js가 필요 없습니다.
설치
공식 문서가 권하는 방법은 네이티브 설치입니다. 터미널에 한 줄이면 됩니다.
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
설치가 끝나면 터미널을 새로 열고 claude --version을 입력합니다. 버전 번호가 나오면 성공입니다. 네이티브 설치는 백그라운드에서 알아서 업데이트됩니다.
패키지 관리자를 쓰고 싶다면 이런 방법도 있습니다.
| 방법 | 명령 | 참고 |
|---|---|---|
| Homebrew | brew install --cask claude-code | 기본으로는 자동 업데이트 안 됨. brew upgrade claude-code로 올림 |
| WinGet | winget install Anthropic.ClaudeCode | 기본으로는 자동 업데이트 안 됨. winget upgrade Anthropic.ClaudeCode로 올림 |
| npm | npm install -g @anthropic-ai/claude-code | Node.js 22 이상. sudo를 붙이지 말 것 |
첫 실행
프로젝트 폴더로 이동한 뒤:
cd my-project
claude
처음 실행하면 로그인 과정이 나옵니다. 브라우저가 열리면 로그인하고, 터미널에 Login successful이 뜨면 Enter를 눌러 대화를 시작합니다.
어떤 계정으로 로그인하는지는 쓰는 방식에 따라 다릅니다.
- Pro·Max 구독: claude.ai 계정으로 로그인합니다. API 키는 필요 없습니다
- Team·Enterprise: 관리자가 초대한 claude.ai 계정으로 로그인합니다
- 쓴 만큼 API 요금으로 내고 싶다면: Claude Console 계정으로 로그인합니다
ANTHROPIC_API_KEY 환경 변수를 설정해 두었다면 Claude Code가 그 키를 쓸지 묻고, 승인하면 로그인 단계를 건너뜁니다. 계정별 설정은 인증 문서에 정리돼 있습니다.
이게 웹 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를 사용합니다"처럼 답하면 제대로 로드된 겁니다.
더 확실하게 보려면 세션 안에서 /context를 입력합니다. Memory files 목록에 CLAUDE.md가 있으면 시작할 때 읽힌 것입니다.
작업 중에 규칙 추가하기
예를 들어, Claude가 컴포넌트를 만들 때 자꾸 export default function 대신 const를 쓴다면 대화 중에 그대로 말하면 됩니다.
> 컴포넌트는 항상 export default function으로 선언한다고 CLAUDE.md에 추가해줘
Claude가 CLAUDE.md를 열어 그 규칙을 적습니다. 직접 고치고 싶으면 /memory를 입력합니다. CLAUDE.md 파일 목록이 나오고, 하나를 고르면 에디터로 열립니다.
"CLAUDE.md에"를 빼고 "기억해줘"라고만 하면 CLAUDE.md가 아니라 Claude Code의 자동 메모리(auto memory)에 저장됩니다. 팀과 같이 쓸 규칙이라면 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 또는 ./.claude/CLAUDE.md | 프로젝트 규칙 | 팀 전체 |
| Local | ./CLAUDE.local.md | 나만의 프로젝트 설정. .gitignore에 넣어 커밋되지 않게 | 나만 |
| Rules | .claude/rules/*.md | 주제별 규칙 파일 | 팀 전체 |
| Directory | 하위폴더/CLAUDE.md | 그 폴더 파일을 읽거나 고칠 때 로드 | 팀 전체 |
Claude Code를 실행한 폴더와 그 위쪽 폴더의 CLAUDE.md는 시작할 때 읽힙니다. 하위 폴더의 CLAUDE.md는 시작할 때가 아니라, Claude가 그 폴더 안의 파일을 읽거나 고칠 때 로드됩니다.
찾은 파일들은 서로 덮어쓰지 않고 모두 이어 붙여 읽힙니다. 상위 폴더부터 읽어서 작업 폴더에 가까운 파일이 나중에 들어갑니다. 두 파일이 같은 일에 다른 지시를 주면 Claude가 어느 쪽을 따를지 정해져 있지 않으니, 겹치지 않게 쓰는 게 안전합니다.
처음에는 프로젝트 루트의 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 — 커뮤니티가 만든 확장팩
2025년 10월 Claude Code에 Plugin 시스템이 공개 베타로 나왔습니다(발표). CLAUDE.md와 Skills를 직접 만드는 게 처음부터 만드는 것이라면, Plugin은 누군가가 만들어둔 걸 설치해서 쓰는 것입니다.
Plugin이 뭔가
Plugin은 Skills, 서브에이전트, Hooks(자동 실행 스크립트), MCP 서버 설정 같은 확장을 한 묶음으로 배포하는 패키지입니다. 설치하면 그 도구의 명령과 워크플로우가 Claude Code에 바로 들어옵니다. Plugin 안에 CLAUDE.md를 넣어도 로드되지 않아서, 규칙을 담을 때는 Skill로 넣습니다.
Plugin은 마켓플레이스(Plugin 목록)에서 설치합니다. Anthropic 공식 마켓플레이스 claude-plugins-official은 대화형 세션을 처음 열 때 자동으로 추가됩니다.
# Claude Code 세션 안에서 (설치 범위를 고르는 화면이 열림)
/plugin install commit-commands@claude-plugins-official
# 셸에서 바로
claude plugin install commit-commands@claude-plugins-official
이름 뒤 @ 다음은 마켓플레이스 이름입니다. 다른 마켓플레이스의 Plugin은 /plugin marketplace add 소유자/저장소로 마켓플레이스를 먼저 추가한 뒤 설치합니다. /plugin만 입력하면 Plugin을 찾아보는 Discover 탭이 열립니다. 자세한 내용은 Plugin 문서에 있습니다.
Plugin은 내 컴퓨터에서 내 사용자 권한으로 코드를 실행할 수 있습니다. Hooks는 셸 명령으로, 로컬 MCP 서버는 내 컴퓨터의 프로세스로 돕니다. Claude Code의 권한 규칙과 샌드박스도 이 코드에는 적용되지 않습니다.
설치 전에 상세 화면의 Will install 목록에서 Hooks와 MCP 서버를 확인하고, 작성자를 모르는 마켓플레이스는 추가하지 마세요. 마켓플레이스 이름은 누가 목록을 냈는지만 알려 주므로 공식 마켓플레이스의 Plugin도 설치 전에 같은 확인을 거칩니다(Plugin 보안 문서).
CLAUDE.md → Skills → Plugin 관계
CLAUDE.md 프로젝트 규칙 (직접 작성)
│
├── Skills 작업별 매뉴얼 (직접 작성)
│
└── Plugin Skills + 서브에이전트 + Hooks + MCP를 패키지로 묶은 것 (커뮤니티/팀이 배포)
- CLAUDE.md: 프로젝트에 맞는 기본 규칙
- Skills: 반복되는 작업을 자동화하는 지시 세트
- Plugin: Skills를 비롯한 확장을 묶은 재사용 가능한 패키지
직접 만들어 쓰다가 "이거 다른 프로젝트에서도 쓰고 싶다" 싶으면 Plugin으로 패키징할 수 있습니다. 반대로, 커뮤니티에서 잘 만들어진 Plugin을 가져와서 바로 쓸 수도 있습니다.
claudeforge — Plugin 이전의 시도
Plugin 시스템이 공식 출시되기 전에, 커뮤니티에서는 이미 비슷한 시도가 있었습니다. 제가 만들었던 claudeforge도 그중 하나입니다.
claudeforge는 CLAUDE.md와 Skills 파일을 프로젝트 유형에 맞게 자동 생성해주는 도구였습니다. "Next.js 블로그 프로젝트야"라고 하면, 해당 스택에 맞는 규칙과 스킬 파일을 뼈대부터 만들어줬습니다.
이후 Anthropic이 Claude Code에 공식 Plugin 시스템을 도입하면서, claudeforge가 하던 역할의 상당 부분을 Plugin이 대체하게 됐습니다. 개인이 만든 도구가 플랫폼 기능으로 흡수되는 전형적인 패턴입니다.
지금은 Plugin 시스템이 공식으로 있으니, 새 프로젝트를 시작할 때는 Plugin부터 찾아보는 게 효율적입니다. 없으면 직접 만들고, 잘 되면 Plugin으로 배포하면 됩니다.
흔한 실수와 해결법
"CLAUDE.md를 만들었는데 안 읽히는 것 같아"
확인 1: 파일 위치를 확인하세요. 세션을 시작할 때 읽히는 건 Claude Code를 실행한 폴더와 그 위쪽 폴더의 CLAUDE.md(또는 .claude/CLAUDE.md)입니다. src/CLAUDE.md 같은 하위 폴더 파일은 Claude가 그 폴더 파일을 다룰 때 로드되니, 프로젝트 전체 규칙은 최상위 폴더에 두세요. /context의 Memory files 목록에서 시작할 때 읽힌 파일을 볼 수 있습니다.
확인 2: 파일명이 정확한지 확인하세요. Claude.md도, claude.md도 아닌 CLAUDE.md입니다. 대문자입니다.
확인 3: Claude Code를 새로 시작했는지 확인하세요. 이미 실행 중인 세션에서는 변경 사항이 바로 반영되지 않을 수 있습니다.
"규칙을 적었는데 Claude가 안 따라"
CLAUDE.md가 너무 길면 규칙이 묻힙니다. 공식 문서는 파일 하나에 200줄 이내를 권합니다. 정말 중요한 규칙은 앞쪽에 배치하세요.
"코드를 잘 짜세요" 같은 모호한 지시는 효과가 없습니다. "inline style 금지, Tailwind만 사용" 처럼 구체적으로 적어야 합니다.
"Skill 파일을 만들었는데 인식이 안 돼"
Skill은 .claude/skills/<이름>/SKILL.md처럼 폴더 하나에 SKILL.md 파일 하나로 둡니다. 프론트매터 필드는 모두 선택이라, name을 빼면 폴더 이름이 명령 이름이 됩니다. 다만 description은 넣는 게 좋습니다. Claude가 이 설명을 보고 언제 Skill을 쓸지 정합니다.
---
name: my-skill # 없으면 폴더 이름을 씀
description: 언제 쓰는 Skill인지 # 자동 호출 판단에 쓰임
---
시작하는 순서
- Claude Code 설치:
curl -fsSL https://claude.ai/install.sh | bash(Windows는 위의 PowerShell 명령) /init으로 CLAUDE.md 생성: 초안을 자동으로 만들어줍니다- 4가지 확인: 명령어, 컨벤션, 구조, 금지사항이 있는지 체크
- 작업하면서 보완: "CLAUDE.md에 추가해줘"라고 말하거나
/memory로 직접 고치기 - 반복 작업이 보이면 Skill로 분리: 블로그 글쓰기, 코드 리뷰 등
- Plugin 검색: 이미 만들어진 게 있는지 확인하고, 설치 전에 작성자와 Hooks·MCP 서버 목록을 확인
완벽한 설정을 한 번에 만들 필요 없습니다. CLAUDE.md 하나 만들고, 빌드 명령어 3줄 적는 것만으로도 효과가 있습니다. 거기서부터 작업하면서 필요한 규칙을 하나씩 추가하면 됩니다. 가장 좋은 CLAUDE.md는 6개월 동안 계속 수정된 CLAUDE.md입니다.
