문제는 속도가 아니라 규율의 부재다
Claude Code 세션을 닫는 순간, 그 안에서 쌓은 컨텍스트는 사라진다. 다음 주 세션을 열면 워크트리 컨벤션을 다시 설명해야 하고, 테스트 플랜 포맷을 다시 가르쳐야 하며, main 브랜치에 --force-push하면 안 된다는 규칙도 처음부터 다시 얘기해야 한다. 혼자 쓸 때도 번거롭다. 팀 다섯 명이 각자의 방식으로 에이전트를 쓰기 시작하면? PR마다 리뷰 깊이가 다르고, 스펙은 구현에서 이탈하고, 에이전트가 실제 코드 경로를 건드리지 않은 '환각 수정'을 올려도 아무도 프로덕션 배포 전까지는 눈치채지 못한다.
컴프리헨션 데트: AI 코드가 진짜 위험해지는 순간
dev.to의 Alan West는 이 현상을 '컴프리헨션 데트(comprehension debt)'라 불렀다. 기술 부채처럼 쌓이되, 더 교활하다. 코드는 있고 이해는 없는 상태. AI가 생성한 fetchUserData 함수를 보자—try-catch로 감싸져 있고 언뜻 멀쩡해 보이지만, fetch는 HTTP 에러에서 throw를 던지지 않는다. 404나 500이 와도 response.json()을 호출하고, 상태 코드는 조용히 사라진다. 직접 한 줄씩 쓰면 자연스럽게 잡히는 버그가, AI 제안을 스캔하며 넘기면 리뷰를 통과한다. 실제로 이 컴프리헨션 데트가 쌓인 코드베이스에서 디버깅 시간은 AI 생성 코드 섹션에서 평균 45분, 직접 작성 코드에서 15분으로 세 배 차이가 났다는 보고도 있다. AI가 코드를 쏟아내는 속도가 인간의 리뷰 속도를 앞지르는 순간, 거버넌스 없는 팀은 기술 부채가 아니라 이해 부채를 쌓기 시작한다.
Terraform MCP가 먼저 보여준 방향
HashiCorp가 출시한 Terraform MCP Server는 다른 각도에서 같은 문제를 건드렸다. AI 에이전트가 학습 데이터 기준의 구식 스키마로 HCL을 생성하는 대신, Registry를 실시간으로 조회해 현재 버전의 정확한 속성을 쓰게 만든 것이다. 컨텍스트 스위칭—Registry 탭 열기, provider 문서 확인, deprecated 속성 발견, 다시 탭으로 돌아가기—을 아예 없앤다. 이게 중요한 선례다. AI 에이전트에 '외부 진실의 소스'를 연결해서, 에이전트의 판단이 아닌 검증된 데이터로 코드를 생성하게 만드는 패턴. dotclaude는 이 방향을 팀 거버넌스 전체로 확장한다.
dotclaude: 거버넌스 레이어의 구체적 구조
MIT 라이선스 오픈소스 프로젝트인 dotclaude(dev.to)는 '개인 스킬 라이브러리'와 '팀 거버넌스 CLI' 두 경로를 하나의 코드베이스로 풀어냈다. 개인 경로는 bootstrap.sh 세 줄로 설치되고, ~/.claude/에 커맨드·스킬·CLAUDE.md를 심링크해 모든 레포 세션에 동일한 규칙 플로어를 깐다. 팀 경로는 npm install -g @dotclaude/dotclaude로 CI에 붙일 수 있는 검증기 세트를 제공한다.
실제로 팀에 쓸만한 검증기는 다섯 개다:
- dotclaude-check-spec-coverage: 보호 경로(protected path)를 건드린 PR은 반드시
Spec ID:헤더나## No-spec rationale섹션을 포함해야 한다. 예외 없음. - dotclaude-validate-specs: 스펙 계약을 감사하고 의존성 사이클을 잡는다.
- dotclaude-detect-drift: 14일 이상
origin/main에서 이탈한 커맨드를 플래그한다. - dotclaude-check-instruction-drift: CLAUDE.md와 README의 stale 항목을 감지한다.
- dotclaude-doctor: 환경·사실·매니페스트·스펙·드리프트·훅 전체를 자가 진단한다.
모든 바이너리는 {0, 1, 2, 64} 종료 코드 컨벤션을 따르고, 실패는 stable .code를 가진 구조화된 ValidationError로 노출된다. CI 스크립트가 문자열 grep 대신 에러 클래스로 분기할 수 있다는 뜻이다.
스펙이 계약이 될 때 AI 속도는 무기가 된다
핵심 인사이트는 여기에 있다. docs/specs/가 계약이 되고, 보호 경로가 집행 표면이 되면, PR 게이트는 "이 경로를 건드렸으면 스펙 ID를 보여라"는 단 하나의 질문으로 AI의 속도를 통제한다. 에이전트가 빠르게 코드를 생성할수록 이 게이트의 가치는 올라간다. 검증 없는 AI 속도는 발등을 찍는 총이지만, 게이트가 있으면 그 속도가 팀의 무기가 된다.
Slash command 레이어도 같은 철학으로 설계됐다. /pre-pr은 PR을 열기 전 단순화·보안 리뷰·전체 테스트 스위트 게이트를 순차 실행하고, /fix-with-evidence는 재현→수정→검증→PR 루프를 강제한다. /ground-first는 편집 전에 file:line 인용과 함께 읽기 우선 패스를 강제한다. 이 커맨드들의 공통점은 하나다—AI가 '그냥 작동하는 코드'를 내뱉는 게 아니라 증거를 남기도록 강제한다.
테크 리드가 설계해야 할 거버넌스 스택
도구가 갖춰졌어도 설계 없이 올리면 소용없다. 내가 실제로 팀에 거버넌스 레이어를 올릴 때 쓰는 순서는 이렇다.
1단계: 보호 경로 정의부터 시작한다. docs/repo-facts.json에 인증, 결제, 데이터 접근 레이어 등 핵심 경로를 먼저 박는다. AI가 이 경로를 건드리는 PR은 무조건 스펙이 붙어야 한다는 규칙을 CI에 심는 게 시작점이다.
2단계: CLAUDE.md를 팀 계약서로 쓴다. main 직접 푸시 금지, --no-verify 금지, 보호 경로 병합 전 전체 테스트 스위트 실행—이 규칙들을 파일에 박고 dotclaude로 드리프트를 주기적으로 체크한다. 팀원이 새로 합류해도 CLAUDE.md가 컨텍스트를 대신 설명한다.
3단계: CI에 검증기를 붙인다. dotclaude-init이 생성하는 세 개의 GitHub Actions 워크플로우(validate-skills, detect-drift, ai-review)를 기반으로 팀 상황에 맞게 조정한다. Node API를 쓰면 커스텀 게이트를 직접 만들 수 있다.
4단계: 스펙-코드 드리프트를 루틴으로 만든다. 스펙을 한 번 쓰고 잊으면 안 된다. dotclaude-detect-drift를 주간 CI 잡으로 돌려서 14일 이상 이탈한 커맨드가 생기면 알림이 오도록 설정한다.
냉정한 평가: 도입 전에 볼 것들
dotclaude는 현재 초기 오픈소스 프로젝트다. 팀 규모가 작을수록 bootstrap 경로만으로도 충분하고, CLI 거버넌스 경로는 CI 파이프라인이 어느 정도 갖춰진 팀에서 가치가 극대화된다. 학습 곡선은 낮다—slash command 문법과 repo-facts.json 구조를 익히는 데 반나절이면 충분하다. 다만 스펙 작성 자체가 팀 규율을 요구한다. 도구가 스펙 커버리지를 검증해줘도, 스펙을 처음부터 제대로 쓰는 습관은 팀이 따로 만들어야 한다.
전망: 거버넌스 레이어는 선택이 아니다
AI 에이전트가 팀에 더 깊게 들어올수록, 규율을 코드화하는 도구의 가치는 올라간다. Terraform MCP가 Registry를 실시간 진실 소스로 연결했듯, dotclaude는 팀의 스펙과 규칙을 AI 세션의 실시간 제약으로 연결한다. 패턴은 같다—AI의 판단을 외부 검증 가능한 소스로 앵커링하는 것. 앞으로 AI 코딩 에이전트를 팀에 올리는 모든 팀은 이 거버넌스 레이어 설계를 피할 수 없다. 도구가 dotclaude인지 다른 무언가인지는 부차적이다. 핵심은 AI 속도가 팀의 규율 속도를 앞지르기 전에, 그 규율을 기계가 읽을 수 있는 형태로 먼저 박아두는 것이다.