Everything Claude Code: Anthropic x Forum Ventures 해커톤 우승자가 정리한, Claude Code 실전 설정 및 가이드

읽을거리&정보공유
, , , , , , , , ,
1

Everything Claude Code: Anthropic x Forum Ventures 해커톤 우승자가 정리한, Claude Code 실전 설정 및 가이드
Everything Claude Code: Anthropic x Forum Ventures 해커톤 우승자가 정리한, Claude Code 실전 설정 및 가이드680×272 34.9 KB

Everything Claude Code 소개

Everything Claude Code는 Anthropic의 CLI 기반 AI 에이전트 도구인 Claude Code를 실제 개발 업무에 효율적으로 활용하기 위한 설정(Configuration) 및 워크플로우 모음집입니다. 이 프로젝트는 Claude Code를 단순 보조 도구가 아닌, 프로젝트 구조를 이해하고 주도적으로 코딩하는 '동료 에이전트'로 만들기 위한 구체적인 파일 구조와 설정값을 제공합니다.

많은 개발자들이 AI 코딩 도구를 사용하지만, 단순한 채팅 인터페이스를 넘어 자신의 워크플로우에 맞게 고도화하는 데에는 어려움을 겪습니다. 이를 위해 Everything Claude Code 저장소는 Anthropic x Forum Ventures 해커톤 우승자인 @affaanmustafa가 10개월간 매일 Claude Code를 사용하며 최적화한 설정을 담고 있습니다.

단순히 도구를 설치하는 것을 넘어, 스킬(Skills), 훅(Hooks), 서브에이전트(Subagents), MCP 등을 유기적으로 연결하여 반복 작업을 자동화하고 컨텍스트 효율을 극대화하는 방법을 제시합니다. 특히, 대규모 코드베이스를 다룰 때 발생할 수 있는 컨텍스트 윈도우 부족 문제를 해결하고, 생산성을 높이는 구체적인 설정값을 포함하고 있습니다.

무엇보다 이 프로젝트는 단순한 기능 설명이 아니라, 실제 프로젝트와 해커톤 현장에서 검증된 실전형 설정(Setup) 을 담고 있다는 것이 특징입니다.

Everything Claude Code 구성

이 저장소는 Claude Code의 잠재력을 100% 끌어내기 위한 디렉토리 구조와 설정 파일들로 구성되어 있습니다. 주요 구성 요소들은 다음과 같습니다:

핵심 디렉토리 구조 (~/.claude/)

Everything Claude Code는 사용자의 홈 디렉토리 내 .claude 폴더를 체계적으로 구조화하여 에이전트의 행동을 정의합니다:

~/.claude/
├── skills/       # 워크플로우 정의 (복잡한 작업 단축키)
├── commands/     # 즉시 실행 가능한 짧은 프롬프트
├── agents/       # 특정 작업에 특화된 서브 에이전트 정의
├── rules/        # AI가 항상 따라야 할 규칙 (Best Practices)
└── config.json   # MCP 및 도구 설정

Skills와 Commands: 워크플로우의 모듈화 및 체이닝

Claude Code를 효율적으로 사용하기 위한 첫 번째 단계는 반복적인 작업을 'Skill(스킬)'로 정의하는 것입니다:

스킬(Skills) 은 특정 범위와 워크플로우에 제한된 규칙(Rules)처럼 작동하며, 복잡한 프롬프트 입력을 단축해 주는 역할을 합니다. 이는 ~/.claude/skills 디렉터리에 마크다운(.md) 파일 형태로 저장됩니다. 예를 들어, 코딩 세션이 끝난 후 죽은 코드를 정리하고 불필요한 파일을 삭제하는 작업을 /refactor-clean이라는 하나의 스킬로 정의할 수 있습니다. 또한, 테스트 주도 개발(TDD)을 위한 /tdd, 엔드 투 엔드 테스트를 위한 /e2e 등 다양한 스킬을 생성하여, 필요할 때마다 호출할 수 있습니다.

image
image680×218 30.6 KB

슬래시 명령어(Commands) 는 이러한 스킬들을 실행하거나 즉각적인 작업을 수행하기 위한 슬래시(/) 명령어입니다. 이들은 ~/.claude/commands에 저장되며, 스킬과 결합하여 강력한 체이닝(Chaining) 기능을 제공합니다. 사용자는 단일 프롬프트 내에서 여러 스킬과 커맨드를 연결하여 "리팩토링 후 테스트를 실행하고, 커버리지를 확인하라"는 복잡한 명령을 한 번에 내릴 수 있습니다. 또한 codemap-updater.md와 같은 스킬을 통해 체크포인트마다 코드맵을 업데이트하게 함으로써, Claude가 매번 전체 코드베이스를 탐색하는 데 컨텍스트를 낭비하지 않고 빠르게 구조를 파악하도록 도울 수 있습니다.

(:pytorch::kr:Claude의 스킬과 관련한 내용은 다음 글에서 더 상세히 확인할 수 있습니다: Anthropic, Claude에 업무 방식과 조직 환경에 맞게 직접 커스터마이징할 수 있는 Claude Agent용 Skills 기능 출시)

Hooks: 이벤트 기반의 지능형 자동화

단순한 명령어 실행을 넘어, 특정 상황에서 자동으로 반응하도록 시스템을 구성하려면 훅(Hooks) 을 설정해야 합니다. Hooks는 도구 사용(Tool Use)이나 시스템의 수명 주기(Lifecycle) 이벤트에 반응하여 실행되는 자동화 트리거입니다:

  • PreToolUse: 도구가 실행되기 직전에 작동하며, 입력값을 검증하거나 개발자에게 중요한 알림을 보낼 때 사용됩니다.

  • PostToolUse: 도구 실행이 완료된 직후에 작동하며, 결과물의 포맷팅을 맞추거나 피드백 루프를 돌릴 때 유용합니다.

  • UserPromptSubmit: 사용자가 메시지를 전송할 때 실행됩니다.

  • Stop: Claude가 응답을 마쳤을 때 실행됩니다.

실전에서 가장 유용한 예시 중 하나는 '장기 실행 명령 보호' 훅(hook)입니다. npm install, cargo build 등 실행 시간이 긴 명령어가 감지되면, 세션 지속성을 위해 tmux를 사용할 것을 제안하는 훅을 PreToolUse 단계에 설정할 수 있습니다.

image
image652×156 14.2 KB

또한, .ts 파일이 수정되면 자동으로 prettier를 실행하거나(PostToolUse), git push 전에 반드시 코드 리뷰를 거치도록 강제하는 등의 설정이 가능합니다.

이러한 설정이 복잡하게 느껴진다면, hookify 플러그인을 설치하여 /hookify 명령어로 대화하듯이 훅을 생성할 수 있습니다.

Subagents: 컨텍스트 절약을 위한 작업 위임

프로젝트가 커질수록 단일 에이전트가 모든 맥락을 기억하는 것은 불가능해집니다. 이를 해결하기 위해 서브에이전트(Subagents) 아키텍처를 사용합니다. 메인 오케스트레이터인 Claude는 특정 작업에 특화된 서브에이전트에게 업무를 위임할 수 있습니다. 서브에이전트는 메인 에이전트와 별도로 백그라운드나 포그라운드에서 실행되며, 제한된 범위(Scope)와 도구 권한을 가집니다.

~/.claude/agents/ 디렉터리에 각 에이전트의 역할 정의 파일(예: planner.md, architect.md, security-reviewer.md)을 생성하여 관리합니다. 예를 들어, '보안 검토자(Security Reviewer)' 에이전트는 오직 보안 관련 도구와 스킬만 사용할 수 있도록 샌드박싱(Sandboxing)하여, 불필요한 도구 사용으로 인한 혼란을 방지하고 컨텍스트 효율을 극대화합니다. 이는 메인 에이전트의 컨텍스트 윈도우를 확보하는 데 핵심적인 전략입니다.

Rules: 일관된 품질을 위한 불변의 규칙

Claude가 매번 일관된 스타일과 품질의 코드를 작성하게 하려면 규칙(Rules) 설정이 필수적입니다. ~/.claude/rules/ 폴더에 .md 파일로 저장된 규칙들은 Claude가 작업을 수행할 때 항상(ALWAYS) 따라야 하는 지침이 됩니다.

이 규칙들은 단일 파일로 관리할 수도 있지만, 관심사별로 모듈화하는 것이 유지보수에 유리합니다. 다음은 이러한 모듈화의 예시입니다:

~/.claude/rules/
  security.md      # 하드코딩된 비밀번호 금지, 모든 입력값에 대한 검증 수행.
  coding-style.md  # 불변성(Immutability) 유지, 파일 크기 제한
  testing.md       # TDD 워크플로우, 80% coverage
  git-workflow.md  # 커밋 메시지 양식(Commit format), PR 프로세스 준수
  agents.md        # 언제 서브에이전트에게 작업을 위임할지
  performance.md   # 모델 선택 및 컨텍스트 관리 등

이러한 규칙들은 단순히 스타일을 맞추는 것을 넘어, "콘솔 로그(console.log)를 절대 커밋하지 말 것"이나 "배포 전에는 반드시 테스트를 수행할 것"과 같은 운영상의 안전장치 역할을 수행합니다.

MCP (Model Context Protocol)와 컨텍스트 관리 전략

MCP는 Claude를 외부 데이터 소스나 서비스(Supabase, PostgreSQL, GitHub, Vercel 등)와 직접 연결해 주는 표준 프로토콜입니다. 이를 통해 Claude는 단순히 코드를 작성하는 것을 넘어, 데이터베이스의 테이블 스키마를 직접 조회하거나 배포 상태를 확인할 수 있습니다. 예를 들어, Supabase MCP를 사용하면 SQL 쿼리를 복사해서 붙여넣을 필요 없이, Claude가 직접 DB에 접속하여 필요한 데이터를 가져옵니다.

image
image677×115 42.9 KB

하지만 MCP 사용 시 가장 주의해야 할 점은 컨텍스트 윈도우(Context Window) 관리입니다. 너무 많은 도구(Tools)를 활성화하면 Claude가 사용할 수 있는 컨텍스트 공간이 급격히 줄어듭니다. 예를 들어, 200k 토큰의 컨텍스트가 있더라도 너무 많은 도구를 켜두면 실제 사용 가능한 공간은 70k로 줄어들어 성능이 심각하게 저하될 수 있습니다.

image
image680×361 31.9 KB

따라서 Everything Claude Code의 저자는 config.json에 20~30개의 MCP를 등록해 두더라도, 프로젝트별로 필요한 5~6개만 활성화(enabled)하고 나머지는 비활성화(disabledMcpServers)하는 전략을 강조합니다. 이렇게 활성화된 MCP들은 10개 미만으로, MCP의 전체 활성 도구(tool)의 수는 80개 미만으로 유지하는 것이 성능 최적화의 핵심입니다.

/plugins 명령어나 /mcp 명령어를 통해 현재 활성화된 도구 목록을 수시로 확인하고 관리해야 합니다.

Plugins와 도구: 기능 확장의 생태계

Plugins(플러그인) 은 스킬, 훅, MCP, 도구 등을 패키지 형태로 묶어 쉽게 설치할 수 있게 해줍니다.

저자는 기본 검색 도구인 grep이나 ripgrep보다 훨씬 강력한 **mgrep (Mixedbread Grep)**의 사용을 권장합니다. 플러그인 마켓플레이스를 통해 설치할 수 있는 mgrep은 로컬 파일 검색뿐만 아니라 웹 검색(--web 옵션)까지 지원하여, "Next.js 15의 변경 사항"과 같은 최신 정보를 검색하여 코딩에 반영할 수 있게 해줍니다.

mgep 설치는 다음과 같이 가능합니다:

# mgrep 마켓플레이스 추가
claude plugin marketplace add https://github.com/mixedbread-ai/mgrep

# Claude 실행 후 `/plugins` 를 실행하여 마켓플레이스 확인 및 설치

image
image680×313 27.9 KB

또한, LSP (Language Server Protocol) 플러그인은 Claude Code를 터미널에서 사용할 때 IDE 수준의 지능을 부여하는 중요한 요소입니다. typescript-lsp나 pyright-lsp를 설치하면, Claude는 별도의 에디터를 열지 않고도 실시간 타입 체크, 정의부 이동(Go-to-definition), 자동 완성을 수행할 수 있습니다.

물리적 환경 설정: Zed Editor와 Tmux

Claude Code는 터미널 도구이지만, 그 효율성은 어떤 에디터와 함께 사용하느냐에 따라 달라집니다. 저자는 Rust 기반의 초고속 에디터인 Zed와의 조합을 강력히 추천합니다. Zed는 Agent Panel 통합을 통해 Claude가 수정하는 파일을 실시간으로 추적하고, 터미널과 에디터 간의 파일 이동(Ctrl+G)을 매끄럽게 지원합니다.

저자는 Zed 에디터를 다음과 같이 사용합니다:

image
image680×491 72 KB

  • 화면 구성: 화면을 분할하여 한쪽에는 Claude Code가 실행되는 터미널을, 다른 쪽에는 Zed 에디터를 배치합니다.
  • 설정: 에디터의 'Auto-save(자동 저장)' 기능을 켜두어 Claude가 항상 최신 파일 내용을 읽을 수 있도록 합니다.
  • Git 통합: Claude가 코드를 수정한 후에는 에디터의 Git 기능을 통해 변경 사항을 시각적으로 검토한 뒤 커밋합니다.

마지막으로, 서버 실행이나 로그 모니터링과 같이 오래 걸리는 작업은 tmux 세션 내에서 실행하는 것이 좋습니다. 이를 통해 Claude가 백그라운드에서 작업을 계속 수행하는 동안 사용자는 세션을 분리(detach)하거나 다시 연결(attach)하며 유연하게 작업을 관리할 수 있습니다.

병렬 작업이 필요할 때는 Git Worktree(git worktree add ...)를 사용하여 충돌 없이 여러 개의 Claude 인스턴스를 동시에 운영하는 방법도 제시됩니다.

저자의 실전 설정 (My Setup)

저자는 또한 실제 프로젝트에서 사용하고 있는 구체적인 설정값들을 공개했습니다. 이 설정들은 단순히 기능 나열이 아니라, 성능 최적화와 자동화를 위해 정교하게 조율된 결과물입니다. 특히 플러그인과 MCP 서버의 경우, 설치는 되어 있되 프로젝트별로 필요한 것만 활성화하여 컨텍스트 윈도우를 관리하는 전략이 핵심입니다.

설치된 플러그인 (Plugins)

저자는 다양한 플러그인을 설치해 두었지만, 한 번에 활성화하는 플러그인은 보통 4~5개로 제한합니다. 이는 불필요한 토큰 소모를 막기 위함입니다. 루프 자동화를 위한 ralph-wiggum, UI/UX 패턴을 다루는 frontend-design, Git 워크플로우를 보조하는 commit-commands 등이 포함됩니다. 또한, 타입스크립트 인텔리전스를 제공하는 typescript-lsp와 더 강력한 검색 기능을 제공하는 mgrep은 개발 효율을 위해 필수적으로 사용됩니다.

ralph-wiggum@claude-code-plugins       # 루프(Loop) 자동화
frontend-design@claude-code-plugins    # UI/UX 디자인 패턴
commit-commands@claude-code-plugins    # Git 워크플로우 자동화
security-guidance@claude-code-plugins  # 보안 검사
pr-review-toolkit@claude-code-plugins  # PR 생성 및 리뷰 자동화
typescript-lsp@claude-plugins-official # TypeScript 인텔리전스 (LSP)
hookify@claude-plugins-official        # 대화형 훅 생성 도구
pyright-lsp@claude-plugins-official    # Python 타입 체크
mgrep@Mixedbread-Grep                  # grep보다 강력한 검색 도구

MCP 서버 설정 및 컨텍스트 관리 전략

사용자 수준(User Level) 설정 파일에는 GitHub, Supabase, Vercel, Cloudflare 등 14개 이상의 다양한 MCP 서버가 등록되어 있습니다. 여기에는 메모리 관리를 위한 memory, 순차적 사고를 돕는 sequential-thinking 서버도 포함됩니다:

{
  "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
  "supabase": {
    "command": "npx",
    "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=YOUR_REF"]
  },
  "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] },
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
  },
  "vercel": { "type": "http", "url": "https://mcp.vercel.com" },
  "cloudflare-docs": { "type": "http", "url": "https://docs.mcp.cloudflare.com/mcp" }
  // ... (기타 서버들)
}

그러나 가장 중요한 것은 프로젝트별 비활성화(Disabled per project) 전략입니다. 모든 MCP를 켜두면 컨텍스트 윈도우가 금방 고갈되므로, ~/.claude.json 파일의 disabledMcpServers 항목을 통해 현재 프로젝트와 관련 없는 도구들을 명시적으로 끕니다. 결과적으로 프로젝트당 활성화된 MCP는 5~6개 수준으로 유지하여 쾌적한 컨텍스트 환경을 보장합니다:

# ~/.claude.json 내 projects.[path].disabledMcpServers 설정 예시
disabledMcpServers: [
  "playwright",
  "cloudflare-workers-builds",
  "cloudflare-observability",
  "clickhouse",
  "AbletonMCP",
  "context7",
  "magic"
]

주요 훅 (Key Hooks) 설정

자동화를 위한 훅 설정은 크게 세 가지 단계로 나뉩니다:

첫째, PreToolUse 단계에서는 npm, cargo 등 오래 걸리는 명령어 실행 시 tmux 사용을 상기시키거나, 불필요한 마크다운 파일 생성을 차단하고, git push 전에는 반드시 에디터를 열어 리뷰를 하게끔 강제합니다.

둘째, PostToolUse 단계에서는 파일 수정 후 prettier로 포맷팅을 자동화하고, 타입스크립트 컴파일 체크(tsc)를 수행하며, console.log가 남아있을 경우 경고를 띄웁니다.

마지막으로 Stop 단계에서는 세션이 종료되기 전 다시 한번 console.log 잔존 여부를 감사합니다.

설정 파일에는 다음과 같이 보입니다:

{
  "PreToolUse": [
    { "matcher": "npm|pnpm|yarn|cargo|pytest", "hooks": ["tmux reminder"] },
    { "matcher": "Write && .md file", "hooks": ["block unless README/CLAUDE"] },
    { "matcher": "git push", "hooks": ["open editor for review"] }
  ],
  "PostToolUse": [
    { "matcher": "Edit && .ts/.tsx/.js/.jsx", "hooks": ["prettier --write"] },
    { "matcher": "Edit && .ts/.tsx", "hooks": ["tsc --noEmit"] },
    { "matcher": "Edit", "hooks": ["grep console.log warning"] }
  ],
  "Stop": [
    { "matcher": "*", "hooks": ["check modified files for console.log"] }
  ]
}

규칙 및 에이전트 파일 구조

규칙(rules/)과 서브에이전트(agents/)는 명확한 역할에 따라 파일별로 분리되어 관리됩니다.

먼저 규칙 디렉토리(rules/) 에는 보안, 코딩 스타일, 테스팅, 깃 워크플로우 등을 정의하여 사용합니다:

~/.claude/rules/
  security.md       # 필수 보안 체크리스트
  coding-style.md   # 불변성, 파일 크기 제한 등
  testing.md        # TDD, 커버리지 80% 유지
  git-workflow.md   # 컨벤셔널 커밋 규칙
  agents.md         # 서브에이전트 위임 규칙
  performance.md    # 모델 선택 기준 (Haiku vs Sonnet vs Opus)

에이전트 디렉토리(agents/) 에는 기획자(planner), 아키텍트(architect), 보안 검토자(security-reviewer) 등 각 역할에 필요한 지침이 모듈화되어 있습니다:

~/.claude/agents/
  planner.md           # 기능 명세 및 분해
  architect.md         # 시스템 설계
  tdd-guide.md         # 테스트 코드 우선 작성 가이드
  security-reviewer.md # 취약점 스캔
  e2e-runner.md        # Playwright 테스트 실행
  refactor-cleaner.md  # 죽은 코드 제거

또한, 커스텀 상태 표시줄(Status Line)을 통해 현재 사용자, 디렉터리, Git 브랜치 상태, 컨텍스트 잔여량(%), 모델명, 시간, 남은 할 일(Todo) 개수를 한눈에 파악합니다.

image
image679×122 36.4 KB

핵심 요약 (Key Takeaways)

저자가 강조하는 성공적인 Claude Code 활용을 위한 5가지 핵심 원칙입니다:

  1. 설정을 미세 조정(Fine-tuning)으로 접근하라: 설정을 거창한 아키텍처 설계로 생각하여 과도하게 복잡하게 만들지 마십시오. 필요할 때마다 조금씩 다듬어가는 튜닝 과정으로 접근해야 합니다.

  2. 컨텍스트 윈도우는 소중하다: 성능 저하를 막기 위해 사용하지 않는 MCP와 플러그인은 과감하게 비활성화하십시오. 이것이 쾌적한 AI 경험의 핵심입니다.

  3. 병렬 실행을 적극 활용하라: 하나의 대화창에서 모든 것을 해결하려 하지 말고, /fork 명령어나 Git Worktree를 사용하여 작업을 병렬로 분산 처리하십시오.

  4. 반복 작업은 자동화하라: 포맷팅, 린팅(Linting), 단순 알림 등 반복되는 작업은 Hooks를 통해 자동화하여 인지 부하를 줄이십시오.

  5. 서브에이전트의 범위를 제한하라: 서브에이전트에게 너무 많은 권한을 주지 마십시오. 제한된 도구와 명확한 역할(Scope)을 부여할 때 실행력이 가장 높아집니다.

:twitter: Everything Claude Code 가이드 원문 (𝕏)

:github: Everything Claude Code 프로젝트 GitHub 저장소



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck:

3개의 좋아요
Claude Code 생산성을 200% 올려주는 Team Attention의 파워 유저 플러그인 저장소
Auto-Claude: Claude Code를 위한 자율 멀티 에이전트 개발 환경
Claude Code Templates: 즉시 사용할 수 있는 Claude Code 도구들을 제공하는 오픈소스 CLI 도구 및 템플릿 라이브러리 (feat. aitmpl.com)