Claude를 제대로 설정하는 방법을 한 번에 정리한 가이드.

source https://blog.dailydoseofds.com/p/anatomy-of-the-claude-folder

Claude Code를 쓰는 사람들은 보통 .claude 폴더를 블랙박스처럼 대하는 경우가 많아요. 있는 건 압니다. 프로젝트 루트에 생긴 것도 봤죠. 그런데 막상 열어보진 않았고, 안에 든 파일들이 각각 무슨 역할을 하는지도 잘 모르는 경우가 대부분입니다.

솔직히 좀 아깝죠.

.claude 폴더는 Claude가 프로젝트 안에서 어떻게 움직일지를 정하는 컨트롤 센터에 가깝습니다.

^{image: https://blog.dailydoseofds.com/p/anatomy-of-the-claude-folder}

여기에는 지시문, 커스텀 커맨드, 권한 규칙, 심지어 세션을 넘겨 이어지는 Claude의 메모리까지 들어 있어요. 뭐가 어디에 있고 왜 필요한지만 감을 잡아도, Claude Code를 팀 스타일에 맞게 훨씬 정교하게 다듬을 수 있습니다.

이 글에서는 매일 쓰게 될 파일부터 한 번 설정해두고 거의 안 건드리게 되는 파일까지, .claude 폴더의 구조를 차근차근 훑어볼게요.

폴더는 하나가 아니라 둘입니다

들어가기 전에 먼저 알아두면 좋은 게 하나 있어요. .claude 디렉터리는 사실 하나가 아니라 둘입니다.

하나는 프로젝트 안에 있고, 다른 하나는 홈 디렉터리에 있어요:

^{image: https://blog.dailydoseofds.com/p/anatomy-of-the-claude-folder}

프로젝트 수준 폴더에는 팀 설정이 들어갑니다. 이건 git에 커밋하죠. 그래서 팀원 모두가 같은 규칙, 같은 커스텀 커맨드, 같은 권한 정책을 공유하게 됩니다.

반대로 전역 ~/.claude/ 폴더에는 개인 취향이나 머신 로컬 상태가 들어갑니다. 예를 들면 세션 기록이나 자동 메모리 같은 것들이요.

CLAUDE.md: Claude의 사용 설명서

이건 전체 시스템에서 가장 중요한 파일입니다. Claude Code 세션을 시작하면 Claude가 가장 먼저 읽는 게 CLAUDE.md예요. 이 파일은 그대로 system prompt에 들어가고, 대화 내내 계속 참고됩니다.

아주 단순하게 말하면, CLAUDE.md에 써둔 내용은 Claude가 따릅니다.

예를 들어 “구현 전에 항상 테스트부터 작성해”라고 적어두면 그대로 그렇게 해요. “에러 처리는 console.log 말고 커스텀 로거를 써”라고 적어두면 매번 그 규칙을 지키려고 합니다.

가장 흔한 구성은 프로젝트 루트에 CLAUDE.md 하나를 두는 방식이에요. 하지만 모든 프로젝트에 공통으로 적용할 전역 취향을 위해 ~/.claude/CLAUDE.md를 둘 수도 있고, 특정 폴더에만 적용할 규칙을 위해 하위 디렉터리 안에 둘 수도 있습니다. Claude는 이런 파일들을 전부 읽고 합쳐서 사용해요.

CLAUDE.md에는 뭘 넣는 게 좋을까

여기서 많이들 실수해요. 너무 많이 쓰거나, 반대로 너무 비워두거나요. 실제로 잘 먹히는 건 대체로 이 정도입니다.

이렇게 쓰세요:

• 빌드, 테스트, 린트 명령 (npm run test, make build 같은 것들)

• 핵심 아키텍처 결정 사항 (“우리는 Turborepo 기반 모노레포를 쓴다” 같은 정보)

• 바로 드러나지 않는 주의점 (“TypeScript strict mode가 켜져 있고, 사용하지 않는 변수는 에러다”)

• import 관례, 네이밍 패턴, 에러 처리 스타일

• 주요 모듈의 파일 및 폴더 구조

이런 건 빼는 게 좋아요:

• 원래 linter나 formatter 설정에 들어가야 할 내용

• 링크로 대체할 수 있는 문서를 통째로 붙여넣는 것

• 이론 설명이 길게 이어지는 문단

CLAUDE.md는 200줄 이하로 유지하는 걸 추천합니다. 그보다 길어지면 컨텍스트를 너무 많이 먹기 시작하고, 오히려 Claude의 지시 준수율이 떨어져요.

아래는 작지만 꽤 실용적인 예시입니다:

# Project: Acme API

## Commands
npm run dev          # Start dev server
npm run test         # Run tests (Jest)
npm run lint         # ESLint + Prettier check
npm run build        # Production build

## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- All handlers live in src/handlers/
- Shared types in src/types/

## Conventions
- Use zod for request validation in every handler
- Return shape is always { data, error }
- Never expose stack traces to the client
- Use the logger module, not console.log

## Watch out for
- Tests use a real local DB, not mocks. Run `npm run db:test:reset` first
- Strict TypeScript: no unused imports, ever

대략 ~20줄 정도예요. 이 정도만 있어도 Claude가 이 코드베이스에서 생산적으로 움직이는 데 필요한 정보는 충분히 얻습니다. 자잘한 걸 계속 다시 물어보는 일도 줄고요.

개인 오버라이드를 위한 CLAUDE.local.md

가끔은 팀 전체가 아니라 나만의 취향이 있죠. 예를 들어 내가 선호하는 테스트 러너가 따로 있거나, Claude가 파일을 열 때 특정 패턴을 따랐으면 할 수도 있습니다.

그럴 땐 프로젝트 루트에 CLAUDE.local.md를 만들면 됩니다. Claude는 이 파일도 메인 CLAUDE.md와 함께 읽어요. 그리고 이 파일은 자동으로 gitignore 처리되기 때문에, 내 개인 설정이 저장소에 섞여 들어갈 일도 없습니다.

^{image: https://blog.dailydoseofds.com/p/anatomy-of-the-claude-folder}

rules/ 폴더: 커질수록 더 유용해지는 모듈형 지시문

CLAUDE.md는 단일 프로젝트에서는 정말 잘 작동합니다. 그런데 팀이 커지기 시작하면, 어느 순간 아무도 관리하지 않고 다 같이 무시하는 300줄짜리 CLAUDE.md가 되기 쉽습니다.

이걸 해결하려고 있는 게 rules/ 폴더예요.

.claude/rules/ 안의 모든 마크다운 파일은 CLAUDE.md와 함께 자동으로 로드됩니다. 즉, 커다란 파일 하나에 다 때려 넣는 대신 관심사별로 규칙을 나눌 수 있는 거죠.

.claude/rules/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.md

이렇게 나누면 각 파일이 짧고 초점이 분명해집니다. API 규칙을 담당하는 사람은 api-conventions.md를 손보면 되고, 테스트 기준을 맡은 사람은 testing.md를 업데이트하면 됩니다. 서로 덮어쓰는 일도 줄어들고요.

진짜 강력한 건 path-scoped rule입니다. 규칙 파일에 YAML frontmatter 블록을 넣어두면, Claude가 해당 경로의 파일을 다룰 때만 그 규칙이 활성화돼요.

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
# API Design Rules

- All handlers return { data, error } shape
- Use zod for request body validation
- Never expose internal error details to clients

예를 들어 React 컴포넌트를 수정할 때는 이 파일을 읽지 않고, src/api/나 src/handlers/ 안에서 작업할 때만 읽게 만들 수 있습니다. 반대로 paths 필드가 없는 규칙은 모든 세션에서 항상 로드되고요.

CLAUDE.md가 점점 답답해지기 시작했다면, 그때부터는 이 패턴으로 넘어가는 게 맞습니다.

commands/ 폴더: 나만의 슬래시 커맨드

Claude Code에는 기본적으로 /help, /compact 같은 내장 슬래시 커맨드가 있죠. commands/ 폴더를 쓰면 여기에 나만의 커맨드를 추가할 수 있습니다.

.claude/commands/에 넣는 모든 마크다운 파일은 각각 하나의 슬래시 커맨드가 됩니다.

예를 들어 review.md라는 파일은 /project:review를 만들고, fix-issue.md는 /project:fix-issue를 만들어요. 파일명이 곧 커맨드 이름입니다.

^{image: https://blog.dailydoseofds.com/p/anatomy-of-the-claude-folder}

간단한 예를 들어보죠. .claude/commands/review.md를 만듭니다:

---
description: Review the current branch diff for issues before merging
---
## Changes to Review

!`git diff --name-only main...HEAD`

## Detailed Diff

!`git diff main...HEAD`

Review the above changes for:
1. Code quality issues
2. Security vulnerabilities
3. Missing test coverage
4. Performance concerns

Give specific, actionable feedback per file.

이제 Claude Code에서 /project:review를 실행하면, Claude가 프롬프트를 보기 전에 실제 git diff가 자동으로 프롬프트에 들어갑니다. ! 백틱 문법은 셸 커맨드를 실행하고 그 출력을 그대로 끼워 넣어요. 그래서 이 커맨드들이 단순 저장 텍스트가 아니라 실제로 쓸모 있는 도구가 됩니다.

커맨드에 인자 넘기기

커맨드 이름 뒤의 텍스트를 전달하려면 $ARGUMENTS를 쓰면 됩니다.

---
description: Investigate and fix a GitHub issue
argument-hint: [issue-number]
---
Look at issue #$ARGUMENTS in this repo.

!`gh issue view $ARGUMENTS`

Understand the bug, trace it to the root cause, fix it, and write a
test that would have caught it.

예를 들어 /project:fix-issue 234를 실행하면 issue 234의 내용이 프롬프트로 바로 들어가요.

개인 커맨드와 프로젝트 커맨드

.claude/commands/에 있는 프로젝트 커맨드는 커밋되어 팀 전체와 공유됩니다. 반대로 어떤 프로젝트에서든 공통으로 쓰고 싶은 커맨드는 ~/.claude/commands/에 넣으면 돼요. 그러면 /user:command-name 형태로 보입니다.

개인 커맨드로는 데일리 스탠드업 도우미, 내 스타일에 맞는 커밋 메시지 생성기, 빠른 보안 점검 커맨드 같은 것들이 꽤 유용합니다.

skills/ 폴더: 필요할 때 재사용하는 워크플로우

이제 커맨드가 어떻게 동작하는지는 알았죠. 스킬도 겉보기엔 비슷하지만, 발동 방식은 완전히 다릅니다. 여기서 차이를 한 번 짚고 갈게요:

^{image: https://blog.dailydoseofds.com/p/anatomy-of-the-claude-folder}

스킬은 사용자가 슬래시 커맨드를 직접 치지 않아도, 지금 대화가 스킬 설명과 맞아떨어지면 Claude가 스스로 호출할 수 있는 워크플로우예요. 커맨드는 사용자가 불러줘야 움직이고, 스킬은 대화를 보다가 적절한 타이밍에 작동합니다.

각 스킬은 SKILL.md 파일을 포함한 독립된 하위 디렉터리에 들어갑니다:

.claude/skills/
├── security-review/
│   ├── SKILL.md
│   └── DETAILED_GUIDE.md
└── deploy/
    ├── SKILL.md
    └── templates/
        └── release-notes.md

SKILL.md는 YAML frontmatter를 사용해서 언제 이 스킬을 써야 하는지 설명합니다:

---
name: security-review
description: Comprehensive security audit. Use when reviewing code for
  vulnerabilities, before deployments, or when the user mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities:

1. SQL injection and XSS risks
2. Exposed credentials or secrets
3. Insecure configurations
4. Authentication and authorization gaps

Report findings with severity ratings and specific remediation steps.
Reference @DETAILED_GUIDE.md for our security standards.

예를 들어 “이 PR 보안 이슈 중심으로 리뷰해줘”라고 하면, Claude는 설명을 읽고 거기에 맞는다고 판단해서 그 스킬을 자동으로 호출합니다. 물론 /security-review처럼 직접 부를 수도 있고요.

커맨드와의 핵심 차이는 여기 있어요. 스킬은 관련 보조 파일을 함께 묶을 수 있습니다. 위의 DETAILED_GUIDE.md처럼SKILL.md 옆에 있는 자세한 문서를 같이 불러올 수 있죠. 커맨드는 파일 하나고, 스킬은 패키지입니다.

개인 스킬은 ~/.claude/skills/에 넣어두면 모든 프로젝트에서 쓸 수 있어요.

agents/ 폴더: 역할이 분리된 서브에이전트 페르소나

작업이 꽤 복잡해서 전담 전문가가 하나 있으면 좋겠다 싶을 때는, .claude/agents/ 안에 서브에이전트 페르소나를 정의할 수 있습니다. 각 에이전트는 자기만의 system prompt, tool access, model preference를 가진 마크다운 파일이에요.

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

예를 들어 code-reviewer.md는 이런 느낌입니다:

---
name: code-reviewer
description: Expert code reviewer. Use PROACTIVELY when reviewing PRs,
  checking for bugs, or validating implementations before merging.
model: sonnet
tools: Read, Grep, Glob
---
You are a senior code reviewer with a focus on correctness and maintainability.

When reviewing code:
- Flag bugs, not just style issues
- Suggest specific fixes, not vague improvements
- Check for edge cases and error handling gaps
- Note performance concerns only when they matter at scale

Claude가 코드 리뷰가 필요하다고 판단하면, 이 에이전트를 별도의 격리된 컨텍스트 창에서 띄웁니다. 에이전트는 자기 일을 하고, 결과를 압축해서 다시 보고해요. 그래서 메인 세션이 수천 토큰짜리 중간 탐색으로 복잡해지지 않습니다.

tools 필드는 그 에이전트가 뭘 할 수 있는지 제한합니다. 예를 들어 보안 감사 역할이라면 Read, Grep, Glob 정도면 충분하죠. 파일을 쓸 이유는 거의 없습니다. 이런 제한은 일부러 거는 게 맞고, 명시적으로 적어두는 편이 좋아요.

model 필드를 쓰면 좁은 작업에는 더 저렴하고 빠른 모델을 붙일 수 있습니다. 읽기 전용 탐색 업무는 대체로 Haiku로도 충분해요. Sonnet이나 Opus는 진짜 그만한 역량이 필요한 작업에 쓰는 편이 낫습니다.

개인 에이전트는 ~/.claude/agents/에 두고 모든 프로젝트에서 사용할 수 있습니다.

^{image: https://blog.dailydoseofds.com/p/anatomy-of-the-claude-folder}

settings.json: 권한과 프로젝트 설정

.claude/ 안의 settings.json 파일은 Claude가 무엇을 할 수 있고 무엇은 하면 안 되는지를 정합니다. 어떤 도구를 실행할 수 있는지, 어떤 파일을 읽을 수 있는지, 특정 명령 전에 사용자 확인을 받아야 하는지 같은 걸 여기서 정의해요.

전체 파일은 이런 형태입니다:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

각 부분이 하는 일은 다음과 같습니다.

$schema 줄은 VS Code나 Cursor에서 자동완성과 인라인 검증을 켜줍니다. 이건 그냥 항상 넣는다고 생각하면 됩니다.

allow list에는 Claude가 확인 없이 바로 실행할 수 있는 명령이 들어갑니다. 대부분의 프로젝트에서는 이 정도가 무난해요:

• Claude가 스크립트를 자유롭게 실행할 수 있도록 Bash(npm run *) 또는 Bash(make *)

• 읽기 전용 git 명령을 위한 Bash(git *)

• 파일 작업용 Read, Write, Edit, Glob, Grep

deny list에는 어떤 경우에도 완전히 막아둘 명령을 넣습니다. 보통은 이런 것들이 들어가죠:

• rm -rf 같은 파괴적인 셸 명령

• curl 같은 직접 네트워크 명령

• .env나 secrets/ 아래 파일 같은 민감 정보

어떤 항목이 두 목록 어디에도 없다면 Claude는 실행 전에 물어봅니다. 이 중간 지대가 꽤 중요해요. 가능한 모든 명령을 미리 예상해둘 필요는 없으면서도, 기본적인 안전망은 유지할 수 있으니까요.

물론 개인 오버라이드를 위한 settings.local.json도 둘 수 있습니다. 개념은 CLAUDE.local.md와 같아요. 커밋하고 싶지 않은 권한 변경은 .claude/settings.local.json에 넣으면 되고, 이것도 자동으로 gitignore 처리됩니다.

전역 ~/.claude/ 폴더

이 폴더를 자주 직접 들여다볼 일은 많지 않지만, 안에 뭐가 있는지는 알아두면 좋습니다.

~/.claude/CLAUDE.md는 어떤 프로젝트에 있든 모든 Claude Code 세션에 로드됩니다. 개인적인 코딩 원칙, 선호 스타일, 저장소와 상관없이 Claude가 기억했으면 하는 내용을 넣어두기 딱 좋은 곳이에요.

~/.claude/projects/에는 프로젝트별 세션 기록과 자동 메모리가 저장됩니다. Claude Code는 작업하면서 스스로 메모를 남겨요. 발견한 명령, 관찰한 패턴, 아키텍처 인사이트 같은 것들입니다. 이런 정보는 세션이 끝나도 남고, /memory로 둘러보거나 수정할 수 있어요.

~/.claude/commands/와 ~/.claude/skills/에는 모든 프로젝트에서 쓸 수 있는 개인 커맨드와 개인 스킬이 들어갑니다.

보통은 이런 것들을 손으로 직접 관리할 필요는 없습니다. 그래도 Claude가 내가 말한 적 없는 걸 “기억”하는 것처럼 보일 때나, 특정 프로젝트의 자동 메모리를 싹 지우고 새로 시작하고 싶을 때는 이 구조를 알고 있으면 꽤 도움이 됩니다.

전체 그림

이제 전체를 합쳐 보면 구조는 이런 식입니다:

your-project/
├── CLAUDE.md                  # Team instructions (committed)
├── CLAUDE.local.md            # Your personal overrides (gitignored)
│
└── .claude/
    ├── settings.json          # Permissions + config (committed)
    ├── settings.local.json    # Personal permission overrides (gitignored)
    │
    ├── commands/              # Custom slash commands
    │   ├── review.md          # → /project:review
    │   ├── fix-issue.md       # → /project:fix-issue
    │   └── deploy.md          # → /project:deploy
    │
    ├── rules/                 # Modular instruction files
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    │
    ├── skills/                # Auto-invoked workflows
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    │
    └── agents/                # Specialized subagent personas
        ├── code-reviewer.md
        └── security-auditor.md

~/.claude/
├── CLAUDE.md                  # Your global instructions
├── settings.json              # Your global settings
├── commands/                  # Your personal commands (all projects)
├── skills/                    # Your personal skills (all projects)
├── agents/                    # Your personal agents (all projects)
└── projects/                  # Session history + auto-memory

처음 시작할 때는 이렇게 가면 됩니다

처음부터 세팅한다면, 저는 이 순서를 추천해요.

Step 1. Claude Code 안에서 /init를 실행합니다. 프로젝트를 읽고 기본 CLAUDE.md를 만들어줘요. 그다음 핵심만 남기도록 직접 줄여 다듬으면 됩니다.

Step 2. 스택에 맞는 allow/deny 규칙으로 .claude/settings.json을 추가합니다. 최소한 실행 커맨드는 허용하고,.env 읽기는 막아두세요.

Step 3. 자주 반복하는 워크플로우에 대해 커맨드 한두 개를 만듭니다. 보통은 코드 리뷰나 이슈 수정부터 시작하면 무난해요.

Step 4. 프로젝트가 커지고 CLAUDE.md가 복잡해지기 시작하면, 지시문을 .claude/rules/ 파일들로 나누세요. 경로별로 나눌 수 있으면 그렇게 범위를 좁히는 편이 더 좋습니다.

Step 5. 개인 취향을 담은 ~/.claude/CLAUDE.md를 추가합니다. 예를 들면 “항상 구현 전에 타입부터 작성해”라든가, “class 기반보다 함수형 패턴을 선호해” 같은 것들이요.

사실 프로젝트의 95%는 이것만으로 충분합니다. 스킬과 에이전트는 반복되는 복잡한 워크플로우를 진짜 패키징할 가치가 있을 때 넣으면 돼요.

핵심 포인트

.claude 폴더는 결국 Claude에게 “너는 여기서 어떻게 일해야 하는지”를 알려주는 프로토콜 같은 겁니다. 당신이 누구인지, 이 프로젝트가 어떤 구조인지, 어떤 규칙을 따라야 하는지를 더 명확하게 적어둘수록, Claude를 계속 교정하는 시간은 줄고 실제로 쓸모 있는 일을 시키는 시간은 늘어나요.

CLAUDE.md는 그중에서도 가장 레버리지가 큰 파일입니다. 제일 먼저 이 파일부터 제대로 잡는 게 좋습니다. 나머지는 그다음 최적화고요.

작게 시작하고, 쓰면서 다듬고, 프로젝트 안의 다른 인프라처럼 관리하세요. 한 번 잘 세팅해두면 매일 조금씩 이득을 돌려주는 종류의 인프라라고 생각하면 딱 맞습니다.

클로드에서 직접 제공하는 스킬가이드도 추천합니다요

https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf