Claude Code를 쓰다 보면 금방 느끼게 됩니다. 기본 설정만으로는 뭔가 아쉽다는 걸요. 어떻게 설정해야 제대로 쓸 수 있을까 고민하다가 이것저것 만져보지만, 막상 체계적인 가이드를 찾기는 쉽지 않죠.
그런데 최근 X(트위터)에서 90만 뷰를 기록한 가이드가 등장했습니다. Affaan Mustafa가 작성한 “The Shorthand Guide to Everything Claude Code”인데요, 10개월 넘게 Claude Code를 실전에서 사용하며 쌓은 노하우를 담은 글입니다. 단순 튜토리얼이 아니라 Anthropic 해커톤에서 우승한 프로젝트를 만들 때 실제로 사용한 설정들이라는 점이 핵심입니다.
Affaan은 자신의 설정을 “everything-claude-code”라는 GitHub 저장소로 공개했습니다. 여기에는 Agents(서브에이전트), Skills(워크플로우), Hooks(자동화), Commands(단축 명령어), Rules(가이드라인), MCP 서버 설정 등 Claude Code를 체계적으로 활용하기 위한 모든 요소가 담겨 있어요.
출처: GitHub – affaan-m/everything-claude-code
6가지 핵심 구성 요소
저장소는 크게 6개 카테고리로 구성되어 있습니다.
Agents는 특정 작업을 위임받아 제한된 범위에서 처리하는 서브에이전트입니다. 예를 들어 code-reviewer는 코드 품질과 보안을 검토하고, planner는 기능 구현 계획을 세우며, tdd-guide는 테스트 주도 개발을 담당하죠. 각 에이전트는 자신만의 도구와 모델(Opus 같은)을 지정받아 독립적으로 작동합니다.
Skills는 워크플로우 정의입니다. TDD 워크플로우는 “인터페이스 정의 → 실패하는 테스트 작성 → 최소 구현 → 리팩토링” 순서를 명시하고, 백엔드 패턴이나 프론트엔드 패턴 같은 도메인 지식도 여기 담깁니다.
Hooks는 이벤트 기반 자동화입니다. 파일을 수정할 때마다 자동으로 console.log를 찾아서 경고를 띄우거나, 특정 조건이 만족되면 스크립트를 실행하는 식이죠.
Commands는 슬래시 명령어입니다. /tdd를 입력하면 테스트 주도 개발이 시작되고, /code-review를 치면 품질 검토가 실행됩니다. 반복 작업을 단축키처럼 만들어둔 거예요.
Rules는 항상 따라야 하는 가이드라인입니다. 보안 체크리스트, 코딩 스타일(불변성, 파일 구조), 테스트 커버리지 80% 이상 같은 규칙이 여기 들어갑니다.
MCP 설정은 GitHub, Supabase, Vercel, Railway 같은 외부 서비스와의 통합 설정입니다.
컨텍스트 윈도우 함정
Affaan이 특히 강조한 부분이 있습니다. 컨텍스트 윈도우 관리입니다.
Claude Code는 기본적으로 200k 토큰의 컨텍스트 윈도우를 제공하는데, MCP를 너무 많이 활성화하면 70k까지 줄어들 수 있다고 합니다. 20~30개 정도의 MCP를 설정해두되 프로젝트당 10개 미만만 활성화하고, 전체 도구는 80개 미만으로 유지하라는 게 그의 조언입니다.
사용하지 않는 MCP는 프로젝트 설정에서 disabledMcpServers로 명시적으로 비활성화해야 컨텍스트를 아낄 수 있어요.
실전에서 검증된 설정의 의미
이 저장소가 주목받는 이유는 단순히 ‘설정 모음집’이 아니기 때문입니다. Affaan은 2025년 9월 Anthropic x Forum Ventures 해커톤에서 zenith.chat을 만들어 우승했는데, 이 프로젝트를 처음부터 끝까지 Claude Code로만 개발했습니다. 그러니까 이 설정들은 실제로 작동하는 프로덕션 애플리케이션을 만드는 과정에서 다듬어진 거예요.
물론 이게 모든 사람에게 완벽한 정답은 아닙니다. Affaan도 README에서 “이건 내 워크플로우에 맞춘 거니까, 여러분은 공감되는 것만 가져다 쓰고 나머지는 고쳐 쓰세요”라고 말합니다. 하지만 시작점으로는 충분히 가치가 있죠. 특히 Claude Code를 막 시작했거나, 어떻게 구조화해야 할지 막막한 사람들에게는 실용적인 템플릿이 될 겁니다.
저장소는 MIT 라이선스로 공개되어 있고, 커뮤니티 기여도 환영합니다.
참고자료:
답글 남기기