Claude Code 설정 완전 가이드: CLAUDE.md, rules, Skills, settings.json 정리하기

Claude Code를 한동안 사용해 보니, 처음에는 "터미널에서 Claude에게 구현을 요청할 수 있는 도구" 정도의 이해만으로도 충분했습니다.

하지만 조금 본격적으로 사용하려고 하면, CLAUDE.md, .claude/rules/, Skills, subagents, agent teams, MCP, hooks, settings.json 등 설정 포인트가 한꺼번에 늘어납니다. 이 부분을 모호하게 둔 채 사용하면 편리한 반면 "어디에 무엇을 써야 하는지", "어디서부터가 위험한 조작인지"가 보이지 않게 됩니다.

이 기사에서는 2026년 6월 6일 시점의 공식 문서를 참고하며, 개인 개발 환경으로서 Claude Code를 어떻게 정비할지를 정리합니다.

주요 대상은 다음과 같습니다.

• Mac / Windows에서 Claude Code와 Claude Desktop을 도입하는 경우
• CLAUDE.md, rules, Skills, settings.json의 역할을 나누는 경우
• subagents / agent teams로 여러 역할을 부여하는 경우
• Google Calendar / Gmail 등의 도구 연동을 고려하는 경우
• 이미지 생성이나 일상 사무에 사용할 때의 현실적인 선을 긋는 경우
• 보안 사고를 피하기 위한 설정을 처음부터 적용하는 경우

※ Claude Code는 업데이트가 빠르므로, 명령어와 설정 키는 공식 문서도 확인해 주세요.

제 개인적으로는 Claude Code의 설정을 "기억"과 "제어"로 나누면 이해하기 쉬워졌습니다.

위치	주요 역할	예시
CLAUDE.md	매번 읽어주길 바라는 전제 및 작업 방침	아키텍처, 테스트 명령어, 리뷰 관점
.claude/rules/*.md	조건부로 읽고 싶은 규칙	src/api/**/*.ts에만 적용되는 API 규칙
.claude/skills/*/SKILL.md	반복해서 사용하는 절차나 전문 태스크	PR 리뷰, 릴리스 절차, 장애 조사
.claude/agents/*.md	역할을 가진 서브 에이전트 (subagents)	security-reviewer, sre-investigator
.claude/settings.json	권한, hooks, 환경 변수 등의 제어	Read(./.env) 거부, 테스트만 허용
.mcp.json / ~/.claude.json	외부 도구 연결	GitHub, Sentry, PostgreSQL, Google 계열 도구

대략 말하자면, CLAUDE.md는 "기억해 두었으면 하는 것", settings.json은 "지키게 하고 싶은 경계", Skills는 "재사용하고 싶은 절차"입니다.

공식 문서에서는 Claude Code의 도입 방법으로 네이티브 인스톨러 (native installer), Homebrew, WinGet, npm, Linux 패키지 등이 안내되어 있습니다.

Mac / Linux / WSL이라면 우선 다음과 같습니다.

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell이라면 다음과 같습니다.

irm https://claude.ai/install.ps1 | iex

Windows CMD라면 다음과 같습니다.

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows는 네이티브 실행과 WSL 실행을 선택할 수 있습니다. Windows 측의 프로젝트를 다룬다면 네이티브가, Linux에 가까운 툴체인 (toolchain)이나 샌드박스 (sandbox)를 중시한다면 WSL 2가 다루기 쉽습니다. 네이티브 Windows에서는 Git for Windows를 설치해 두면 Claude Code가 Bash tool을 사용하기 쉬워집니다.

설치 후에는 임의의 리포지토리 (repository)에서 실행합니다.

claude

버전 확인은 다음과 같습니다.

claude --version

수동 업데이트는 다음과 같습니다.

claude update

Mac에서 Homebrew를 사용하고 있는 경우에는 공식 문서에 있는 cask를 사용할 수 있습니다.

brew install --cask claude-code

claude-code

claude-code는 stable(안정) 지향적이며, claude-code@latest는 새로운 릴리스를 빠르게 추적하는 채널입니다. 업무용 PC에서는 stable을, 검증용 PC에서는 latest를 사용하는 방식이 무난하다고 느낍니다.

brew install --cask claude-code@latest

Homebrew를 경유하는 경우, 업데이트는 Homebrew 측에서 수행합니다.

brew upgrade claude-code

Windows에서 패키지 관리를 통합하고 싶다면, 공식 FAQ에서는 WinGet도 안내하고 있습니다.

winget install Anthropic.ClaudeCode

업데이트는 다음과 같습니다.

winget upgrade Anthropic.ClaudeCode

Node.js 18 이상이 설치되어 있다면, npm으로도 설치할 수 있습니다.

npm install -g @anthropic-ai/claude-code

단, 공식 문서에서는 sudo npm install -g가 권한 및 보안 문제로 이어질 수 있으므로 피하도록 안내하고 있습니다. npm으로 설치하는 경우에도 최신 버전으로 올릴 때는 다음과 같이 명시합니다.

npm install -g @anthropic-ai/claude-code@latest

mise를 사용하는 환경에서는 registry 상에 claude-code가 있었습니다. 내부적으로는 npm 패키지를 사용하는 형태이므로, 공식 인스톨러와는 별개의 경로로 생각해야 합니다.

mise use -g claude-code@latest

프로젝트마다 고정하고 싶은 경우에는 .mise.toml에 설정합니다.

mise use claude-code@latest

mise를 경유하는 경우에도 Claude Code 자체의 공식 문서에서 안내하는 업데이트, 권한, 지원 범위와 차이가 발생할 가능성이 있습니다. 팀 표준으로 삼기 전에 실제 설치 경로와 업데이트 절차를 확인해 두는 것이 좋습니다.

Chocolatey에도 claude-code 패키지가 있습니다. 다만, 기사 작성 시점에서는 공식 문서의 주요 경로로서 PowerShell 인스톨러나 WinGet이 더 전면에 나와 있습니다.

업무용 PC에서 Chocolatey 관리를 사용하는 경우에는 사내 미러(mirror)나 승인된 패키지로 취급할 수 있는지 확인한 후 사용하는 것이 좋습니다.

choco install claude-code

Nix / NixOS에서는 nixpkgs 측에 claude-code 패키지가 있습니다. 재현성(reproducibility)을 중시하는 개발 환경이라면 선택지가 될 수 있습니다.

일시적으로 테스트하려면 다음과 같은 형태를 사용합니다.

nix shell nixpkgs#claude-code

flake로 고정하는 경우에는 팀의 Nix 운영 방식에 맞춰 devShells에 포함합니다. Claude Code는 업데이트가 빠르기 때문에, nixpkgs의 추종 타이밍과 공식 최신 버전 사이의 차이를 살펴볼 필요가 있습니다.

Claude Desktop은 Claude의 데스크톱 애플리케이션입니다. Mac과 Windows용으로 제공됩니다.

Claude Code CLI만으로도 개발은 가능하지만, Desktop을 설치해 두면 다음과 같은 용도로 편리합니다.

• 로컬/SSH 세션을 GUI로 다룸
• 이미지나 PDF 등의 첨부 파일 사용
• Connectors UI를 통해 Google Calendar, Slack, GitHub, Notion 등을 연결
• Desktop extensions를 통해 로컬 앱이나 데이터에 연결
• 여러 세션을 탭(tab) 형태로 다룸

도입은 공식 다운로드 페이지에서 진행합니다.

Mac은 .dmg, Windows는 인스톨러를 사용합니다. Windows에서 Code tab을 사용하는 경우 Git for Windows가 필요할 수 있으므로, 미리 설치해 두면 막힘없이 진행할 수 있습니다.

CLI와 Desktop은 비슷해 보이지만 완전히 같지는 않습니다. 예를 들어 Desktop은 첨부 파일이나 Connectors UI가 편리합니다. 반면, agent teams나 일부 터미널 대화 명령은 CLI 측의 기능입니다. 저는 "리포지토리 작업은 CLI, 자료·일상 작업·커넥터 확인은 Desktop"으로 나누는 것이 적절하다고 느꼈습니다.

CLAUDE.md는 Claude Code가 매번 읽어주길 바라는 프로젝트의 전제 조건을 작성하는 파일입니다.

공식 문서에서는 주로 다음 위치들을 안내하고 있습니다.

스코프 (Scope)	위치	용도
사용자 (User)	~/.claude/CLAUDE.md	개인의 작업 스타일
프로젝트 (Project)	./CLAUDE.md 또는 ./.claude/CLAUDE.md	팀 공유 전제 조건
로컬 (Local)	./CLAUDE.local.md	개인의 로컬 사정
관리 설정 (Admin)	OS별 관리 디렉토리	조직 전체의 방침

처음에는 /init 명령어로 생성한 뒤, 나중에 수동으로 수정하는 것이 편합니다.

claude
/init

저라면 첫 CLAUDE.md는 이 정도로 작성하겠습니다.

# Project Guide
## Project overview
- This repository contains a Next.js application and Terraform modules.
...

포인트는 너무 추상적으로 쓰지 않는 것입니다.

품질을 높인다보다는 pnpm test를 실행한다가 더 효과적입니다. 안전하게 작업한다보다는 terraform apply를 실행하지 않는다가 사고를 줄일 수 있습니다.

참고로, CLAUDE.md는 '문맥 (Context)'입니다. 강제성이 있는 가드 (Guard)가 아닙니다. 반드시 막아야 하는 작업은 settings.json의 permissions.deny나 hooks를 통해 제어합니다.

이전에는 "규칙을 작성한다면 CLAUDE.md에 전부 모은다"라고 생각했지만, 지금은 .claude/rules/를 사용하는 것이 정리하기 더 쉽습니다.

예시입니다.

your-project/
├── CLAUDE.md
└── .claude/
...

전체에 적용되는 규칙은 일반적인 Markdown 형식으로 둘 수 있습니다.

# Testing rules
- Prefer focused tests close to the changed module.
- When changing shared logic, add regression tests.
...

특정 경로에만 적용하고 싶을 때는 YAML frontmatter의 paths를 사용합니다.

---
paths:
- "src/api/**/*.ts"
...

저의 구분 방식은 다음과 같습니다.

위치	작성 내용
CLAUDE.md	매번 필요한 짧은 전제 조건
.claude/rules/	영역별·경로별 작업 규칙
Skills	절차화할 수 있는 작업
hooks / permissions	준수해야 할 제약 사항

Skills는 Claude에게 추가적인 절차나 지식을 전달하는 메커니즘입니다. .claude/skills/<skill-name>/SKILL.md에 두면 프로젝트 전용 Skill이 됩니다.

예시로, PR 리뷰용 Skill을 만들어 보겠습니다.

.claude/
└── skills/
    └── pr-review/
...

SKILL.md의 예시입니다.

---
name: pr-review
description: Review the current git diff for correctness, tests, and security risks.
...

사용할 때는 Claude Code 상에서 다음과 같이 호출합니다.

/pr-review

Skills는 CLAUDE.md가 비대해졌을 때 내용을 분산시키는 용도로 사용할 수 있습니다. "매번 읽을 필요는 없지만, 작업 시에는 필요한 것"을 옮기면 컨텍스트 (Context)를 절약할 수 있습니다.

settings.json은 Claude Code의 제어 측면입니다. 공식 문서에서는 주로 다음 위치들을 안내하고 있습니다.

스코프 (Scope)	위치	Git 관리
사용자 (User)	~/.claude/settings.json	하지 않음
프로젝트 (Project)	.claude/settings.json	함
로컬 (Local)	.claude/settings.local.json	하지 않음
관리 설정 (Admin)	OS별 관리 디렉토리	조직 관리

최소한, 프로젝트에는 이 정도는 넣어두고 싶습니다.

{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
...

여기서 중요한 것은, CLAUDE.md에 "읽지 마세요"라고 쓰는 것만으로는 부족하다는 점입니다. .env나 secrets/는 permissions.deny에 넣어 실행 경계 (Execution Boundary)로서 차단해야 합니다.

개인적인 실험은 .claude/settings.local.json으로 분리합니다.

{
"permissions": {
"allow": [
...

.claude/settings.local.json은 생성 시 git ignore되는 취급을 받지만, 리포지토리의 .gitignore에도 명시해 두는 것이 안심됩니다.

subagents는 특정 역할을 가진 AI 작업자입니다. 프로젝트에서는 .claude/agents/에 배치할 수 있습니다.

예시입니다.

.claude/
└── agents/
├── security-reviewer.md
...

security-reviewer.md의 예시입니다.

---
name: security-reviewer
description: Reviews code and configuration for security risks before release.
...

subagent는 독립된 컨텍스트 (Context)에서 작업하며, 결과를 메인 대화로 반환합니다. 대규모 조사 위임, 리뷰 관점 분리, 문서 담당 생성 등의 용도에 적합합니다.

agent teams는 여러 개의 Claude Code 세션을 팀처럼 동작시키는 실험적인 기능입니다. 공식 문서에 따르면 기본적으로는 비활성화되어 있으며, 환경 변수를 통해 활성화하는 방식입니다.

{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
...

subagents와의 차이점은 작업자들끼리 직접 상호작용할 수 있는지 여부입니다.

메커니즘	적합한 작업
subagents	조사, 리뷰, 요약 등 결과만 반환하면 되는 작업
agent teams	다각도 연구, 병렬 리뷰, 프론트/백엔드/테스트 분담

예를 들어, 큰 변경 사항을 적용하기 전에 다음과 같이 요청할 수 있습니다.

Create an agent team with three teammates:
1. security reviewer
2. performance reviewer
...

아직 실험적인 기능이므로, 일상적인 운영 표준으로 삼기 전에 비용, 권한, 로그, 리뷰 절차를 결정한 후 사용하는 것이 좋다고 생각합니다.

Claude Code는 실행된 디렉토리를 기준으로 프로젝트를 바라봅니다.

cd path/to/your-project
claude

다른 디렉토리도 보여주고 싶다면 --add-dir을 사용합니다.

claude --add-dir ../shared-docs

단, 추가된 디렉토리의 CLAUDE.md는 기본적으로 읽히지 않습니다. 추가된 디렉토리 측의 기억(Memory)도 읽고 싶다면 공식 문서에 있는 환경 변수를 사용합니다.

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-docs

이 기능들은 편리하지만, 보여주는 범위가 넓어질수록 리스크도 증가합니다. 저라면 처음에는 리포지토리 단위로 범위를 제한하고, 공유 문서나 다른 리포지토리는 필요할 때만 추가하겠습니다.

Claude Code는 MCP (Model Context Protocol)를 통해 외부 도구에 연결할 수 있습니다. 공식 문서에서는 MCP를 통해 이슈 트래커 (Issue Tracker), 모니터링 도구, DB, GitHub, Gmail 초안 등을 다루는 예시가 소개되어 있습니다.

Claude Desktop의 Code 탭에서는 Connectors UI를 통해 Google Calendar, Slack, GitHub, Linear, Notion 등을 추가할 수 있습니다. 일상적인 이용에서는 CLI에서 JSON을 작성하는 것보다 Desktop의 Connectors UI를 통해 시작하는 것이 더 간편합니다.

반면, Gmail이나 Google Calendar 등 일부 Anthropic-hosted 커넥터는 Claude Code의 로컬 OAuth로는 사용할 수 없는 경우가 있다고 문서에 주의사항이 명시되어 있습니다. 즉, Google 계열 도구는 다음과 같이 생각하는 것이 현실적입니다.

하고 싶은 일	입구
Google Calendar를 보고 일정 조정	Claude Desktop의 Connectors UI
...

예를 들어, 일상적인 사무 처리라면 다음과 같이 부탁할 수 있습니다.

내일 빈 시간을 확인해서, A님과의 30분 미팅 후보를 3개 제안해 주세요.

이 이메일 스레드에 대한 답장 초안을 작성해 주세요.
전송은 하지 말고, 초안으로서 자연스러운 경어를 사용해 주세요.

개인적으로는 '읽기, 요약, 초안 작성'까지는 상당히 사용하기 편하다고 느끼고 있습니다. 전송, 삭제, 외부 공유, 일정 확정은 인간의 확인 과정을 남겨두는 것이 안심됩니다.

Claude는 이미지를 이해하거나 디자인 안, 카피, 프롬프트, SVG/HTML 안을 만드는 데 능숙합니다. 반면, Claude Code 단독을 '이미지 생성 엔진'으로 다루기보다는, 이미지 생성 도구나 디자인 도구와 연결하는 것이 현실적입니다.

사용 예시입니다.

이 기사의 아이캐치 이미지를 만들고 싶습니다.
Qiita용으로, Claude Code 설정의 레이어 구조가 전달되는 구도를 3안 제안해 주세요.
각 안(案)에 대해, 이미지 생성 AI를 위한 영어 프롬프트도 만들어 주세요.

X(구 Twitter) 게시용으로, 이 기사의 요점을 3장의 슬라이드 이미지로 만듭니다.
1장은 과제, 2장은 설정 레이어, 3장은 보안 체크리스트로 구성해 주세요.
Canva나 Figma에 붙여넣기 쉬운 문구로 작성해 주세요.

광고나 SNS 소재의 경우, 다음과 같은 역할 분담이 다루기 쉽습니다.

작업	Claude에게 맡기기 쉬운 정도
컨셉	상당히 적합함
...

규모가 큰 변경의 경우, 갑자기 편집하게 하지 말고 먼저 계획을 세우도록 합니다.

구현 전에 계획만 세워 주세요.
대상 파일, 변경 방침, 테스트 방침, 리스크를 정리해 주세요.
아직 파일은 편집하지 마세요.

hooks를 사용하면 도구 실행 전후 등의 타이밍에 스크립트를 실행할 수 있습니다. 예를 들어, 위험한 명령어를 감지하거나, 편집 후에 formatter를 실행하는 등의 작업이 가능합니다.

단, hooks 자체도 코드 실행이므로, 신뢰할 수 없는 리포지토리의 .claude/settings.json은 주의 깊게 살펴본 뒤에 trust(신뢰)해야 합니다.

CI에서 Claude Code를 사용하는 경우에는 로컬의 허술한 권한 설정을 그대로 가져오지 않는 것이 좋습니다.

저라면 CI 용도는 다음과 같이 한정하겠습니다.

• PR 차이점(diff) 리뷰
• 테스트 실패 로그 요약
• 변경 영향 파악
• 릴리스 노트 초안 작성

쓰기(Write) 작업을 수행하는 경우에도, 처음에는 '댓글 달기', '수정안 제시' 단계까지만 제한합니다. 직접 push나 운영 환경 조작까지 맡기는 것은 감사 로그(Audit log), 권한 분리, 리뷰, 롤백(Rollback) 체계가 갖춰진 이후에 해야 합니다.

Claude Code는 기업용으로 Amazon Bedrock나 Google Vertex AI 등 기존 클라우드 인프라를 사용하는 구성도 안내되어 있습니다. 회사에서 사용한다면 개인 계정으로 직접 사용하는 것보다 SSO, 로그, 데이터 보존, 모델 제공 경로를 통일하는 것이 운영하기 쉽습니다.

Claude Code는 편리하지만, 로컬 파일을 읽고 명령어를 실행하며 외부 서비스에도 접속할 수 있습니다. 즉, 개발자 PC 상에서 상당히 강력한 권한을 가진 도구입니다.

최소한, 다음 사항들은 처음부터 설정해 두고 싶습니다.

리스크	대책
.env나 비밀키 읽기	permissions.deny로 Read(./.env*)나 Read(./secrets/**)를 거부
위험한 명령어 실행	terraform apply, kubectl delete, git reset --hard 등을 거부
의심스러운 설치 스크립트	`curl *
MCP를 통한 데이터 유출	접속처를 승인된 곳으로 한정하고, OAuth scope를 최소화
프롬프트 인젝션 (Prompt Injection)	외부 콘텐츠를 읽는 MCP를 너무 신뢰하지 않음
...	.claude/settings.json과 관리 설정으로 표준화

보안용 rules도 배치해 두면 편리합니다.

# 보안 규칙 (Security rules)
- `.env`, `.env.*`, 개인 키(private keys) 또는 `secrets/` 하위의 파일은 절대 읽지 마십시오.
- 비밀 정보(secrets)를 이슈(issues), 풀 리퀘스트(pull requests), 로그(logs) 또는 채팅 응답에 절대 붙여넣지 마십시오.
...

단, 이것은 어디까지나 "행동 지침"입니다. 강제하고 싶은 사항은 settings.json, hooks, MDM/Intune/Jamf 등의 관리 설정에 맡깁니다.

새로운 리포지토리(repository)에서 Claude Code를 사용하기 시작한다면, 저는 다음 순서로 정리합니다.

claude
/init

그 후, 다음 파일들을 만듭니다.

your-project/
├── CLAUDE.md
└── .claude/
...

처음부터 모든 것을 다 채우기보다, 다음 3가지만 결정하는 것이 좋은 시작이라고 생각합니다.

• 무엇을 읽게 하지 않을 것인가
• 무엇을 실행하게 하지 않을 것인가
• 변경 후에 무엇을 확인하게 할 것인가

이 3가지만 있어도 Claude Code의 편리함을 유지하면서 사고의 불씨를 상당히 줄일 수 있습니다.

Claude Code의 설정은 처음에는 다소 광범위해 보일 수 있습니다. 하지만 역할별로 나누면 정리하기 쉽습니다.

• CLAUDE.md: 매번 읽어주기를 바라는 전제 조건
• .claude/rules/: 영역별·경로별 규칙
• Skills: 반복되는 절차
• subagents: 전문 작업자
• agent teams: 여러 세션의 역할 분담
• MCP / Connectors: 외부 도구 연동
• settings.json: 권한과 실행 경계

개인적으로 Claude Code는 "설정을 작성한 후부터가 본게임"인 도구라고 느끼고 있습니다.

편리하게 만들수록 읽을 수 있는 것, 실행할 수 있는 것, 연결할 수 있는 것이 늘어납니다. 그렇기에 처음에 CLAUDE.md로 작업 방침을 맞추고, settings.json으로 위험한 조작을 차단하며, Skills나 subagents를 통해 재사용할 수 있는 형태로 만들어 두는 것이 중요합니다.

다음에는 Claude Code/Codex와 같은 AI 코딩 환경에서 철저하게 제거해야 할 보안 리스크를 조금 더 깊이 있게 정리해 보고 싶습니다.

• Set up Claude Code - Anthropic
• Claude Code settings - Anthropic
• How Claude remembers your project - Anthropic
• Extend Claude with skills - Anthropic
• Create custom subagents - Anthropic
• Orchestrate teams of Claude Code sessions - Anthropic
• Connect Claude Code to tools via MCP - Anthropic
• Claude Code on desktop - Anthropic
• Install Claude Desktop - Anthropic Help Center
• Claude Code user FAQ - Anthropic Help Center
• Chocolatey Software | Claude Code
• MyNixOS | claude-code