클로드 코드 — 터미널에서 일하는 Anthropic 의 에이전틱 코딩 도구

무엇인가요

클로드 코드는 Anthropic 이 만든 에이전틱 코딩 도구(agentic coding tool)입니다. 할 일을 말로 부탁하면 파일을 읽고 코드를 고치고 명령을 실행하며, 그 전에 허락을 구합니다. 터미널에서 실행되고, VS Code·JetBrains 같은 코드 편집기, Claude 데스크톱 앱, 웹에서도 쓸 수 있습니다.

필요한 것

• 계정: Claude Pro·Max·Team·Enterprise 요금제나 Console(API) 계정. 무료 claude.ai 요금제에는 클로드 코드가 들어 있지 않습니다.
• 컴퓨터: macOS 13 이상, Windows 10(1809) 이상, Ubuntu 20.04·Debian 10 이상, 메모리 4GB 이상, 인터넷 연결.
• 일할 프로젝트 폴더 — 바뀐 것을 모두 보고 되돌릴 수 있도록 Git 저장소면 좋습니다.

설치

macOS·Linux·WSL 은 첫 줄, Windows 는 PowerShell 줄을 실행하세요. 이렇게 설치하면 백그라운드에서 스스로 최신 버전으로 업데이트됩니다. Homebrew·WinGet 으로 설치하면 스스로 업데이트하지 않습니다.

macOS · Linux · WSL

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

Windows PowerShell

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

Homebrew

brew install --cask claude-code 복사

WinGet

winget install Anthropic.ClaudeCode 복사

npm (Node.js 22+)

npm install -g @anthropic-ai/claude-code 복사

설치 확인

새 터미널 창을 여세요. claude --version 이 버전 번호를 보여 주고, claude doctor 가 설치 상태를 보여 줍니다. "command not found" 가 나오면 터미널을 다시 열고 PATH 를 확인하세요.

첫 실행 — 다섯 걸음

1. 터미널을 열고 작업할 폴더로 갑니다. 기존 프로젝트는 cd <폴더> 로 들어가고, 새로 시작하면 아래 명령으로 빈 폴더를 만듭니다. 그런 다음 claude 를 입력하고 Enter 를 누릅니다(데스크톱 앱이 아니라 터미널 도구가 시작됩니다). 처음에는 브라우저가 열려 로그인합니다.
2. 기존 프로젝트: "이 프로젝트에는 무엇이 있어?" 하고 물어 프로젝트를 읽게 합니다. 빈 폴더: "오늘 날짜를 보여 주는 한 쪽짜리 웹사이트를 만들고 싶어. 어떻게 시작할까?"처럼 만들 것을 말합니다.
3. 기존 프로젝트: /init 으로 CLAUDE.md 를 만들고, 테스트 명령과 지킬 규칙을 더합니다. 빈 폴더: 이 걸음은 건너뜁니다. /init 은 읽을 코드가 있어야 하므로 파일이 생긴 뒤에 실행합니다.
4. /plan 을 입력하거나 plan mode 가 보일 때까지 Shift+Tab 을 눌러 계획 모드로 바꾸고 변경을 부탁합니다. 빈 폴더에서는 첫 파일을 부탁합니다. 승인하기 전에 어떤 파일을 바꾸고 어떤 명령을 실행하는지 확인합니다. 내가 맡긴 일에 해당하는 동작만 승인하고, 다른 것이 섞여 있으면 계획부터 고칩니다.
5. git status(새 파일)와 git diff(고친 파일)로 바뀐 것을 보고, 테스트를 돌리는 식으로 결과를 직접 확인한 뒤 커밋합니다.

기존 프로젝트

새 프로젝트(빈 폴더)

기초 연습 — 처음 한 번 해 보기

막히면: claude 가 시작되지 않으면 claude doctor 로 설치를 확인하고, 로그인 창이 열리지 않으면 터미널을 닫고 새로 열어 claude 를 다시 실행하세요. 다섯 가지를 모두 해 봤다면 [중급] 탭으로 넘어가세요.

SONUB 에서 더 배우기

• 클로드 코드 1: 프로젝트를 준비하고 오래 가는 지시 주기
• 클로드 코드 2: 계획하고, 바꾸고, 테스트하고, 검토하기
• 에이전트와 서브 에이전트: AI 가 한 단계씩 일하는 방법
• Goal 과 Ralph Loop: 정말 끝날 때까지 에이전트가 계속 일하게 하기
• claude-skill 에이전트 스킬 — 클로드 코드를 순서대로 배우고 새 기능 따라잡기

공식 문서

• Claude Code — Overview
• Claude Code — Advanced setup
• Claude Code — Quickstart
• Claude Code — Common workflows
• Claude Code — Use Claude Code with Chrome

2026-10-19 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.

모델과 생각 수준(effort) — 무엇을 쓸까 (추천: Opus 5.5, High)

2026년 11월 기준 개발에는 Opus 5.5 를 High 수준으로 쓰세요. 기본 수준이 medium 이므로 아래처럼 설정하거나 /model opus 와 /effort high 를 실행합니다. 모든 모델과 생각 수준, 언제 낮추고 올릴지는 툴 마스터의 툴 추천 사용법에 있습니다.

{
  "model": "opus",
  "effortLevel": "high"
}

claude --model opus --effort high

# inside Claude Code
/model opus
/effort high

• 추천 모델 — 툴 마스터

CLAUDE.md — 세션마다 읽는 프로젝트 지시

CLAUDE.md 는 클로드 코드가 세션을 시작할 때마다 읽는 마크다운 파일입니다. 빌드·테스트 명령, 코드 규칙, 하지 말아야 할 일처럼 매번 말하기 번거로운 것을 적어 둡니다. /init 을 실행하면 프로젝트를 읽고 첫 CLAUDE.md 를 만들어 줍니다. 여러 곳의 CLAUDE.md 는 서로 덮어쓰지 않고 모두 합쳐 읽습니다.

• ~/.claude/CLAUDE.md — 내 모든 프로젝트에 쓰는 개인 지시
• ./CLAUDE.md 또는 ./.claude/CLAUDE.md — 팀이 함께 쓰는 프로젝트 지시(Git 에 커밋)
• ./CLAUDE.local.md — 이 프로젝트에서 나만 쓰는 지시(.gitignore 에 넣음)
• 하위 폴더의 CLAUDE.md — 그 폴더의 파일을 읽거나 고칠 때 더 읽음. .claude/rules/ 의 규칙 파일은 paths 로 특정 파일에만 걸 수 있음
• 주의: 작업 폴더나 그 위 폴더에 CLAUDE.md·.claude/CLAUDE.md·CLAUDE.local.md 가 하나라도 있으면 클로드 코드는 AGENTS.md 를 읽지 않습니다. 내 개인 지시 ~/.claude/CLAUDE.md 는 여기에 들어가지 않습니다 — 바로 아래 단락을 보세요.

# My App

## Commands
- Install: npm install
- Test: npm test
- Lint: npm run lint

## Rules
- TypeScript strict mode. Do not use `any`.
- Put new API routes in src/routes/.
- Never edit files in vendor/.
- Run the tests before you say a task is done.

@docs/architecture.md

짧게 쓰세요(공식 문서 권장 200줄 이하). 매번 읽으므로 길면 자리를 차지하고 중요한 규칙이 묻힙니다. /memory 로 지금 읽힌 지시 파일을 보고 바로 열어 고칠 수 있고, @docs/architecture.md 처럼 @경로 로 다른 파일을 불러올 수 있습니다. 여러 AI 를 함께 쓴다면 프로젝트에는 CLAUDE.md 대신 AGENTS.md 만 두는 것이 가장 좋습니다 — 바로 아래 단락을 보세요.

AGENTS.md 만 쓰기 — 여러 AI 가 같은 지시로 일하게

왜 이렇게 할까요? 한 프로젝트에서 클로드 코드와 함께 Codex·Cursor·Gemini 같은 다른 AI 도 쓴다면, 도구마다 지시 파일을 따로 두면 금방 내용이 서로 달라집니다. AGENTS.md 는 여러 코딩 에이전트가 함께 읽는 열린 형식입니다. 규칙을 AGENTS.md 한 곳에 적어 두면 어느 AI 로 일하든 모두 같은 지시를 따릅니다. 아래 방법은 바로 이것 — 하나의 프로젝트에서 여러 AI 가 AGENTS.md 를 통해 모두 같은 지시를 쓰게 하는 것 — 을 위한 것입니다.

클로드 코드도 AGENTS.md 를 직접 읽지만(v2.1.277 이상), CLAUDE.md 와 똑같지는 않습니다.

• 기본 설정에서는 작업 폴더나 그 위 폴더에 CLAUDE.md·.claude/CLAUDE.md·CLAUDE.local.md 가 하나도 없을 때만 AGENTS.md 를 읽습니다. 개인 메모용 CLAUDE.local.md 하나만 만들어도 AGENTS.md 는 읽히지 않습니다(~/.claude/CLAUDE.md 와 .claude/rules/ 는 이 판단에 들어가지 않습니다).
• 하위 폴더의 AGENTS.md 는 그 폴더에 자기 CLAUDE.md 가 없을 때, Claude 가 그 폴더에 이미 있는 파일을 Read 도구로 열면 읽힙니다. 기존 파일을 읽기 전에 그 폴더에 새 파일부터 만들면, 아직 그 폴더의 지시를 읽지 않았을 수 있습니다. 하위 폴더의 CLAUDE.md 는 Claude 가 그 폴더의 파일을 읽거나 만들거나 고칠 때 읽힙니다.
• AGENTS.local.md·AGENTS.override.md·.agents/ 폴더 안의 파일은 읽지 않고, --add-dir 로 더한 폴더의 AGENTS.md 도 읽지 않습니다.

가장 좋은 방법은 프로젝트 폴더에서 CLAUDE.md 를 아예 쓰지 않고 AGENTS.md 만 쓰는 것입니다. 그러면 내 전역 지시인 ~/.claude/CLAUDE.md 는 그대로 기본으로 읽히고, 프로젝트 폴더에서는 AGENTS.md 가 쓰입니다. Codex 같은 다른 AI 도 같은 AGENTS.md 를 읽으므로, 규칙은 AGENTS.md 한 곳에서만 고치면 됩니다.

하지만 프로젝트 폴더·지금 폴더·상위 폴더·하위 폴더 중 한 곳에서라도 CLAUDE.md 를 쓴다면, 반드시 모든 폴더에서 CLAUDE.md 를 써야 합니다. 작업 폴더나 그 위에 CLAUDE.md 가 하나라도 있으면 클로드 코드는 AGENTS.md 를 읽지 않으므로, 섞어 쓰면 어떤 폴더의 규칙은 읽히고 어떤 폴더의 규칙은 빠집니다. 이때 AGENTS.md 도 같이 쓰고 싶다면 각 CLAUDE.md 에 @AGENTS.md 한 줄만 더하면 됩니다. @경로 는 그 파일의 내용을 그 자리에 불러오는 문법이고, 공식 문서도 이렇게 불러와도 AGENTS.md 를 두 번 읽지는 않는다고 설명합니다.

1. 공통 규칙(설치·테스트 명령, 코드 규칙, 하지 말 것)을 프로젝트 맨 위의 AGENTS.md 에 적습니다. Codex 의 /init 으로 만들어도 됩니다.
2. 프로젝트 안(지금 폴더·상위 폴더·하위 폴더 어디에도)에 CLAUDE.md·.claude/CLAUDE.md·CLAUDE.local.md 를 만들지 않습니다.
3. 모든 프로젝트에 쓰는 내 개인 지시는 ~/.claude/CLAUDE.md 에 둡니다 — AGENTS.md 와 함께 늘 읽힙니다.
4. 하위 폴더에 따로 규칙이 있으면(예: api/) 그 폴더에도 AGENTS.md 를 둡니다.
5. 클로드 코드에서 /memory 를 열어 AGENTS.md 가 읽혔는지 확인합니다. CLAUDE.md 를 쓰기로 했다면 모든 폴더의 CLAUDE.md 에 @AGENTS.md 한 줄이 있는지도 확인합니다.

~/.claude/CLAUDE.md    ← your personal rules (still loaded by default)

my-project/
├── AGENTS.md          ← shared rules for every AI (Claude Code, Codex, Cursor, Gemini …)
└── api/
    └── AGENTS.md      ← rules only for api/

(no CLAUDE.md anywhere in the project)

my-project/
├── AGENTS.md
├── CLAUDE.md          ← @AGENTS.md
└── api/
    ├── AGENTS.md
    └── CLAUDE.md      ← @AGENTS.md

@AGENTS.md

알아 둘 점과 다른 방법. ① /config 의 Project instructions 를 claude-md-and-agents-md 로 바꾸면 폴더마다 CLAUDE.md 다음에 AGENTS.md 를 함께 읽습니다. ② 심볼릭 링크(ln -s AGENTS.md CLAUDE.md)도 되지만 Windows 가 섞이면 @AGENTS.md 한 줄이 안전합니다.

• Codex 가 AGENTS.md 를 읽는 순서 — Codex 중급

권한과 모드 — 묻지 않고 해도 되는 일 정하기

클로드 코드는 파일을 고치거나 명령을 실행하기 전에 허락을 묻습니다. 같은 허락을 매번 누르기 번거로우면 규칙으로 정해 두고, 일의 성격에 맞게 모드를 바꿉니다.

• Shift+Tab — 모드 바꾸기: 기본(매번 묻기) → acceptEdits(파일 편집은 묻지 않음) → plan(읽기만 하고 계획을 보여 줌). auto 모드에서 시작했다면 첫 번째 누름이 기본으로 바꿉니다.
• /permissions — 허락(allow)·묻기(ask)·거부(deny) 규칙과 그 규칙이 어느 파일에서 왔는지 보고 고칩니다.
• .claude/settings.json 은 팀이 함께 쓰는 규칙(커밋), .claude/settings.local.json 은 나만 쓰는 규칙, ~/.claude/settings.json 은 내 모든 프로젝트의 규칙입니다.
• 규칙은 deny → ask → allow 순서로 봅니다. 어느 곳에서든 deny 한 것은 다른 곳의 allow 로 풀 수 없으니, .env 같은 비밀 파일은 deny 로 막아 둡니다.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

bypassPermissions(--dangerously-skip-permissions)는 모든 확인을 끕니다. 인터넷이 막힌 컨테이너·가상 머신처럼 망가져도 괜찮은 곳에서만 쓰세요.

컨텍스트 관리 — 대화가 길어질 때

Claude 가 한 번에 볼 수 있는 양(컨텍스트 창)은 정해져 있습니다. 대화·읽은 파일·명령 출력이 모두 여기에 쌓이고, 가득 차면 앞의 내용을 요약합니다. 길어질수록 앞의 지시가 흐려지므로 정리하는 습관을 들입니다.

• /context — 지금 컨텍스트를 무엇이 얼마나 차지하는지 색깔 칸으로 봅니다.
• /compact — 지금까지의 대화를 요약해 자리를 비웁니다. 남길 것을 덧붙일 수 있습니다(예: /compact 로그인 버그 수정 위주로).
• /clear — 관계없는 다른 일을 시작할 때 컨텍스트가 빈 새 대화를 엽니다. 이전 대화는 지워지지 않고 /resume 으로 다시 열 수 있습니다.
• claude -c 는 이 폴더의 마지막 대화를 이어 가고, claude -r 이나 /resume 은 지난 대화를 골라 이어 갑니다.
• Esc 두 번(또는 /rewind) — 체크포인트 목록에서 앞 시점을 골라 대화·코드를 되돌립니다. Bash 로 지우거나 옮긴 파일은 되돌리지 못하므로 Git 커밋을 대신하지는 않습니다.

한 대화에는 한 가지 일. 일이 바뀌면 /clear 로 새로 시작하는 것이 가장 쉬운 정리입니다.

컨텍스트 아끼기 — 클로드 코드를 444k 에서 자동 요약하게 설정(SONUB 기준)

잘 부탁하는 법 — 어디·무엇·어떻게 확인

• 막연한 부탁: "로그인 고쳐 줘"
• 또렷한 부탁: "@app/Http/Controllers/LoginController.php 에서 비밀번호가 틀리면 500 오류가 나. 422 와 오류 문구를 돌려주게 고치고, tests/Feature/LoginTest.php 에 테스트를 더해 통과하는 것까지 확인해 줘."

• @ 를 입력하면 파일을 골라 부탁에 붙일 수 있습니다(@src/login.ts).
• 오류 화면·디자인 시안은 스크린샷을 붙여 넣거나 끌어다 놓습니다.
• 큰 일은 먼저 /plan(또는 Shift+Tab)으로 계획 모드에 들어갑니다. Claude 는 코드를 살펴보고 계획을 쓰며, 내가 승인하기 전에는 파일을 고치지 않습니다.
• 어려운 문제는 /model 에서 모델과 노력 수준(effort)을 높이거나, 부탁에 ultrathink 를 넣어 그 차례만 더 깊이 생각하게 합니다.
• /goal <끝나는 기준> — 다음 부탁 없이도 그 기준을 채울 때까지 Claude 가 차례를 이어 가며 일합니다(예: /goal tests/ 의 테스트가 모두 통과한다, or stop after 20 turns). /goal 만 치면 상태를 보고, /goal clear 로 지웁니다.

모범 사례 — Anthropic 이 권하는 Claude Code 사용법

줄이면 — Claude 가 스스로 확인할 방법을 주고, 어려운 일은 먼저 계획하고, 구체적으로 부탁하고, CLAUDE.md 는 짧게, 관계없는 새 일로 넘어갈 때는 /clear 를 씁니다 — 이어지는 후속 작업이면 지금 컨텍스트를 그대로 둡니다. 두 공식 안내의 좋은 습관 여섯과 Claude Code·Codex 명령은 툴 추천 사용법에 있습니다.

• 좋은 습관 여섯 — 툴 마스터

흔한 실수 — 그리고 고치는 법

공식 안내는 실패 패턴 다섯을 경고합니다 — 잡탕 세션, 고치고 또 고치기, 너무 긴 CLAUDE.md, 확인 없이 믿기, 끝없는 조사. 두 안내의 흔한 실수 열 가지와 고치는 법은 툴 추천 사용법에 있습니다.

• 흔한 실수 열 가지 — 툴 마스터

중급 연습 — 내 프로젝트에서 해 보기

1. 내 프로젝트의 루트(root) 폴더에 AGENTS.md 파일을 만들어 테스트 명령과 규칙 세 가지를 적고, 프로젝트 안에 CLAUDE.md 가 없는지 확인합니다.
2. /memory 를 열어 AGENTS.md 와 ~/.claude/CLAUDE.md 가 읽혔는지 확인합니다.
3. .claude/settings.json 에 테스트 명령 하나를 allow 로, .env 를 deny 로 넣고 /permissions 로 확인합니다.
4. 작은 기능 하나를 계획 모드로 부탁하고, 계획을 읽고 고친 뒤 승인합니다.
5. /context 로 차지한 양을 보고, /compact 로 줄인 뒤 다시 봅니다.

다섯 가지를 모두 해 봤다면, 마지막으로 관계없는 새 일로 넘어갈 준비가 되었을 때 /clear 를 쓰고 [고급] 탭으로 넘어가세요.

공식 문서

• Use Claude Code with Chrome
• Memory — CLAUDE.md · AGENTS.md
• Permissions
• Settings
• Checkpointing
• Model configuration — auto-compact window
• Best practices
• Best practices — common failure patterns

2026-10-19 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.

에이전트 스킬 — 반복하는 일을 가르치기

스킬은 SKILL.md 가 든 폴더입니다. Claude 는 평소에는 스킬의 이름과 설명만 알고 있다가, 일이 그 설명에 맞으면 본문을 읽어 따릅니다. 그래서 스킬을 많이 둬도 자리를 거의 차지하지 않습니다. 예전의 사용자 명령(.claude/commands/)도 이제 스킬로 합쳐졌습니다.

• .claude/skills/<이름>/SKILL.md 는 이 프로젝트, ~/.claude/skills/<이름>/SKILL.md 는 내 모든 프로젝트에서 씁니다.
• description 에 무엇을 하고 언제 쓰는지 분명히 적어야 Claude 가 알아서 고릅니다.
• /<스킬 이름> 으로 직접 부를 수도 있습니다. 새 스킬을 만들기 전에 /skills 로 이미 쓰는 이름을 확인하세요 — 다른 곳의 스킬과 이름이 같으면 /<이름> 으로는 그중 하나만 실행됩니다(이름 규칙은 아래 두 단락).
• 스크립트·참고 문서는 같은 폴더에 두고 SKILL.md 에서 가리킵니다. SKILL.md 는 500줄 아래로 짧게 둡니다.

---
name: release-notes
description: Write release notes from the git log. Use when the user asks for release notes, a changelog or "what changed since the last tag".
---

# Release notes

1. Find the last tag: `git describe --tags --abbrev=0`
2. Read the commits since then: `git log <tag>..HEAD --oneline`
3. Group them under Added / Fixed / Changed.
4. Write plain sentences a user can understand. Skip internal refactors.

• 에이전트 스킬 알아보기 — 만들기·설치·SONUB 스킬

스킬은 열린 표준 — 하지만 클로드 코드는 자기 방식으로 동작

스킬은 Claude 를 만든 Anthropic 이 처음 만들어 무료로 공개했고, 지금은 agentskills.io 에서 Agent Skills 라는 범용 열린 표준으로 관리합니다. Codex·Cursor·Gemini CLI·GitHub Copilot 등 많은 AI 도구가 같은 SKILL.md 폴더를 읽습니다.

하지만 주의하세요. 표준은 스킬 폴더 안에 무엇을 넣는지만 정하고, 스킬을 어디서 찾는지·이름이 겹치면 무엇을 쓰는지는 도구마다 다릅니다. 클로드 코드는 agentskills.io 가 권하는 방식과 다르게 동작하므로, 다른 도구에서 잘 되던 스킬이 클로드 코드에서는 다르게 동작할 수 있습니다.

• 폴더: agentskills.io 는 여러 도구가 함께 쓰는 .agents/skills/ 를 권하지만, 클로드 코드는 .claude/skills/(프로젝트)와 ~/.claude/skills/(개인)를 읽습니다. .agents/skills/ 는 읽지 않습니다.
• 이름이 겹칠 때: 표준의 일반 규칙은 프로젝트 스킬이 개인 스킬을 이기지만, 클로드 코드는 반대입니다 — 엔터프라이즈 > 개인(~/.claude/skills/) > 프로젝트 순이라 개인 스킬이 실행됩니다.
• 상위·하위 폴더: 표준은 정하지 않습니다. 클로드 코드는 시작한 폴더와 그 위로 git 저장소 루트까지를 읽고, 하위 폴더는 그곳에서 일할 때 읽습니다(다음 단락).
• frontmatter: 표준 필드는 name·description·license·compatibility·metadata·allowed-tools 여섯 개입니다. 클로드 코드는 disable-model-invocation·context: fork·paths 같은 필드를 더했는데, 다른 도구는 이를 무시하고 claude.ai 업로드·Skills API 는 오류로 멈춥니다.

다른 AI 도구와 함께 쓸 스킬은 frontmatter 를 표준 여섯 필드로만 쓰세요. 그러면 클로드 코드와 다른 도구에서 고치지 않고 그대로 읽힙니다.

클로드 코드가 스킬을 찾는 곳 — 지금 폴더와 상위 폴더를 함께

클로드 코드는 claude 를 시작한 폴더와, 그 위로 git 저장소 루트까지 모든 상위 폴더의 .claude/skills/ 를 읽어 함께 씁니다 — apps/web/ 에서 시작해도 루트의 스킬이 함께 잡힙니다(git worktree 에서는 worktree 루트까지만 올라갑니다). 저장소 루트보다 위 폴더의 .claude/skills/ 는 읽지 않으므로, 여러 프로젝트에 공통으로 쓸 스킬은 ~/.claude/skills/ 에 두세요.

• 시작한 폴더보다 아래(하위) 폴더의 스킬은 처음엔 읽지 않습니다. Claude 가 그 폴더의 파일을 처음 읽거나 고칠 때 읽혀 세션이 끝날 때까지 남고, 그 전에는 / 메뉴에도 없습니다. 미리 읽으려면 /add-dir 로 그 폴더를 더합니다.
• 루트와 apps/web/ 양쪽에 deploy 스킬이 있으면 둘 다 남습니다. /deploy 는 루트의 스킬, /apps/web:deploy 는 apps/web/ 의 스킬을 실행합니다. 클로드 코드는 Claude 에게 두 스킬을 모두 보여 주면서 작업 중인 파일이 있는 폴더의 스킬을 쓰라는 지시를 함께 붙이므로, apps/web/ 에서 하는 일에는 apps/web/ 의 스킬이 쓰입니다(공식 문서: Skills — 이름이 같은 스킬).
• 플러그인 스킬은 /<플러그인 이름>:<스킬 이름> 으로 따로 구분되므로 내 스킬과 겹치지 않습니다.

~/projects/                    ← above the repository root
├── .claude/skills/            ← not loaded (put shared skills in ~/.claude/skills/)
└── repo/                      ← git repository root
    ├── .claude/skills/        ← loaded
    └── apps/web/              ← run claude here
        ├── .claude/skills/    ← loaded (used together with the root)
        └── src/
            └── .claude/skills/  ← not at start — loads when Claude first reads or edits a file in src/

repo/
├── .claude/skills/deploy/SKILL.md            → /deploy
└── apps/web/.claude/skills/deploy/SKILL.md   → /apps/web:deploy

지금 어떤 스킬이 읽혔는지는 /skills 로 봅니다. 상위·하위에 스킬을 많이 쌓으면 자주 안 쓰는 스킬부터 설명이 잘리므로, 가끔 /skill-doctor 로 점검하세요.

서브 에이전트 — 일을 나눠 맡기기

서브 에이전트는 자기만의 컨텍스트 창과 지시·도구를 가진 도우미입니다. 다시 볼 일 없는 검색 결과·로그·파일 내용으로 대화를 가득 채울 곁가지 일 — 큰 조사, 코드 검토, 테스트 실행 — 을 맡기세요. 그 안에서 파일을 아무리 많이 읽어도 요약만 돌아오므로, 메인 대화는 짧게 내 일에만 집중합니다. 다루기도 쉬워집니다: 쓸 수 있는 도구를 제한하고(읽기만 하는 검토자), 더 빠르고 싼 모델로 돌리고, 매번 같은 지시로 일하게 할 수 있습니다. 같은 종류의 도우미를 자주 부른다면 하나 만들어 두세요.

• .claude/agents/<이름>.md 는 프로젝트(커밋해 팀과 나눔), ~/.claude/agents/ 는 나만 씁니다. 꼭 필요한 항목은 name 과 description 뿐입니다.
• tools 로 쓸 수 있는 도구를 줄이면 안전합니다 — 검토 담당은 읽기만 하게 둡니다.
• 시작되는 길은 둘입니다. ① 프롬프트에서 직접 부탁 — 이름을 말하거나("code-reviewer 서브 에이전트로 이 변경을 검토해 줘") @ 를 쳐서 고르면 그 서브 에이전트가 확실히 실행됩니다. ② Claude 가 알아서 맡김 — 내 부탁을 서브 에이전트 파일의 description 과 비교해 정하므로, description 에 무엇을 하고 언제 쓰는지 적으세요. "use proactively"를 넣으면 더 적극적으로 맡깁니다.
• 새 서브 에이전트는 Claude 에게 만들어 달라고 하거나 위 폴더에 파일을 직접 씁니다. 처음부터 들어 있는 Explore·Plan 도 있습니다.

---
name: code-reviewer
description: Reviews code changes for bugs, security problems and missing tests. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a careful senior reviewer.
Run `git diff` to see the changes, then report:
1. Bugs (with file and line)
2. Security problems
3. Missing tests
Do not edit files.

훅 — 정해진 때 반드시 실행되는 명령

CLAUDE.md 는 부탁이라 가끔 잊힐 수 있지만, 훅은 클로드 코드가 정해진 순간마다 반드시 실행하는 쉘 명령입니다. 파일을 고친 뒤 포매터 돌리기, 위험한 명령이나 비밀 파일 편집 막기, 일이 끝나면 알림 받기에 씁니다.

• PreToolUse — 도구를 쓰기 전(막을 수 있음), PostToolUse — 도구를 쓴 뒤
• UserPromptSubmit — 부탁을 보낼 때, Stop — Claude 가 답을 마칠 때, SessionStart — 세션을 시작할 때, Notification — 내 확인이 필요할 때
• matcher 로 어느 도구에 걸지 고릅니다(예: Edit|Write, Bash).
• 종료 코드 2의 효과는 이벤트마다 다릅니다. PreToolUse 에서는 동작이 막히고 stderr 에 쓴 이유가 Claude 에게 전달됩니다. PostToolUse 에서는 도구가 이미 실행된 뒤라 Claude 가 그 이유를 피드백으로 받을 뿐입니다.
• /hooks 로 지금 걸린 훅을 봅니다. 아래 예는 Claude 가 고치거나 쓴 파일마다 Prettier 를 돌립니다: jq 가 훅 입력에서 파일 경로를 꺼내고 npx prettier --write 가 그 파일을 정리하므로, jq 와 Node.js(npx)가 있어야 합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

훅은 내 컴퓨터에서 내 권한으로 실행됩니다. 남이 준 훅은 명령을 읽고 이해한 뒤에만 넣으세요.

MCP — 바깥 도구와 잇기

MCP(Model Context Protocol)는 AI 도구가 바깥 서비스(이슈 관리·데이터베이스·브라우저·문서 도구)를 쓰게 하는 열린 표준입니다. MCP 서버를 하나 더하면 그 서버가 주는 도구를 Claude 가 쓸 수 있습니다.

• claude mcp add --transport http <이름> <주소> — 인터넷에 있는 원격 서버를 더합니다.
• claude mcp add <이름> -- <명령> — 내 컴퓨터에서 실행하는 서버(stdio)를 더합니다. -- 뒤는 그대로 서버에 넘어갑니다.
• --scope project 로 더하면 저장소 맨 위의 .mcp.json 에 저장돼 팀이 함께 씁니다(처음 쓸 때 승인을 묻습니다).
• /mcp 로 연결 상태를 보고 로그인(OAuth)합니다. claude mcp list 로 목록을 봅니다.

# A remote server (HTTP)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# A server that runs on your computer (stdio)
claude mcp add playwright -- npx @playwright/mcp@latest

# Share it with the team — saved in .mcp.json
claude mcp add --scope project playwright -- npx @playwright/mcp@latest

claude mcp list

• MCP 전체 안내 — MCP 란 무엇인지, 서버 연결과 활용

헤드리스 — 대화 화면 없이 스크립트로

claude -p "…" 는 대화 화면 없이 한 번 실행하고 결과를 출력한 뒤 끝납니다. 쉘 스크립트·cron·CI 에서 Claude 를 부품처럼 씁니다.

• 파이프로 입력을 넘깁니다(cat error.log | claude -p "…").
• --output-format json 은 결과·세션 id·비용을 JSON 으로, stream-json 은 진행을 줄마다 내보냅니다.
• --allowedTools 로 이번 실행에 허락할 도구를, --max-turns 로 최대 차례 수를 정합니다.
• claude -p --continue 로 앞 실행을 이어 가거나, --resume <세션 id> 로 그 세션을 이어 갑니다.

# One question, one answer
claude -p "Explain what src/auth.ts does in 5 lines"

# Pipe input in
cat build-error.log | claude -p "Find the cause and suggest a fix"

# JSON output for scripts (result, session_id, total_cost_usd)
claude -p "List the TODO comments in src/" --output-format json

# Limit what it may do and how long it runs
claude -p "Run the tests and fix failures" \
  --allowedTools "Read,Edit,Bash(npm test *)" --max-turns 10

스크립트에서는 --bare 를 붙이면 CLAUDE.md·훅·플러그인·MCP 를 읽지 않고 빠르게 시작합니다(공식 문서는 앞으로 -p 의 기본이 된다고 안내합니다). 프로젝트 지시가 필요하면 빼세요.

고급 연습

1. 자주 하는 일 하나(예: 릴리스 노트, 커밋 메시지)를 .claude/skills/ 에 스킬로 만들고 /스킬이름 으로 불러 봅니다.
2. 읽기만 하는 code-reviewer 서브 에이전트를 만들어 지금 변경을 검토하게 합니다.
3. PostToolUse 훅으로 파일을 고칠 때마다 포매터나 린터가 돌게 합니다.
4. MCP 서버 하나를 더하고 /mcp 로 연결을 확인합니다.
5. claude -p 로 오류 로그를 요약하는 한 줄짜리 쉘 스크립트를 만듭니다.

다섯 가지를 모두 해 봤다면 [마스터] 탭으로 넘어가세요.

공식 문서

• Skills
• Subagents
• Hooks
• MCP
• Headless (-p)

2026-10-19 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.

Git worktree — 여러 세션을 동시에

한 폴더에서 두 세션이 같은 파일을 고치면 서로 덮어씁니다. git worktree 는 같은 저장소를 다른 폴더에 다른 브랜치로 꺼내 주므로, 폴더마다 Claude 를 하나씩 띄워 여러 일을 동시에 진행할 수 있습니다.

• claude --worktree <이름>(-w)은 .claude/worktrees/<이름>/ 에 worktree 와 브랜치를 만들고 그 안에서 시작합니다. 바뀐 것 없이 끝내면 저절로 지웁니다.
• .claude/worktrees/ 는 .gitignore 에 넣고, .env 처럼 Git 이 무시하는 파일을 새 worktree 로 복사하려면 .worktreeinclude 에 적습니다.
• worktree 마다 의존성 설치(npm install 등)가 따로 필요할 수 있습니다.
• 서로 다른 파일을 고치는 독립된 일끼리 나누고, 끝나면 PR 로 합칩니다.

# Claude Code makes the worktree for you (.claude/worktrees/<name>/)
claude --worktree feature-login
claude -w bugfix-cart

# Or with plain git
git worktree add ../myapp-search -b feature-search
cd ../myapp-search && claude

git worktree list
git worktree remove ../myapp-search

GitHub Actions — 이슈·PR 에서 @claude

클로드 코드 GitHub Actions 를 설치하면 이슈나 PR 댓글에 @claude 라고 쓰는 것만으로 Claude 가 저장소를 읽고, 고쳐서 PR 을 올리거나 리뷰를 남깁니다. GitHub 의 러너에서 돌므로 내 컴퓨터가 꺼져 있어도 됩니다.

1. 터미널의 클로드 코드에서 /install-github-app 을 실행합니다. GitHub 앱 설치와 비밀값(ANTHROPIC_API_KEY 또는 claude setup-token 으로 만든 토큰) 등록을 안내합니다(gh 와 저장소 관리자 권한이 필요).
2. .github/workflows/ 에 위와 같은 워크플로 파일이 생깁니다.
3. 이슈나 PR 에 "@claude 이 버그 고쳐 줘" 처럼 댓글을 답니다.
4. Claude 가 올린 PR 은 사람이 검토하고 테스트한 뒤 합칩니다.

name: Claude
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Actions 의 Claude 도 저장소의 지시 파일(AGENTS.md, 또는 CLAUDE.md)을 읽습니다. 규칙을 지키게 하는 가장 쉬운 방법은 지시 파일을 잘 써 두는 것입니다.

플러그인·마켓플레이스 — 설정을 묶어 나누기

스킬·서브 에이전트·훅·MCP 서버를 하나로 묶은 것이 플러그인입니다. 마켓플레이스는 플러그인 목록이 든 저장소입니다. 팀이 같은 도구 상자를 명령 하나로 설치하고 함께 업데이트합니다.

• /plugin — 플러그인을 찾아 설치하고 켜고 끕니다.
• /plugin marketplace add <owner/repo> 로 마켓플레이스를 더하고, /plugin install <플러그인>@<마켓플레이스> 로 설치합니다.
• 플러그인 폴더의 .claude-plugin/ 에는 plugin.json 만 둡니다. skills/·agents/·hooks/ 는 폴더 맨 위에 둡니다. claude --plugin-dir ./my-plugin 으로 시험합니다.
• 스킬만 나눈다면 npx skills add 로도 됩니다 — SONUB 스킬이 이 방식입니다.

my-plugin/
├── .claude-plugin/
│   └── plugin.json        ← name, description, version
├── skills/
│   └── release-notes/SKILL.md
├── agents/
│   └── code-reviewer.md
├── hooks/
│   └── hooks.json
└── .mcp.json

/plugin marketplace add my-team/claude-plugins
/plugin install my-plugin@claude-plugins
/plugin

• SONUB 에이전트 스킬 설치하기

팀 설정 운영 — 규칙이 쌓여도 흐려지지 않게

여러 사람과 여러 AI 가 같은 저장소에서 일하면 설정이 금방 쌓입니다. 무엇을 함께 쓰고 무엇을 나만 쓸지, 무엇을 부탁하고 무엇을 강제할지 나눠 둡니다.

• 함께 씀(커밋): AGENTS.md·.claude/settings.json·.claude/skills/·.claude/agents/·.mcp.json(CLAUDE.md 를 쓴다면 모든 폴더의 CLAUDE.md 도)
• 나만 씀(커밋 안 함): .claude/settings.local.json·~/.claude/ — 개인 지시는 ~/.claude/CLAUDE.md 에 둡니다(프로젝트의 CLAUDE.local.md 는 AGENTS.md 를 막으니 두지 않습니다)
• 지시 파일은 짧게 유지합니다. 같은 실수가 되풀이될 때만 규칙을 더하고, 틀리거나 쓸모없어진 규칙은 지웁니다.
• 꼭 지켜야 하는 것은 지시가 아니라 권한(deny)과 훅으로 강제합니다.
• 회사 전체의 규칙은 관리자 설정(managed settings)으로 내려보냅니다 — 다른 설정이 덮어쓸 수 없습니다.

긴 작업 — 스스로 확인하며 끝까지

마스터는 Claude 에게 "끝난 기준"을 주고 그 기준을 스스로 확인하게 합니다. 테스트·린트·빌드처럼 기계가 판정할 수 있는 기준이 있으면 사람이 지켜보지 않아도 오래 일할 수 있습니다.

• 끝난 기준을 명령으로 줍니다 — "npm test 와 npm run lint 가 모두 통과할 때까지".
• 한 일·남은 일을 PROGRESS.md 같은 파일에 적게 하면 컨텍스트가 요약되거나 세션이 바뀌어도 이어 갈 수 있습니다.
• 그 자체로 동작하는 완성된 단계마다 커밋하게 해, 그 단계만 따로 되돌릴 수 있게 합니다. 끝나지 않은 한 가지 변경을 여러 커밋에 나눠 함께 되돌려야 하게 만들지 않습니다.
• 같은 문제를 세 번 시도해도 풀리지 않으면 Claude 를 멈추게 하고, 다시 시도하기 전에 무엇을 해 봤는지·왜 실패했는지·무엇이 막고 있는지 적게 합니다. 헛도는 반복을 막습니다.
• 다 끝나면 다른 AI(예: codex review)나 서브 에이전트에게 교차 검토를 맡깁니다.

• Goal 과 Ralph Loop: 정말 끝날 때까지 에이전트가 계속 일하게 하기
• VPS 와 tmux: 에이전트가 하루 24시간 일하게 하기

마스터 연습 — 여러 세션과 자동화

1. git worktree add ../my-project-b -b try-b 로 작업 폴더를 하나 더 만들고, 두 폴더에서 claude 를 하나씩 실행해 서로 다른 작은 일을 맡깁니다. 두 폴더의 git status 가 따로 바뀌면 성공입니다.
2. git diff | claude -p "List bugs in this diff" 로 한 줄 검토 명령을 만듭니다. 일부러 버그를 하나 넣고 그것을 찾는지 봅니다.
3. 팀 규칙 하나(예: 커밋 전에 테스트 실행)를 AGENTS.md 에 적고 훅으로도 강제합니다. 일부러 규칙을 어겨 훅이 막는지 확인합니다.
4. 내 스킬 하나와 서브 에이전트 하나를 위 플러그인 단락대로 플러그인으로 묶어 설치하고, 다른 프로젝트에서도 불러지는지 확인합니다.
5. 끝난 기준을 명령으로 적어(예: npm test 통과) 긴 일을 맡기고, 끝났다고 하면 diff 와 테스트 결과를 직접 확인합니다.

막히면: worktree 는 git worktree list 로 보고 git worktree remove 로 지웁니다. 훅이 너무 막으면 settings.json 에서 잠시 빼고 /hooks 로 확인하세요. 다섯 가지를 모두 해 봤다면 아래 체크리스트로 스스로 점검하세요.

마스터 체크리스트 — 기초부터 마스터까지 전체 과정

• 기초 — Git 프로젝트 폴더에서 claude 를 실행하고, 먼저 /plan 으로 계획하고, 이 일에 해당하는 것만 승인하고, 커밋 전에 git status·git diff 로 확인한다
• 중급 — 웹 일에는 브라우저 연결을 켜 두어 Claude 가 바꾼 화면을 직접 열어 확인한다
• 중급 — 프로젝트에는 AGENTS.md 만 두어 여러 AI 가 같은 지시로 일한다. CLAUDE.md 를 쓴다면 AGENTS.md 가 있는 모든 폴더에 CLAUDE.md 를 두고 그 안에 @AGENTS.md 한 줄로 참조한다
• 중급 — 권한 규칙으로 안전한 명령은 묻지 않고, 비밀 파일은 deny 로 막았다
• 중급 — /context 로 컨텍스트를 보고 /compact 로 줄이며, 관계없는 새 일로 넘어갈 때 /clear 를 쓴다. 부탁마다 어디서·무엇을·어떻게 확인할지 적는다
• 고급 — 반복하는 일은 스킬(먼저 /skills 로 쓰는 이름 확인), 큰 조사·검토는 서브 에이전트에게 맡긴다
• 고급 — 꼭 지켜야 하는 것은 훅과 권한으로 강제하고, 바깥 도구는 믿을 수 있는 MCP 서버로 잇고, 한 번에 끝나는 일은 claude -p 로 스크립트에서 돌린다
• 마스터 — 병렬 작업은 worktree 로 하고, 이슈·PR 일은 GitHub Actions 의 @claude 에게 맡긴다
• 마스터 — 팀의 스킬·서브 에이전트·훅·MCP 서버를 플러그인 하나로 나눠 쓰고, 함께 쓰는 설정과 나만 쓰는 설정을 나눈다
• 마스터 — 끝난 기준을 명령으로 주고, 동작하는 완성 단계마다 커밋하고, 결과는 diff 와 테스트로 직접 확인한다

도구는 자주 바뀝니다. 새 기능은 claude-skill 스킬의 /claude-skill update 나 공식 문서의 변경 기록(CHANGELOG)으로 따라잡으세요.

공식 문서

• Worktrees
• GitHub Actions
• Plugins
• Settings

2026-10-19 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.