일상적인 도구로서의 Claude Code: Claude.md, 기술, Subagents, Plugins, 그리고 MCPs

Claude Code는 가벼운 사용자(casual user)와 이를 완전히 내재화한 사람 사이의 차이가 엄청난 도구 중 하나입니다. 가벼운 사용자는 프롬프트를 입력하고, 제안을 수락하며, 이를 더 화려한 자동 완성(autocomplete) 기능처럼 취급합니다. 반면, 이를 일상적인 도구(daily driver)로 사용하는 사람은 이를 메모리, 커스텀 명령(custom commands), 병렬 세션(parallel sessions), 그리고 시간이 지날수록 복리로 쌓이는 프로젝트 설정(project setup)을 갖춘 프로그래밍 가능한 에이전트(programmable agent)처럼 사용합니다. 이 가이드는 후자의 사람들을 위한 것이며, 터미널에 claude를 입력했을 때 어떤 일이 일어나는지 이미 알고 있다고 가정합니다.

Claude Code를 '프롬프트를 입력하고 기다리는 챗봇'으로 생각하는 것을 멈추고, 가드레일(guardrails)이 필요한 자율 에이전트(autonomous agent)로 취급하기 시작하면 워크플로우가 변화합니다. Boris Cherny와 Anthropic 팀이 강조하는 가장 중요한 원칙은 다음과 같습니다: Claude에게 자신의 작업물을 스스로 검증할 수 있는 방법을 제공하라. 이것이 없다면 당신만이 유일한 피드백 루프(feedback loop)가 됩니다. 이것이 있다면 Claude는 실제로 작동할 때까지 반복(iterate)하며, Boris는 이것만으로도 품질이 2~3배 향상된다고 말합니다.

매일의 운영 방식을 바꾸는 몇 가지 패턴은 다음과 같습니다:

탐색하고, 계획하고, 코딩하라. 계획 모드(Plan mode, Shift+Tab을 두 번 입력)는 Claude를 읽기 전용 탐색 상태로 전환합니다. 파일을 읽고, 흐름을 추적하며, 데이터 모델을 이해하십시오. 그런 다음 계획을 세우고, 실행하십시오. 작은 수정 사항에는 계획 단계를 건너뛰어도 되지만, 두 개 이상의 파일을 건드리는 모든 작업에는 계획 모드를 사용하십시오.

계획 모드를 설계 문서(design document)처럼 사용하라. 한 명의 Claude가 계획을 작성하게 한 다음, 새로운 세션에서 두 번째 Claude를 실행하여 스태프 엔지니어(staff engineer)로서 그 계획을 검토하게 하십시오. 컨텍스트 편향(context bias)이 없는 상태에서 검토하게 함으로써 실제로 공백을 찾아낼 수 있습니다. 만약 구현이 잘못된다면, 다시 계획 모드로 돌아가 검증 단계(verification steps)를 포함하여 다시 계획을 세우십시오.

설명하지 말고 참조하라. "인증 모듈을 봐줘"라고 하는 대신 @src/auth/login.py를 입력하십시오. 에러를 붙여넣는 대신 파이프(pipe)를 사용하십시오: cat error.log | claude . 정확한 컨텍스트(context)는 언제나 모호한 설명보다 강력합니다.

페어 프로그래밍(pair-program)을 하지 말고, 위임(Delegate)하십시오. Cat Wu (Claude Code 팀): "모델을 한 줄씩 가이드하는 페어 프로그래머(pair programmer)가 아니라, 업무를 맡기는 엔지니어처럼 대할 때 가장 성능이 좋습니다." 처음에 명확한 브리프(brief)를 작성한 다음, 모델이 실행되도록 두십시오.

Ctrl+G를 눌러 에디터에서 Claude의 계획(plan)을 열고, Claude가 진행하기 전에 이를 수정하십시오. 계획은 단순한 텍스트이므로, 코드가 되기 전에 형태를 잡으십시오.

Claude가 실수를 하면, 프롬프트 끝에 "이런 실수를 반복하지 않도록 CLAUDE.md를 업데이트해"라고 입력하십시오. Boris는 Claude가 자신의 실패로부터 스스로 규칙을 작성하는 능력이 "섬뜩할 정도로 뛰어나다"고 말합니다. 이 습관은 이 가이드의 그 어떤 습관보다 더 큰 복리 효과를 가져옵니다.

대부분의 사람들은 .claude/를 한 번 열어보고, CLAUDE.md를 확인한 뒤 더 이상 보지 않습니다. 하지만 이것은 실제로는 계층화된 설정 시스템(layered configuration system)입니다.

두 가지 범위(scope): **프로젝트 범위(Project scope)**는 리포지토리 내부의 .claude/에 존재하며, 팀원들과 공유할 수 있도록 git에 커밋됩니다. **글로벌 범위(Global scope)**는 ~/.claude/에 존재하며, 사용자의 머신에 있는 모든 프로젝트에 적용됩니다.

멘탈 모델(Mental model): 프로젝트 파일은 프로젝트를 설명하고, 글로벌 파일은 당신을 설명합니다.

파일	범위	커밋 여부	역할
CLAUDE.md	프로젝트 및 글로벌	예	매 세션마다 로드되는 지침
CLAUDE.local.md	프로젝트 전용	아니요 (gitignore 처리)	개인적인 프로젝트 메모
settings.json	프로젝트 및 글로벌	예	권한(permissions), 훅(hooks), 환경 변수(env vars), 모델 기본값
settings.local.json	프로젝트 전용	아니요	개인별 오버라이드(overrides), 자동 gitignore 처리
.mcp.json	프로젝트 전용	예	팀이 공유하는 MCP 서버
skills/<name>/SKILL.md	프로젝트 및 글로벌	예	/name으로 호출되는 재사용 가능한 프롬프트
commands/*.md	프로젝트 및 글로벌	예	단일 파일 슬래시 명령어(slash commands)
agents/*.md	프로젝트 및 글로벌	예	서브에이전트(Subagent) 정의
rules/*.md	프로젝트 및 글로벌	예	주제별 범위의 지침, 선택적으로 경로 제한(path-gated) 가능

전형적인 레이아웃:

[IMG:1]

놓치기 쉬운 몇 가지 사항:

CLAUDE.md 파일은 계층적으로 적용(cascade)됩니다. 모노레포(monorepo)에서는 root/CLAUDE.md와 root/services/billing/CLAUDE.md가 모두...

billing 서비스에서 작업할 때 모두 로드됩니다. 폴더마다 서로 다른 컨벤션 (conventions)을 가진 코드베이스에 매우 강력합니다.

rules/*.md

경로 기반 제어 (path-gated) 방식입니다. 마이그레이션 (migrations) 폴더에 특화된 가이드는 CLAUDE.md에 포함되어서는 안 됩니다.

모든 세션의 용량을 불필요하게 늘리는 대신, .claude/rules/migrations.md에 두어야 합니다.

글로브 (glob) 패턴을 사용합니다.

명령어보다 기술 (Skills). .claude/commands/*.md와 .claude/skills/<name>/SKILL.md는

둘 다 슬래시 명령어 (slash commands)를 생성하지만, 기술 (skills)은 지원 파일 (supporting files), disable-model-invocation (모델 호출 비활성화), 허용된 도구 (allowed tools), 그리고 에이전트 오버라이드 (agent overrides)를 지원합니다. 새로운 작업은 skills/에 작성해야 합니다.

.claude/project-purge ~/path/to/repo --dry-run을 실행하여

Claude가 특정 프로젝트에 대해 보유하고 있는 로컬 상태를 정확히 확인하세요. 노트북을 양도하기 전에 유용합니다.

CLAUDE.md는

모든 세션이 시작될 때 로드됩니다. 잘못 작성하면 Claude가 똑같은 실수를 반복합니다. 제대로 작성하면 동일한 프롬프트로도 극적으로 더 나은 결과물을 얻을 수 있습니다.

Boris는 다른 무엇보다 중요한 두 가지 사항에 대해 단호하게 말합니다:

짧게 유지하세요. 파일이 길어지면 중요한 규칙이 묻힙니다. 모든 줄에 대해 스스로 물어보세요: "이 줄을 삭제했을 때 Claude가 실수를 하게 될까?" 만약 그렇지 않다면, 삭제하세요.

Claude가 스스로 규칙을 쓰게 하세요. Claude가 무언가 잘못했을 때마다 이렇게 말하세요: "이런 실수를 반복하지 않도록 CLAUDE.md를 업데이트해줘." Claude는 자신의 실수를 정밀한 규칙으로 추출하는 데 놀라울 정도로 능숙합니다. 몇 주 동안 이 작업을 반복하면, 해당 파일은 프로젝트의 모든 주의 사항 (gotcha)이 정리된 큐레이션 목록이 됩니다.

3.1 Claude Code 팀이 사용하는 실제 CLAUDE.md

Boris는 Claude Code 팀이 자신들의 리포지토리 (repo)에 직접 커밋하여 사용하는 실제 CLAUDE.md를 공유했습니다. 팀 전체가 일주일에 여러 번 기여합니다:

|
|

이것이 파일의 전부입니다. Claude가 추측할 수 없는 빌드 명령어 (build commands), 실행해야 하는 정확한 순서, 단일 테스트 호출 (single-test invocations), PR 전 의식 (pre-PR ritual) 등을 포함합니다. 스타일 선호도, 코드베이스 투어, 상투적인 문구는 없습니다.

Boris는 또한 PR 코멘트에서 @claude를 사용하여 Claude가 규칙을 직접 커밋하도록 합니다:

|
|

그는 이를 "복리 엔지니어링 (Compounding Engineering)"이라고 부릅니다. 모든 PR 리뷰가 CLAUDE.md를 개선하는 과정이 됩니다.

동일한 철학을 따르는 구체화된 템플릿:

|
|

"주의 사항 (Gotchas)" 섹션이 핵심입니다. 모든 항목은 Claude가 저지른 실수이며, 그 실수가 발생한 순간 기록된 것입니다.

CLAUDE.md에 포함되지 말아야 할 것: 표준 언어 관습, 파일별 코드베이스 설명, 긴 튜토리얼, API 문서, 빈번하게 변경되는 모든 것.

IMPORTANT 또는 YOU MUST와 같은 단어는 준수율을 높여줍니다. 무게감을 가질 수 있도록 절제해서 사용하세요.

@path 구문을 사용하여 다른 파일을 가져오면, 세부 사항을 불러오면서도 CLAUDE.md를 짧게 유지할 수 있습니다:

|
|

3.2 공부할 가치가 있는 인기 CLAUDE.md 파일들

mattpocock/skills CLAUDE.md: 기술(skills)을 어떻게 작성하고 테스트해야 하는지에 대한 관습
anthropics/claude-code-action: Anthropic의 자체 리포지토리(repo)로, 내부 도구와 동일하게 취급됨
awesome-claude-code: 다양한 언어 생태계에 걸친 수십 개의 공개 CLAUDE.md 파일 링크
claudelog.com: 스택별로 정리된 커뮤니티 큐레이션 예시

CLAUDE.local.md는 CLAUDE.md와 함께 존재하며 동일한 방식으로 로드되지만, 절대 사용자의 기기를 떠나지 않습니다. .gitignore에 추가하세요.

제가 사용하는 방식은 이렇습니다: 모든 PR을 오픈한 후 리뷰어들이 코멘트를 남깁니다. 그것들을 기억하려고 애쓰는 대신, 확인하는 즉시 CLAUDE.local.md에 쏟아붓습니다. 시간이 지나면 이는 제가 가장 자주 받는 피드백에 최적화된 개인화된 규칙 파일이 됩니다.

|
|

매 세션마다 로드되므로, Claude는 제가 언급하지 않아도 인증 실패(auth-failure) 테스트를 포함하고 OpenAPI 명세(spec)를 업데이트해야 한다는 것을 이미 알고 있습니다. 몇 주 안에 제 PR에 달리는 사소한 지적(Nitpick) 코멘트가 눈에 띄게 줄어들었습니다.

: 프로젝트별 피드백과 교정해야 할 개인적 습관이라는 두 섹션을 명확히 분리하세요. 이 둘을 섞으면 나중에 파일을 정리하기가 더 어려워집니다.

: 몇 주마다 정리(Prune)하세요. 근육 기억(muscle memory)이 된 것들은 삭제해도 됩니다. 파일은 당신이 이미 자동으로 수행하고 있는 것이 아니라, 여전히 배우고 있는 것을 포착해야 합니다.

Skills (기술)는 Claude Code를 “무엇이든 할 수 있는 에이전트”에서 “당신의 프로젝트를 위해 특정 작업을 정말 잘 수행하는 에이전트”로 진화시킵니다. Skills는 재사용 가능한 전문 지식의 단위입니다.

5.1 Skills의 실체

Skill은 .claude/skills/<name>/ 하위의 폴더입니다.

• .claude/skills/<name>/ (프로젝트 단위)
• ~/.claude/skills/<name>/ (글로벌 단위)

이 폴더는 프론트매터 (frontmatter)와 지침 (instructions)이 포함된 SKILL.md 파일을 포함합니다. 폴더 이름은 슬래시 명령어 (slash command)가 됩니다.

가장 단순한 형태의 Skill:

SKILL.md 내용:
|
|

~/.claude/skills/summarize-changes/SKILL.md에 저장하면,
/summarize-changes 명령어를 모든 세션에서 사용할 수 있습니다.

Skills를 강력하게 만드는 세 가지 요소:

점진적 공개 (Progressive disclosure). Claude는 세션 시작 시 프론트매터 설명(각각 약 100 토큰)만 로드합니다. 전체 SKILL.md 및 보조 파일들은 해당 Skill이 실제로 필요할 때만 로드됩니다.

Skills는 파일이 아닌 폴더입니다. 템플릿, 참조 문서, 스크립트, 설정 등을 하나로 묶을 수 있습니다. SKILL.md는 단지 진입점 (entry point)일 뿐입니다.

인라인 쉘 (Inline shell). !로 시작하는 라인은 명령어를 실행하고 호출 시점에 그 출력을 주입합니다.

프론트매터는 유용한 추가 기능을 지원합니다:

SKILL.md 내용:
|
|

부수 효과 (side effects)가 있는 Skill의 경우 disable-model-invocation: true를 사용하세요. 예를 들어, /ship 명령어는 Claude가 관련이 있다고 판단할 때가 아니라, 사용자가 명시적으로 입력했을 때만 배포를 수행하기를 원할 것입니다.

5.2 실제 Skill 작성하기: Go API 컨벤션 (Conventions)

Go 서비스 팀을 위해 컨벤션, 주의사항 (gotchas), 그리고 새로운 HTTP 핸들러를 위한 스캐폴딩 (scaffolding)을 다루는 완전한 Skill 예시:

SKILL.md 내용:
|
|
instructions 내용:
|
|

이러한 Skill을 사용하면 신입 개발자가 전체 코드베이스를 먼저 읽지 않고도 완전히 컨벤션에 맞는 엔드포인트를 추가할 수 있습니다.

5.3 설치할 가치가 있는 인기 Skills

mattpocock/skills: 가장 인기 있는 skills 저장소입니다 (약 10만 스타). 주요 기능:

• /grill-me: 코드가 작성되기 전에 계획에 대해 인터뷰를 진행합니다.
• /tdd: 레드-그린-리팩터 (red-green-refactor)를 엄격하게 강제합니다.
• /diagnose: 절제된 디버깅 (reproduce, minimize, hypothesize, fix, regression test)을 수행합니다.

설치: npx skills@latest add mattpocock/skills

Jeffallan/claude-skills: 66개의 언어별 프로필을 제공합니다: go-pro, python-pro, java-architect

, typescript-pro

, rust-engineer

, sql-pro

, 그리고 더 많이 제공합니다. 이들을 조합할 수도 있습니다. 예를 들어, Next.js 관련 작업 시 nextjs-developer와 typescript-pro를 함께 불러올 수 있습니다.

Anthropic의 공식 스킬 (Official skills):

/code-review
: 네 개의 병렬 에이전트가 diff(차이점)를 감사하며, 신뢰 점수가 부여된 결과만을 보고합니다.
/simplify
: 최근 코드를 검토하여 재사용성과 효율성을 확인합니다.
/batch
: 마이그레이션 작업을 수십 개의 병렬 에이전트로 분산하며, 각 에이전트는 자신만의 워크트리 (worktree)에서 작업합니다.
/webapp-testing
: Claude에게 Playwright 제어권을 부여하여 로컬 웹 앱을 테스트합니다.

: 하루에 두 번 이상 반복하는 일이 있다면, 그것을 스킬로 만드세요. 반복되는 모든 것은 작성되기를 기다리는 스킬입니다.

: 스킬을 git에 커밋하세요. 스킬은 조직의 지식 (institutional knowledge)이 되며, 새로운 엔지니어들은 저장소를 클론(clone)함으로써 팀의 축적된 관행을 무료로 습득할 수 있습니다.

서브에이전트 (Subagent)는 자신만의 도구 권한을 가진 별도의 컨텍스트 윈도우 (context window)에서 실행되며 요약본을 보고합니다. 메인 세션을 가득 채우지 않고도 50개의 파일을 읽을 수 있습니다. 이것이 서브에이전트가 제공하는 핵심 가치입니다.

서브에이전트는 .claude/agents/ (프로젝트 단위) 또는 ~/.claude/agents/ (글로벌 단위) 아래에 위치한 마크다운 (markdown) 파일이며, 이름, 설명, 도구 (tools), 모델 (model)을 선언하는 프론트매터 (frontmatter) 블록을 포함합니다.

6.1 /pr-review 에이전트 살펴보기

| |
| :--- | :--- |

Have the pr-review agent look at my current branch.라고 말하여 실행할 수 있습니다.

서브에이전트가 자신의 컨텍스트 내에서 모든 것을 처리하므로, 사용자의 메인 세션은 깔끔하게 유지됩니다.

주요 설계 선택 사항: tools는 읽기 전용 (read-only)입니다. 코드를 수정하는 리뷰어는 자신의 수정 사항을 옹호하는 쪽으로 편향될 수 있기 때문입니다. 높은 수준의 검토가 필요한 경우를 위해 model: opus를 사용합니다. "Do NOT flag" 섹션은 신호 대 잡음비 (signal-to-noise ratio)를 높게 유지해 줍니다.

6.2 가져다 쓸 만한 인기 있는 서브에이전트

Claude Code 팀은 다음과 같은 스킬들을 커밋하여 제공합니다: build-validator, code-architect, code-simplifier, oncall-guide, verify-app.

채택할 가치가 있는 커뮤니티 패턴들:

에이전트 (Agent)	역할
security-reviewer	인젝션 (injection), 인증 (auth), 비밀 정보 (secrets), 불안전한 역직렬화 (insecure deserialization) 검토
test-writer	테스트 생성, code-reviewer와 루프를 형성하여 협업
debugger	실패하는 테스트의 근본 원인 추적
performance-auditor	흐름(flows) 및 쿼리(queries) 프로파일링
migration-writer	프로젝트 컨벤션에 맞는 DB 마이그레이션 생성
release-notes-writer	커밋 히스토리를 기반으로 변경 로그 (changelogs) 작성

큐레이션된 저장소 (Curated repos): VoltAgent/awesome-claude-code-subagents (100개 이상의 에이전트) 및 hesreallyhim/a-list-of-claude-code-agents.

:체인 에이전트 (Chain agents): 세션 A가 구현을 완료한 후, Use the code-reviewer subagent to check the work.라고 호출합니다.

리뷰어는 구현 편향 (implementation bias) 없이 새로운 컨텍스트에서 평가를 수행합니다.

:추가 isolation: worktree

을 프론트매터 (frontmatter)에 추가하면 서브에이전트를 자체적인 git 워크트리 (worktree)에서 실행할 수 있습니다. 이는 수십 개의 병렬 에이전트를 통해 마이그레이션을 확산시킬 때 특히 강력합니다.

플러그인 (Plugins)은 기술, 훅 (hooks), 서브에이전트 (subagents), 그리고 MCP 서버를 하나의 설치 가능한 단위로 묶습니다. /plugin을 실행하여 마켓플레이스 브라우저를 엽니다. /plugin marketplace add owner/repo를 사용하여 커뮤니티 마켓플레이스를 추가할 수 있습니다.

첫날 설치 항목 (Day-one installs):