Claude Code 설정, 앤트로픽 워크숍 정리

Claude Code를 설치해서 쓰고는 있지만 무엇부터 손대야 할지 막막하다면, 이 글이 그 순서를 잡아줍니다. 앤트로픽에서 Claude Code의 개발자 경험을 담당하는 리디아 할리(Lydia Hallie)가 진행한 무료 워크숍 'Claude Code'를 처음부터 끝까지 확인하고, 실제로 따라 할 수 있는 항목만 추렸습니다. 이 코스는 master.dev(구 Frontend Masters)에서 이름과 이메일만으로 볼 수 있는 16개 레슨, 1시간 56분 분량입니다. 코스 자체가 요구하는 사전 지식은 프롬프트 엔지니어링에 대한 이해와 기본적인 소프트웨어 개발 경험이면 충분합니다.

먼저 알아둘 것 — 생각은 모델이, 실행은 하네스가 한다

Claude Code를 이해하는 가장 기초적인 구도는 두 부분으로 나뉩니다. 하나는 Opus·Sonnet·Haiku 같은 모델 자체이고, 다른 하나는 그 모델을 감싸고 있는 하네스(harness), 즉 Claude Code 프로그램 자체입니다. 모델은 프롬프트를 보고 무엇을 해야 할지 추론할 뿐, 실제로 파일을 읽거나 고치는 일은 하지 못합니다. 그 실행은 전부 하네스의 몫.

모델은 또한 상태를 기억하지 못합니다. 매번 호출될 때마다 이전 대화를 전혀 모르는 상태에서 다시 시작합니다. 그래서 파일 내용, 대화 기록, 실행 환경 같은 모든 맥락을 매번 새로 조립해 모델에 전달하는 것도 하네스의 일입니다. 이렇게 조립된 프롬프트에는 무엇을 할 수 있는지 정의한 도구 목록, 시스템 프롬프트, 실행 환경 정보, 그리고 지금까지의 대화 기록이 함께 담깁니다.

모델이 도구를 쓰겠다고 응답하면 하네스가 그걸 실제로 실행하고 결과를 다시 모델에 돌려주는 과정이 반복됩니다. 이 왕복을 에이전틱 루프(agentic loop)라고 부르고, 모델이 더 이상 도구를 부르지 않고 텍스트로만 답하는 순간 이 루프가 끝납니다. 이 구도를 알아두면 뒤에서 다룰 CLAUDE.md·권한·컨텍스트 관리가 왜 필요한지 분명해집니다 — 전부 하네스가 모델에게 무엇을, 얼마나 보여줄지 조절하는 장치입니다.

CLAUDE.md, 처음 만들 때는 /init부터

이미 진행 중인 프로젝트에 CLAUDE.md 파일을 넣는 가장 쉬운 방법은 /init 명령입니다. Claude Code가 코드베이스를 스스로 탐색해 기술 스택·명령어·아키텍처·상태 관리 방식 같은 것들을 파악한 뒤 그 내용으로 CLAUDE.md를 만들어줍니다. 이미 알고 있는 내용을 정리하는 작업이라 모델은 Opus가 아니라 Sonnet으로도 충분합니다.

CLAUDE.md는 계층 구조를 가집니다. 사용자 홈 디렉터리에 두면 모든 프로젝트에 적용되고, 저장소 안에 두면 그 프로젝트에만 적용됩니다. 모노레포처럼 하위 저장소마다 파일이 있으면, Claude를 어느 디렉터리에서 시작했는지에 따라 가장 가까운 파일이 우선 적용됩니다.

이 파일은 매 대화의 첫 프롬프트에 통째로 들어가 컨텍스트를 차지합니다. 그래서 파일이 커질수록 실제로 쓰이지 않는 내용도 함께 실려 컨텍스트를 낭비합니다. 최신 모델일수록 의도를 더 잘 파악하기 때문에, 예전에 꼭 필요했던 지시문도 지금은 없어도 될 수 있습니다. 내용을 최대한 줄여보고 모델이 실제로 헤매는 지점만 다시 채워 넣는 방식이 유용합니다.

코드를 건드리기 전에, 플랜 모드로 먼저 확인한다

플랜 모드는 CLI에서 Shift+Tab을 누르거나, "아직 코드는 짜지 말고 계획부터 말해줘"라고 직접 요청해서 켤 수 있습니다.

구현에 들어가기 전 검증 수단을 하나 끼워 넣으면 이 단계가 더 유용해집니다. 워크숍에서는 디자인 목업 이미지를 스크린샷으로 찍어 플랜 모드 프롬프트에 그대로 붙여 넣고 "이 디자인대로 구현하려면 어떻게 해야 할지 계획부터 말해줘"라고 요청하는 방식을 보여줬습니다. 이미지·테스트처럼 결과를 대조할 수 있는 것을 검증 루프에 넣어두면, 계획이 실제 의도와 맞는지 코드를 쓰기 전에 확인할 수 있습니다.

권한은 allow·ask·deny 세 가지로 미리 정해둔다

.claude/settings.json에 권한 규칙을 적어두면 Claude Code가 무엇을 자동으로 하고, 무엇을 물어보고, 무엇을 아예 못 하게 할지 미리 정할 수 있습니다. 워크숍 화면에 나온 예시는 이런 구조.

npm run이나 git commit처럼 자주 쓰고 되돌리기 쉬운 것은 allow 목록에, git push처럼 원격 저장소를 건드리는 것은 deny 목록에, rm처럼 되돌리기 어려운 것은 ask 목록에 두는 식입니다. 직접 파일을 편집하는 대신 /permissions 명령으로 규칙을 추가할 수도 있습니다.

규칙이 여러 층에서 겹칠 때는 조직 차원의 managed settings가 개인 설정보다 항상 우선합니다. 팀원 개인이 회사가 정한 제한을 자기 마음대로 풀 수 없게 하려는 설계입니다. 매번 승인 창을 띄우는 게 번거롭다면 /fewer-permission-prompts 명령도 있습니다. 그동안의 대화 기록을 훑어 반복적으로 승인해온 도구 호출을 찾아 권한 규칙으로 자동 추가해주는데, 이미 다른 규칙으로 커버되거나 애매한 것은 "when in doubt, leave it out"이라는 원칙으로 스스로 걸러냅니다.

모델 선택과 effort 설정

Claude Code는 Opus·Sonnet·Haiku 세 모델 중에서 고를 수 있습니다. Opus는 깊은 추론이 필요한 어려운 문제에 강하지만 느리고 비쌉니다. Sonnet은 일반적인 소프트웨어 작업, 즉 기능 추가나 버그 수정, 리팩터링에 가장 균형이 좋습니다. Haiku는 추론이 필요 없는 반복 작업, 이를테면 여러 파일의 이름을 바꾸거나 나열하는 일에 빠르고 저렴합니다.

여기에 더해 각 모델에는 max·high·medium·low 네 단계의 effort 수준이 따로 있습니다. 모델이 게으르게 답하는 것처럼 보일 때, 원인이 모델 자체가 아니라 effort 수준이 낮게 잡혀 있는 경우가 있습니다. 반대로 간단한 요청에 과하게 많은 걸 고치려 든다면 effort 수준을 낮춰볼 일이지, 모델을 낮출 일이 아닐 수 있습니다. 두 다이얼은 따로 움직입니다. 워크숍에서 든 비유가 감을 잡기 좋습니다 — Opus를 low effort로 쓰는 것은 "전문가를 10분만 고용하는 것"과 비슷하고, Sonnet을 high effort로 쓰는 것은 "초보자를 한 시간 고용하는 것"과 비슷합니다.

모델을 자주 바꾸고 싶다면 워크숍 녹화 당시 새로 추가된 어드바이저(Advisor) 기능도 있습니다. 지금 세션은 Sonnet에 두고 계획 단계만 Opus에게 맡기는 식으로, 세션 중간에 모델을 직접 바꾸지 않고도 필요한 순간에만 더 강한 모델의 판단을 빌릴 수 있습니다. 세션 도중에 모델 자체를 바꾸는 것은 프롬프트 캐시를 깨뜨려 비용이 늘어나므로, 모델을 바꾸려면 새 세션을 시작하는 편이 낫습니다.

컨텍스트가 크다고 무조건 좋은 게 아니다

컨텍스트 윈도우(context window)는 기본 20만 토큰에서 100만 토큰까지 늘었습니다. 하지만 창이 커진다고 계속 채워도 되는 것은 아닙니다. 관련 없는 내용이 쌓일수록 모델이 지금 무엇을 하려는지 파악하는 정확도가 떨어집니다. 대략 30만~40만 토큰을 넘어서면 직접 압축(compact)하거나 초기화(clear)하는 편이 낫습니다.

압축은 지금까지의 대화를 요약해 하나로 합치는 것이고, 초기화는 대화를 통째로 지우는 것. 압축할 때 아무 힌트 없이 실행하면 모델이 무엇이 중요한지 스스로 판단해야 해서, 세워둔 계획이나 앞서 지시한 세부 사항을 놓치는 경우가 있습니다. "이전 계획과 지금까지의 코멘트는 유지해줘" 같은 힌트를 함께 주면 이런 손실을 줄일 수 있습니다. 완전히 다른 작업으로 넘어갈 때는 압축보다 초기화가 낫습니다.

토큰 사용량 관점에서 한 가지 더 — 세션이 70만~80만 토큰을 넘어간 상태에서 오래 지난 대화를 다시 불러오면, 그사이 캐시가 만료돼 그 구간을 다시 계산해야 하므로 비용이 더 든다는 점도 알아둘 만합니다.

반복되는 절차는 스킬로 묶는다

같은 절차를 매번 프롬프트로 다시 설명하고 있다면 스킬로 만들 차례입니다. 스킬은 .claude/skills/ 아래에 스킬 이름을 딴 폴더를 만들고 그 안에 SKILL.md 파일을 두는 구조입니다(워크숍 화면에 실제로 뜬 경로는 .claude/skills/deploy/SKILL.md였습니다). 이름과 설명만 매 프롬프트에 실리고, 실제 절차 내용은 그 스킬이 호출될 때만 불러옵니다. 그래서 스킬을 아무리 많이 만들어도 평소 컨텍스트 사용량은 크게 늘지 않습니다.

직접 마크다운을 쓰는 대신 Claude Code에 내장된 '스킬 크리에이터(Skill Creator)'에게 맡길 수도 있습니다. 무엇을 하는 스킬인지 몇 마디만 던지면 이름·설명·절차까지 대신 작성해줍니다. 새 스킬을 추가한 뒤에는 플러그인을 다시 불러와야(reload plugins) Claude Code가 그 존재를 인식합니다.

스킬의 앞부분(front matter)에는 세부 설정을 여러 가지 넣을 수 있습니다. 특정 모델을 고정해두거나(예: 코드 리뷰 스킬은 항상 Sonnet으로), 슬래시 명령으로만 실행되고 모델은 자동으로 부르지 못하게 하거나, 반대로 모델만 호출하고 슬래시 명령으로는 못 쓰게 하거나, 이 스킬에서만 쓸 수 있는 도구를 따로 제한할 수도 있습니다. (정확한 설정 키 이름은 워크숍에서 음성으로만 언급돼 화면으로 확인하지 못했습니다 — 실제 적용 전 공식 문서로 표기를 다시 확인해야 합니다.) 배포 대상처럼 값이 바뀌는 인자를 받게 만들 수도 있고("deploy staging"), 특정 셸 명령의 출력을 스킬 내용에 끼워 넣게 할 수도 있습니다(팀 밖으로 공유할 스킬이라면 이 기능은 끌 수도 있습니다). 스킬 크리에이터는 그 스킬을 켰을 때와 껐을 때 결과를 비교하는 평가(eval)도 실행해 줘서, 토큰만 더 쓰고 실제로는 도움이 안 되는 스킬을 걸러낼 수 있습니다. 스킬은 기본적으로 본체 대화 안에서 실행되지만, 컨텍스트 포크(context fork) 설정을 쓰면 그 스킬만 따로 서브에이전트 안에서 실행해 본체 대화를 어지럽히지 않게 할 수도 있습니다.

반드시 지켜야 하는 건 훅으로 강제한다

스킬이나 프롬프트는 결국 모델에게 "이렇게 해줘"라고 부탁하는 방식이라 잊히거나 건너뛰어질 수 있습니다. 절대 건너뛰면 안 되는 것은 훅으로 강제합니다. 훅은 프롬프트나 HTTP 엔드포인트, 셸 명령을 에이전트 루프의 특정 지점에 강제로 끼워 넣는 방식. 워크숍 화면에 나온 전체 흐름은 다음과 같았습니다.

가장 자주 쓰는 지점은 두 곳. PreToolUse는 모델이 도구 호출을 내놓았지만 아직 실행되기 전이라 위험한 동작을 막기 좋고, PostToolUse는 도구가 성공적으로 끝난 직후라 포매팅이나 린트, 타입 체크를 실행하기 좋습니다. 워크숍에서는 파일을 편집하거나 쓸 때마다 타입 체크를 자동으로 실행하는 PostToolUse 훅을 예시로 보여줬습니다. /hooks 명령으로 어떤 지점에 훅을 걸 수 있는지 목록을 확인할 수 있고, 실제 설정은 .claude/settings.json에 적습니다. 플러그인으로 묶어 배포할 훅은 settings.json 대신 hooks/hooks.json 파일을 씁니다.

맥락을 흐리는 작업은 서브에이전트로 떼어낸다

본 작업과 상관없는 곁가지 작업이 대화에 계속 끼어들면, 관련 없는 도구 호출 결과가 쌓여 모델의 집중도가 떨어집니다. 이럴 때는 서브에이전트를 씁니다. 서브에이전트는 자기만의 맥락·도구·시스템 프롬프트를 갖고 따로 실행되다가 결과만 본체 대화로 돌려주는 별도의 루프.

Claude Code Guide(공식 문서 접근), Explore(Haiku 기반 코드베이스 탐색), general purpose, Plan, Status, Setup 같은 서브에이전트가 기본으로 들어 있습니다. /agents 명령으로 직접 만들 수도 있는데, 이 프로젝트에서만 쓸지 여러 프로젝트에서 재사용할지 범위를 고르고, Claude에게 설명을 대신 써달라고 할 수 있습니다. 이 설명이 정확할수록 모델이 언제 이 서브에이전트를 자동으로 부를지 더 잘 판단합니다. 이렇게 만든 서브에이전트는 .claude/agents/이름.md 자리에 파일로 생깁니다(워크숍 화면에 실제로 뜬 경로는 .claude/agents/code-improver.md였습니다). 워크숍에서 실제로 만든 코드 리뷰 서브에이전트의 파일은 이런 모습.

서브에이전트는 백그라운드에서 실행해 두고 본체 대화를 계속 진행할 수도 있고, 필요하면 도중에 멈출 수도 있습니다.

여러 에이전트가 실제로 협의해야 할 때만 에이전트 팀

서브에이전트는 여러 개를 동시에 띄워도 서로 대화하지 못하고, 각자 결과만 본체로 돌려줍니다. 워크숍 녹화 당시 새로 추가된 에이전트 팀은 다릅니다. 팀장 역할의 메인 에이전트가 공유 작업 목록을 만들면, 여러 팀원 에이전트가 그 목록을 두고 서로 진행 상황을 확인하며 실제로 대화합니다. "use a team of five agents to run this"처럼 직접 요청하면 켤 수 있습니다.

다만 여러 에이전트가 서로 대화하는 만큼 토큰도 더 씁니다. 워크숍에서는 이렇게 분명히 선을 그었습니다.

"...for some cases, you don't need a whole team, you just need one good developer which could be a sub-agent, but it's a nifty little feature."

많은 경우 팀 전체가 아니라 좋은 개발자 한 명, 즉 서브에이전트 하나로 충분하다는 뜻. 여러 전문 에이전트가 실제로 서로 확인하며 협의해야 하는 드문 경우가 아니라면, 서브에이전트 하나로 시작하는 편이 낫습니다. 다만 서브에이전트 여러 개를 병렬로 띄워 같은 파일을 동시에 건드리면 머지 충돌이 나기 쉬운데, 에이전트 팀은 서로 진행 상황을 확인하고 지나가기 때문에 이런 충돌이 그만큼 덜 납니다.

팀과 공유하려면 플러그인, 외부 시스템과 연결하려면 MCP

스킬·훅·서브에이전트를 만들었으면 이제 팀과 공유할 차례입니다. 플러그인은 이것들을 하나로 묶는 단위. .claude-plugin/plugin.json 파일에 이름·버전·작성자 같은 정보를 담는데, 정작 스킬이나 훅 파일 자체는 이 폴더 안이 아니라 그 바깥 저장소 루트에 둡니다. 아직 npm 같은 자동 배포 체계는 없어서, 공식 마켓플레이스에 올리려면 신청 폼을 거쳐야 합니다. /plugins 명령으로 이미 있는 공식 마켓플레이스(Anthropic agent skills, Claude plugins official 등)를 둘러볼 수 있습니다.

프로젝트 파일을 편집하는 것을 넘어 외부 시스템과 직접 연결하려면 MCP(Model Context Protocol)를 씁니다. 예전에는 도구마다 자기만의 연동 방식을 따로 만들었는데, MCP는 이걸 하나의 표준으로 통일합니다. 워크숍 화면에 나온 공식 다이어그램은 MCP를 한쪽의 채팅 인터페이스(Chat interface, Claude Desktop 등)·IDE(IDEs and code editors, Claude Code 등)·다른 AI 애플리케이션(Other AI applications)과, 다른 쪽의 데이터·파일 시스템(Data and file systems)·개발 도구(Development tools, Git 등)·생산성 도구(Productivity tools, Slack·Google Maps 등) 사이를 잇는 표준 계층으로 그리고 있었습니다. 직접 서버를 만들 때는 @modelcontextprotocol/sdk 패키지로 도구 이름과 설명, 처리 함수를 등록하고 전송 방식을 연결하면 됩니다.

데스크톱 앱, Cowork, Agent SDK

터미널 밖에서도 같은 것을 쓸 수 있습니다. 데스크톱 앱은 프런트엔드 프로젝트의 미리보기 창을 내장하고 있어서 브라우저 확장 없이 바로 화면을 확인할 수 있고, 화면의 UI 요소를 클릭해서 바로 프롬프트에 참조시킬 수 있습니다. 스크린샷과 컴포넌트 코드, props가 함께 전달돼 "어느 버튼 말씀이세요?" 같은 되물음이 줄어듭니다. PR 생성 버튼은 실제로는 스킬 하나를 실행하는 것이고, CI가 실패하면 백그라운드에서 자동으로 고치고 리뷰 코멘트까지 반영하게 할 수 있습니다. GitHub의 자동 병합 설정을 켜두면 CI가 초록불이 될 때까지 기다렸다가 스스로 병합되는 것도 볼 수 있습니다.

Cowork는 같은 런타임을 코딩이 아닌 일상 업무에 맞춘 것. 슬랙·이메일·캘린더 정리, 정해진 시간마다 실행되는 루틴, AppleScript를 통한 macOS 제어 같은 것을 다룹니다. 이 모든 것을 프로그래밍적으로 직접 다루고 싶다면 Agent SDK로 API 키 하나만으로 같은 런타임에 접근할 수 있습니다. Cowork도 내부적으로 이 SDK 위에서 작동합니다. 플랜 모드에서 "ask user question 도구를 써서 내가 놓쳤을 만한 예외 상황까지 물어봐줘"라고 명시적으로 요청하면, Claude가 구조화된 질문 목록으로 먼저 되물어보고 계획을 세우게 만들 수도 있습니다.

여기까지 따라오면 CLAUDE.md와 권한으로 기본 틀을 잡고, 반복되는 절차는 스킬로, 반드시 지켜야 하는 것은 훅으로, 맥락을 흐리는 작업은 서브에이전트로 나눌 수 있습니다. 에이전트 팀과 플러그인·MCP는 이 기본기 위에서 필요해질 때 그다음으로 찾아보면 됩니다.

이 워크숍은 2026년 4월 21일 녹화본입니다. 그 뒤로 Claude Code에는 Fable 5.1 모델, 더 높은 xhigh effort 수준, 여러 에이전트를 하나의 워크플로로 묶는 ultracode 같은 기능이 새로 추가됐습니다. 이 가이드는 녹화 시점까지의 내용만 다룹니다.

출처

이메일로 실제 계정을 만들어 master.dev에 로그인한 뒤 16개 레슨 전체를 직접 확인했습니다.

• master.dev 무료 코스 'Claude Code'(리디아 할리, 앤트로픽) · https://master.dev/courses/claude-code/ · 2026년 9월 17일 확인