Skip to content

About

Custom Claude Code settings — rules, hooks, skills, and scheduled tasks

Resources

Stars

36 stars

Watchers

0 watching

Forks

Repository files navigation

claude-soul

Claude Code 커스텀 설정 백업 (~/.claude 원천 동기화)

Note

빠른 개발보다 안전한 개발을 우선하도록 설계되었습니다. 가드레일로 인해 동작이 일부 제한될 수 있으며, 업무용에 더 적합합니다. 특히 Kotlin + WebFlux 기반 백엔드 개발 환경을 기준으로 설계되었으며, 다른 환경에서 쓸 경우 프롬프트와 rule 구성을 검수 후 사용하는 것을 권장합니다. 사내 정보(도메인·프로젝트 키·사내 전용 스킬·토큰)는 제거하고 예시 값으로 치환했습니다.


철학

  • 보안 중심 설계 — 외부 저장소/인프라에 영향을 줄 수 있는 작업은 차단하고 read-only 커맨드만 허용한다.
  • 중단 없는 실행 — ask를 지양하고 allow/deny로 즉시 판단해서, 작업이 중단 없이 끝까지 수행되도록 한다.
  • 환경이 강제하는 검증 — 사람이 기억해야 지켜지는 규칙보다, 안 지키면 훅/CI가 막는 구조를 우선한다 (rules/09-persona.md R1).
  • 가드레일은 플러그인으로 분리 — 실행 로직은 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 방식으로 동일하게 동작한다.

Rules

파일 내용
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.


Guardrails

가드레일 차단 로직은 이 레포에 없다. 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 옵션은 쓰지 않는 것을 권장한다.

관련 이슈: #20946, #26923


Setup

사전 요구사항

없어도 설치는 되고 해당 기능만 비활성된다. 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 서버

MCP 서버는 ~/.claude.json에서 관리되고 이 레포에 포함되지 않는다 (대부분 사내용 + 인증정보 경유). 공개 서버 headroom만 install.sh가 등록한다 — headroom 바이너리가 이미 있을 때만:

claude mcp add headroom --scope user -- headroom mcp serve

settings.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 (개인 정책)

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를 참고한다.


Structure

.
├── 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/

Commands

커맨드 설명
/backup-customs ~/.claude/ 설정을 이 레포에 동기화
/handoff 세션 인수인계 문서(HANDOFF.md) 생성

Skills

스킬 설명 출처
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 를 확인하고 위 표에 반영한다.


Scheduled Tasks

태스크 설명
github-notification-cleanup merged PR의 GitHub 알림을 자동으로 done 처리

About

Custom Claude Code settings — rules, hooks, skills, and scheduled tasks

Resources

Stars

36 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages