클로드 코드 — 터미널에서 일하는 Anthropic 의 에이전틱 코딩 도구
를 설치해 첫 작업을 해 보고 네 단계 탭으로 실력을 올립니다. 에 맞는 설치 을 복사해 시작해 보세요.
기초 — 설치하고 첫 작업 해 보기
처음이라면 여기부터 시작하세요. 가 무엇인지 알고, 설치하고, 첫 다섯 걸음을 따라 합니다. 다 해 봤다면 위의 [중급] 탭으로 넘어가세요.
무엇인가요
는 이 만든 ( tool)입니다. 할 일을 말로 부탁하면 파일을 읽고 코드를 고치고 을 실행하며, 그 전에 허락을 구합니다. 에서 실행되고, · 같은 코드 편집기, , 웹에서도 쓸 수 있습니다.
바꾸기 전에 계획을 보여 줄 수 있고, 파일을 고치거나 명령을 실행하기 전에 허락을 묻습니다. 무엇을 해도 되는지는 내가 정하고(), 프로젝트의 은 에 적어 두면 마다 읽습니다.
필요한 것
- 계정: Pro·Max·Team·Enterprise 요금제나 Console() 계정. 무료 claude.ai 요금제에는 클로드 코드가 들어 있지 않습니다.
- 컴퓨터: 13 이상, 10(1809) 이상, 20.04· 10 이상, 이상, 인터넷 연결.
- 일할 프로젝트 폴더 — 바뀐 것을 모두 보고 되돌릴 수 있도록 저장소면 좋습니다.
설치
macOS·· 은 첫 줄, Windows 는 줄을 실행하세요. 이렇게 설치하면 에서 스스로 최신 으로 업데이트됩니다. ·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- ( 22+)
npm install -g @anthropic-ai/claude-code
설치 확인
새 터미널 창을 여세요. 이 버전 번호를 보여 주고, 가 설치 상태를 보여 줍니다. "" 가 나오면 터미널을 다시 열고 를 확인하세요.
claude --version
claude doctor
첫 실행 — 다섯 걸음
- 터미널을 열고 <폴더> 로 프로젝트 폴더에 들어간 뒤, claude 를 입력하고 Enter 를 누릅니다(데스크톱 앱이 아니라 터미널 도구가 시작됩니다). 처음에는 가 열려 로그인합니다.
- "이 프로젝트에는 무엇이 있어?" 하고 물어 프로젝트를 읽게 합니다.
- 으로 CLAUDE.md 를 만들고, 명령과 지킬 규칙을 더합니다.
- 으로 로 바꾸고 변경을 부탁합니다. 계획을 읽고 고친 뒤 승인합니다.
- git 로 바뀐 것을 읽고, 테스트를 직접 돌려 본 뒤 합니다.
cd my-project
claude
반드시 브라우저를 연결하세요 — Claude in Chrome(browser connected)
클로드 코드에서 가장 중요한 설정 하나를 꼽으라면 브라우저 연결입니다. 을 클로드 코드와 연결해 두면, Claude 가 코드를 고친 뒤 내 에서 직접 페이지를 열고, 클릭하고, 입력하고, 를 읽어 결과를 스스로 확인합니다. 연결하지 않으면 Claude 는 화면을 보지 못한 채 "고쳤습니다"라고 말할 뿐이고 확인은 모두 내 몫이 됩니다. 웹 화면을 다루는 일이라면 시작하기 전에 반드시 연결하세요.
- Chrome 웹 에서 Claude in Chrome 확장(1.0.36 이상)을 설치하고, 클로드 코드와 같은 claude.ai 계정으로 로그인합니다. Chrome· 와 ·Arc 같은 브라우저에서 됩니다.
- 터미널에서 claude --chrome 으로 시작합니다. 처음 한 번 안내 창이 뜨면 Enter 를 누릅니다.
- /chrome 을 열어 Status: Enabled 와 Extension: Installed 가 보이는지 확인하고, Enabled by default 를 켭니다. 그러면 다음부터는 --chrome 없이도 매번 연결됩니다( 와 VS Code 가 같은 설정을 씁니다).
- VS Code 확장에서는 입력 칸에 @browser 를 쓰면 연결되고, Enabled by default 를 켜 두면 세션이 시작할 때부터 연결되어 있습니다.
claude --chrome # start with the browser connected
# inside Claude Code
/chrome # Status: Enabled · Extension: Installed
# → turn on "Enabled by default" once
@browser open localhost:3000 and check the console for errors
Pro·Max·Team·Enterprise 요금제로 /login 했을 때만 됩니다 — 나 같은 다른 제공자로는 안 되고, WSL 에서도 쓸 수 없습니다. 로그인 화면이나 를 만나면 Claude 가 멈추고 나에게 맡깁니다.
브라우저 연결 자세히 보기 — 중급의 첫 단락자주 쓰는 기능
- CLAUDE.md — 세션마다 읽는 프로젝트 지시(/init 으로 시작)
- 권한과 계획 모드 — 묻지 않고 해도 되는 일, 바꾸기 전의 계획
- — 의 폴더로 반복하는 일 가르치기
- ·· — 일을 나눠 맡기고, 정해진 때 명령을 돌리고, 바깥 도구를 잇기
- claude -p "…" — 대화 화면 없이 한 번 실행(·)
- 로 새로 시작, 로 멈추기, claude update 로 바로 업데이트
안전하게 쓰기
- 이해하지 못한 명령은 허락하지 마세요. 처음에는 엄격하게 시작해 믿을 수 있는 것만 풀어 줍니다.
- 요약이 아니라 출력을 믿으세요. "테스트 통과"라고 해도 직접 돌려 봅니다.
- 큰 요청 하나보다 작은 바퀴 여러 번이 낫습니다. 한 바퀴마다 커밋하거나 되돌립니다.
기초 연습 — 처음 한 번 해 보기
- 연습용 폴더를 만들고( hello-ai cd hello-ai) git init 으로 Git 로 만든 뒤 claude 를 실행합니다. 입력 칸이 보이면 성공입니다.
- "오늘 날짜를 보여 주는 한 쪽짜리 웹 페이지 을 만들어 줘" 하고 부탁합니다. 파일을 만들기 전에 물으면, 무엇을 할지 읽고 허락합니다.
- 만들어진 index.html 을 브라우저로 열어 날짜가 보이는지 직접 확인합니다.
- git status 로 무엇이 바뀌었는지 보고, git add . 와 git commit -m "첫 페이지" 로 저장합니다.
- "날짜 글자를 크게 해 줘" 하고 한 번 더 부탁합니다. 결과가 마음에 들지 않으면 git restore index.html 로 마지막 커밋 상태로 되돌립니다.
막히면: claude 가 시작되지 않으면 claude doctor 로 설치를 확인하고, 로그인 창이 열리지 않으면 터미널을 닫고 새로 열어 claude 를 다시 실행하세요. 다섯 가지를 모두 해 봤다면 [중급] 탭으로 넘어가세요.
SONUB 에서 더 배우기
공식 문서
- Claude Code — Overview
- Claude Code — Advanced setup
- Claude Code — Quickstart
- Claude Code — Common workflows
- Claude Code — Use Claude Code with Chrome
2026-10-19 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.
중급 — 매일 쓰는 습관: 지시 파일·권한·컨텍스트
설치하고 첫 작업을 해 봤다면 이제 매일 쓰는 습관을 들입니다. 프로젝트 지시(), 여러 가 함께 읽는 , 과 모드, 정리, 잘 부탁하는 법을 차례로 익히고 연습으로 마무리합니다. 그중 가장 먼저 할 일은 연결입니다 — 가 고친 화면을 직접 열어 확인하게 하세요.
브라우저 연결 — 고친 화면을 Claude 가 직접 열어 확인하게
웹 화면을 만드는 일에서 는 브라우저가 연결되어 있을 때 가장 잘 일합니다. 를 고치고, 를 열고, 클릭과 입력으로 흐름을 따라가고, 와 을 읽고, 틀린 곳을 다시 고치는 바퀴를 사람 없이 끝까지 돕니다. " 통과"라는 말만 믿지 않고 실제 화면에서 확인하게 하는 것 — 이것이 브라우저 연결을 반드시 써야 하는 이유입니다.
Claude 는 을 열어 일하고(마다 탭 그룹 하나로 묶습니다), 내 브라우저의 로그인 상태를 그대로 씁니다. 그래서 따로 를 잇지 않아도 이미 로그인한 관리 화면·Google Docs·Gmail 같은 에서 일할 수 있습니다. 어느 사이트에서 클릭·입력해도 되는지는 의 사이트 권한으로 정합니다.
- 실시간 — 콘솔 오류와 DOM 상태를 직접 읽고, 원인이 된 코드를 고칩니다.
- 화면 확인 — 시안대로 만들었는지, 넓은 화면과 좁은 화면에서 깨지지 않는지 열어 봅니다.
- 웹 앱 테스트 — 폼 검사·로그인·주문 같은 사용자 흐름을 끝까지 따라가 봅니다.
- 로그인된 사이트에서 일하기 — 설정 바꾸기, 폼 채우기, 의 파일 올리기, 페이지의 를 뽑아 파일로 저장하기.
- 기록 — 한 일을 로 녹화하거나 을 파일로 저장해 보고에 붙입니다.
claude --chrome
# inside Claude Code
/chrome # Status: Enabled · Extension: Installed · "Enabled by default"
/mcp # claude-in-chrome → View tools
I changed the login form validation. Open localhost:3000/login,
submit it with an empty email, and check that the error message
appears and the console has no errors. Fix anything that is wrong.
@browser go to localhost:3000 and check the console for errors
가 안 들으면 /chrome 에서 Reconnect extension 을 고릅니다. 확장과 클로드 코드가 서로 다른 계정이나 조직으로 로그인되어 있으면 "Browser extension is not connected" 가 납니다(/status 로 조직 확인). 이 뜨면 브라우저 이 막히니 직접 닫고 계속하라고 말합니다. 브라우저 도구가 늘 실려 컨텍스트를 조금 더 쓰지만, 웹 일을 한다면 켜 두는 편이 훨씬 낫습니다.
모델과 생각 수준(effort) — 무엇을 쓸까 (추천: Opus 5.5, High)
2026년 11월 기준 개발에는 Opus 5.5 를 High 수준으로 쓰세요. 기본 수준이 medium 이므로 아래처럼 설정하거나 / opus 와 /effort high 를 실행합니다. 모든 모델과 생각 수준, 언제 낮추고 올릴지는 툴 마스터의 툴 추천 사용법에 있습니다.
{
"model": "opus",
"effortLevel": "high"
}
claude --model opus --effort high
# inside Claude Code
/model opus
/effort high
CLAUDE.md — 세션마다 읽는 프로젝트 지시
CLAUDE.md 는 클로드 코드가 세션을 시작할 때마다 읽는 파일입니다. ·테스트 명령, 코드 , 하지 말아야 할 일처럼 매번 말하기 번거로운 것을 적어 둡니다. 을 실행하면 프로젝트를 읽고 첫 CLAUDE.md 를 만들어 줍니다. 여러 곳의 CLAUDE.md 는 서로 덮어쓰지 않고 모두 합쳐 읽습니다.
- ~/.claude/CLAUDE.md — 내 모든 프로젝트에 쓰는 개인 지시
- ./CLAUDE.md 또는 ./.claude/CLAUDE.md — 팀이 함께 쓰는 프로젝트 지시( 에 )
- ./CLAUDE.local.md — 이 프로젝트에서 나만 쓰는 지시( 에 넣음). 단, 하나라도 있으면 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
짧게 쓰세요(공식 문서 권장 줄 이하). 매번 읽으므로 길면 자리를 차지하고 중요한 규칙이 묻힙니다. /memory 로 지금 읽힌 지시 파일을 보고 바로 열어 고칠 수 있고, @docs/architecture.md 처럼 로 다른 파일을 불러올 수 있습니다. 여러 AI 를 함께 쓴다면 프로젝트에는 CLAUDE.md 대신 AGENTS.md 만 두는 것이 가장 좋습니다 — 바로 아래 단락을 보세요.
AGENTS.md 만 쓰기 — 여러 AI 가 같은 지시로 일하게
왜 이렇게 할까요? 한 프로젝트에서 클로드 코드와 함께 ·· 같은 다른 AI 도 쓴다면, 도구마다 지시 파일을 따로 두면 금방 내용이 서로 달라집니다. AGENTS.md 는 여러 가 함께 읽는 열린 형식입니다. 규칙을 AGENTS.md 한 곳에 적어 두면 어느 AI 로 일하든 모두 같은 지시를 따릅니다. 아래 방법은 바로 이것 — 하나의 프로젝트에서 여러 AI 가 AGENTS.md 를 통해 모두 같은 지시를 쓰게 하는 것 — 을 위한 것입니다.
클로드 코드도 AGENTS.md 를 직접 읽지만(v2.1.277 이상), CLAUDE.md 와 똑같지는 않습니다.
- 기본 설정에서는 작업 폴더나 그 위 폴더에 CLAUDE.md·./CLAUDE.md· 가 하나도 없을 때만 AGENTS.md 를 읽습니다. 개인 메모용 CLAUDE.local.md 하나만 만들어도 AGENTS.md 는 읽히지 않습니다(~/.claude/CLAUDE.md 와 .claude/rules/ 는 이 판단에 들어가지 않습니다).
- 하위 폴더의 AGENTS.md 는 그 폴더의 파일을 Read 도구로 열 때만 읽습니다. 그 폴더에 새 파일을 바로 만들 때는 아직 규칙을 모를 수 있습니다. 하위 폴더의 CLAUDE.md 는 읽기·쓰기·편집 모두에서 읽힙니다.
- AGENTS.local.md··./ 폴더 안의 파일은 읽지 않고, --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 를 두 번 읽지는 않는다고 설명합니다.
- 공통 규칙(설치·테스트 명령, 코드 규칙, 하지 말 것)을 프로젝트 맨 위의 AGENTS.md 에 적습니다. Codex 의 /init 으로 만들어도 됩니다.
- 프로젝트 안(지금 폴더·상위 폴더·하위 폴더 어디에도)에 CLAUDE.md·.claude/CLAUDE.md·CLAUDE.local.md 를 만들지 않습니다.
- 모든 프로젝트에 쓰는 내 개인 지시는 ~/.claude/CLAUDE.md 에 둡니다 — AGENTS.md 와 함께 늘 읽힙니다.
- 하위 폴더에 따로 규칙이 있으면(예: api/) 그 폴더에도 AGENTS.md 를 둡니다.
- 클로드 코드에서 /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)도 되지만 가 섞이면 @AGENTS.md 한 줄이 안전합니다.
권한과 모드 — 묻지 않고 해도 되는 일 정하기
클로드 코드는 파일을 고치거나 명령을 실행하기 전에 허락을 묻습니다. 같은 허락을 매번 누르기 번거로우면 규칙으로 정해 두고, 일의 성격에 맞게 모드를 바꿉니다.
- — 모드 바꾸기: 기본(매번 묻기) → (파일 편집은 묻지 않음) → plan(읽기만 하고 계획을 보여 줌). auto 모드에서 시작했다면 첫 번째 누름이 기본으로 바꿉니다.
- /permissions — 허락(allow)·묻기(ask)·거부(deny) 규칙과 그 규칙이 어느 파일에서 왔는지 보고 고칩니다.
- 은 팀이 함께 쓰는 규칙(커밋), .claude/settings.local.json 은 나만 쓰는 규칙, ~/.claude/settings.json 은 내 모든 프로젝트의 규칙입니다.
- 규칙은 deny → ask → allow 순서로 봅니다. 어느 곳에서든 deny 한 것은 다른 곳의 allow 로 풀 수 없으니, 같은 비밀 파일은 deny 로 막아 둡니다.
{
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)",
"Bash(git diff *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
}
}
(--dangerously-skip-permissions)는 모든 확인을 끕니다. 인터넷이 막힌 ·처럼 망가져도 괜찮은 곳에서만 쓰세요.
컨텍스트 관리 — 대화가 길어질 때
Claude 가 한 번에 볼 수 있는 양()은 정해져 있습니다. 대화·읽은 파일·명령 출력이 모두 여기에 쌓이고, 가득 차면 앞의 내용을 요약합니다. 길어질수록 앞의 지시가 흐려지므로 정리하는 습관을 들입니다.
- /context — 지금 컨텍스트를 무엇이 얼마나 차지하는지 색깔 칸으로 봅니다.
- /compact — 지금까지의 대화를 요약해 자리를 비웁니다. 남길 것을 덧붙일 수 있습니다(예: /compact 로그인 수정 위주로).
- — 관계없는 다른 일을 시작할 때 대화를 새로 시작합니다.
- claude -c 는 이 폴더의 마지막 대화를 이어 가고, claude -r 이나 은 지난 대화를 골라 이어 갑니다.
- 두 번(또는 /rewind) — 목록에서 앞 시점을 골라 대화·코드를 되돌립니다. 로 지우거나 옮긴 파일은 되돌리지 못하므로 Git 커밋을 대신하지는 않습니다.
한 대화에는 한 가지 일. 일이 바뀌면 /clear 로 새로 시작하는 것이 가장 쉬운 정리입니다.
컨텍스트 아끼기 — SONUB 기준: 약 400k 에서 자동 요약, 기본 컨텍스트는 6% 이하
Claude 는 부탁을 받을 때마다 지금 컨텍스트 전체를 다시 읽습니다. 컨텍스트가 클수록 한 번의 부탁에 드는 이 많아집니다. 그래서 (자동 요약)로 1M 전부가 아니라 약 400k 토큰으로 쓰고, 대화를 시작하기 전부터 자리를 차지하는 기본 컨텍스트(기본 ·· 등)를 6% 이하로 유지합니다. 이렇게 하면 사용량을 크게 줄일 수 있습니다. 약 400k·6% 는 SONUB 이 정한 기준이며 공식 권장값이 아닙니다 — 공식 문서는 설정 방법만 설명합니다.
- /autocompact 444k — 컨텍스트가 444k 토큰에 이르면 자동으로 요약하게 합니다. 지금 모델의 사용자 설정에 저장되고, /autocompact auto 로 되돌립니다.
- 모든 모델에 쓰려면 ~/.claude/settings.json 에 "autoCompactWindow": 444000 을 넣습니다(아래 예). 한 번만 쓸 때는 claude --autocompact 444k 로 시작합니다.
- 새 대화를 열자마자 /context 를 봅니다. 아직 아무것도 부탁하지 않았는데 차지한 몫 — 시스템 프롬프트·시스템 도구·MCP 도구·스킬·(CLAUDE.md·AGENTS.md) — 이 기본 컨텍스트이고, 합이 6% 이하여야 합니다.
- 6% 를 넘으면 줄입니다 — 쓰지 않는 는 /mcp 에서 끄고, 쓰지 않는 스킬·은 지우고, CLAUDE.md·AGENTS.md 에는 꼭 필요한 규칙만 남깁니다.
{
"autoCompactWindow": 444000
}
기본 컨텍스트는 부탁할 때마다 함께 보내지므로 몇 % 만 줄여도 대화 내내 쌓여 사용량이 크게 줄어듭니다. 압축되기 전이라도 일이 바뀌면 /clear 로 새로 시작하는 것이 가장 큰 절약입니다.
잘 부탁하는 법 — 어디·무엇·어떻게 확인
좋은 부탁에는 세 가지가 들어 있습니다: 어디(파일·폴더), 무엇(바라는 동작), 어떻게 확인할지(테스트·명령·화면). 셋이 분명할수록 Claude 가 덜 헤매고 결과를 스스로 확인합니다.
- 막연한 부탁: "로그인 고쳐 줘"
- 또렷한 부탁: "@app//Controllers/LoginController.php 에서 비밀번호가 틀리면 가 나. 422 와 오류 문구를 돌려주게 고치고, tests/Feature/LoginTest.php 에 테스트를 더해 통과하는 것까지 확인해 줘."
- @ 를 입력하면 파일을 골라 부탁에 붙일 수 있습니다(@src/login.ts).
- 오류 화면·디자인 은 스크린샷을 붙여 넣거나 끌어다 놓습니다.
- 큰 일은 "먼저 읽고 계획만 보여 줘, 아직 고치지 마"로 시작하거나 /plan 으로 에 들어갑니다.
- 어려운 문제는 /model 에서 모델과 (effort)을 높이거나, 부탁에 를 넣어 그 차례만 더 깊이 생각하게 합니다.
- <> — 다음 부탁 없이도 그 기준을 채울 때까지 Claude 가 차례를 이어 가며 일합니다(예: /goal tests/ 의 테스트가 모두 통과한다, or stop after 20 ). /goal 만 치면 상태를 보고, /goal clear 로 지웁니다.
모범 사례 — Anthropic 이 권하는 Claude Code 사용법
줄이면 — Claude 가 스스로 확인할 방법을 주고, 어려운 일은 먼저 계획하고, 구체적으로 부탁하고, CLAUDE.md 는 짧게, 일 사이에는 컨텍스트를 비웁니다. 두 공식 안내의 좋은 습관 여섯과 Claude Code·Codex 명령은 툴 추천 사용법에 있습니다.
흔한 실수 — 그리고 고치는 법
공식 안내는 실패 패턴 다섯을 경고합니다 — 잡탕 세션, 고치고 또 고치기, 너무 긴 CLAUDE.md, 확인 없이 믿기, 끝없는 조사. 두 안내의 흔한 실수 열 가지와 고치는 법은 툴 추천 사용법에 있습니다.
중급 연습 — 내 프로젝트에서 해 보기
- 내 프로젝트 맨 위에 AGENTS.md 를 만들어 테스트 명령과 규칙 세 가지를 적고, 프로젝트 안에 CLAUDE.md 가 없는지 확인합니다.
- /memory 를 열어 AGENTS.md 와 ~/.claude/CLAUDE.md 가 읽혔는지 확인합니다.
- .claude/settings.json 에 테스트 명령 하나를 allow 로, .env 를 deny 로 넣고 /permissions 로 확인합니다.
- 작은 기능 하나를 계획 모드로 부탁하고, 계획을 읽고 고친 뒤 승인합니다.
- /context 로 차지한 양을 보고, /compact 로 줄인 뒤 다시 봅니다.
다섯 가지를 모두 해 봤다면 [고급] 탭으로 넘어가세요.
공식 문서
- 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 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.
고급 — 넓히기: 스킬·서브 에이전트·훅·MCP·헤드리스
반복하는 일은 로 가르치고, 큰 일은 에게 나눠 맡기고, 꼭 지켜야 할 것은 으로 강제하고, 바깥 는 로 잇고, 사람 없이 돌릴 일은 claude -p 로 스크립트에 넣습니다.
에이전트 스킬 — 반복하는 일을 가르치기
스킬은 가 든 폴더입니다. 는 평소에는 스킬의 이름과 설명만 알고 있다가, 일이 그 설명에 맞으면 본문을 읽어 따릅니다. 그래서 스킬을 많이 둬도 자리를 거의 차지하지 않습니다. 예전의 사용자 (.//)도 이제 스킬로 합쳐졌습니다.
- .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.
스킬은 열린 표준 — 하지만 클로드 코드는 자기 방식으로 동작
스킬은 Claude 를 만든 이 처음 만들어 무료로 공개했고, 지금은 agentskills.io 에서 라는 범용 으로 관리합니다. ··· 등 많은 도구가 같은 SKILL.md 폴더를 읽습니다.
하지만 주의하세요. 표준은 스킬 폴더 안에 무엇을 넣는지만 정하고, 스킬을 어디서 찾는지·이름이 겹치면 무엇을 쓰는지는 도구마다 다릅니다. 는 agentskills.io 가 권하는 방식과 다르게 동작하므로, 다른 도구에서 잘 되던 스킬이 클로드 코드에서는 다르게 동작할 수 있습니다.
- 폴더: agentskills.io 는 여러 도구가 함께 쓰는 .agents/skills/ 를 권하지만, 클로드 코드는 (프로젝트)와 ~/.claude/skills/(개인)를 읽습니다. .agents/skills/ 는 읽지 않습니다.
- 이름이 겹칠 때: 표준의 일반 은 프로젝트 스킬이 개인 스킬을 이기지만, 클로드 코드는 반대입니다 — 엔터프라이즈 > 개인(~/.claude/skills/) > 프로젝트 순이라 개인 스킬이 실행됩니다.
- 상위·: 표준은 정하지 않습니다. 클로드 코드는 시작한 폴더와 그 위로 까지를 읽고, 하위 폴더는 그곳에서 일할 때 읽습니다(다음 단락).
- : 표준 필드는 name·description··compatibility·· 여섯 개입니다. 클로드 코드는 disable-model-invocation·: fork·paths 같은 필드를 더했는데, 다른 도구는 이를 무시하고 claude.ai 업로드· 는 오류로 멈춥니다.
다른 AI 도구와 함께 쓸 스킬은 frontmatter 를 표준 여섯 필드로만 쓰세요. 그러면 클로드 코드와 다른 도구에서 고치지 않고 그대로 읽힙니다.
클로드 코드가 스킬을 찾는 곳 — 지금 폴더와 상위 폴더를 함께
에 .claude/skills 폴더가 있고 에도 같은 폴더가 있으면, 클로드 코드는 지금 폴더와 상위 폴더의 스킬을 모두 같이 씁니다. 다만 위로는 git 저장소 루트까지만 올라갑니다.
- claude 를 시작한 폴더와, 그 위로 저장소 루트까지 모든 상위 폴더의 .claude/skills/ 를 읽습니다. apps/web/ 에서 시작해도 루트의 스킬이 함께 잡힙니다.
- 저장소 루트보다 위 폴더의 .claude/skills/ 는 읽지 않습니다. 여러 프로젝트에 공통으로 쓸 스킬은 ~/.claude/skills/ 에 두세요. 에서는 worktree 루트까지만 올라갑니다.
- 시작한 폴더보다 아래(하위) 폴더의 스킬은 처음엔 읽지 않습니다. Claude 가 그 폴더의 파일을 처음 읽거나 고칠 때 읽혀 이 끝날 때까지 남고, 그 전에는 / 메뉴에도 없습니다. 미리 읽으려면 /add-dir 로 그 폴더를 더합니다.
- 루트와 apps/web/ 양쪽에 스킬이 있으면 둘 다 씁니다. /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.
훅 — 정해진 때 반드시 실행되는 명령
는 부탁이라 가끔 잊힐 수 있지만, 훅은 클로드 코드가 정해진 순간마다 반드시 실행하는 명령입니다. 파일을 고친 뒤 돌리기, 위험한 명령이나 비밀 파일 편집 막기, 일이 끝나면 알림 받기에 씁니다.
- — 도구를 쓰기 전(막을 수 있음), PostToolUse — 도구를 쓴 뒤
- UserPromptSubmit — 부탁을 보낼 때, Stop — Claude 가 답을 마칠 때, SessionStart — 세션을 시작할 때, Notification — 내 확인이 필요할 때
- 로 어느 도구에 걸지 고릅니다(예: Edit|Write, ).
- 훅 명령이 2 로 끝나면 그 동작을 막고, 에 쓴 이유를 Claude 에게 알려 줍니다.
- /hooks 로 지금 걸린 훅을 봅니다. 위 예는 파일을 고칠 때마다 로 정리합니다( 가 필요).
{
"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 도구가 바깥 서비스( 관리···문서 도구)를 쓰게 하는 열린 표준입니다. 를 하나 더하면 그 가 주는 도구를 Claude 가 쓸 수 있습니다.
- claude mcp add --transport http <이름> <주소> — 인터넷에 있는 원격 서버를 더합니다.
- <이름> -- <명령> — 내 컴퓨터에서 실행하는 서버(stdio)를 더합니다. 는 그대로 서버에 넘어갑니다.
- project 로 더하면 맨 위의 에 저장돼 팀이 함께 씁니다(처음 쓸 때 승인을 묻습니다).
- /mcp 로 연결 상태를 보고 로그인()합니다. 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 "…" 는 대화 화면 없이 한 번 실행하고 결과를 출력한 뒤 끝납니다. 쉘 스크립트·· 에서 Claude 를 부품처럼 씁니다.
- 파이프로 입력을 넘깁니다(cat error.log | claude -p "…").
- 은 결과·세션 id·비용을 JSON 으로, stream-json 은 진행을 줄마다 내보냅니다.
- --allowedTools 로 이번 실행에 허락할 도구를, --max-turns 로 최대 차례 수를 정합니다.
- claude -p --continue 로 앞 실행을 이어 가거나, <세션 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
스크립트에서는 를 붙이면 CLAUDE.md·훅·플러그인·MCP 를 읽지 않고 빠르게 시작합니다(공식 문서는 앞으로 -p 의 기본이 된다고 안내합니다). 프로젝트 지시가 필요하면 빼세요.
고급 연습
- 자주 하는 일 하나(예: , 커밋 메시지)를 .claude/skills/ 에 스킬로 만들고 /스킬이름 으로 불러 봅니다.
- 읽기만 하는 code-reviewer 서브 에이전트를 만들어 지금 변경을 검토하게 합니다.
- PostToolUse 훅으로 파일을 고칠 때마다 포매터나 가 돌게 합니다.
- MCP 서버 하나를 더하고 /mcp 로 연결을 확인합니다.
- claude -p 로 를 요약하는 한 줄짜리 쉘 스크립트를 만듭니다.
다섯 가지를 모두 해 봤다면 [마스터] 탭으로 넘어가세요.
공식 문서
2026-10-19 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.
마스터 — 팀과 자동화: 병렬 작업·GitHub·플러그인·긴 작업
혼자 쓰는 에서 팀의 작업 방식으로 넘어갑니다. 여러 을 동시에 돌리고, 에서 @claude 를 부르고, 팀 설정을 으로 나누고, 오래 걸리는 일을 스스로 확인하며 끝내게 합니다.
Git worktree — 여러 세션을 동시에
한 폴더에서 두 세션이 같은 파일을 고치면 서로 덮어씁니다. 는 같은 를 다른 폴더에 다른 로 꺼내 주므로, 폴더마다 를 하나씩 띄워 여러 일을 동시에 진행할 수 있습니다.
- claude --worktree <이름>(-w)은 .claude/worktrees/<이름>/ 에 worktree 와 브랜치를 만들고 그 안에서 시작합니다. 바뀐 것 없이 끝내면 저절로 지웁니다.
- .claude/worktrees/ 는 에 넣고, 처럼 이 무시하는 파일을 새 worktree 로 복사하려면 .worktreeinclude 에 적습니다.
- worktree 마다 의존성 설치( install 등)가 따로 필요할 수 있습니다.
- 서로 다른 파일을 고치는 독립된 일끼리 나누고, 끝나면 로 합칩니다.
# 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
를 설치하면 나 PR 댓글에 @ 라고 쓰는 것만으로 Claude 가 저장소를 읽고, 고쳐서 PR 을 올리거나 리뷰를 남깁니다. GitHub 의 에서 돌므로 가 꺼져 있어도 됩니다.
- 터미널의 클로드 코드에서 /install-github-app 을 실행합니다. GitHub 앱 설치와 (ANTHROPIC_API_KEY 또는 claude 으로 만든 ) 등록을 안내합니다( 와 저장소 관리자 이 필요).
- .github/workflows/ 에 위와 같은 이 생깁니다.
- 이슈나 PR 에 "@claude 이 고쳐 줘" 처럼 댓글을 답니다.
- 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 도 저장소의 지시 파일(, 또는 )을 읽습니다. 을 지키게 하는 가장 쉬운 방법은 지시 파일을 잘 써 두는 것입니다.
플러그인·마켓플레이스 — 설정을 묶어 나누기
···를 하나로 묶은 것이 플러그인입니다. 는 플러그인 목록이 든 저장소입니다. 팀이 같은 도구 상자를 하나로 설치하고 함께 업데이트합니다.
- /plugin — 플러그인을 찾아 설치하고 켜고 끕니다.
- /plugin marketplace add <owner/repo> 로 마켓플레이스를 더하고, /plugin install <플러그인>@<마켓플레이스> 로 설치합니다.
- 플러그인 폴더의 .claude-plugin/ 에는 plugin.json 만 둡니다. skills/·agents/·hooks/ 는 폴더 맨 위에 둡니다. claude --plugin-dir ./my-plugin 으로 시험합니다.
- 스킬만 나눈다면 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
팀 설정 운영 — 규칙이 쌓여도 흐려지지 않게
여러 사람과 여러 가 같은 저장소에서 일하면 설정이 금방 쌓입니다. 무엇을 함께 쓰고 무엇을 나만 쓸지, 무엇을 부탁하고 무엇을 강제할지 나눠 둡니다.
- 함께 씀(): AGENTS.md····(CLAUDE.md 를 쓴다면 모든 폴더의 CLAUDE.md 도)
- 나만 씀(커밋 안 함): .claude/settings.local.json·~/.claude/ — 개인 지시는 ~/.claude/CLAUDE.md 에 둡니다(프로젝트의 는 AGENTS.md 를 막으니 두지 않습니다)
- 지시 파일은 짧게 유지합니다. 같은 실수가 되풀이될 때만 규칙을 더하고, 틀리거나 쓸모없어진 규칙은 지웁니다.
- 꼭 지켜야 하는 것은 지시가 아니라 권한(deny)과 훅으로 강제합니다.
- 회사 전체의 규칙은 (managed settings)으로 내려보냅니다 — 다른 설정이 덮어쓸 수 없습니다.
긴 작업 — 스스로 확인하며 끝까지
마스터는 Claude 에게 "끝난 기준"을 주고 그 기준을 스스로 확인하게 합니다. 테스트··처럼 기계가 판정할 수 있는 기준이 있으면 사람이 지켜보지 않아도 오래 일할 수 있습니다.
- 끝난 기준을 명령으로 줍니다 — "npm test 와 lint 가 모두 통과할 때까지".
- 한 일·남은 일을 PROGRESS.md 같은 파일에 적게 하면 가 요약되거나 세션이 바뀌어도 이어 갈 수 있습니다.
- 작은 단계마다 커밋하게 해 언제든 되돌릴 수 있게 합니다.
- 세 번 시도해도 안 되면 멈추고 이유를 적게 해, 헛도는 반복을 막습니다.
- 다 끝나면 다른 AI(예: codex review)나 서브 에이전트에게 를 맡깁니다.
마스터 연습 — 여러 세션과 자동화
- git worktree add ../my-project-b -b try-b 로 작업 폴더를 하나 더 만들고, 두 폴더에서 claude 를 하나씩 실행해 서로 다른 작은 일을 맡깁니다. 두 폴더의 git status 가 따로 바뀌면 성공입니다.
- git | claude -p "List bugs in this diff" 로 한 줄 검토 명령을 만듭니다. 일부러 버그를 하나 넣고 그것을 찾는지 봅니다.
- 팀 규칙 하나(예: 커밋 전에 테스트 실행)를 AGENTS.md 에 적고 훅으로도 강제합니다. 일부러 규칙을 어겨 훅이 막는지 확인합니다.
- 내 스킬 하나와 서브 에이전트 하나를 위 플러그인 단락대로 플러그인으로 묶어 설치하고, 다른 프로젝트에서도 불러지는지 확인합니다.
- 끝난 기준을 명령으로 적어(예: npm test 통과) 긴 일을 맡기고, 끝났다고 하면 diff 와 테스트 결과를 직접 확인합니다.
막히면: worktree 는 git worktree list 로 보고 git worktree remove 로 지웁니다. 훅이 너무 막으면 settings.json 에서 잠시 빼고 /hooks 로 확인하세요. 다섯 가지를 모두 해 봤다면 아래 체크리스트로 스스로 점검하세요.
마스터 체크리스트
- 프로젝트에는 AGENTS.md 만 — 여러 AI 가 같은 지시로 일한다(CLAUDE.md 를 쓴다면 모든 폴더에 두고 @AGENTS.md 한 줄)
- 으로 안전한 명령은 묻지 않고, 비밀 파일은 deny 로 막았다
- 반복하는 일은 스킬, 큰 조사·검토는 서브 에이전트에게 맡긴다
- 꼭 지켜야 하는 것은 훅으로 강제한다
- 작업은 worktree 로, 반복 작업은 claude -p 와 GitHub Actions 로 한다
- 끝난 기준을 명령으로 주고, 결과는 diff 와 테스트로 직접 확인한다
도구는 자주 바뀝니다. 새 기능은 claude-skill 스킬의 /claude-skill update 나 공식 문서의 (CHANGELOG)으로 따라잡으세요.
공식 문서
2026-10-19 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.
불러오는 중…
취소할 대기 예약을 선택하세요. 각 예약은 확인 후 취소됩니다.
내 :