Claude Code 완벽 마스터 가이드 V3: LSP, CLAUDE.md, MCP, Skills & Hooks

원문 출처: TheDecipherist - Claude Code Mastery

이 가이드는 원문을 기반으로 한국어 사용자를 위해 재구성하고, 실전 예제를 추가했습니다.

---

1. 왜 Claude Code 설정이 중요한가?

핵심 인사이트: CLAUDE.md는 제안, Hooks는 강제

많은 개발자들이 CLAUDE.md에 ".env 파일 수정 금지"라고 적어놓고 안심합니다. 하지만 이것은 **제안(suggestion)**일 뿐입니다:

CLAUDE.md에 "don't edit .env" 작성
    ↓
LLM이 파싱
    ↓
다른 컨텍스트와 함께 고려
    ↓
"아마도" 따를 것... 하지만 보장 없음

반면 PreToolUse Hook으로 .env 접근을 차단하면:

.env 파일 접근 시도
    ↓
Hook 실행 (항상)
    ↓
Exit code 2 반환
    ↓
작업 차단. 끝.

"내 PreToolUse Hook은 매주 몇 번씩 Claude가 비밀 파일(.env)에 접근하는 것을 차단합니다." — TheDecipherist

연구 결과: 멀티턴 대화의 성능 저하

arXiv 연구에 따르면:

상황 성능 저하

단일 주제 대화 유지	기준선
여러 주제 혼합	평균 39% 저하
긴 컨텍스트 (64k 토큰)	최대 73% 저하

결론: 한 채팅에서 한 가지 작업만 하세요.

---

2. CLAUDE.md 완벽 가이드

메모리 계층 구조

Claude Code는 CLAUDE.md 파일을 특정 순서로 로드합니다:

레벨 위치 용도 우선순위

Enterprise	/etc/claude-code/CLAUDE.md	조직 전체 정책	최상위
Global User	~/.claude/CLAUDE.md	모든 프로젝트 기본값	높음
Project	./CLAUDE.md	팀 공유 프로젝트 지침	중간
Project Local	./CLAUDE.local.md	개인 프로젝트 오버라이드	낮음

Global CLAUDE.md 템플릿 (한국어 버전)

# 글로벌 Claude Code 설정

## 🔐 GitHub 계정
**항상** 모든 프로젝트에 **YourUsername** 사용:
- SSH: `git@github.com:YourUsername/.git`
- HTTPS: `https://github.com/YourUsername/.git`

## 🐳 Docker Hub
이미 인증됨. 사용자명은 `~/.env`의 `DOCKER_HUB_USER`에 저장

---

## ⛔ 절대 하지 말아야 할 것들

다음 규칙은 **절대적**입니다:

### 민감 데이터 배포 금지
- 절대로 비밀번호, API 키, 토큰을 git/npm/docker에 배포하지 마세요
- 모든 커밋 전: 비밀 정보가 포함되지 않았는지 확인

### .env 파일 커밋 금지
- 절대로 `.env`를 git에 커밋하지 마세요
- 항상 `.env`가 `.gitignore`에 있는지 확인

### 위험한 명령어 금지
- `rm -rf /` 또는 시스템 디렉토리 삭제 금지
- `sudo` 없이 시스템 파일 수정 금지
- 프로덕션 데이터베이스 직접 조작 금지

---

## 📁 새 프로젝트 생성 시

새 프로젝트 생성 시 다음을 항상 포함:

### 필수 파일
- `.env` — 환경 변수 (절대 커밋 금지)
- `.env.example` — 플레이스홀더가 있는 템플릿
- `.gitignore` — 포함 필수: .env, node_modules/, dist/, __pycache__/
- `CLAUDE.md` — 프로젝트 개요

### 필수 구조
project/
├── src/
├── tests/
├── docs/
├── .claude/skills/
└── scripts/

### Node.js 프로젝트 필수 사항
진입점에 다음 추가:
```javascript
process.on('unhandledRejection', (reason, promise) => {
  console.error('처리되지 않은 Rejection:', reason);
  process.exit(1);
});

Python 프로젝트 필수 사항

• pyproject.toml 또는 requirements.txt 포함
• 타입 힌트 사용 권장
• pytest 테스트 구조 따르기

---

🇰🇷 한국어 프로젝트 규칙

코드 주석

• 복잡한 로직은 한국어 주석으로 설명
• 함수/클래스 docstring은 한국어로 작성

커밋 메시지

Conventional Commits 형식 사용 (한국어):

• feat: 새로운 기능 추가
• fix: 버그 수정
• docs: 문서 업데이트
• refactor: 코드 리팩토링

에러 메시지

• 사용자 facing 에러: 한국어
• 시스템 로그: 영어

### 프로젝트별 CLAUDE.md 예제

**예제: Next.js + TypeScript 프로젝트**

```markdown
# 프로젝트: 쇼핑몰 관리자 대시보드

## 기술 스택
- **Frontend**: Next.js 15, TypeScript, Tailwind CSS
- **Backend**: Next.js API Routes, Prisma
- **Database**: PostgreSQL (Supabase)
- **Testing**: Jest, React Testing Library

## 핵심 디렉토리
- `app/` — App Router 페이지 및 레이아웃
- `components/` — 재사용 컴포넌트
- `lib/` — 유틸리티 및 헬퍼
- `prisma/` — 스키마 및 마이그레이션

## 코딩 규칙
- TypeScript strict mode 필수
- `any` 타입 사용 금지 — `unknown` 사용
- 컴포넌트는 함수형 + hooks
- API 응답은 항상 타입 정의

## 자주 사용하는 명령어
```bash
npm run dev          # 개발 서버
npm run test         # 테스트 실행
npm run lint         # ESLint
npx prisma studio    # DB GUI

중요 참고사항

• 모든 API 라우트에 인증 미들웨어 필수
• 환경 변수는 env.mjs에서 검증
• 한국 시간대(KST) 기준으로 날짜 처리

---

## 3. Hooks: 결정론적 제어의 힘

### Hook 이벤트 종류

| 이벤트 | 실행 시점 | 주요 용도 |
|--------|----------|----------|
| `PreToolUse` | 도구 실행 전 | 위험한 작업 차단 |
| `PostToolUse` | 도구 실행 후 | 포매터/린터 실행 |
| `Stop` | Claude 응답 완료 | 품질 게이트 |
| `UserPromptSubmit` | 프롬프트 제출 시 | 입력 검증 |
| `SessionStart` | 세션 시작 시 | 컨텍스트 로딩 |

### Hook Exit 코드

| 코드 | 의미 |
|------|------|
| 0 | 작업 허용 |
| 1 | 에러 (사용자에게 표시) |
| 2 | **작업 차단**, stderr를 Claude에게 전달 |

### 예제 1: 민감 파일 접근 차단 (Python)

**`~/.claude/hooks/block-secrets.py`**

```python
#!/usr/bin/env python3
"""
민감 파일 접근을 차단하는 PreToolUse 훅
"""
import json
import sys
from pathlib import Path

# 차단할 파일 패턴
SENSITIVE_FILES = {
    '.env',
    '.env.local',
    '.env.production',
    'secrets.json',
    'credentials.json',
    'id_rsa',
    'id_ed25519',
    '.aws/credentials',
}

SENSITIVE_PATTERNS = [
    '**/secret*',
    '**/*password*',
    '**/*credential*',
]

def main():
    # stdin에서 JSON 데이터 읽기
    data = json.load(sys.stdin)
    
    # 파일 경로 추출
    tool_input = data.get('tool_input', {})
    file_path = tool_input.get('file_path', '') or tool_input.get('path', '')
    
    if not file_path:
        sys.exit(0)  # 파일 경로 없음 - 허용
    
    path = Path(file_path)
    
    # 파일명 체크
    if path.name in SENSITIVE_FILES:
        print(f"🚫 차단됨: {file_path}에 대한 접근이 거부되었습니다.", file=sys.stderr)
        print("이 파일은 민감 정보를 포함할 수 있습니다.", file=sys.stderr)
        sys.exit(2)
    
    # 경로 패턴 체크
    for pattern in SENSITIVE_PATTERNS:
        if path.match(pattern):
            print(f"🚫 차단됨: {file_path} 패턴 매칭으로 거부됨", file=sys.stderr)
            sys.exit(2)
    
    sys.exit(0)  # 허용

if __name__ == '__main__':
    main()

예제 2: 위험한 명령어 차단 (Bash)

~/.claude/hooks/block-dangerous-commands.sh

#!/bin/bash
#
# 위험한 bash 명령어를 차단하는 PreToolUse 훅
#

# stdin에서 JSON 읽기
INPUT=$(cat)

# 명령어 추출
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
    exit 0  # 명령어 없음 - 허용
fi

# 위험한 패턴 목록
DANGEROUS_PATTERNS=(
    "rm -rf /"
    "rm -rf /*"
    "rm -rf ~"
    "> /dev/sda"
    "mkfs."
    "dd if=/dev/zero"
    ":(){:|:&};:"   # Fork bomb
    "chmod -R 777 /"
    "curl.*|.*sh"   # 원격 스크립트 실행
    "wget.*|.*sh"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
    if echo "$COMMAND" | grep -qE "$pattern"; then
        echo "🚫 차단됨: 위험한 명령어가 감지되었습니다." >&2
        echo "명령어: $COMMAND" >&2
        echo "이 명령어는 시스템에 심각한 손상을 줄 수 있습니다." >&2
        exit 2
    fi
done

# main 브랜치 보호
if echo "$COMMAND" | grep -qE "git push.*(-f|--force).*main"; then
    echo "🚫 차단됨: main 브랜치에 force push는 금지되어 있습니다." >&2
    exit 2
fi

exit 0  # 허용

예제 3: PostToolUse - 자동 포매팅

~/.claude/hooks/auto-format.sh

#!/bin/bash
#
# 파일 편집 후 자동으로 포매터 실행
#

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Edit/Write 도구에서만 실행
if [[ ! "$TOOL_NAME" =~ ^(Edit|Write|str_replace_editor)$ ]]; then
    exit 0
fi

if [ -z "$FILE_PATH" ]; then
    exit 0
fi

# 파일 확장자에 따른 포매터 실행
case "$FILE_PATH" in
    *.py)
        if command -v black &> /dev/null; then
            black --quiet "$FILE_PATH" 2>/dev/null
        fi
        if command -v isort &> /dev/null; then
            isort --quiet "$FILE_PATH" 2>/dev/null
        fi
        ;;
    *.ts|*.tsx|*.js|*.jsx)
        if command -v prettier &> /dev/null; then
            prettier --write "$FILE_PATH" 2>/dev/null
        fi
        ;;
    *.go)
        if command -v gofmt &> /dev/null; then
            gofmt -w "$FILE_PATH" 2>/dev/null
        fi
        ;;
    *.rs)
        if command -v rustfmt &> /dev/null; then
            rustfmt "$FILE_PATH" 2>/dev/null
        fi
        ;;
esac

exit 0

settings.json Hook 설정

~/.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/block-secrets.py",
            "timeout": 5
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/block-dangerous-commands.sh",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/auto-format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  },
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./**/credentials.json)"
    ]
  }
}

---

4. Skills: 재사용 가능한 전문성

Skills vs CLAUDE.md

구분 CLAUDE.md Skills

로딩	항상	필요할 때만
범위	전체 프로젝트	특정 작업
토큰	항상 소비	필요시에만
적합한 경우	항상 적용되는 규칙	<20% 대화에만 필요한 지침

Skills 디렉토리 구조

~/.claude/skills/           # 글로벌 스킬 (모든 프로젝트)
├── code-review/
│   └── SKILL.md
├── commit-message/
│   └── SKILL.md
└── security-audit/
    └── SKILL.md

./project/.claude/skills/   # 프로젝트 스킬
├── api-design/
│   └── SKILL.md
└── testing/
    └── SKILL.md

예제 1: 코드 리뷰 스킬

~/.claude/skills/code-review/SKILL.md

---
name: code-review
description: 코드 리뷰 시 버그, 보안 취약점, 성능 이슈를 체크합니다. "리뷰", "review", "검토" 키워드 사용 시 활성화.
allowed-tools: Read, Grep, Glob
---

# 코드 리뷰 스킬

## 언제 사용하나요?
- 사용자가 "코드 리뷰해줘", "review this", "검토해줘" 요청 시
- PR 리뷰 요청 시
- 코드 품질 체크 요청 시

## 리뷰 체크리스트

### 1. 보안 취약점
- [ ] SQL Injection 가능성
- [ ] XSS 취약점
- [ ] 하드코딩된 비밀 정보
- [ ] 인증/인가 누락
- [ ] 입력 검증 부재

### 2. 성능 이슈
- [ ] N+1 쿼리 문제
- [ ] 불필요한 반복문
- [ ] 메모리 누수 가능성
- [ ] 무한 루프 위험

### 3. 코드 품질
- [ ] 함수가 너무 길지 않은가? (50줄 이하 권장)
- [ ] 중복 코드는 없는가?
- [ ] 명확한 변수/함수명을 사용하는가?
- [ ] 에러 처리가 적절한가?

### 4. 테스트
- [ ] 테스트 코드가 있는가?
- [ ] 엣지 케이스를 커버하는가?
- [ ] 테스트가 독립적인가?

## 리뷰 결과 형식

```markdown
## 코드 리뷰 결과

### 🔴 심각 (Blocker)
- [파일:라인] 설명

### 🟠 중요 (Major)
- [파일:라인] 설명

### 🟡 권장 (Minor)
- [파일:라인] 설명

### ✅ 잘한 점
- 칭찬할 부분

### 예제 2: 커밋 메시지 스킬

**`~/.claude/skills/commit-message/SKILL.md`**

```markdown
---
name: commit-message
description: Conventional Commits 형식의 커밋 메시지를 생성합니다. "커밋", "commit" 키워드 사용 시 활성화.
---

# 커밋 메시지 생성 스킬

## Conventional Commits 형식

<type>(<scope>): <subject>

<body> <footer> ```

타입 (Type)

타입 설명 이모지

feat	새로운 기능	✨
fix	버그 수정	🐛
docs	문서 변경	📝
style	포매팅 (코드 변경 없음)	💄
refactor	리팩토링	♻️
perf	성능 개선	⚡
test	테스트 추가/수정	✅
chore	빌드, 설정 변경	🔧

예제

기능 추가

feat(auth): 소셜 로그인 기능 추가

- Google OAuth 2.0 연동
- 기존 사용자 계정 연결 기능
- 로그인 상태 유지 옵션

Closes #123

버그 수정

fix(cart): 장바구니 수량 업데이트 오류 수정

수량이 0일 때 음수로 변경되는 버그 수정
최소 수량을 1로 제한하는 validation 추가

Fixes #456

한국어 커밋 메시지 가이드

• subject는 50자 이내
• 명령조 사용 ("추가한다" X → "추가" O)
• body는 "왜"와 "무엇"을 설명
• footer에 이슈 번호 연결

### 예제 3: API 설계 스킬

**`~/.claude/skills/api-design/SKILL.md`**

```markdown
---
name: api-design
description: RESTful API 설계 가이드라인. "API", "엔드포인트", "endpoint" 키워드 사용 시 활성화.
---

# API 설계 스킬

## RESTful 명명 규칙

### 좋은 예

GET /users # 목록 조회 GET /users/:id # 단일 조회 POST /users # 생성 PATCH /users/:id # 부분 수정 DELETE /users/:id # 삭제 GET /users/:id/orders # 중첩 리소스

### 나쁜 예

GET /getUsers ❌ 동사 사용 POST /createUser ❌ 동사 사용 GET /user/:id ❌ 단수형 DELETE /deleteUser/:id ❌ 동사 중복

## 응답 형식 (한국어 프로젝트)

### 성공 응답
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "홍길동"
  },
  "message": "사용자 정보를 성공적으로 조회했습니다."
}

에러 응답

{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "사용자를 찾을 수 없습니다.",
    "details": {
      "userId": 999
    }
  }
}

HTTP 상태 코드

코드 의미 사용 시점

200	OK	성공 (GET, PATCH)
201	Created	생성 성공 (POST)
204	No Content	삭제 성공 (DELETE)
400	Bad Request	잘못된 요청
401	Unauthorized	인증 필요
403	Forbidden	권한 없음
404	Not Found	리소스 없음
422	Unprocessable Entity	검증 실패
500	Internal Server Error	서버 에러

페이지네이션

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}

필터링 & 정렬

GET /products?category=electronics&minPrice=1000&sort=-createdAt

• 필터: query parameter로
• 정렬: sort 파라미터 (- prefix = 내림차순)

---

## 5. MCP 서버 통합

### MCP란?

MCP(Model Context Protocol)는 Claude Code가 외부 도구와 통신할 수 있게 해주는 프로토콜입니다.

### MCP 서버 추가 방법

```bash
# 서버 추가
claude mcp add <server-name> -- <command>

# 서버 목록 확인
claude mcp list

# 서버 제거
claude mcp remove <server-name>

⚠️ MCP 사용 시 주의사항

MCP 서버는 토큰과 컨텍스트를 소비합니다. 단순한 작업에는 과도할 수 있습니다:

상황 MCP 오버헤드 대안

Trello 작업	높음	CLI 도구 (trello-cli)
단순 HTTP 호출	과도함	Bash에서 curl
일회성 쿼리	낭비	직접 명령어

경험 규칙: 세션당 한 번 호출할 MCP 도구는 CLI가 더 효율적입니다.

추천 MCP 서버 (카테고리별)

핵심 개발

서버 용도 설치 명령어

Context7	최신 라이브러리 문서	claude mcp add context7 -- npx -y @upstash/context7-mcp@latest
GitHub	PR, 이슈, CI/CD	claude mcp add github -- npx -y @modelcontextprotocol/server-github
Sequential Thinking	구조적 문제 해결	claude mcp add thinking -- npx -y @modelcontextprotocol/server-sequential-thinking

데이터베이스

서버 용도 설치 명령어

PostgreSQL	Postgres 자연어 쿼리	claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres
MongoDB	Atlas/Community DB	claude mcp add mongodb -- npx -y mongodb-mcp-server
DBHub	범용 (MySQL, SQLite 등)	claude mcp add db -- npx -y @bytebase/dbhub

문서 & 검색

서버 용도 설치 명령어

Docling	PDF/DOCX 파싱 (97.9% 테이블 정확도)	claude mcp add docling -- uvx docling-mcp-server
Brave Search	프라이버시 중심 웹 검색	claude mcp add brave -- npx -y @anthropic-ai/brave-search-mcp

브라우저 & 테스팅

서버 용도 설치 명령어

Playwright	E2E 테스팅, 스크래핑	claude mcp add playwright -- npx -y @anthropic-ai/playwright-mcp
Browser MCP	로그인된 Chrome 사용	browsermcp.io 참조

클라우드 & 협업

서버 용도 설치 명령어

AWS	AWS 서비스 전체	claude mcp add aws -- uvx awslabs.aws-api-mcp-server@latest
Slack	메시지, 채널 요약	claude mcp add slack -- npx -y @anthropic-ai/slack-mcp
Linear	이슈 트래킹	claude mcp add linear -- npx -y @linear/mcp-server

Context7 실전 예제

문제: Claude의 학습 데이터 컷오프로 인해 최신 라이브러리 정보가 부정확할 수 있습니다.

해결책: Context7으로 최신 문서 접근

사용자: "context7 사용해서 Next.js 15의 캐시 API 알려줘"
Claude: *최신 문서 fetch* → 정확하고 최신 코드 제공

---

6. 컨텍스트 엔지니어링 전략

컨텍스트 윈도우 현실

Claude Code의 컨텍스트 윈도우는 200,000 토큰입니다. 하지만 실제로 사용 가능한 양은:

구성 요소 토큰 사용

버퍼 예약	~22.5%
시스템 프롬프트	~10.2%
MCP 서버/서브에이전트	가변
실제 사용 가능	~120,000 토큰

성능 저하 연구 결과

Chroma Research의 "Context Rot" 연구:

"컨텍스트 윈도우의 토큰이 증가할수록, 모델의 정보 리콜 정확도가 감소합니다."

컨텍스트 사용량 성능

20%	기준선
50%	약간 저하
80%+	현저한 저하

황금 규칙: "한 작업, 한 채팅"

시나리오 행동

새 기능 개발	새 채팅
(관련 없는) 버그 수정	/clear 후 새 작업
리서치 vs 구현	별도 채팅
20+ 턴 경과	새로 시작

실전 컨텍스트 관리

1. /context 명령어로 현황 파악

/context

현재 토큰 사용량과 구성 요소별 breakdown을 확인할 수 있습니다.

2. /clear 자주 사용

/clear

작업 완료 후 컨텍스트를 리셋합니다.

3. /compact 활용

/compact

긴 대화를 요약하여 컨텍스트 공간을 확보합니다.

구조화된 노트 테이킹

장기 작업 시 컨텍스트를 파일로 저장:

"이 대화 내용을 design-decisions.md에 요약해줘. 
핵심 결정사항과 이유를 중심으로 정리해."

다음 세션에서:

"design-decisions.md를 읽고 이어서 작업하자."

---

7. LSP: IDE 수준의 코드 인텔리전스

LSP란?

2025년 12월 (v2.0.74)부터 Claude Code에 LSP(Language Server Protocol) 지원이 추가되었습니다.

LSP가 제공하는 기능

기능 설명

Go to Definition	심볼이 정의된 위치로 점프
Find References	함수가 사용된 모든 곳 찾기
Hover	타입 시그니처 및 문서 확인
Diagnostics	실시간 에러 감지
Document Symbols	파일 내 모든 심볼 목록

성능 향상

항목 LSP 이전 LSP 이후

코드베이스 탐색	~45초 (grep)	~50ms
개선율	-	900배

지원 언어

Python, TypeScript, Go, Rust, Java, C/C++, C#, PHP, Kotlin, Ruby, HTML/CSS

설정

v2.0.74 이상에서는 기본 내장. 이전 버전:

export ENABLE_LSP_TOOL=1

---

8. 실전 설정 템플릿

전체 설정 구조

~/.claude/
├── CLAUDE.md                    # 글로벌 규칙
├── settings.json                # 훅 및 권한 설정
├── hooks/
│   ├── block-secrets.py         # 민감 파일 차단
│   ├── block-dangerous-commands.sh  # 위험 명령어 차단
│   └── auto-format.sh           # 자동 포매팅
└── skills/
    ├── code-review/
    │   └── SKILL.md
    ├── commit-message/
    │   └── SKILL.md
    └── api-design/
        └── SKILL.md

완성 settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/block-secrets.py",
            "timeout": 5
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/block-dangerous-commands.sh",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/auto-format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  },
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./.env.local)",
      "Read(./.env.production)",
      "Read(./secrets/**)",
      "Read(./**/credentials.json)",
      "Read(./**/*secret*)",
      "Read(~/.ssh/**)"
    ]
  },
  "env": {
    "EDITOR": "code --wait",
    "TZ": "Asia/Seoul"
  }
}

dotfiles로 동기화 (여러 컴퓨터 사용 시)

# GNU Stow 사용
cd ~/dotfiles
mkdir -p claude/.claude

# 설정 파일 복사
cp -r ~/.claude/* claude/.claude/

# 심볼릭 링크 생성
stow claude

이제 ~/dotfiles를 git으로 관리하면 모든 컴퓨터에서 동일한 Claude Code 설정을 유지할 수 있습니다.

---

빠른 참조 카드

도구 용도 위치

Global CLAUDE.md	보안 + 스캐폴딩	~/.claude/CLAUDE.md
Project CLAUDE.md	아키텍처 + 팀 규칙	./CLAUDE.md
MCP 서버	외부 통합	claude mcp add
Skills	재사용 전문성	.claude/skills/*/SKILL.md
Hooks	결정론적 강제	~/.claude/settings.json
LSP	시맨틱 코드 인텔리전스	내장 (v2.0.74+)
/clear	컨텍스트 리셋	채팅에서 입력
/context	토큰 사용량 확인	채팅에서 입력
/compact	대화 요약	채팅에서 입력

---

마무리

Claude Code를 효과적으로 사용하려면:

1. CLAUDE.md로 기본 규칙과 컨텍스트 제공
2. Hooks로 중요한 규칙을 강제 (CLAUDE.md는 제안일 뿐!)
3. Skills로 반복 작업을 패키징
4. MCP 서버는 신중하게 (토큰 비용 고려)
5. 한 작업, 한 채팅 원칙 준수
6. /clear와 /compact 적극 활용

"설정에 시간을 투자하면, 이후 모든 작업이 더 빨라집니다."

---

참고 자료

• Claude Code Best Practices — Anthropic
• Effective Context Engineering — Anthropic
• Claude Code Hooks Reference
• LLMs Get Lost In Multi-Turn Conversation — arXiv
• Context Rot Research — Chroma
• TheDecipherist - Claude Code Mastery (원문)

---

이 가이드가 도움이 되셨다면, 여러분의 Hook, Skill, MCP 설정을 공유해주세요!