Claude Code 실전 활용법의 출발점은 매 세션마다 같은 지시를 반복하지 않는 것이다. 그냥 챗 인터페이스처럼 쓰면 “우리 프로젝트는 TypeScript strict 모드를 쓴다”, “테스트는 vitest로 돌린다” 같은 안내를 매번 다시 적게 된다. CLAUDE.md, 커스텀 슬래시 커맨드, Skills, Subagents, Plugins, Scope만 제대로 잡아두면 이 반복이 한 번의 설정으로 끝나고, 팀 전체가 같은 워크플로우를 공유하는 것도 그제야 가능해진다. 이 글에서는 Claude Code 실전 활용법을 여섯 가지 축으로 한 번에 정리한다. 각각이 언제 어떻게 쓰이는지를 코드 예제와 함께 본다.
이 글에서 다루는 내용
- CLAUDE.md — 프로젝트 메모리를 어디에 두고 무엇을 적는가
- 커스텀 슬래시 커맨드 —
.claude/commands/로 단축 명령 만들기 - Skills — Claude가 자동 호출하는 절차 패키지
- Subagents — 격리된 컨텍스트로 위임하는 독립 에이전트
- Plugins — 마켓플레이스 기반 사내 팀 배포
- User/Project Scope — 4단계 우선순위와 충돌 해결
Claude Code 실전 활용법의 출발점, CLAUDE.md는 어디에 두는가
CLAUDE.md는 Claude Code가 모든 세션 시작 시점에 자동으로 읽는 마크다운 파일로, 프로젝트 구조, 코딩 규칙, 빌드 명령처럼 매번 반복 설명할 가치가 없는 정보를 한 번 적어두는 용도다. 위치는 4단계로 나뉘는데, 프로젝트 루트의 CLAUDE.md(팀 공유, Git 커밋), .claude/CLAUDE.md(동일하게 동작), ~/.claude/CLAUDE.md(개인 전역), CLAUDE.local.md(개인 프로젝트별, gitignore 권장)이다. 더 구체적인 위치(프로젝트)가 일반적인 위치(개인 전역)를 우선한다.
| 스코프 | 경로 | 공유 범위 | Git 커밋 |
|---|---|---|---|
| 프로젝트 | ./CLAUDE.md 또는 ./.claude/CLAUDE.md | 팀 전체 | 예 |
| 개인 전역 | ~/.claude/CLAUDE.md | 본인 모든 프로젝트 | 아니오 |
| 개인 프로젝트별 | ./CLAUDE.local.md | 본인 + 이 프로젝트 | 아니오 |
| 조직 정책 (macOS) | /Library/Application Support/ClaudeCode/CLAUDE.md | 모든 사용자 | IT 배포 |
| 조직 정책 (Linux/WSL) | /etc/claude-code/CLAUDE.md | 모든 사용자 | IT 배포 |
| 조직 정책 (Windows) | C:\Program Files\ClaudeCode\CLAUDE.md | 모든 사용자 | IT 배포 |
CLAUDE.md에 적을 때 가장 흔한 실수는 “좋은 코드를 작성해 주세요” 같은 추상적 지시문을 적는 것이다. Claude Code 자체가 이미 좋은 코드를 지향하므로 이런 문장은 토큰만 잡아먹는다. 대신 빌드 명령(npm run dev), 디렉토리 규칙(API 핸들러: src/api/handlers/), 코드 컨벤션(2칸 들여쓰기, JSDoc 필수)처럼 검증 가능한 사실만 적는 편이 효과적이다.
# 기술 블로그 - 포스팅 작성 규칙
## 프로젝트 구조
- 포스팅 작성: posts/drafts/{날짜}-{주제}.md
- 최종 포스트: posts/published/{카테고리}/{포스트}.md
- WordPress 업로드 스크립트: scripts/publish-to-wp.js
## 빌드 및 실행
npm run publish -- --file {파일경로} # 임시글 업로드
node scripts/update-post.js --id {ID} # 기존 포스트 갱신
## 작성 규칙 (필수)
- 코드 블록 직후 3~4줄 설명 단락 추가
- 도입부는 bullet list 아닌 서술형 문단
- HTML 이스케이프(", ', &) 사용 금지
@docs/aeo-checklist.md
@docs/image-copyright.md위 CLAUDE.md가 프로젝트 메모리의 전형적인 모양이다. 마지막 두 줄의 @는 다른 마크다운 파일을 import하는 문법인데, 세션 시작 시점에 함께 로드된다. 재귀 import는 5단계까지 지원하고, 상대 경로는 CLAUDE.md 자신의 위치를 기준으로 해석된다. 더 자세한 규약은 Claude Code Memory 공식 문서에 정리돼 있다. CLAUDE.md를 세션 메모리와 연동해 더 영속적인 컨텍스트를 만드는 방법은 claude-mem 플러그인 활용 가이드에서도 다룬다.
커스텀 슬래시 커맨드는 어떻게 만드는가
커스텀 슬래시 커맨드는 .claude/commands/{name}.md 파일을 만드는 것만으로 /name 형태로 호출 가능한 단축 명령이 된다. 프로젝트 단위라면 .claude/commands/, 개인 전역이라면 ~/.claude/commands/에 둔다. 최신 Claude Code에서 슬래시 커맨드는 사실상 Skills 시스템에 통합됐기 때문에, 새로 만든다면 디렉토리 기반의 .claude/skills/{name}/SKILL.md 구조를 우선 검토하는 편이 좋다. 두 경로 모두 /name으로 호출되며, Plugin에서 노출되는 경우에 한해 콜론 네임스페이싱(/plugin-name:command)이 적용된다. 인자는 $ARGUMENTS(전체 문자열) 또는 위치 기반 $0, $1(셸 스타일 쿼팅 지원)로 본문에 삽입된다.
---
description: GitHub 이슈를 분석하고 코드를 수정합니다
argument-hint: [이슈번호]
allowed-tools: Bash(gh issue *) Read Edit
---
# 이슈 #$ARGUMENTS 수정
다음 단계를 따른다.
1. `gh issue view $ARGUMENTS`로 이슈 본문 확인
2. 관련 파일 식별 후 수정 계획 수립
3. 코드 수정 및 단위 테스트 추가
4. 커밋 메시지에 "Fix #$ARGUMENTS" 포함위 파일을 .claude/commands/fix-issue.md로 저장하면 /fix-issue 142 같은 호출이 가능해진다. frontmatter의 allowed-tools는 이 커맨드가 실행되는 동안 사용자 승인 없이 자동으로 허용할 도구 패턴이다. argument-hint는 입력 자동완성 UI에 뜨는 힌트 문자열이고, description은 /help나 커맨드 팔레트에 노출되므로 한 줄로 짧게 적어두는 편이 좋다.
---
description: 컴포넌트를 다른 프레임워크로 마이그레이션합니다
argument-hint: [컴포넌트명] [기존프레임워크] [신규프레임워크]
---
$0 컴포넌트를 $1에서 $2로 마이그레이션한다. 기존 동작과 테스트는 보존한다.$0, $1, $2를 사용하면 위치 기반 인자 처리가 된다. /migrate-component SearchBar React Vue로 호출하면 $0=SearchBar, $1=React, $2=Vue로 치환된다. 인자에 공백이 포함된 자연어를 받아야 한다면 $ARGUMENTS로 통째 받아 본문에서 분기 처리하는 편이 안전하다.
Skills는 슬래시 커맨드와 어떻게 다른가
Skills는 Claude가 대화 맥락을 보고 자동으로 호출 여부를 결정한다는 점에서 사용자가 명시적으로 입력해야 하는 슬래시 커맨드와 결정적으로 다르다. 파일 위치는 .claude/skills/{skill-name}/SKILL.md 구조이며, frontmatter의 description(필요 시 when_to_use까지 합산)이 Claude가 “이 스킬을 지금 써야 하나”를 판단하는 핵심 단서다. 두 필드의 합은 1,536자에서 잘리므로 핵심 트리거 키워드를 앞쪽에 배치하는 편이 좋다. 사용자가 직접 /skill-name으로 호출할 수도 있어 자동/수동 양방향 사용이 가능하다.
| 구분 | 슬래시 커맨드(레거시 단일 파일) | Skills(권장 디렉토리 구조) |
|---|---|---|
| 호출 방식 | 사용자가 명시적으로 /name 입력 | Claude가 맥락 보고 자동 호출 + 사용자 수동 호출 |
| 파일 구조 | 단일 마크다운 (name.md) | 디렉토리 + SKILL.md + 부가 파일 |
| description 역할 | UI 노출용 설명 위주 | 자동 호출 판단의 핵심 단서 |
| 부가 파일 | 함께 패키징 어려움 | scripts, examples 등 같은 디렉토리에 패키징 |
| 동적 컨텍스트 주입 | !`command` 표기 지원 | !`command` 표기 지원 |
| 자동 호출 차단 | disable-model-invocation: true | 동일 옵션 지원 |
---
name: pr-summary
description: GitHub Pull Request의 변경사항을 요약하고 리뷰 포인트를 추출한다
allowed-tools: Bash(gh *) Read
---
## PR 컨텍스트 자동 수집
- **Diff**: !`gh pr diff`
- **변경 파일 목록**: !`gh pr diff --name-only`
- **기존 코멘트**: !`gh pr view --comments`
## 작업
위에 자동 주입된 정보를 기반으로 다음을 출력한다.
1. PR이 무엇을 바꾸는지 3줄 요약
2. 리뷰어가 특히 주의 깊게 봐야 할 파일
3. 누락 가능성이 있는 테스트 케이스이 SKILL.md의 핵심은 !`gh pr diff` 표기다. 백틱 앞의 느낌표 구문은 스킬이 실행되기 직전에 셸 명령을 돌려 결과를 본문에 삽입하는 동적 컨텍스트 주입 문법이다. 그래서 Claude는 PR diff와 코멘트가 이미 채워진 프롬프트를 받게 되고, 별도의 도구 호출 없이 바로 요약을 시작할 수 있다. allowed-tools: Bash(gh *)가 없으면 gh 호출 때마다 권한 프롬프트가 뜨므로 함께 두는 편이 자연스럽다.
Subagents는 Skills와 어떻게 구분해서 써야 하는가
Subagents와 Skills의 결정적 차이는 컨텍스트 격리 여부다. Subagents는 Claude가 위임할 때마다 새 컨텍스트를 열어 독립 실행되지만, Skills는 메인 대화 컨텍스트에 그대로 로드돼 토큰을 공유한다. 즉 메인 대화 흐름에 영향을 주지 않고 깊은 탐색이 필요한 작업(코드 리뷰, 보안 감사, 리서치)은 Subagent로 위임하고, 절차나 가이드라인을 메인 작업에 인라인으로 끼워 넣는 용도라면 Skills가 맞다. 파일은 .claude/agents/{name}.md(프로젝트) 또는 ~/.claude/agents/{name}.md(개인 전역)에 둔다.
| 구분 | Skills | Subagents |
|---|---|---|
| 실행 환경 | 메인 대화 컨텍스트 | 격리된 독립 컨텍스트 |
| 컨텍스트 비용 | 메인에 합산 | 메인과 분리 |
| 시스템 프롬프트 | 메인과 동일 | agent 파일에서 별도 정의 |
| 도구 제한 | allowed-tools | tools 필드로 화이트리스트 |
| 호출 방식 | Claude 자동 + 사용자 /name | Claude가 자동으로 위임 |
| 주 용도 | 가이드라인, 체크리스트, 절차 인라인 | 독립 분석, 병렬 작업, 격리된 탐색 |
---
name: code-reviewer
description: 변경된 코드의 버그, 보안 취약점, 성능 이슈를 독립 컨텍스트에서 검토한다. PR 직전에 사용한다.
model: claude-opus-4-1
tools: [Bash(git *), Read, Grep]
---
당신은 코드 리뷰어다. 검토 시 다음을 점검한다.
1. 논리 오류와 엣지 케이스
2. 보안 취약점 (인젝션, 인증, 데이터 노출)
3. 성능 최적화 여지
4. 에러 처리 누락
구체적인 라인 번호와 함께 실행 가능한 제안만 한다.agent 파일은 frontmatter의 description이 위임 판단의 핵심이다. “PR 직전에 사용한다”처럼 사용 시점을 적어두면 Claude가 적절한 시점에만 위임한다. tools 필드로 git/Read/Grep만 허용하면 코드 리뷰 외 작업으로 권한이 새는 것도 함께 막을 수 있다. 공식 정의와 모든 frontmatter 필드는 Subagents 공식 문서에 정리돼 있다.
결정 가이드는 단순하다. Skills를 먼저 검토하되 단순 가이드라인이나 자주 쓰는 절차, 토큰 절약이 중요한 경우라면 Skills로 충분하다. 반대로 독립 분석이 필요하거나, 메인 대화에 탐색 로그를 노출하고 싶지 않거나, 여러 작업을 병렬로 돌리고 싶다면 Subagent로 승격해야 한다. 한 plugin 안에 Skills와 Subagents를 함께 묶어 배포하는 것도 가능하므로 둘 중 하나를 고르기보다는 역할에 따라 같이 사용하는 패턴이 일반적이다. 같은 격리 원리로 멀티 브랜치를 동시에 운영하는 패턴은 Git Worktrees 실전 활용 가이드에서 다뤘다.
Claude Code Plugins는 언제 써야 하는가
Plugins는 커맨드, Skills, agents, hooks, MCP 서버까지 한 패키지로 묶어 배포 가능한 단위로 만든다. 즉 한 사람이 쓰던 스킬 묶음을 팀 또는 커뮤니티에 공유하고 버전을 관리하고 싶을 때 plugin으로 승격하는 식이다. 매니페스트 파일은 .claude-plugin/plugin.json이고, 설치는 /plugin install {name} 또는 GitHub 마켓플레이스 등록 후 자동 배포된다.
blog-automation-plugin/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ ├── blog-topic/SKILL.md
│ ├── blog-write/SKILL.md
│ └── blog-review/SKILL.md
├── agents/
│ ├── seo-specialist.md
│ └── code-reviewer.md
├── hooks/
│ └── hooks.json
└── README.md위 디렉토리 구조가 블로그 자동화 plugin의 전형적인 모양이다. skills/, agents/, hooks/는 plugin 루트에 두고 .claude-plugin/ 안에는 plugin.json만 둬야 정상 인식된다. commands/ 디렉토리도 함께 둘 수는 있지만, 최신 가이드는 단일 마크다운 커맨드보다 디렉토리 기반의 Skills를 권장한다.
{
"name": "blog-automation",
"description": "WordPress 기술 블로그 자동화 — 주제 선정, 글 작성, 검토, 이미지 삽입, 업로드",
"version": "2.0.0",
"author": {
"name": "Your Name",
"email": "you@example.com"
},
"homepage": "https://github.com/username/blog-automation",
"repository": {
"type": "git",
"url": "https://github.com/username/blog-automation"
},
"license": "MIT"
}이 plugin.json은 마켓플레이스 노출과 버전 관리를 위한 최소 메타데이터다. name은 설치 후 스킬을 호출할 때 네임스페이스 접두어로 쓰이는데, 이 plugin이 노출하는 스킬은 /blog-automation:blog-topic 형태로 호출된다. version을 생략하면 git 커밋 SHA가 자동으로 들어가서 개발 단계에서는 비워둬도 동작은 하지만, 배포 시점에는 명시하는 편이 좋다. 등록과 배포 절차는 Claude Code Plugins 공식 문서에 단계별로 정리돼 있다.
사내 팀 배포용 Plugin은 어떻게 만들어 배포하는가
사내 팀 배포는 세 단계로 끝난다. plugin 디렉토리에 plugin.json을 만들고, 마켓플레이스 저장소에 marketplace.json을 두고, 팀원들이 프로젝트 settings.json에 그 마켓플레이스를 등록하는 흐름이다. Private GitHub 저장소를 그대로 마켓플레이스로 쓸 수 있어서 별도 인프라 없이 보안과 버전 관리를 동시에 챙길 수 있다. 새 팀원도 저장소를 클론한 뒤 /plugin install 한 줄로 동일한 환경을 받는다.
1단계 — Plugin 디렉토리와 plugin.json 작성
먼저 plugin 하나의 내부 구조다. 아래 트리는 한 plugin이 가져야 할 최소 폴더와 파일을 나타낸다.
blog-atomation/ # plugin 내부 구조
├── .claude-plugin/
│ └── plugin.json # plugin 메타데이터 (필수)
├── skills/
│ └── code-review/SKILL.md
├── agents/
│ └── security-reviewer.md
└── README.md{
"name": "blog-automation",
"description": "블로그 포스팅 자동화 — 주제 선정, 작성, 검토, 업로드",
"version": "1.0.0",
"author": { "name": "Dev Team" }
}위 디렉토리 구조와 plugin.json이 plugin의 최소 단위다. version을 SemVer로 명시하면 그 버전이 핀(pin)되어 명시적 업데이트가 필요하고, 생략하면 매 커밋이 새 버전으로 취급된다. 활발히 개발 중이면 생략하고, 사내 안정 배포 단계라면 SemVer로 핀하는 패턴을 권장한다. name은 kebab-case로 두어야 하며 호출 시 네임스페이스 접두어로 그대로 쓰인다.
2단계 — 마켓플레이스 저장소에 marketplace.json 두기
여러 plugin을 한 곳에서 카탈로그 형태로 관리하려면 별도의 마켓플레이스 저장소를 만든다. 저장소 루트의 .claude-plugin/marketplace.json이 카탈로그 역할을 한다. 마켓플레이스 저장소는 plugin과는 별개의 저장소이며, 모노레포 패턴이라면 plugin 디렉토리를 같은 저장소에 함께 두고, 멀티레포라면 plugin은 외부 저장소에 두고 카탈로그만 가리키게 한다.
your-organization/claude-plugins/ # 마켓플레이스 저장소 전체 구조
├── .claude-plugin/
│ └── marketplace.json # 카탈로그 (필수)
└── plugins/
└── blog-automation/ # 모노레포로 함께 둔 plugin (1단계 구조)
├── .claude-plugin/
│ └── plugin.json
├── skills/
├── agents/
└── README.md
# (deployment-tools는 별도 저장소 your-organization/deployment-tools에 위치)위 트리가 마켓플레이스 저장소 전체 모양이다. plugins/blog-automation/은 1단계에서 만든 plugin 내부 구조 그대로이고, 같은 저장소에 카탈로그(.claude-plugin/marketplace.json)와 plugin 디렉토리들이 공존한다. 멀티레포로 분리한 plugin(deployment-tools)은 이 트리 안에는 없고, marketplace.json의 source: {github, repo} 필드로 외부 저장소를 참조한다.
{
"name": "acme-team-plugins",
"owner": { "name": "ACME Dev Team" },
"plugins": [
{
"name": "blog-automation",
"source": "./plugins/blog-automation",
"version": "1.0.0"
},
{
"name": "deployment-tools",
"source": { "source": "github", "repo": "your-organization/deployment-tools" }
}
]
}source 필드가 핵심이다. 같은 마켓플레이스 저장소 안에 plugin 디렉토리를 두는 모노레포 패턴이라면 상대 경로(./plugins/...)를 쓰고, plugin마다 별도 저장소로 분리하고 싶다면 GitHub 객체({source, repo}) 형태를 쓴다. 위 예시는 두 패턴을 같이 보여주는데, blog-automation은 마켓플레이스 저장소 안에 함께 두고 deployment-tools만 별도 저장소(your-organization/deployment-tools)에 둔 형태다. 이 marketplace.json 자체는 사내 GitHub의 your-organization/claude-plugins 저장소 루트에 둔다고 가정하므로, 다음 단계의 extraKnownMarketplaces와 /plugin marketplace add가 모두 같은 저장소를 가리키게 된다.
3단계 — 팀원의 settings.json에 마켓플레이스 등록 (선택)
여기서부터는 팀 차원 자동 배포가 필요할 때 거치는 단계다. 1·2단계가 끝났다면 plugin 자체는 이미 설치 가능한 상태이고, 개인 사용자는 3단계를 건너뛰고 4단계 명령만으로도 곧장 설치할 수 있다. 다만 새 팀원이 저장소를 클론하는 순간 동일한 환경이 자동으로 깔리길 원한다면 settings.json에 마켓플레이스를 박아두는 편이 효율적이다.
{
"extraKnownMarketplaces": {
"acme-team-plugins": {
"source": { "source": "github", "repo": "your-organization/claude-plugins" }
}
},
"enabledPlugins": {
"blog-automation@acme-team-plugins": true
}
}이 설정을 프로젝트 .claude/settings.json에 넣어 Git에 커밋해 두면 새 팀원이 저장소를 클론하는 순간 마켓플레이스가 자동 인식된다. enabledPlugins로 기본 활성화 plugin을 지정해 두면 설치 후 별도 작업 없이 바로 호출 가능하다. Private 저장소를 마켓플레이스로 쓰는 경우라면 팀원이 GitHub에 인증돼 있거나 GITHUB_TOKEN 환경 변수가 설정돼 있어야 자동 fetch가 동작한다.
4단계 — 설치, 활성화, 버전 관리
3단계를 거쳤다면 새 팀원은 저장소 trust 후 /reload-plugins만 실행하면 마켓플레이스와 기본 활성 plugin이 자동으로 깔린다. 3단계를 건너뛰고 개인 사용자가 직접 설치하려면 아래 세 명령을 순서대로 실행한다.
/plugin marketplace add your-organization/claude-plugins
/plugin install blog-automation@acme-team-plugins
/reload-plugins첫 줄은 마켓플레이스를 Claude Code에 등록하는 명령이고, 두 번째는 plugin 설치, 세 번째는 즉시 활성화 명령이다. 설치 후 /blog-automation:blog-topic 형태로 plugin이 노출하는 skill을 호출할 수 있다. 새 버전을 배포하려면 plugin.json의 version을 1.0.1로 올려 커밋하고, 팀원은 /plugin marketplace update로 최신 버전을 받는다. CI에서 plugin lint와 tag 자동화까지 묶어두면 사내 표준 개발 환경이 한 줄 명령으로 동기화된다. 이 흐름을 IDE 단까지 확장하고 싶다면 Dev Container 표준화 가이드와 함께 쓰면 효과가 배가된다.
User Scope와 Project Scope는 어떻게 분리해야 하는가
Claude Code 설정은 Managed > Local > Project > User 순으로 우선순위가 적용되며, 같은 키가 여러 곳에 정의되면 더 구체적인 스코프가 일반적인 스코프를 덮어쓴다. 일반적으로 개인 전역 정보(개인 API 키, 에디터 선호도)는 User scope(~/.claude/settings.json)에, 팀 공유 정보(권한 정책, 팀 마켓플레이스)는 Project scope(.claude/settings.json)에 둔다. 머신 특화 임시 설정은 Local scope(.claude/settings.local.json)에 두고 gitignore한다.
| Scope | 경로 | 우선순위 | Git | 적합한 내용 |
|---|---|---|---|---|
| Managed | OS별 시스템 디렉토리 | 1 (최상) | 아니오 | 조직 보안 정책 |
| Local | .claude/settings.local.json | 2 | 아니오 | 개인 머신 임시 설정 |
| Project | .claude/settings.json | 3 | 예 | 팀 공유 권한, 마켓플레이스 |
| User | ~/.claude/settings.json | 4 (최하) | 아니오 | 개인 전역 선호도, API 키 |
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git *)",
"WebSearch"
]
},
"env": {
"GITHUB_TOKEN": "ghp_...",
"OPENAI_API_KEY": "sk-..."
}
}위는 ~/.claude/settings.json에 둘 만한 User scope 설정이다. 모든 프로젝트에서 공통으로 쓰는 npm/git 권한과 개인 토큰을 한 곳에 모아두는 식이다. 토큰은 dotenv 파일에 두는 편이 더 안전하긴 하지만, Claude Code가 셸 환경 변수와 별개로 자체 env 블록을 지원하기 때문에 머신 단위로 한 번만 설정하고 싶을 때 유용하다.
{
"permissions": {
"allow": [
"Bash(npm run publish:*)",
"Bash(node scripts/wp-categories.js)",
"Read(posts/**)",
"Read(scripts/**)"
],
"deny": [
"Read(.env*)",
"Read(secrets/**)"
]
},
}이 .claude/settings.json이 Project scope의 전형이다. 이 프로젝트에서만 허용할 npm 스크립트와 절대 읽으면 안 되는 비밀 파일을 한 파일에 모아 두고 Git에 커밋한다. 팀 단위 비공개 plugin 마켓플레이스도 settings.json에 함께 등록할 수 있는데, 정확한 키 이름과 스키마는 Discover and install plugins 공식 가이드에서 확인하는 것이 안전하다. 권한은 deny → ask → allow 순으로 평가되기 때문에, User scope에서 Bash(npm run *)을 허용했더라도 Project scope의 deny가 우선 차단한다. 활성 스코프 확인은 /status로 언제든 검사할 수 있다.
FAQ
CLAUDE.md와 README.md는 어떻게 다른가?
README.md는 사람이 읽고 프로젝트를 시작하기 위한 문서이고, CLAUDE.md는 Claude Code가 매 세션 시작 시점에 자동으로 읽는 컨텍스트 파일이다. 둘 다 마크다운이지만 CLAUDE.md는 빌드 명령, 디렉토리 규칙, 코드 컨벤션처럼 Claude의 행동을 직접 바꾸는 정보 위주이며, README.md에 적은 내용 중 Claude가 알아야 할 부분만 골라서 @README.md import로 가져오는 패턴이 자주 쓰인다.
Skills와 Subagents는 어떻게 구분되는가?
Skills는 마크다운 지침 파일을 Claude가 자동으로 로드해 자기 자신의 컨텍스트에 추가하는 방식이고, Subagents는 별도의 격리된 컨텍스트를 가진 에이전트를 호출해 작업을 위임하는 방식이다. 토큰 절약과 컨텍스트 격리가 필요하면 Subagent, 단순한 절차 자동화나 자동 호출이 필요하면 Skill을 선택한다. Subagent도 Plugin에 함께 묶어 배포할 수 있다.
슬래시 커맨드와 Skills 중 어느 쪽을 만들어야 하는가?
명시적으로 사용자가 트리거하는 명령(예: /deploy, /blog-upload)은 슬래시 커맨드가 적합하고, Claude가 대화 맥락에 따라 자동으로 활용해야 하는 절차(예: PR 요약, 코드 리뷰)는 Skills가 적합하다. Skills는 부가 파일과 동적 컨텍스트 주입이 가능하므로 절차가 복잡하거나 외부 명령 결과를 함께 묶고 싶을 때 더 유리하다. 다만 단순 한 줄 프롬프트라면 슬래시 커맨드가 더 가볍다.
Plugins는 npm처럼 공개 저장소가 있는가?
Anthropic이 공식 운영하는 Claude Plugins 마켓플레이스가 있으며, 별도로 GitHub 저장소를 통한 비공개 팀 마켓플레이스도 구성 가능하다. 비공개 마켓플레이스는 .claude/settings.json에 마켓플레이스 소스를 등록한 뒤 /plugin install 흐름으로 가져오는 식으로 구성하며, 정확한 키 이름과 구조는 Discover and install plugins 공식 문서에서 확인하는 것이 안전하다. npm 같은 메이저 패키지 매니저에 직접 등록되지는 않지만 GitHub URL 기반 배포 흐름이 표준이다.
Project scope 설정이 User scope를 무시하게 하려면 어떻게 하는가?
같은 키를 양쪽에 정의하면 Project scope가 자연스럽게 우선한다. 다만 배열 필드(permissions.allow 등)는 단순 덮어쓰기가 아니라 중복 제거 후 연결되므로, User scope의 allow를 무력화하고 싶다면 Project scope의 deny에 같은 패턴을 명시하면 된다. 예를 들어 User에서 Bash(npm run *)을 허용했더라도 Project의 deny에 Bash(npm run *)을 두고 화이트리스트를 따로 잡으면 deny가 이긴다.
마무리하며
지금까지 살펴본 Claude Code 실전 활용법 여섯 축이 처음부터 자연스러웠던 것은 아니다. 처음 Claude Code를 도입했을 때는 매 세션마다 “우리는 vitest를 쓰고, 테스트는 tests/ 디렉토리에 넣고, ESM이고…” 같은 안내를 반복했다. 한 달쯤 지나서 CLAUDE.md를 제대로 작성하고 나니 그 반복이 사라졌고, 그제야 Claude Code가 단순 챗봇이 아니라 프로젝트 컨텍스트를 함께 들고 다니는 동료에 가깝다는 인상이 들었다. 이후 슬래시 커맨드를 만들어 자주 쓰는 절차를 단축시켰고, Skills로 PR 리뷰 자동 호출까지 옮기고 나니 사실상 별도의 도구 없이도 일일 워크플로우가 정리됐다.
가장 큰 변화는 Plugin으로 묶어 팀에 배포한 뒤다. 누가 어떤 슬래시 커맨드를 쓰는지, 어떤 Skill이 필요한지 슬랙에서 묻는 일이 사라졌다. 새 팀원이 합류해도 /plugin install team/blog-automation 한 줄로 같은 환경이 만들어진다는 점이 가장 큰 보상이었다. 다음 포스팅에서는 hooks와 MCP 서버를 plugin에 같이 묶어 배포하는 패턴, 그리고 settings.json의 Auto Mode와 soft_deny를 활용한 안전 가드레일 설정을 다뤄볼 예정이다. Claude Code 실전 활용법은 한 번 잡아두면 팀 전체의 시간을 매주 단위로 절약해 주는 영역이라, 작은 단계부터 하나씩 도입해 보길 권한다.