홈 / 학습 코스 / Claude Code 안내서

부록 B. 설정 파일 레퍼런스

자주 쓰는 설정 키 모음. 설정 키는 빠르게 바뀌니, IDE 자동완성을 위해 $schema를 지정하고 공식 설정 문서에서 최신 키를 확인하세요.

파일 위치와 우선순위

파일위치범위커밋?
관리 정책OS별 정책 경로조직 강제—
프로젝트 설정.claude/settings.json팀 공유✅
로컬 설정.claude/settings.local.json개인❌
유저 설정~/.claude/settings.json모든 프로젝트—

우선순위(높음→낮음): 관리 정책 > 프로젝트 > 로컬 > 유저 (대략). 자세한 계층은 10장.

.claude/ 디렉터리 구조

CODE
.claude/
├── settings.json          # 프로젝트 설정 (커밋)
├── settings.local.json    # 개인 설정 (비커밋)
├── CLAUDE.md              # 프로젝트 메모리 (루트의 ./CLAUDE.md도 가능)
├── rules/                 # path-scoped 규칙 (*.md)
├── skills/                # 스킬 (<name>/SKILL.md)
├── agents/                # 서브에이전트 (<name>.md)
├── commands/              # 커스텀 명령 (구식, 동작은 함)
├── plans/                 # 계획 파일 (plansDirectory로 변경)
└── .mcp.json             # MCP 서버 정의
💡 팁
팀 일관성을 위해 .claude/(CLAUDE.md·rules·skills·settings.json)를 버전 관리하세요(23장).

주요 설정 키 (예시)

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

  "model": "sonnet",
  "outputStyle": "default",
  "lang": "ko",

  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(npm run *)", "Read"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Bash(rm *)", "Bash(git push --force *)", "Read(./.env)"]
  },

  "autoMemory": true,
  "plansDirectory": "./docs/plans",

  "hooks": {
    "PreToolUse": [ /* ... */ ],
    "PostToolUse": [ /* ... */ ]
  },

  "mcpServers": {
    /* 서버 정의 — 전송 방식별로 다름 */
  }
}
키의미장
model기본 모델 (별칭 sonnet·opus·haiku 또는 전체 ID)4
permissions.defaultMode기본 권한 모드8
permissions.allow/ask/deny권한 규칙8
autoMemory자동 메모리 on/off10
autoMemoryDirectory자동 메모리 위치(프로젝트 설정 불가)10, 23
plansDirectory계획 파일 위치7
outputStyle출력 스타일11
hooks라이프사이클 훅15
mcpServersMCP 서버 정의14
lang응답 언어—
⚠️ 흔한 실수
autoMemoryDirectory는 보안상 프로젝트 설정에서 못 쓰고 유저·로컬·정책 설정에서만 가능합니다(10장).

SKILL.md frontmatter

YAML
---
name: my-skill
description: 무엇을 하고 언제 쓰는지 (3인칭, 구체적으로)
disable-model-invocation: true   # 자동 호출 끄기
allowed-tools: Read, Grep        # 활성 시 승인 없이 쓸 도구
context: fork                    # 서브에이전트 격리 실행
---
지침 본문 (500줄 이하 권장)

자세히: 12장.

서브에이전트 frontmatter

YAML
---
name: code-reviewer
description: 무엇을·언제 (자동 위임 근거)
model: sonnet
tools: Read, Grep, Glob, Bash    # 허용 도구
disallowedTools: Write, Edit     # 금지 도구
memory: project                  # 메모리 범위
isolation: worktree              # 격리(값은 worktree만)
---
시스템 프롬프트 본문
📌 핵심
플러그인이 배포하는 서브에이전트는 hooks·mcpServers·permissionMode를 선언할 수 없습니다(16장).

자세히: 13장.

커스텀 명령 frontmatter

YAML
---
description: 명령 설명
allowed-tools: Read, Grep, Glob, Bash, WebFetch
model: sonnet
---
프롬프트 템플릿 본문 ($ARGUMENTS, $1 등 사용 가능)

자세히: 11장.

CLAUDE.md import

MARKDOWN
@README.md
@docs/architecture.md
@~/.claude/personal-rules.md

재귀 import 가능(깊이 제한), 코드블록 안의 @는 해석 안 됨, import해도 컨텍스트는 절약 안 됨. 자세히: 9장.

다음: 부록 C. 용어집