AI 에이전트는 설정이 모델보다 중요하다
Claude Code를 처음 프로젝트에 붙이면 흔히 겪는 경험이 있다. 코드는 빠르게 쓰는데, 세션 중간에 컨벤션을 잊고, 확인 없이 마이그레이션을 실행하고, 실패하는 테스트를 지워서 빌드를 통과시킨다. dev.to에 올라온 한 사례에서 저자는 이 문제를 몇 주의 튜닝으로 해결했다고 밝힌다. 핵심은 더 좋은 모델이 아니라 더 나은 설정이었다. CLAUDE.md, 서브에이전트, MCP, 훅—이 네 레이어를 제대로 조립하면 AI는 "읽기만 하고 배포한 적 없는 똑똑한 주니어"에서 "스스로 계획하고 검토하고 위험 명령을 거부하는 시니어 팀"으로 바뀐다.
CLAUDE.md는 위시리스트가 아니라 예산이다
CLAUDE.md를 README처럼 쓰는 팀이 많다. 이게 문제다. 프론티어 모델이 신뢰할 수 있게 따르는 지시는 동시에 150~200개 수준이고, 규칙을 쌓을수록 각 규칙의 준수율은 조금씩 떨어진다. 여기에 Claude Code 자체 시스템 프롬프트가 이미 일부 예산을 소진하므로, 실제 프로젝트 규칙에 쓸 수 있는 여유는 더 작다. 300줄짜리 CLAUDE.md는 300개 규칙이 지켜지는 게 아니라, 앞쪽 150개가 잘 지켜지고 나머지는 배경 소음이 된다.
실용적인 기준은 단순하다. 각 규칙에 "이게 매번 발동된다고 5달러를 걸 수 있나?"라고 물어보는 것이다. 걸 수 없다면 잘라내거나 참조 파일로 분리한다. 파일은 50줄 이하로 유지하고, 항상 적용되는 규칙만 메인에 두고 마이그레이션 가이드나 API 컨벤션 같은 세부 사항은 docs/ 하위 파일을 경로로 참조하게 한다. 컨텍스트 예산은 필요할 때만 소비된다.
반드시 일어나야 하는 규칙은 훅으로 내보내라
CLAUDE.md 규칙의 준수율은 최선의 경우에도 약 80%다. 스타일 선호나 네이밍 컨벤션에는 충분하지만, 시크릿 커밋 금지, 프로덕션 DB 삭제 방지, 테스트 통과 전 완료 선언 금지 같은 항목에는 받아들이기 어려운 수치다. 이런 규칙은 프롬프트가 아니라 훅으로 구현해야 한다.
훅은 Claude Code가 특정 이벤트에 자동으로 실행하는 셸 명령이다. PreToolUse 훅으로 .env나 .git/ 경로 편집을 원천 차단하고, PostToolUse 훅으로 저장 후 Prettier를 자동 실행하면 diff에서 공백 노이즈가 사라진다. 모델이 틀릴 수 있다. 훅은 결정론적이다. 이 차이가 자율 에이전트를 신뢰하는 것과 감시하는 것의 경계를 가른다.
서브에이전트로 제너럴리스트를 스페셜리스트 팀으로 쪼개라
하나의 에이전트에게 "리뷰도 하고, 테스트도 짜고, 리팩토링도 해"라고 시키면 모든 작업이 평범해진다. 서브에이전트는 각 역할에 독립된 지시와 컨텍스트 윈도우를 부여해 이 문제를 해결한다. .claude/agents/*.md 파일 하나가 에이전트 하나다.
핵심은 포맷 강제다. 예를 들어 code-reviewer 에이전트는 출력을 세 섹션—Blocking(버그·보안·데이터 손실), Should fix(정확성·명확성), Nits(스타일)—으로만 내보내고, "문제가 없으면 첫 줄에 그렇다고 써라", "지적할 줄을 정확히 인용해라"라는 두 규칙을 박아넣는다. 이 두 줄이 없으면 리뷰어는 아무것도 잘못 없는 코드에서 문제를 만들어내거나, 막연한 조언의 벽을 쏟아낸다. 같은 패턴으로 debugger, test-writer, security-auditor, api-designer를 각각 파일 하나씩 구성하면 26개 스페셜리스트 팀도 결국 같은 방법의 반복이다.
GitHub Actions로 팀 전체의 코드 리뷰를 자동화하라
서브에이전트가 개인 워크플로우를 바꾼다면, GitHub Actions 기반 AI 코드 리뷰는 팀 워크플로우를 바꾼다. PR이 열리면 Actions가 diff를 추출해 Claude API로 보내고, 코드베이스 패턴과 보안 체크리스트를 담은 프롬프트로 구조화된 피드백을 받는다. 이 초기 분석에 걸리는 시간은 2~3분이다.
dev.to에서 공유된 실제 측정치는 설득력이 있다. PR당 평균 리뷰 시간이 38분에서 12분으로 줄었고, 주 3개 PR 기준 주당 1.5시간이 해방됐다. 더 중요한 건 시간이 아니라 집중의 질이다. AI가 null 체크, 네이밍 컨벤션, SQL 인젝션 패턴 같은 반복적 항목을 처리하면, 사람은 아키텍처 결정, 비즈니스 로직, 엣지 케이스에 집중할 수 있다. 단, AI 출력을 블라인드로 신뢰하면 안 된다. 주니어 개발자 제안을 검토하듯 읽고, 컨텍스트를 더해서 최종 판단은 사람이 내린다.
워크플로우를 레이어로 조립하면 팀이 얻는 것
세 소스가 가리키는 방향은 하나다. CLAUDE.md 예산 관리 → 훅 기반 결정론적 가드레일 → 서브에이전트 분업 → GitHub Actions 자동 리뷰. 이 네 레이어를 쌓으면 AI가 타이핑하고 개발자가 결정하는 워크플로우가 완성된다.
팀 리드 입장에서 이 구조의 진짜 가치는 개인 생산성 향상이 아니다. 팀 지식을 에이전트 설정에 코드화할 수 있다는 점이다. CLAUDE.md의 컨벤션, 서브에이전트의 리뷰 기준, 훅의 보안 정책—이것들은 온보딩 문서보다 신뢰할 수 있는 팀 운영 표준이 된다. 새 팀원이 레포를 클론하면 AI 워크플로우도 함께 복제된다.
내일 당장 시작할 수 있는 최소 스택
26개 서브에이전트와 완성된 파이프라인은 이상적인 목표지만, 시작은 훨씬 작게 해도 된다. 오늘 할 수 있는 것: CLAUDE.md를 50줄 이하로 다이어트하고, code-reviewer 서브에이전트 하나를 만들고, .env 경로 차단 훅 하나를 붙인다. 이 세 가지만으로도 다음 커밋의 질감이 달라진다. GitHub Actions 연동은 그다음 주에 해도 늦지 않다. 설정 비용 2시간, 주 3개 PR 기준 손익분기점은 한 달이다.
AI-First 워크플로우의 핵심은 AI를 더 많이 쓰는 게 아니라 AI가 잘 작동하는 구조를 먼저 설계하는 것이다. 도구는 이미 충분히 강력하다. 부족한 건 언제나 설정이다.