Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 27. 23:13

26개의 프로덕션 서브에이전트(CLAUDE.md, MCP, Hooks)를 활용한 Claude Code 설정 방법

요약

Claude Code를 단순한 코딩 도구를 넘어 시니어 개발자 팀처럼 동작하게 만드는 고급 설정 방법을 소개합니다. CLAUDE.md를 계약서로 활용하고, MCP와 서브에이전트를 통해 에이전트의 전문성을 극대화하는 전략을 다룹니다.

핵심 포인트

  • CLAUDE.md를 구체적인 명령어가 포함된 '계약서'로 활용하여 에이전트의 추측 방지
  • 서브에이전트(.claude/agents/*.md)를 통해 단일 에이전트를 전문가 그룹으로 분리
  • MCP 서버와 Hooks를 결합하여 워크플로우의 자동화 및 정밀도 향상
  • 컨텍스트 희석을 막기 위해 CLAUDE.md는 50줄 이내로 간결하게 유지

실제 프로젝트에서 Claude Code를 처음 실행했을 때, 마치 모든 책을 읽었지만 한 번도 제품을 출시해 본 적 없는 똑똑한 주니어 개발자를 고용한 것 같은 기분이 들었습니다. 코드는 빠르게 작성할 수 있었지만, 세션 중간에 저의 컨벤션(Convention)을 잊어버리거나, 묻지도 않고 마이그레이션(Migration)을 실행하거나, 실패하는 테스트를 삭제함으로써 버그를 "수정"해 버리곤 했습니다.

몇 주간의 튜닝을 거친 결과, 이제는 마치 소규모 시니어 팀처럼 동작합니다. 코드를 작성하기 전에 계획을 세우고, 자신의 작업물을 검토하며, 테스트를 작성하고, 파괴적인 작업은 실행하기를 거부합니다. 차이점은 더 나은 모델이 아니었습니다. 그것은 더 나은 설정 (Setup) — 즉, CLAUDE.md, 집중된 서브에이전트(Subagents) 세트, 몇 개의 MCP 서버, 그리고 두 개의 작은 훅(Hooks)이었습니다.

여러분이 직접 구축할 수 있도록, 이 설정이 정확히 어떻게 작동하는지 설명하겠습니다.

1. CLAUDE.md는 희망 사항 목록이 아니라 계약서입니다

CLAUDE.md는 Claude Code가 매 세션 시작 시 자동으로 읽는 파일입니다. 대부분의 사람들은 이를 README처럼 취급합니다. 하지만 이 파일은 계약서 (Contract) 로 사용할 때 훨씬 더 효과적입니다. 즉, 에이전트가 오해할 수 없도록 짧고, 구체적이며, '항상/절대 ~할 것'과 같은 용어로 작성되어야 합니다.

저에게 가장 큰 품질 향상을 가져다준 두 가지 규칙은 다음과 같습니다:

## Build & test (run these, do not guess)
- Install:  pnpm install
- Dev:      pnpm dev
...

"Build & test" 블록이 중요한 이유는 다음과 같습니다. 정확한 명령어가 없으면 에이전트는 이를 추측 (Guess) 하여 (npm test, yarn test, make test 등) 실패하며 턴(Turn)을 낭비하게 됩니다. 실제 명령어를 한 번만 제공하면 추측을 멈춥니다.

이 파일은 50줄 이내로 유지하세요. CLAUDE.md가 너무 길어지면 컨텍스트(Context) 내에서 내용이 희석되어 에이전트가 중간 부분을 무시하기 시작합니다. 냉정하게 작성하세요.

2. 서브에이전트 (Subagents): 하나의 일반론자를 여러 명의 전문가로 분리하기

"이것을 검토하고, 테스트도 작성하고, 리팩토링도 해줘"라는 작업을 혼자서 처리하는 단일 에이전트는 모든 작업에서 평범한 결과물을 내놓습니다. 서브에이전트는 각 작업에 집중된 지침과 고유한 컨텍스트 윈도우(Context Window)를 부여함으로써 이 문제를 해결합니다. Claude Code에서 이들은 .claude/agents/*.md에 존재하며, 이름을 통해 호출할 수 있습니다.

서브에이전트는 프론트매터(Frontmatter)와 시스템 프롬프트(System Prompt)가 포함된 단순한 마크다운(Markdown) 파일입니다. 실제 사례인 저의 code-reviewer를 소개합니다:

---
name: code-reviewer
description: "버그, 보안 문제 및 컨벤션 위반 사항을 검토합니다. 코드를 작성하거나 변경한 후에 사용하세요."
...

이것을 유용하게 만드는 두 줄의 문구는 _"철저해 보이기 위해 문제를 지어내지 마세요(Do not invent problems to look thorough)"_와 _"정확한 라인을 인용하세요(Quote the exact line)."_입니다. 이 문구들이 없다면, 리뷰어는 모든 것을 무조건 승인(rubber-stamp)하거나 일반적인 조언만 나열하게 됩니다. 이 문구들이 있으면 실행 가능한(actionable) 결과물을 얻을 수 있습니다.

저는 이런 방식으로 집중된 전문가 명단을 운영합니다. 이론을 세우기 전에 재현부터 하는 debugger, 해피 패스(happy paths) 대신 엣지 케이스(edge cases)를 타겟팅하는 test-writer, OWASP 카테고리에 따라 사고하는 security-auditor, api-designer, refactor-architect 등이 그 예입니다. 각각은 엄격한 출력 형식을 가진 작은 파일입니다. 패턴은 항상 동일합니다: 하나의 작업, 하나의 출력 형식, 하나의 불필요한 정보 방지(anti-fluff) 제약 조건.

3. MCP: 에이전트에게 눈과 기억을 부여하기

MCP (Model Context Protocol) 서버는 Claude Code가 채팅 외부의 요소들, 즉 파일 시스템(filesystem), 브라우저(browser), 지속적인 메모리 저장소(persistent memory store)에 접근하는 방식입니다. 이는 .mcp.json에서 설정합니다:

{
  "mcpServers": {
    "filesystem": {
...

제가 가장 먼저 추가할 것은 sequential-thinking입니다. 이는 에이전트가 행동하기 전에 문제를 단계별로 나눌 수 있는 연습장(scratchpad)을 제공하며, 이를 통해 다단계 작업에서 "자신 있게 틀리는(confidently wrong)" 답변을 눈에 띄게 줄여줍니다. 두 번째로 사용하는 것은 브라우저 MCP (Playwright)입니다. 이는 에이전트가 UI가 왜 깨졌는지 추측하는 대신, 실제로 페이지를 로드하고 콘솔을 읽을 수 있게 해주기 때문입니다.

한 가지 주의할 점은, MCP 서버는 발전 속도가 매우 빠르며 일부는 방치되기도 한다는 것입니다. 유지보수가 잘 되는 서버를 고정(pin)해서 사용하고, 의존하기 전에 여전히 설치가 잘 되는지 확인하세요.

4. Hooks: 묻지 않고 실행되는 안전망

Hooks는 Claude Code가 사용자가 선택한 이벤트에 따라 실행하는 셸 명령(shell commands)입니다. 첫날부터 설정해둘 만한 가치가 있는 두 가지가 있습니다.

저장 시 자동 포맷팅 (Auto-format on save) — 공백 노이즈로 가득 찬 diff를 검토하지 않기 위해 설정합니다:

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

위험한 명령 차단 (Block dangerous commands) — 에이전트가 시도하더라도 파괴적인 셸 호출을 거부하는 실행 전 가드(pre-execution guard)입니다:

#!/usr/bin/env bash
# .claude/hooks/guard.sh — 명령을 차단하려면 0이 아닌 값을 반환하며 종료
if echo "$CLAUDE_TOOL_INPUT" | grep -qE 'rm -rf /|git reset --hard|DROP TABLE'; then
...

이것은 자율 에이전트(autonomous agent)를 신뢰하는 것과 에이전트를 일일이 감시(babysitting)하는 것의 차이입니다. 모델은 틀릴 수 있지만, 훅(hook)은 결정론적(deterministic)입니다.

종합하기: 기능의 시작부터 끝까지

위의 설정을 통해, 새로운 기능(feature)을 개발할 때 저의 실제 워크플로우는 매우 짧습니다:

  1. 에이전트에게 **계획(plan)**을 요청합니다 — 에이전트는 코드를 건드리기 전에 단계를 작성합니다.
  2. 에이전트가 스캐폴딩(scaffolding) 및 구현을 수행하며, 훅(hook)을 통해 저장 시 포맷팅을 진행합니다.
  3. diff에 대해 code-reviewer를 호출한 다음, 발견된 공백에 대해 test-writer를 호출합니다.
  4. CLAUDE.md에 명시된 대로 pnpm typecheck && pnpm test가 실행됩니다.
  5. 에이전트가 커밋(commit)과 PR(Pull Request) 설명을 초안으로 작성합니다.

에이전트는 타이핑을 하고, 저는 결정을 내립니다. 그것이 이 모든 것의 핵심입니다.

전체 구성을 바로 사용할 수 있는 형태로 원하시나요?

이 모든 것을 처음부터 구축하는 것은 정말 많은 시간이 소요되는 작업입니다. 26개의 서브에이전트(subagents)만 조정하는 데에도 출력 형식을 맞추기 위해 몇 주가 걸렸습니다. 만약 이 과정을 건너뛰고 완성된 설정을 어떤 저장소(repo)에든 바로 적용하고 싶다면, 제가 사용한 정확한 구성을 **Claude Code Agent OS**로 패키징했습니다: 26개의 특화된 서브에이전트, 12개의 슬래시 명령어 (/plan, /review, /test, /ship...), 바로 편집 가능한 5개의 CLAUDE.md 템플릿, MCP 설정, 그리고 안전 및 포맷 훅(bash 및 PowerShell)이 포함되어 있습니다. 또한 약 5분 안에 실행할 수 있는 'START HERE' 퀵스타트 가이드도 제공됩니다.

하지만 이 포스트의 가치를 얻기 위해 반드시 이것이 필요한 것은 아닙니다. 오늘 바로 정교한 CLAUDE.md와 하나의 code-reviewer 서브에이전트로 시작해 보세요. 그 조합만으로도 다음 커밋을 대하는 느낌이 달라질 것입니다.

직접 서브에이전트 목록을 구축하신다면, 어떤 전문가가 가장 유용했는지 정말 궁금합니다. 댓글로 알려주세요.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0