Claude Code 세팅 가이드: MCP, Plan 모드, 서브 에이전트, 훅까지

여러분, 요즘 Cursor에서 Claude Code로 갈아타는 분들이 점점 늘고 있습니다. 저도 최근에는 Cursor보다 Claude Code를 훨씬 더 많이 쓰고 있는데요. 결론부터 말하면, Claude Code는 터미널에서 코드를 물어보는 도구가 아닙니다. 프로젝트 구조를 이해하고, MCP 서버를 연결하고, Plan 모드로 작업을 설계하고, 서브 에이전트로 역할을 나누고, 훅으로 특정 동작을 강제할 수 있는 개발 에이전트 환경이라고 봅니다. 제대로 세팅하면 코딩 보조 도구를 넘어 작업 흐름 전체를 맡길 수 있죠.

제가 말하고 싶은 건, 처음 쓰는 분에게 중요한 건 기능을 많이 아는 게 아니라는 점입니다. 내 작업 방식에 맞게 안전하게 조합하는 것이 핵심입니다. 이 글에서는 기본 설치와 초기화, MCP 연동, output style, 서브 에이전트, hooks, custom slash command, bash command, bypass permissions, dev container, ccusage, SuperClaude, Claude Code Template까지 실무 기준으로 정리합니다.

Claude Code 핵심 요약

• Claude Code를 프로젝트에서 처음 실행하면 /init으로 CLAUDE.md를 생성해 프로젝트 맥락을 잡는 것이 좋습니다.
• MCP 서버는 local, project, user scope로 연결할 수 있고, 프로젝트 단위 설정은 .mcp.json에 저장됩니다.
• Shift+Tab으로 Plan 모드와 Accept Edit 모드를 오가며 계획과 구현을 분리할 수 있습니다.
• output style은 기본, 설명형, 학습형뿐 아니라 사용자 지정 스타일도 만들 수 있습니다.
• 서브 에이전트는 전문 역할과 독립 컨텍스트를 가진 별도 작업자로, 병렬 처리에 강점이 있습니다.
• hooks는 특정 이벤트에서 쉘 명령을 실행해 포매팅, 알림, 로깅, 보안 가드를 자동화합니다.
• bypass permissions는 강력하지만 위험하므로 dev container 같은 격리 환경과 함께 쓰는 것이 좋습니다.

시작은 CLAUDE.md에서 한다

/init으로 프로젝트 구조를 먼저 읽힌다

Claude Code를 특정 프로젝트에서 처음 쓸 때는 바로 기능 개발을 시키기보다 프로젝트 초기화를 먼저 하는 편이 좋습니다. /init 명령을 입력하면 Claude Code가 현재 코드베이스 구조를 분석하고 CLAUDE.md 파일을 생성해 줍니다.

CLAUDE.md에는 프로젝트 개요, 프레임워크, 라우팅 방식, 핵심 아키텍처, 패키지 관리 방식 같은 정보가 들어갑니다. 이 파일은 Claude Code의 시스템 프롬프트 상단에 들어가는 프로젝트 맥락이므로, 에이전트가 같은 저장소를 반복해서 작업할 때 이해도를 높이는 데 도움이 됩니다.

생성된 문서는 팀 규칙으로 다듬어야 한다

자동 생성된 CLAUDE.md는 출발점일 뿐입니다. 여기에 자주 쓰는 명령어, 코딩 스타일, 네이밍 규칙, 금지 사항, 테스트 기준, 배포 방식 같은 팀 규칙을 추가하면 더 실용적입니다. Cursor의 rules 파일처럼, Claude Code가 프로젝트별로 따라야 할 기본 지침이 되는 셈입니다.

중요한 것은 문서를 한 번 만들고 방치하지 않는 것입니다. 실제 코드와 규칙 사이에 괴리가 생기면 에이전트가 잘못된 판단을 하게 됩니다. 프로젝트 구조가 바뀌면 CLAUDE.md도 함께 갱신해야 합니다.

MCP 연결: 도구를 프로젝트 맥락에 넣기

세 가지 스코프를 구분한다

Claude Code는 MCP 서버를 local, project, user scope로 연동할 수 있습니다. project scope로 연결하면 프로젝트 루트의 .mcp.json에 설정이 들어가고, 해당 저장소에서 함께 관리할 수 있습니다. user scope는 개인 환경 전체에서 쓰는 도구에 적합하고, local scope는 임시 또는 로컬 전용 연결에 맞습니다.

MCP 서버를 연결한 뒤에는 상태 확인 명령으로 제대로 연결되었는지 봐야 합니다. 정상 연결된 서버는 잘 붙었다고 뜨고, 경로가 맞지 않는 서버는 실패로 표시됩니다. 에이전트가 도구를 쓰기 전에 연결 상태를 확인하는 습관이 필요합니다.

MCP 성능은 모델과 함께 봐야 한다

대규모 MCP 도구 환경에서 LLM 에이전트의 실제 작업 수행 능력을 평가한 벤치마크가 있습니다. 95개 일상 과제와 527개 MCP 도구로 문제 해결 능력을 측정했는데, 여기서 Claude Sonnet 4가 가장 높은 성공률을 보였습니다. MCP 서버를 많이 붙이는 환경일수록 모델의 도구 사용 능력이 그만큼 중요해진다는 이야기죠.

그런데 제가 더 중요하게 보는 건 도구 개수가 아닙니다. 도구가 많다고 성능이 자동으로 좋아지지는 않거든요. 모델이 어떤 도구를 언제 호출할지 판단해야 하고, 잘못 호출했을 때 복구할 수 있어야 합니다. MCP는 연결 레이어일 뿐이고, 실제 품질은 모델, 지침, 권한, 검증 흐름이 함께 결정한다고 봅니다.

Plan 모드와 output style

Plan 모드로 구현 전 판단을 분리한다

Claude Code에서는 Shift+Tab으로 Accept Edit 모드와 Plan 모드를 오갈 수 있습니다. 저는 먼저 Plan 모드로 계획을 세우고, 그 계획이 괜찮으면 Accept Edit 모드에서 실제 변경을 수행하는 방식을 추천합니다.

복잡한 기능일수록 이 분리가 중요합니다. 바로 파일을 수정하게 하면 요구사항이 애매한 상태에서 잘못된 구조를 만들 수 있습니다. Plan 모드에서는 작업 범위, 파일 위치, 구현 순서, 검증 방법을 먼저 정리할 수 있습니다.

output style은 협업 방식에 맞춘다

Claude Code는 기본 output style 외에도 설명이 더 많은 스타일, 학습을 돕는 스타일을 제공합니다. 사용자 지정 output style도 만들 수 있습니다. 원하는 응답 스타일을 설명하면 Claude Code가 해당 스타일 지침을 알아서 만들어 주고, 프로젝트 또는 사용자 스코프에서 사용할 수 있습니다.

예를 들어 학습 목적이면 설명형 스타일이 좋고, 실무 자동화에서는 간결한 기본 스타일이 좋을 수 있습니다. 팀 협업에서는 너무 장황한 응답보다 변경 이유와 검증 결과가 명확한 스타일이 더 실용적입니다.

서브 에이전트와 병렬 처리

독립 컨텍스트가 성능을 만든다

서브 에이전트는 특정 목적과 전문 영역을 가진 별도 에이전트입니다. 프로젝트의 .claude/agents/ 같은 경로에 마크다운 파일로 정의할 수 있고, Claude Code 안에서 /agents 명령으로 관리할 수 있습니다. 각 서브 에이전트는 도구, 모델, 색상, 설명을 따로 가질 수 있습니다.

가장 큰 장점은 컨텍스트 분리입니다. 메인 에이전트의 긴 대화 맥락이 그대로 전파되지 않고, 특정 작업에 필요한 지침만 가진 에이전트가 움직입니다. 따라서 테스트 작성, UI 컴포넌트 마이그레이션, 보안 리뷰처럼 역할이 분명한 작업에 잘 맞습니다.

병렬 처리로 속도를 높인다

예를 들어 shadcn/ui 컴포넌트 마이그레이션이라면, 여러 컴포넌트를 각각 다른 서브 에이전트에게 맡길 수 있습니다. 네 개의 컴포넌트를 한 에이전트가 순차 처리하는 대신, 네 개의 서브 에이전트가 병렬로 처리하면 속도가 크게 올라가죠.

단, 병렬 처리는 무조건 좋지 않습니다. 같은 파일을 동시에 수정하거나 서로 의존성이 있는 작업은 충돌이 날 수 있습니다. 병렬화하기 좋은 작업은 입력과 출력이 독립적이고, 마지막에 통합만 하면 되는 작업입니다.

hooks와 custom slash command

hooks는 반드시 실행되어야 하는 일을 맡는다

Claude Code hooks는 특정 이벤트에 자동으로 실행되는 쉘 명령을 등록하는 기능입니다. 작업 완료 알림, 코드 포매팅, 로깅, 특정 파일 보호, 도구 실행 후 후처리 같은 작업을 자동화할 수 있습니다. 문서 규칙이 “지켜야 한다”라면, 훅은 “실행되게 만든다”에 가깝습니다.

예를 들어 파일 작성 후 포매터를 실행하거나, 민감 파일 접근을 차단하거나, 작업 완료 시 기록을 남기는 방식으로 활용할 수 있습니다. LLM 판단에 맡기면 빠질 수 있는 반복 절차를 훅으로 보강하는 것이 좋습니다.

custom slash command로 반복 프롬프트를 줄인다

반복적으로 쓰는 프롬프트는 custom slash command로 만들 수 있습니다. 프로젝트 루트의 .claude/commands/에 마크다운 파일을 추가하면, Claude Code 안에서 해당 명령을 호출할 수 있습니다. 예를 들어 코드 최적화용 명령을 하나 만들어 두면, 매번 같은 프롬프트를 다시 적지 않아도 됩니다.

팀에서 자주 쓰는 리뷰 절차, 성능 점검, 리팩토링 기준, 배포 전 체크리스트를 slash command로 만들면 에이전트에게 매번 같은 설명을 반복하지 않아도 됩니다.

권한과 격리: bypass permissions는 신중하게

모든 권한을 주면 속도와 위험이 함께 올라간다

Claude Code는 기본적으로 사용자의 허락을 받은 명령만 실행하도록 설정할 수 있습니다. 그러나 bypass permissions 옵션을 켜면 사용자 확인 없이 모든 작업을 진행할 수 있습니다. 이 모드는 빠르지만, 파일 삭제, 민감 정보 접근, 외부 요청 같은 위험도 커집니다.

bypass permissions를 사용할 때 dev container를 함께 쓰는 것을 추천합니다. 격리된 컨테이너 내부에서 실행하면 로컬 전체 환경을 건드릴 위험을 줄일 수 있고, 방화벽 설정으로 네트워크 접근도 제한할 수 있습니다.

환경 변수는 특히 조심해야 한다

AI 에이전트가 모든 권한을 갖게 되면 환경 변수나 비밀 파일에 접근할 가능성이 생깁니다. 실제 업무에서는 .env, 인증 토큰, API key가 유출되면 치명적입니다. 이런 파일은 문서 규칙만으로 막기보다 권한, 훅, 컨테이너 격리로 보호해야 합니다.

추천 서비스와 도구

도구	역할	활용 포인트
ccusage	Claude Code 사용량 확인	일별 토큰, 캐시, 비용 추적
SuperClaude	커스텀 명령과 페르소나	아키텍트, 프론트엔드, 백엔드 등 역할 전환
Claude Code Template	필요한 훅과 명령 선택 설치	원하는 컴포넌트만 장바구니처럼 골라 설치
dev container	격리 실행 환경	bypass permissions 사용 시 안전성 보강
MCP 서버	외부 도구 연결	프로젝트별 또는 사용자별 도구 통합

마무리

결론부터 말하면, Claude Code를 잘 쓰는 핵심은 기능을 많이 켜는 게 아닙니다. 작업 방식에 맞게 안전하게 조합하는 것입니다. CLAUDE.md로 프로젝트 맥락을 잡고, MCP로 도구를 연결하고, Plan 모드로 구현 전 계획을 세우고, 서브 에이전트와 hooks로 복잡한 작업을 나누고 강제하는 식이죠.

처음에는 /init, MCP 상태 확인, Plan 모드, todo list 정도만 적용해도 충분합니다. 이후 반복 작업이 생기면 custom slash command와 서브 에이전트로 확장하고, 위험한 자동화가 필요할 때는 dev container와 hooks를 함께 설계하면 좋겠습니다. 제가 말하고 싶은 건 결국 Claude Code는 도구 자체보다 하네스 설계에 따라 생산성 차이가 크게 나는 환경이라는 점입니다.