Claude Code — 터미널에서 일하는 Anthropic 의 코딩 에이전트

무엇인가요

Claude Code 는 Anthropic 이 만든 코딩 에이전트입니다. 터미널에서 실행되고, VS Code·JetBrains 같은 코드 편집기, Claude 데스크톱 앱, 웹에서도 쓸 수 있습니다.

바꾸기 전에 계획을 보여 줄 수 있고, 파일을 고치거나 명령을 실행하기 전에 허락을 묻습니다. 무엇을 해도 되는지는 내가 정하고(권한), 프로젝트의 규칙은 CLAUDE.md 에 적어 두면 세션마다 읽습니다.

필요한 것

• 계정: Claude Pro·Max·Team·Enterprise 요금제나 Console(API) 계정. 무료 claude.ai 요금제에는 Claude Code 가 들어 있지 않습니다.
• 컴퓨터: 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. 프로젝트 폴더로 가서 claude 를 실행합니다. 처음에는 브라우저가 열려 로그인합니다.
2. "이 프로젝트에는 무엇이 있어?" 하고 물어 프로젝트를 읽게 합니다.
3. /init 으로 CLAUDE.md 를 만들고, 테스트 명령과 지킬 규칙을 더합니다.
4. Shift+Tab 으로 계획 모드로 바꾸고 변경을 부탁합니다. 계획을 읽고 고친 뒤 승인합니다.
5. git diff 로 바뀐 것을 읽고, 테스트를 직접 돌려 본 뒤 커밋합니다.

SONUB 에서 더 배우기

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

공식 문서

• Claude Code — Overview
• Claude Code — Advanced setup
• Claude Code — Quickstart
• Claude Code — Common workflows

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

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

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

• ~/.claude/CLAUDE.md — 내 모든 프로젝트에 쓰는 개인 지시
• ./CLAUDE.md 또는 ./.claude/CLAUDE.md — 팀이 함께 쓰는 프로젝트 지시(Git 에 커밋)
• ./CLAUDE.local.md — 이 프로젝트에서 나만 쓰는 지시(.gitignore 에 넣음). 단, 하나라도 있으면 AGENTS.md 가 읽히지 않습니다
• 하위 폴더의 CLAUDE.md — 그 폴더의 파일을 읽거나 고칠 때 더 읽음. .claude/rules/ 의 규칙 파일은 paths 로 특정 파일에만 걸 수 있음

# 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 가 같은 지시로 일하게

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

Claude Code 도 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 는 그 폴더의 파일을 Read 도구로 열 때만 읽습니다. 그 폴더에 새 파일을 바로 만들 때는 아직 규칙을 모를 수 있습니다. 하위 폴더의 CLAUDE.md 는 읽기·쓰기·편집 모두에서 읽힙니다.
• 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 가 하나라도 있으면 Claude Code 는 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. Claude Code 에서 /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

알아 둘 점과 다른 방법. ① AGENTS.md 만 쓸 때 하위 폴더의 AGENTS.md 는 그 폴더의 파일을 Read 로 열 때 읽힙니다. ② /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 중급

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

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

• 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 — 관계없는 다른 일을 시작할 때 대화를 새로 시작합니다.
• claude -c 는 이 폴더의 마지막 대화를 이어 가고, claude -r 이나 /resume 은 지난 대화를 골라 이어 갑니다.
• Esc 두 번(또는 /rewind) — 체크포인트 목록에서 앞 시점을 골라 대화·코드를 되돌립니다. Bash 로 지우거나 옮긴 파일은 되돌리지 못하므로 Git 커밋을 대신하지는 않습니다.

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

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

좋은 부탁에는 세 가지가 들어 있습니다: 어디(파일·폴더), 무엇(바라는 동작), 어떻게 확인할지(테스트·명령·화면). 셋이 분명할수록 Claude 가 덜 헤매고 결과를 스스로 확인합니다.

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

• @ 를 입력하면 파일을 골라 부탁에 붙일 수 있습니다(@src/login.ts).
• 오류 화면·디자인 시안은 스크린샷을 붙여 넣거나 끌어다 놓습니다.
• 큰 일은 "먼저 읽고 계획만 보여 줘, 아직 고치지 마"로 시작하거나 /plan 으로 계획 모드에 들어갑니다.
• 어려운 문제는 /model 에서 모델과 노력 수준(effort)을 높이거나, 부탁에 ultrathink 를 넣어 그 차례만 더 깊이 생각하게 합니다.

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

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

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

공식 문서

• Memory — CLAUDE.md · AGENTS.md
• Permissions
• Settings
• Checkpointing

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

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

스킬은 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 Code 는 자기 방식으로 동작

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

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

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

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

Claude Code 가 스킬을 찾는 곳 — 지금 폴더와 상위 폴더를 함께

지금 폴더에 .claude/skills 폴더가 있고 상위 폴더에도 같은 폴더가 있으면, Claude Code 는 지금 폴더와 상위 폴더의 스킬을 모두 같이 씁니다. 다만 위로는 git 저장소 루트까지만 올라갑니다.

• claude 를 시작한 폴더와, 그 위로 저장소 루트까지 모든 상위 폴더의 .claude/skills/ 를 읽습니다. apps/web/ 에서 시작해도 루트의 스킬이 함께 잡힙니다.
• 저장소 루트보다 위 폴더의 .claude/skills/ 는 읽지 않습니다. 여러 프로젝트에 공통으로 쓸 스킬은 ~/.claude/skills/ 에 두세요. git worktree 에서는 worktree 루트까지만 올라갑니다.
• 시작한 폴더보다 아래(하위) 폴더의 스킬은 처음엔 읽지 않습니다. Claude 가 그 폴더의 파일을 처음 읽거나 고칠 때 읽혀 세션이 끝날 때까지 남고, 그 전에는 / 메뉴에도 없습니다. 미리 읽으려면 /add-dir 로 그 폴더를 더합니다.
• 루트와 apps/web/ 양쪽에 deploy 스킬이 있으면 둘 다 씁니다. /deploy 는 루트의 스킬, /apps/web:deploy 는 하위 폴더의 스킬을 실행하고, Claude 에게는 작업 중인 파일이 있는 폴더의 스킬을 쓰라는 지시가 붙습니다.
• 플러그인 스킬은 /<플러그인 이름>:<스킬 이름> 으로 따로 구분되므로 내 스킬과 겹치지 않습니다.

~/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 서브 에이전트로 이 변경을 검토해 줘" 처럼 부르거나, description 이 맞으면 Claude 가 알아서 맡깁니다.
• 새 서브 에이전트는 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 는 부탁이라 가끔 잊힐 수 있지만, 훅은 Claude Code 가 정해진 순간마다 반드시 실행하는 쉘 명령입니다. 파일을 고친 뒤 포매터 돌리기, 위험한 명령이나 비밀 파일 편집 막기, 일이 끝나면 알림 받기에 씁니다.

• PreToolUse — 도구를 쓰기 전(막을 수 있음), PostToolUse — 도구를 쓴 뒤
• UserPromptSubmit — 부탁을 보낼 때, Stop — Claude 가 답을 마칠 때, SessionStart — 세션을 시작할 때, Notification — 내 확인이 필요할 때
• matcher 로 어느 도구에 걸지 고릅니다(예: Edit|Write, Bash).
• 훅 명령이 종료 코드 2 로 끝나면 그 동작을 막고, stderr 에 쓴 이유를 Claude 에게 알려 줍니다.
• /hooks 로 지금 걸린 훅을 봅니다. 위 예는 파일을 고칠 때마다 Prettier 로 정리합니다(jq 가 필요).

{
  "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 서버만 더하세요. 바깥 글을 읽어 오는 서버는 그 글에 숨은 지시(프롬프트 주입)를 함께 들여올 수 있습니다.

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

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-18 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.

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

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

1. 터미널의 Claude Code 에서 /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 같은 파일에 적게 하면 컨텍스트가 요약되거나 세션이 바뀌어도 이어 갈 수 있습니다.
• 작은 단계마다 커밋하게 해 언제든 되돌릴 수 있게 합니다.
• 세 번 시도해도 안 되면 멈추고 이유를 적게 해, 헛도는 반복을 막습니다.
• 다 끝나면 다른 AI(예: codex review)나 서브 에이전트에게 교차 검토를 맡깁니다.

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

마스터 체크리스트

• 프로젝트에는 AGENTS.md 만 — 여러 AI 가 같은 지시로 일한다(CLAUDE.md 를 쓴다면 모든 폴더에 두고 @AGENTS.md 한 줄)
• 권한 규칙으로 안전한 명령은 묻지 않고, 비밀 파일은 deny 로 막았다
• 반복하는 일은 스킬, 큰 조사·검토는 서브 에이전트에게 맡긴다
• 꼭 지켜야 하는 것은 훅으로 강제한다
• 병렬 작업은 worktree 로, 반복 작업은 claude -p 와 GitHub Actions 로 자동화한다
• 끝난 기준을 명령으로 주고, 결과는 diff 와 테스트로 직접 확인한다

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

공식 문서

• Worktrees
• GitHub Actions
• Plugins
• Settings

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