Claude Code를 쓰는 개발자 대부분은 전체 기능의 20% 정도만 활용한다. 터미널에서 명령을 내리고, 코드를 제안받고, 수락하거나 거절하는 식의 반응형 루프. 이 패턴이 나쁜 건 아니지만, Claude Code가 실제로 할 수 있는 것과 대부분이 실제로 쓰는 것 사이의 간극은 꽤 크다. 문제는 도구의 한계가 아니라 워크플로우 설계의 부재다.
CLAUDE.md vs Hooks: '대체로'와 '반드시'의 차이
Claude Code의 핵심 설정 레이어는 두 개다. CLAUDE.md는 세션 시작 시 읽히는 지시 파일로, 코드 스타일·스택 컨텍스트·선호도를 담는다. 하지만 이건 어디까지나 권고다. dev.to의 Claude Code 치트시트에 따르면, CLAUDE.md의 지시는 약 80% 수준에서 따라진다. 나머지 20%는 모델의 판단에 달려 있다.
반면 Hooks는 결정론적이다. PreToolUse 훅에서 exit code 1을 반환하면 Claude는 멈춘다. 예외도, 모델 판단도 없다. rm -rf 차단, 모든 파일 쓰기에 Prettier 강제 적용, .env 파일의 커밋 방지—이런 규칙은 Hooks로만 구현할 수 있다. 규칙을 세울 때 '대체로 따를 것'으로 충분한 영역은 CLAUDE.md에, '반드시 지켜야 하는 것'은 Hooks에 넣는 것이 핵심 원칙이다.
Subagents: 컨텍스트 창의 물리적 한계를 우회하는 방법
LLM의 실질적인 병목 중 하나는 컨텍스트 창의 한계다. 세션이 길어질수록 초반 대화가 희미해지고 출력 품질이 떨어진다. 이 문제에 대한 Claude Code의 구조적 답이 Subagents다.
Subagents는 비어 있는 컨텍스트를 가진 별도의 Claude 인스턴스로 작업을 분산시킨다. 최대 3개를 동시에 실행할 수 있으며, 코드 리뷰·테스트 실행·DB 마이그레이션 검사를 순차가 아닌 병렬로 처리한다. 실제 사례에서 단일 세션으로 20분 걸리던 작업이 7분으로 단축된다고 보고된다. 이건 단순한 속도의 문제가 아니다. 컨텍스트 오염 없이 각 작업을 신선한 상태로 처리한다는 품질 설계다.
Gate 패턴: 에이전트가 스스로 검증하게 만드는 구조
Subagents와 Hooks가 실행 효율의 문제를 다룬다면, Gate 패턴은 신뢰 비용의 문제를 다룬다. dev.to에 공개된 Mycelium 프레임워크 사례는 이 문제를 적나라하게 보여준다. Claude로 구동되는 에이전트가 기회 탐색 단계를 완벽하게 수행했지만, 테스트와 접근성 없이 앱을 완성하고 "잘 됐다"고 보고했다. 거짓말이 아니었다. 에이전트는 자신이 모르는 것을 몰랐고, 그 사실은 리뷰 시점이 되어서야 드러났다.
이 문제의 핵심은 에이전트의 지능이 아니다. 검증 비용을 누가, 언제 지불하는가의 문제다. 리뷰 시점은 검증 비용이 가장 비싼 순간이다. Gate 패턴은 이 비용을 에이전트가 코드를 작성하기 이전에, 루프 내부에서 치르게 만든다. '그럴듯해 보이는가'가 아니라 '증거가 실제로 존재하는가'를 묻는 것이 Gate의 기준이다.
예를 들어, 에이전트가 한 번도 읽지 않은 외부 API를 대상으로 코드를 작성하려 할 때 Gate가 개입한다. 실제 스키마 없이 상상된 인터페이스로 코드를 작성하는 대신, 에이전트는 스스로 기술 탐색이 필요하다고 선언하고 문서를 읽은 뒤에야 코드 작성 권한을 얻는다. Mycelium의 현재 빌드에는 아이디어에서 출시까지의 경로에 걸쳐 13개의 Gate가 정의되어 있다.
이 패턴의 의미는 단순하다. 에이전트가 주장을 펼칠 때 그 근거를 즉시 제시하게 강제하면, 검증 부담이 리뷰어에서 에이전트 자신에게 이동한다. 에이전트를 더 똑똑하게 만드는 게 아니라, 비용을 앞당겨 지불하게 만드는 것이다.
조합하면 보이는 것: 실행 속도 × 검증 신뢰
Subagents·Hooks·Gate 패턴은 각각 다른 문제를 해결하지만, 조합될 때 하나의 일관된 워크플로우 철학을 완성한다. Hooks는 에이전트가 절대 해서는 안 될 것을 막고, Subagents는 동시에 처리할 수 있는 것을 병렬화하며, Gate는 다음 단계로 넘어가기 전에 증명해야 할 것을 요구한다.
이 세 레이어를 갖춘 워크플로우에서 에이전트는 단순 실행자가 아니라 자체 검증 루프를 가진 작업 단위가 된다. 프론트엔드 개발 맥락에서 구체화하면: API 연동 전 스키마 검증 Gate, 컴포넌트 작성 후 접근성 체크를 Subagent로 병렬화, .env 노출 방지 Hook—이런 구성이 가능하다.
설계자의 시각으로 도구를 바라볼 것
한 가지 솔직한 실패 사례가 인상적이다. Mycelium을 테스트한 개발자가 에이전트가 자신의 브리프를 임의로 수정한 것을 발견하고, 직접 원본을 유지하도록 강제했다. 프레임워크가 처리했어야 할 규율을 사람이 대신 집행한 순간이었다. 동시에 그 테스터는 프레임워크의 언어가 이미 아는 사람만을 위해 쓰여 있다고 지적했다. 기술 구조는 맞았지만 온보딩이 틀렸다는 것—두 가지가 동시에 사실일 수 있다.
AI 도구가 고도화될수록, 설계의 무게중심은 도구 자체에서 그것을 어떻게 구조화할 것인가로 이동한다. Hamel Husain의 표현처럼, 검증하기 어려운 것은 제품 설계의 악취다. Claude Code의 Subagents·Hooks·Gate 패턴은 그 악취를 제거하기 위한 구조적 접근이다. 도구를 켜는 것과 설계하는 것은 여전히 다른 문제다.