Claude Code 커스텀 설정 백업 (~/.claude 원천 동기화)
Note
빠른 개발보다 안전한 개발을 우선하도록 설계되었습니다.
가드레일로 인해 동작이 일부 제한될 수 있으며, 업무용에 더 적합합니다.
특히 Kotlin + WebFlux 기반 백엔드 개발 환경을 기준으로 설계되었으며, 다른 환경에서 쓸 경우 프롬프트와 rule 구성을 검수 후 사용하는 것을 권장합니다.
사내 정보(도메인·프로젝트 키·사내 전용 스킬·토큰)는 제거하고 예시 값으로 치환했습니다.
- 보안 중심 설계 — 외부 저장소/인프라에 영향을 줄 수 있는 작업은 차단하고 read-only 커맨드만 허용한다.
- 중단 없는 실행 — ask를 지양하고 allow/deny로 즉시 판단해서, 작업이 중단 없이 끝까지 수행되도록 한다.
- 환경이 강제하는 검증 — 사람이 기억해야 지켜지는 규칙보다, 안 지키면 훅/CI가 막는 구조를 우선한다 (
rules/09-persona.mdR1). - 가드레일은 플러그인으로 분리 — 실행 로직은 guardrail 플러그인이 관리하고, 이 레포는 개인 정책
policy.json만 들고 있다. - 시크릿 분리 관리 — 민감 정보는 git-ignored된
settings.local.json에서 관리한다.
| 파일/디렉토리 | 내용 |
|---|---|
CLAUDE.md |
진입점 라우터 (언어 정책, 핵심 원칙, 워크플로우, 출력 규약, 자기 점검) |
rules/ |
상세 룰셋 (아래 표) |
settings.json |
permission allow/deny, 훅 등록, 활성 플러그인, marketplace 등록 |
policy.json |
guardrail 플러그인이 읽는 개인 정책 |
commands/ |
슬래시 커맨드 |
skills/ |
직접 만든 스킬 (marketplace/플러그인 스킬은 제외) |
scheduled-tasks/ |
예약 작업 (cron) |
persona/ |
개인 선호·판단 기준의 원본 — 실제 세션에서 반복된 지적·거절 사례 모음 |
hooks/ |
settings.json이 등록하는 훅 스크립트 (전부 fail-open) |
rules/*.md는 CLAUDE.md 하단의 @rules/... import로 프롬프트에 로드된다. CLAUDE.md만 깔고 rules/를 빼면 룰이 하나도 적용되지 않는다.
원천 환경에서는 ruler가 ~/.config/ruler/*.md를 합쳐 ~/.claude/CLAUDE.md 단일 파일을 만든다. ruler를 쓰지 않아도 위 import 방식으로 동일하게 동작한다.
| 파일 | 내용 |
|---|---|
00-core.md |
지시/데이터 경계, 불확실성 처리, 출력 규약, 범위 규율, 자연어 모호성 |
01-safety-approvals.md |
시크릿, 파괴적 작업, 승인 프로토콜, 운영 안전, 내부 도메인·사설 IP, 가드레일·테스트 우회 금지 |
02-workflow-orchestration.md |
계획 모드, 조사 후 중단, 서브 에이전트, 완료 전 검증 |
04-repo-boundaries.md |
저장소 구조·읽기 전용 경계, worktree 위치 컨벤션 |
06-coding-discipline.md |
코딩 전 판단, 단순함 우선, 외과적 변경, 검증 가능한 success criteria |
07-writing-style.md |
한국어 글쓰기 (직역체·rhetorical question 금지) |
09-persona.md |
개인 선호·판단 기준 (환경이 강제하는 검증, 파괴 용이성, 진짜 중복, 응답 형식) |
10-stack-kotlin.md |
Kotlin 네이밍/함수/에러 처리/라이브러리 정책/주석 |
11-stack-reactive.md |
WebFlux·Reactor 블로킹 금지, 스케줄러, traceId 전파 |
12-stack-testing.md |
테스트 필요 조건, Gradle 검증 명령, async 테스트 hang 방지, 테스트 결정성 |
persona 문서가 뭔지: 이 사용자가 코드 리뷰·설계 논의에서 반복적으로 지적하고 거절해 온 것들을 정리한 문서다. "미니멀이 기본", "확장성보다 파괴 용이성", "AI 주장 대신 실행 흔적" 같은 판단 기준을 매번 다시 설명하지 않기 위해 있다.
rules/09-persona.md는 프롬프트에 항상 로드되는 규칙 요약이고,persona/PERSONA-FULL.md는 그 규칙이 어떤 지적에서 나왔는지 담은 원본이다 — 교정·반박 사례, 반복 표현, 안 하는 것 목록, 이상(선언한 규칙) vs 실제(행동으로 드러난 것) 대조. 설치 위치~/.claude/persona/PERSONA-FULL.md.
가드레일 차단 로직은 이 레포에 없다. guardrail@lauvsong 플러그인이 담당하고, settings.json에 설치 선언만 들어있다.
{
"enabledPlugins": {
"guardrail@lauvsong": true,
"scan-injection@lauvsong": true
},
"extraKnownMarketplaces": {
"lauvsong": { "source": { "source": "git", "url": "https://github.com/lauvsong/marketplace.git" } }
}
}| 플러그인 | 역할 |
|---|---|
guardrail@lauvsong |
PreToolUse 훅. 위험 Bash 명령·보호 파일 접근·MCP 쓰기 호출 차단 |
scan-injection@lauvsong |
PostToolUse 훅. 외부 텍스트의 prompt injection 의심 패턴 경고 (차단 아님) |
주요 차단 대상:
- 외부 Write 작업 —
git push, PR 생성 등 - Claude 설정 파일 접근/수정 — self-modification 및 권한 상승 방지
- 시크릿 파일 접근 —
.env,*.key,~/.ssh,~/.aws등 - 차단 우회 명령어 —
eval,sh -c,base64 -d등 - 컨텍스트 폭식 명령 —
cat/head/tail원본 덤프, 최상위grep/find/ls -R(Read·Glob·rtk 사용 유도)
settings.json의 deny 설정으로도 차단할 수 있지만 미동작 버그(#8961)로 쓰지 않는다.
Warning
bypassPermissions: true 설정 시 PreToolUse 훅이 비동기로 동작하면서
exit code 2 기반 차단이 정상 적용되지 않는 문제가 있다.
일부 차단 로직이 우회될 수 있으므로 bypassPermissions 옵션은 쓰지 않는 것을 권장한다.
없어도 설치는 되고 해당 기능만 비활성된다. install.sh의 preflight가 무엇이 빠졌는지 알려준다.
| 도구 | 없으면 |
|---|---|
rtk |
Bash PreToolUse 훅(rtk hook claude) 실패. CLAUDE.md의 rtk prefix 규약도 무효 |
jq |
hooks/*.sh 전부 동작 안 함 |
gh |
gh/gh-enterprise 스킬, github-notification-cleanup 예약작업 비활성 |
bun |
statusLine(claude-hud) 표시 안 됨 |
git clone https://github.com/lauvsong/claude-soul.git
cd claude-soul && ./install.sh기존 ~/.claude가 있으면 자동으로 ~/.claude.bak에 백업한다.
install.sh가 하는 일:
| 대상 | 설치 위치 |
|---|---|
CLAUDE.md, settings.json |
~/.claude/ |
rules/, commands/, skills/, scheduled-tasks/, persona/, hooks/ |
~/.claude/ |
policy.json |
~/.claude/plugins/guardrail/policy.json |
install.sh가 settings.json의 extraKnownMarketplaces / enabledPlugins를 읽어 claude plugin marketplace add + claude plugin install을 직접 실행한다. 활성 24개(비활성 5개는 설치 안 함)가 항목별 [ok]/[FAIL]로 찍히므로 뭐가 안 깔렸는지 바로 보인다. 목록은 plugins.md.
선언만으로 Claude Code가 재시작 시 설치를 시도하기도 하지만, 성공 여부가 확인되지 않아 CLI로 명시 설치한다. 건너뛰려면 SKIP_PLUGINS=1 ./install.sh.
claude CLI가 없으면 이 단계는 건너뛰고 나머지 설치는 그대로 끝난다.
MCP 서버는 ~/.claude.json에서 관리되고 이 레포에 포함되지 않는다 (대부분 사내용 + 인증정보 경유). 공개 서버 headroom만 install.sh가 등록한다 — headroom 바이너리가 이미 있을 때만:
claude mcp add headroom --scope user -- headroom mcp servesettings.json의 permissions.allow에 선언된 다른 mcp__* 항목은 서버가 없으면 그냥 무시된다.
| 항목 | 왜 |
|---|---|
env / 토큰 |
시크릿. settings.local.json에 직접 작성 |
| 사내 MCP 서버·marketplace | 레포에서 의도적으로 제외 |
rtk, jq, gh, bun |
환경별 설치 경로가 달라 preflight 경고만 |
settings.json이 등록하는 훅. 전부 fail-open이라 조건에 안 맞는 프로젝트에서는 조용히 통과한다.
| 훅 | 시점 | 동작 |
|---|---|---|
rtk hook claude |
PreToolUse Bash | 명령을 rtk로 재작성해 출력 토큰 절감 (rtk 필요) |
precommit_coverage.sh |
PreToolUse Bash | AI가 git commit 할 때 staged *Service.kt의 branch coverage 미달이면 차단. gradle/jacoco 아니면 통과 |
serena-discovery-gate.sh |
PreToolUse Read·Grep | .serena/ 있는 프로젝트에서 serena로 범위를 좁히기 전 원본 Read/Grep 차단. 해제: touch /tmp/serena-unlock |
serena-marker.sh |
PostToolUse serena | serena 호출 후 120초간 Read 허용 창을 연다 |
settings.json에는 토큰을 넣지 않는다. env 섹션 자체가 이 레포에서 제외되어 있다.
~/.claude/settings.local.json에 머신별로 만든다.
{
"env": {
"GITHUB_HOST": "...",
"GITHUB_PERSONAL_ACCESS_TOKEN": "..."
}
}settings.local.json은 .gitignore에 포함되어 git에 올라가지 않는다.
policy.json은 guardrail 플러그인의 개인 정책 파일이다. 플러그인 내부 기본값(policies/default.json)을 덮어쓰는 개인 커스텀 레이어이고, 설치 위치는 ~/.claude/plugins/guardrail/policy.json이다.
플러그인은 첫 실행 시 이 파일이 없으면 기본 정책을 복사해서 만들고, 이후 플러그인이 업데이트돼도 이미 만들어진 개인 파일은 덮어쓰지 않는다. 즉 여기 있는 policy.json이 내 환경의 실제 정책 스냅샷이다.
이 파일 자체가 guardrail 보호 대상이라 Claude를 통한 수정이 차단된다 (자기 가드레일 우회 방지). 직접 편집해야 한다.
주요 키:
| 키 | 설명 |
|---|---|
protect.files |
Read/Edit/Write/Bash 접근을 차단할 파일 glob 목록 |
protect.hints |
보호 파일별 차단 안내 메시지 (왜 막혔는지, 뭘 대신 고쳐야 하는지) |
allow.read_files |
protect.files에 걸리더라도 Read 툴만 허용할 파일 |
deny |
Bash 명령 차단 규칙. rule 이름 → 정규식 |
always_deny |
scoped_allow로도 풀 수 없는 rule 이름 목록 |
scoped_allow.repos |
특정 저장소에서만 일부 deny rule을 허용하는 예외 |
mcp_write_actions |
차단할 MCP 쓰기 action (mcp__server__action 형식) |
특정 repo에서만 막힌 명령을 허용하려면:
{
"scoped_allow": {
"repos": {
"lauvsong/backtest": ["git push", "gh pr comment"]
}
}
}저장소 판정은 현재 git remote 기준이고, gh 명령은 --repo/-R 인자를 우선한다. always_deny에 들어간 rule은 scoped allow로도 풀리지 않는다.
정책 경로를 다른 곳에 두려면 플러그인 README의 환경변수 override를 참고한다.
.
├── CLAUDE.md # 진입점 라우터
├── settings.json # permission, 훅, 플러그인, marketplace
├── policy.json # guardrail 개인 정책 (→ ~/.claude/plugins/guardrail/)
├── install.sh
├── plugins.md # 사용 중인 플러그인 목록
├── rules/ # 상세 룰셋 (CLAUDE.md 에서 @import)
├── commands/ # 슬래시 커맨드
├── skills/ # 직접 만든 스킬
├── hooks/ # settings.json 이 등록하는 훅 스크립트
├── persona/ # 개인 선호·판단 기준 원본 (사례 모음)
└── scheduled-tasks/
└── github-notification-cleanup/
| 커맨드 | 설명 |
|---|---|
/backup-customs |
~/.claude/ 설정을 이 레포에 동기화 |
/handoff |
세션 인수인계 문서(HANDOFF.md) 생성 |
| 스킬 | 설명 | 출처 |
|---|---|---|
ask |
코드 수정 없이 코드베이스 질의응답 | 자작 |
claude-security-review |
보안 설정(settings.json, 훅, rules) 검수 | 자작 |
codex |
Codex CLI 연동 (토큰 절약용) | 자작 |
docs-ux-review |
문서를 독자 관점에서 검수 | 자작 |
domain-modeling |
도메인 용어·ADR 정리 (CONTEXT.md, docs/adr/) |
mattpocock/skills |
gh |
GitHub 작업 시 gh CLI 가이드 | 자작 |
gh-enterprise |
GitHub Enterprise 환경에서의 gh CLI 가이드 | 자작 |
grilling |
설계·계획을 질문으로 스트레스 테스트 | mattpocock/skills |
grill-me |
grilling 세션 시작 (슬래시 커맨드용) |
mattpocock/skills |
grill-with-docs |
grilling + domain-modeling으로 용어·ADR까지 기록 |
mattpocock/skills |
handoff |
세션 인수인계 문서 작성 규칙 | mattpocock/skills |
korean-tone-review |
한국어 산출물의 직역체·기계 번역체 검수 | 자작 (참조 문서 1개는 외부 출처) |
lesson |
프로젝트 로컬 교훈 기록 | 자작 |
lesson-global |
전역 rules에 교훈 반영 | 자작 |
template |
새 스킬 작성용 템플릿 | 자작 |
외부에서 가져온 스킬은 자작이 아니고, 로컬에서 손본 상태다. 원본과 diff 가 있으니 업데이트할 때 그대로 덮어쓰면 로컬 수정이 날아간다.
domain-modeling,grilling,grill-me,grill-with-docs,handoff— mattpocock/skills (MIT). 전부 로컬 수정본.grilling은 라운드 포맷을 걷어내고 craft-alignment 패스를 붙였고,handoff는 저장 위치를 프로젝트.claude/handoffs/로 바꿨다.grill-me/grill-with-docs는 호출 방식만 슬래시 커맨드로 고쳤다.domain-modeling은 가져온 시점의 원본과 문장 표현 차이가 있다.korean-tone-review/references/ai-tell-taxonomy.md— epoko77-ai/im-not-ai 의ai-tell-taxonomy.md를 한국어 케이스로 재작성 (MIT). 파일 상단에 출처 명시.
출처는 ~/.agents/.skill-lock.json 이 원천이다. 스킬을 새로 넣을 때 여기서 source 를 확인하고 위 표에 반영한다.
| 태스크 | 설명 |
|---|---|
github-notification-cleanup |
merged PR의 GitHub 알림을 자동으로 done 처리 |