Claude Code의 .claude 설정을 키워온 이야기

서론

Claude Code를 사용하기 시작한 지 몇 달, 어느덧 ~/.claude/ 디렉토리가 **53개의 스킬(Skill)·12개의 에이전트(Agent)·15개 이상의 환경별 규칙(Rule)**을 가진 "자율 개발 인프라"가 되어 있었다.

이 기사에서는 필자가 실제로 운용하고 있는 .claude 설정의 전체 모습과 설계 사상, 그리고 주의해야 할 점(ハマりどころ)을 공유한다. 마찬가지로 "Claude Code를 더 잘 활용하고 싶다"는 사람들에게 참고가 되기를 바란다.

전체 구성

~/.claude/
├── CLAUDE.md # 핵심 원칙 (200행 이내로 엄수)
├── rules/ # 규칙 모음 (자동 로드)
...

설계의 근본 사상: "토큰은 신선 식품이다"

모든 설정의 근저에 있는 원칙은 하나.

Claude의 토큰은 "판단과 편집"에만 사용한다. 조사·분석·검색은 외부로 위임한다.

작업	도구
1~2개 파일 읽기	Claude 직접 (Read/Edit)
300행 초과 파일 구조 파악	Serena get_symbols_overview
50KB 초과 코드베이스 분석	Gemini CLI @syntax
Web 검색	Gemini CLI (WebSearch/WebFetch는 금지)
git commit/push	Gemini CLI (커밋 메시지 생성 포함)
라이브러리 API 문서	Context7

이를 "하이브리드 위임 원칙"이라고 부르고 있다. 처음에는 "Serena/Gemini CLI에 전부 위임"하는 방식이었으나, 1~2개 파일의 단순 작업에 Serena를 호출하는 것은 오히려 오버헤드라는 것을 깨닫고 현재의 형태로 안착했다.

CLAUDE.md 작성법: 200행의 벽

CLAUDE.md가 길어지면 Claude는 아래의 규칙을 무시하기 시작한다 (Instruction Overload). Anthropic의 권장 사항은 400토큰(Token) 정도이다.

필자의 해결책은 "포인터 구동형 CLAUDE.md"이다:

## 핵심 원칙
**ABSOLUTE: Claude의 토큰 절약은 모든 규칙에 우선하는 절대 원칙.**
상세 내용: `~/.claude/rules/_core/token-efficiency.md`
...

CLAUDE.md는 포인터만 남긴다. 상세 내용은 rules/ 디렉토리에 분할하여 저장한다. 이를 통해 CLAUDE.md 자체의 토큰 소비를 최소화하면서도, 필요한 정보는 필요할 때 참조할 수 있는 구조로 만들었다.

rules/ 디렉토리: 지식을 분류하여 관리

_core/ (모든 세션 필수)

_core/
├── language.md # 일본어·간결·대화체
├── token-efficiency.md # 토큰 절약 (절대 원칙)
...

session-start.md가 특히 중요한데, 세션 시작 시 다음을 순서대로 실행하도록 정의하고 있다:

• Serena로 프로젝트 활성화
• claude-mem으로 과거 작업 기록 검색
• 라이브러리 관련일 경우 Context7로 문서 확인

environments/ (환경 특유의 함정 모음)

Windows 환경에서 Claude Code를 사용하는 과정에서의 함정들을 정성스럽게 문서화한 것이다.

windows-powershell.md의 교훈들:

# ❌ Write 도구로 ps1을 전체 덮어쓰기 → 1줄로 변하여 Parse Error 발생
# ✅ Edit 도구로 차분 편집(diff edit)만 수행
# ❌ Join-Path의 3개 인자 (PowerShell v5에서는 불가)
...

pywinauto-winforms.md에서는 WinForms GUI 자동화의 함정을 기록했다:

# ❌ UIA Invoke → COMError -2146233083
win.child_window(title='등록').click()
# ✅ 물리 마우스 클릭
...

이러한 "실제로 빠졌던 함정"들을 그때마다 rules/에 추가하여, 다음 Claude 세션에서 같은 실수를 반복하지 않도록 하고 있다.

settings.json: 자동화의 핵심

주요 설정

{
"model": "claude-sonnet-4-6",
"effortLevel": "medium",
...

effortLevel: "medium"

는 Pro 플랜에서의 권장값입니다. high

는 위와 같이 설정할 경우 몇 번의 작업만으로도 5시간 롤링 상한(rolling limit)에 도달할 위험이 있습니다.

CLAUDE_CODE_AUTO_COMPACT_WINDOW: "400000"

는 컨텍스트 부패 (Context Rot) 대책입니다. 1M 토큰 모델이라 하더라도 300~400k 부근부터 성능 저하가 시작되기 때문에, 조기에 자동 컴팩트 (auto-compact)를 설정해 두었습니다.

Hooks 설정: 시스템 레벨의 품질 보증

Hooks는 CLAUDE.md의 프롬프트 지시와 달리, 강제성을 가집니다.

{
"hooks": {
"SessionStart": [
...

각 Hook의 역할:

Hook	스크립트	목적
SessionStart	serena-auto-prime.ps1	Serena의 자동 실행 및 프로젝트 선택
PreToolUse(Bash)	unc-path-check.sh	UNC 경로 직접 사용 탐지 및 경고
PreToolUse(Bash)	block-main-push.sh	main/master로의 force push 차단
PostToolUse(Write/Edit)	auto-format.sh	Ruff/ESLint 자동 실행
PostToolUse(모두)	context-monitor.sh	컨텍스트 사용률 모니터링
PostCompact	inline	CLAUDE.md를 자동 재주입 (압축 후 지시 사항 소실 방지)
Stop	on-stop.sh	세션 종료 시 상태 저장

skills/: 53개의 슬래시 명령어

스킬(skill)은 사용자가 /skill-name이라고 입력함으로써 호출할 수 있는 워크플로우(workflow)의 집합입니다.

실행 시에는 "이름과 개요(약 100 토큰)"만 로드되며, 사용할 때만 전체 내용이 로드되는 지연 로딩 (lazy loading) 방식을 채택하고 있습니다.

대표적인 스킬

** /bp-research** — 베스트 프랙티스 (Best Practice) 자동 조사

Gemini CLI를 사용하여 Zenn, Qiita, Reddit, HN을 병렬 검색하고, 발견한 지식을 rules/에 자동으로 반영한 뒤 git push까지 수행합니다. 30일 스로틀링 (throttling)이 적용되어 있습니다.

** /mem-checkpoint** — 세션 기록 저장

중요한 작업 완료 시 claude-mem에 관측 내용을 기록합니다. 이를 통해 이후 세션에서 "지난번에 어디까지 했는지"를 즉시 파악할 수 있게 되었습니다.

** /commit-push-pr** — git 워크플로우 일괄 완료

Gemini CLI로 커밋 메시지를 자동 생성하고, 확인 후 커밋, 푸시(push), PR 생성까지 한 번에 완료합니다.

** /ask-gemini** — Gemini CLI로 위임

코드베이스가 100KB를 초과하거나, 웹 검색 또는 diff 리뷰가 필요한 경우 Gemini CLI에 처리를 위임합니다.

** /session-yolo-confirm** — YOLO 모드 전환

확인 프롬프트 없이 모든 조작을 자동 승인하는 모드로 전환합니다.

스킬 설계의 철칙

description 필드를 정확하게 작성하는 것이 가장 중요합니다. Claude는 오직 이곳만을 보고 스킬을 선택합니다:

---
name: commit-push-pr
description: |
...

agents/: 12개의 커스텀 에이전트

서브 에이전트 (sub-agent)로 호출할 수 있는 특화형 에이전트 그룹입니다.

에이전트	역할
tech-lead	태스크 분해 및 위임의 오케스트레이터
code-architect	설계 리뷰 (신규 기능 추가 전)
build-validator	빌드, 테스트, Lint 품질 검증
code-simplifier	중복 제거 및 가독성 향상
security-auditor	OWASP Top10 준수 정적 분석
test-writer	TDD 기반 테스트 작성
verify-app	E2E 동작 확인
gemini-researcher	웹 검색 및 50KB 초과 코드 분석
ui-designer	AI Slop 배제 및 디자인 시스템
tech-debt-auditor	기술 부채 식별 및 우선순위 지정
pdf-form-layout	PDF 폼 좌표 자동 분석
pdf-ocr-fixer	PDF OCR 실패 자율 수정

실제 사용법

# PR 전 풀 체크 (병렬 실행)
Agent(subagent_type="security-auditor") + Agent(subagent_type="build-validator")
# TDD 사이클
...

CRITICAL: 파일 삭제 사고 방지

isolation: "worktree"

이 설정 없이 tech-lead에게 대규모 변경을 위임하면, 에이전트가 "불필요하다고 판단한 파일"을 삭제하는 사고가 발생한다 (실제로 발생함).

# ✅ 안전한 패턴
Agent(
isolation="worktree",
...

MCP 서버 구성

mcpServers:
├── serena # 코드베이스 조작 (OSS · 사용 제한 없음)
├── context7 # 라이브러리 문서 참조
...

Serena는 오픈 소스 코드베이스 조작 MCP이다. 사용 제한이 없기 때문에 적극적으로 활용할 수 있다.

파일 횡단 패턴 검색, 심볼 이름 변경(Symbol Rename), 메서드 전체 재작성은 Serena에 맡긴다.

2층 메모리 시스템

auto memory (환경 특화)

~/.claude/projects/<CWD 인코딩>/memory/MEMORY.md에 자동으로 주입된다. 세션 간 작업 기록 및 환경 특화된 함정(Pitfalls)을 관리한다.

Serena memories (프로젝트 특화)

아키텍처 결정, 버그의 근본 원인 등을 write_memory를 통해 프로젝트에 귀속시켜 저장한다.

claude-mem (관측 이력)

claude-mem MCP 플러그인을 사용하여 태스크 경위, 디버깅 과정, 의사결정을 시계열로 기록한다. 3층 워크플로우를 통해 단계적으로 정보를 취득한다:

Layer 1: search (경량 인덱스)
Layer 2: timeline (시계열 컨텍스트)
Layer 3: get_observations (완전한 상세 정보)

운영하며 좋았던 점

1. 셀프 수정 규칙

사용자로부터 행동을 수정받았을 경우, 즉시 ~/.claude/rules/의 해당 파일을 업데이트함으로써 동일한 실수의 반복을 방지한다. Claude Code를 "키워 나가는" 느낌에 가깝다.

2. Gemini CLI와의 역할 분담

Claude는 구현 및 편집 전문, Gemini는 조사 및 분석 전문으로 역할을 명확히 나눔으로써, Claude의 컨텍스트를 코드의 "판단과 편집"에 집중시킬 수 있다.

# 웹 검색은 모두 Gemini CLI로 (Bash 자동화 시 --skip-trust은 필수)
gemini --skip-trust -p "질문" -o text 2>/dev/null

3. /rewind 활용

Claude가 잘못된 접근 방식을 취했을 경우, 수정하는 것보다 rewind가 정답이다.

# ❌ "그건 안 돼, 대신 X를 시도해봐" → 실패한 시도가 컨텍스트에 남아 오염됨
# ✅ Double Esc 또는 /rewind → 실패를 완전히 제거한 후 다시 프롬프트 작성

주의할 점과 해결책

PowerShell의 ps1 파일 문제

Write 도구로 ps1 파일을 전체 덮어쓰기하면 줄바꿈이 \r\n 리터럴이 되어 한 줄로 변한다. 항상 Edit 도구를 사용하여 차분 편집(Diff Edit)을 수행한다.

--skip-trust

필수

Gemini CLI의 Claude Code Bash 도구에서 Gemini CLI를 호출할 때는 --skip-trust가 필수이다. 생략하면 exit 55로 실패한다. 이를 스킬/규칙(skill/rule)에 철저히 반영하는 데 반나절이 걸렸다.

Context Rot (컨텍스트 부패)

1M 토큰 모델이라도 300~400k 부근부터 모델 성능이 저하된다. CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000을 설정하여, 빠른 자동 컴팩트(Auto Compact)로 대처하고 있다.

에이전트에 의한 파일 삭제 사고

앞서 언급했듯이, isolation: "worktree" 없이 대규모 변경을 에이전트에게 위임하면 예기치 않은 파일 삭제가 발생한다. 반드시 worktree 격리를 사용하고, 지시 사항에 "기존 파일을 삭제하지 말 것"을 명시한다.

요약

Claude Code의 .claude 설정을 진심으로 키워나가면 다음과 같은 결과가 된다:

• CLAUDE.md는 포인터만 유지 (200행 이내)
• **rules/**에 환경 특유의 함정(Pitfall)을 축적 (실제로 빠졌던 함정만 기록)
• **skills/**에서 자주 사용하는 워크플로우를 슬래시 명령어(Slash Command)화 (53개)
• **agents/**에서 특화형 에이전트 팀을 편성 (12개)
• Hooks로 시스템 레벨의 품질 보증 (포맷팅, 블로킹, 모니터링)
• 토큰 절약을 절대 원칙으로 하여 Gemini CLI, Serena, Context7과 역할 분담

"AI에게 전부 시키는 것"보다 "AI의 강점을 끌어내는 설계를 하는 것"이 압도적으로 효과적이었다.

설정은 GitHub에서 관리하고 있으며, 여러 단말기에서 git pull을 하는 것만으로 동기화할 수 있는 체제로 구축했다.

참고

• Claude Code 공식 문서
• Serena MCP
• Context7
• Boris Cherny (Claude Code 제작자)의 87 Tips 컬렉션