Claude Code 해커톤 우승자의 셋업 가이드 완전 정리

어제 Anthropic 해커톤 우승자가 자신의 Claude Code 셋업 가이드를 공개했고, 저는 그 내용을 하나도 빠짐없이 적용했습니다. 하루 종일 매달렸는데, 체감 차이가 확실했습니다.

가이드의 주인공은 affaan(@affaanmustafa)이라는 개발자로, Claude Code를 10개월째 매일 쓰고 있는 사람입니다. 그의 설정을 읽으면서 든 첫 번째 생각은 “나는 그동안 대체 뭘 한 거지?”였습니다.

가이드는 GitHub 레포로 공개되어 있고, 핵심 메시지는 명확합니다: 더 많이가 아니라, 정확히 필요한 것만.

200K 컨텍스트 윈도우는 허상입니다 - 실제로 쓸 수 있는 건 70K

Claude Code의 200K 컨텍스트 윈도우는 이론상 최댓값입니다. MCP 서버와 플러그인을 잔뜩 올리면 실제 사용 가능한 컨텍스트가 70K 정도로 줄어듭니다.

affaan의 접근법:

1. MCP 서버를 14개 구성하되, 프로젝트당 5~6개만 활성화한다.
2. 동시에 켜놓는 도구는 80개 미만으로 유지한다.

그의 실제 설정에는 GitHub, Supabase, Vercel, Railway, Cloudflare 시리즈, ClickHouse 등 총 14개 서버가 등록되어 있습니다. 하지만 쓰지 않는 서버는 disabledMcpServers로 명시적으로 비활성화합니다. 이 패턴을 적용한 뒤 응답 품질이 눈에 띄게 좋아졌습니다.

Skills vs Hooks vs Subagents - 역할 분리가 핵심입니다

처음에는 이 세 개념이 헷갈리는데, 구분을 정확히 해야 합니다.

• Skills: ~/.claude/skills에 위치합니다. /refactor-clean 같은 명령 하나로 전체 워크플로우를 실행합니다.
• Hooks: 이벤트 기반 자동화입니다. .ts 파일 수정 후 Prettier 자동 포맷, console.log 경고 등을 처리합니다. hookify 플러그인을 사용하면 대화를 통해 Hook을 생성할 수도 있습니다.
• Subagents: ~/.claude/agents에 위치합니다. planner, architect, tdd-guide, security-reviewer 같은 전담 역할을 맡아 위임된 작업을 수행합니다.

affaan은 Hook을 PreToolUse, PostToolUse, Stop 세 시점에 배치해서 포맷팅, 타입 체크, 보안 감사를 자동화합니다. 이 패턴은 Boris Cherny도 추천한 방식입니다.

mgrep과 Git Worktree가 판도를 바꿉니다

가이드에서 가장 실용적이었던 팁들입니다.

mgrep

ripgrep보다 정확하고, 웹 검색 기능까지 내장되어 있습니다. /mgrep 'function handleSubmit' 한 줄이면 로컬 파일과 웹을 동시에 검색합니다.

Git Worktree

여러 기능을 동시에 작업할 때, 독립된 체크아웃을 만들어서 각각에서 Claude Code를 실행합니다. /fork로 대화를 분기할 수도 있습니다. Worktree와 레포 클론 중 어느 쪽이 더 나은지에 대해서는 의견이 갈리는데, 워크플로우에 따라 장단점이 다릅니다.

Zed 에디터

Rust 기반이라 가볍습니다. Agent Panel에서 Claude의 파일 수정 내역을 실시간으로 추적할 수 있고, CMD+Shift+R로 커스텀 명령을 즉시 실행할 수 있습니다.

일관성을 위한 Rules 구조

~/.claude/rules를 관심사별로 모듈화합니다:

• security.md - 하드코딩된 시크릿 금지
• coding-style.md - 불변성, 파일 구조 가이드라인
• testing.md - TDD 워크플로우, 최소 80% 커버리지
• git-workflow.md - 커밋 메시지 포맷
• performance.md - 모델 선택 기준

“console.log를 절대 커밋하지 마라” 같은 규칙을 여기에 추가하고, Stop Hook으로 변경사항을 감사하면 됩니다. 자동화가 실수를 코드에 반영되기 전에 잡아주니까, 실수 자체가 사라집니다.

핵심 원칙 다섯 가지

affaan은 자신의 철학을 다섯 가지로 압축합니다:

• 설정은 아키텍처가 아니라 파인튜닝처럼 다뤄라. 대대적인 개편보다 작고 정확한 조정이 효과적입니다.
• 컨텍스트 윈도우는 귀중한 자원이다. 지금 안 쓰는 건 전부 꺼둬라.
• 병렬 실행을 활용하라. /fork와 Worktree로 에이전트를 동시에 돌려라.
• 반복 작업은 자동화하라. Hook이 수작업을 대신해서 속도를 높여줍니다.
• 서브에이전트의 범위를 제한하라. 각 에이전트에게 좁고 명확한 책임을 부여하라.

과도한 설정은 오히려 역효과를 냅니다. 실제로 쓰는 도구만 활성화해두는 것이 진짜 생산성입니다. 대부분의 사람에게 “빼는 것”이 가장 어렵고, 이 가이드는 그 사실을 강하게 일깨워줍니다.

개인적으로 한 가지 덧붙이자면, 브라우저 자동화의 경우 원본 가이드에서 언급하는 Playwright 등보다 Vercel의 agent-browser가 훨씬 안정적이었습니다. 처리할 수 있는 작업의 폭과 속도가 차원이 다릅니다.

전체 셋업은 affaan의 GitHub 레포에서 확인할 수 있습니다. 그대로 복사하기보다는 각 선택의 이유를 이해하고 자신의 워크플로우에 맞게 조정하는 것이 중요합니다. 진짜 가치는 거기에 있습니다.