실제 프로젝트에서 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
if echo "$CLAUDE_TOOL_INPUT" | grep -qE 'rm -rf /|git reset --hard|DROP TABLE'; then
...
이것은 자율 에이전트(autonomous agent)를 신뢰하는 것과 에이전트를 일일이 감시(babysitting)하는 것의 차이입니다. 모델은 틀릴 수 있지만, 훅(hook)은 결정론적(deterministic)입니다.
종합하기: 기능의 시작부터 끝까지
위의 설정을 통해, 새로운 기능(feature)을 개발할 때 저의 실제 워크플로우는 매우 짧습니다:
- 에이전트에게 **계획(plan)**을 요청합니다 — 에이전트는 코드를 건드리기 전에 단계를 작성합니다.
- 에이전트가 스캐폴딩(scaffolding) 및 구현을 수행하며, 훅(hook)을 통해 저장 시 포맷팅을 진행합니다.
- diff에 대해
code-reviewer를 호출한 다음, 발견된 공백에 대해 test-writer를 호출합니다.
CLAUDE.md에 명시된 대로 pnpm typecheck && pnpm test가 실행됩니다.- 에이전트가 커밋(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 서브에이전트로 시작해 보세요. 그 조합만으로도 다음 커밋을 대하는 느낌이 달라질 것입니다.
직접 서브에이전트 목록을 구축하신다면, 어떤 전문가가 가장 유용했는지 정말 궁금합니다. 댓글로 알려주세요.