Claude Code는 설치하는 순간부터 강력합니다. 하지만 이를 진짜 팀원처럼 느껴지게 만드는 것은 모델이 아니라, 그 주변에 구축한 설정입니다. 즉, 커스텀 슬래시 명령어(slash commands), 전문 서브에이전트(subagents), 그리고 적절한 시점에 실행되는 훅(hooks)입니다.

문제는 새로 설치하면 .claude/ 폴더가 비어 있다는 점입니다. 문서를 읽고 직접 설정을 작성한 후에야 비로소 그 모든 가치를 얻을 수 있습니다.

그래서 저는 이제 모든 저장소(repo)에 복사해 넣는 설정을 소개하려 합니다. 아래의 모든 내용은 그대로 붙여넣고, 읽고, 수정할 수 있는 일반 파일입니다. 실제 명령어, 서브에이전트, 그리고 훅을 실제 코드와 함께 왜 각 부분이 필요한지 설명해 드릴 테니, 여러분도 오후 시간 동안 직접 다시 구축할 수 있을 것입니다.

비공식이며 커뮤니티에서 제작되었습니다. Anthropic과 제휴하거나 Anthropic의 승인을 받지 않았습니다. "Claude" 및 "Claude Code"는 Anthropic의 상표입니다. 이것은 Claude Code를 위한 독립적인 설정이며, Anthropic의 제품이 아닙니다.

이 설정이 위치하는 곳

두 군데의 위치가 있으며, 둘 다 사용할 수 있습니다:

• 홈 디렉토리의 ~/.claude/ — 여러분이 여는 모든 프로젝트에 적용됩니다.
• 저장소 루트의 .claude/ — 해당 프로젝트에만 적용되며, 팀과 공유하기 위해 커밋할 수 있습니다.

프로젝트 파일과 글로벌 파일이 충돌할 경우, 프로젝트 파일이 우선합니다. 저는 범용적인 명령어와 서브에이전트는 ~/.claude/에 두고, 프로젝트별 규칙은 저장소에 둡니다.

1. 슬래시 명령어는 단순한 마크다운 파일입니다

파일 이름이 곧 명령어 이름이 됩니다. 예를 들어 .claude/commands/review.md는 /review가 됩니다. 본문은 Claude가 실행할 프롬프트(prompt)입니다. 여기 유용하게 사용할 수 있는 전체 예시인 프리 커밋(pre-commit) 코드 리뷰 명령어가 있습니다:

---
description: "커밋하기 전에 버그, 리스크 및 품질을 위해 현재 변경 사항을 검토합니다"
argument-hint: [선택 사항인 경로 또는 집중 분야]
...

여기서 세 가지 요소가 작업을 수행합니다:

• !는 셸 명령어를 실행하고 그 출력을 프롬프트에 주입합니다. !`git diff HEAD`는 Claude가 차이점에 대한 설명이 아니라, 사용자의 실제 현재 diff를 검토한다는 것을 의미합니다. 이것은 시스템 전체에서 가장 유용한 단일 트릭입니다.
• **allowed-tools**는 정확히 해당 git 명령어들을 사전 승인하여, /review가 diff를 읽을 때마다 매번 권한을 묻기 위해 멈추지 않도록 합니다.
• **$ARGUMENTS**는 명령어 뒤에 입력하는 모든 내용입니다. /review the auth changes는 리뷰의 초점을 맞추고, /review만 입력하면 모든 것을 검토합니다.

이제 /review는 모호한 "이것 좀 확인해 줄래?" 대신, 매번 변경 사항에 대해 일관된 시니어 스타일의 검토를 제공합니다.

2. 저장소의 컨벤션(Conventions)을 /commit에 녹여내기

커밋(commit)을 대상으로 하는 동일한 아이디어입니다. 여기서의 핵심은 Claude에게 최근 히스토리를 제공하여, 새로운 메시지가 사용자가 이미 사용 중인 스타일과 일치하도록 만드는 것입니다:

---
description: 현재 변경 사항으로부터 잘 구성된 git commit을 생성합니다
argument-hint: [선택 사항인 메시지 또는 의도]
...

!`git log --oneline -10`이 마지막 10개의 커밋을 주입하기 때문에, Claude는 일반적인 chore: update files가 아니라 사용자의 스타일로 작성합니다. 그리고 "do not push"는 사용자의 머신을 벗어나는 단 한 단계에 대해 사람이 개입(human in the loop)하도록 유지합니다.

3. 서브에이전트(Subagents): 자체 컨텍스트 윈도우를 가진 전문가

서브에이전트는 약간의 프론트매터(frontmatter)와 시스템 프롬프트(system prompt)를 포함한 .claude/agents/ 디렉토리 내의 마크다운(markdown) 파일입니다. Claude는 자동으로 서브에이전트에게 작업을 넘길 수 있으며, 사용자가 이름을 직접 호출할 수도 있습니다. 이점은 서브에이전트가 **별도의 컨텍스트 윈도우 (separate context window)**에서 작동하므로, 긴 리뷰나 감사(audit) 작업이 메인 대화를 어지럽히지 않는다는 것입니다.

제가 사용하는 code-reviewer는 다음과 같습니다:

---
name: code-reviewer
description: 전문 코드 리뷰어. 코드를 작성하거나 변경한 직후에 선제적으로(PROACTIVELY) 사용하십시오,
...

두 가지 세부 사항이 중요합니다:

• description은 Claude가 언제 위임할지를 결정하는 기준입니다. "코드를 작성한 직후에 선제적으로(PROACTIVELY) 사용하십시오"와 같이 작성해야 서브에이전트(subagent)가 스스로 트리거됩니다. 모호한 설명은 절대 실행되지 않습니다.
• tools는 접근 가능한 범위를 제한합니다. 리뷰어는 읽기와 검색(Read, Grep, Glob, Bash)만 수행하면 됩니다. 파일을 직접 수정해서는 안 됩니다. tools를 완전히 생략하면 모든 권한을 상속받게 됩니다.

이렇게 설정해 두면, Claude는 변경 사항이 발생한 후 스스로 리뷰어를 호출하는 경향이 있습니다. 물론 "code-reviewer가 auth 모듈을 살펴보게 해줘"와 같이 언제든 강제로 실행할 수도 있습니다.

4. 훅(Hooks): 잊기 쉬운 작업을 자동화하기

훅(Hooks)은 세션의 정의된 시점에 사용자의 셸 명령어를 실행합니다. 이들은 settings.json에 저장됩니다. 제가 없으면 작업할 수 없을 정도로 애용하는 훅은 Claude가 파일을 수정하는 즉시 모든 파일을 포맷팅합니다:

{
  "hooks": {
    "PostToolUse": [
...

해석 방법은 다음과 같습니다:

• **PostToolUse + matcher: "Edit|Write|MultiEdit"**는 "Claude가 파일을 수정하거나 작성한 후에 실행하라"는 의미입니다. 매처(matcher)는 도구 이름에 대한 정규 표현식(regex)입니다.
• Claude Code는 훅에 **stdin을 통해 JSON 페이로드(payload)**를 보냅니다. 여기서는 jq를 사용하여 방금 수정된 파일인 .tool_input.file_path를 추출합니다.
• 확장자에 따라 포맷터를 선택하며, 해당 포맷터가 설치되어 있지 않으면 조용히 아무 작업도 하지 않습니다(no-ops). 따라서 black이 설치되지 않은 환경에서도 세션이 중단되지 않습니다.
• 종료 코드(Exit codes)가 계약 조건입니다: 0은 정상이며 계속 진행합니다. 2는 해당 동작을 차단하고 Claude에게 그 이유로서 메시지를 전달합니다. (예를 들어 .env 경로에 대해 2를 반환하며 종료하는 PreToolUse 훅은 Claude가 비밀 정보를 수정하는 것을 방지하는 훌륭한 가드 역할을 합니다.)

jq가 유일한 의존성입니다 (brew install jq / sudo apt install jq).

2분 만에 설치하기

파일을 가져와서 넣고, 재시작하세요:

mkdir -p ~/.claude/commands ~/.claude/agents
cp commands/*.md ~/.claude/commands/
cp agents/*.md   ~/.claude/agents/
...

Claude Code를 재시작하고 /를 입력하면 명령어가 나타납니다. /agents를 실행하여 서브에이전트를 확인하고, /hooks를 실행하여 훅이 로드되었는지 확인하세요.

이 모든 것을 더 낫게 만드는 하나의 습관

위의 프롬프트들에서 하나의 공통된 테마를 발견할 수 있습니다. 바로 정직하게 (honest) 작성되었다는 점입니다. 리뷰 명령어는 문제를 지어내지 말라고 지시받습니다. 동반 명령어인 /pr은 테스트를 통과한 척하는 대신 "아직 테스트되지 않음 (not yet tested)"라고 작성합니다. 이것은 매우 중요합니다. AI 팀원에 대한 신뢰를 잃는 가장 빠른 방법은, 테스트를 실행하지도 않았으면서 테스트를 통과했다고 주장하는 것을 목격하는 것이기 때문입니다. 프롬프트에 이러한 점을 녹여내면 출력 결과의 신뢰성을 유지할 수 있습니다.

파일 가져오기

4개의 명령어, code-reviewer 서브에이전트 (subagent), 자동 포맷팅 훅 (auto-format hook), 그리고 CLAUDE.md 템플릿을 MIT 라이선스의 무료 리포지토리 (repo)에 올려두었으니 바로 복사해서 사용하실 수 있습니다:

→ Claude Code Starter Kit on GitHub (MIT — 사용하고, 수정하고, 배포하세요)

만약 12개의 명령어, 6개의 서브에이전트 (subagents), 5개의 훅 (hooks), git을 인식하는 상태 표시줄 (status line), 그리고 전체 CLAUDE.md 템플릿이 포함된 전체 세트를 원하신다면, 단계별 가이드와 함께 묶인 유료 Power Pack이 준비되어 있습니다. 하지만 위의 리포지토리만으로도 오늘 바로 충분한 가치를 얻으실 수 있습니다.

즐거운 개발 되시길 바랍니다.