AI 코딩 도구는 빠르게 코드를 만들지만, 프로젝트 맥락과 팀 규칙을 매 세션마다 새로 잊는다. 이 글은 claude-code를 중심으로 CLAUDE.md, 세부 규칙 파일, 전문 에이전트, pre-commit 훅, 의사결정 프로토콜을 조합해 AI 보조 개발의 품질 드리프트를 줄이는 실전 거버넌스 구조를 정리한다.
프롬프트만으로는 부족한 이유
AI 코딩 실패는 대개 모델이 “나빠서”라기보다 프로젝트의 암묵지를 매번 새로 전달해야 하기 때문에 생긴다. 어제 지적한 네이밍 규칙, 지난주에 설명한 인증 패턴, 세션 초반에 합의한 파일 범위는 다음 세션에 자동으로 남지 않는다.
프롬프트는 일회성 지시다. 거버넌스 시스템은 반복 로드되는 프로젝트 인프라다. 목표는 AI가 매번 같은 기준으로 일하도록 만드는 것이다.
대표적인 드리프트는 다음과 같다.
| 드리프트 | 증상 | 거버넌스 대응 |
|---|---|---|
| 타입 안전성 약화 | TypeScript에서 any로 컴파일만 통과 | 규칙 파일 + 훅 경고 |
| 보안 누락 | 새 API 라우트에 인증·소유권 검증 없음 | 보안 규칙 + 리뷰 에이전트 |
| 구현 스타일 분산 | 파일마다 컴포넌트 패턴과 이름이 다름 | CLAUDE.md + 예시 파일 |
| 범위 확장 | 요청하지 않은 리팩터링·기능 추가 | 계획/실행 역할 분리 |
| 모호한 요구 해석 | 질문 없이 엉뚱한 기능 구현 | 신뢰도 게이트 프로토콜 |
4계층 거버넌스 구조
1. 컨벤션 파일
루트의 CLAUDE.md는 모든 세션에 자동 주입되는 기본 규칙이다. 여기에 모든 문서를 넣으면 토큰을 낭비하고 중요한 컨텍스트를 밀어낸다. 좋은 CLAUDE.md는 라우팅 테이블처럼 작동한다.
## Overview
React Router 7, Supabase, Drizzle 기반 영상 분석 SaaS.
## Core rules
- TypeScript strict, no any
- 모든 API endpoint는 auth와 data ownership 확인
- React component는 const arrow function 사용
- 파일이 300줄에 가까워지면 분리
## Deep rules
- rules/architecture.md
- rules/api-patterns.md
- rules/security.md핵심은 세 가지 질문에 빠르게 답하는 것이다. 이 프로젝트가 무엇인지, 절대 어기면 안 되는 규칙이 무엇인지, 더 깊은 규칙은 어디에 있는지.
2. 전문 에이전트
복잡한 작업에서는 한 에이전트가 계획, 구현, 리뷰, 커밋까지 모두 담당하면 범위가 쉽게 흐려진다. 역할을 나누면 품질 기준을 더 강하게 걸 수 있다.
| 역할 | 책임 | 제약 |
|---|---|---|
| Planner | 관련 파일 조사, 구현 계획, 수용 기준 정의 | 코드 작성 금지 |
| Executor | 승인된 계획대로 구현 | 계획 임의 변경 금지 |
| Security reviewer | 인증, 권한, 입력 검증, 비밀정보 노출 점검 | 구현 후 자동 실행 |
모든 팀에 다중 에이전트가 필요한 것은 아니다. 하지만 계획 전담 역할 하나만 추가해도 “일단 만들고 보는” 실패를 크게 줄일 수 있다.
3. pre-commit 훅
규칙은 AI에게 방향을 주고, 훅은 규칙 위반이 저장소에 들어오는 것을 막는다. 초기에는 아래 항목부터 시작하면 효과가 크다.
# 차단
- .env 파일 커밋
- 하드코딩된 API 키·토큰
- 실패한 테스트
# 경고 또는 차단 후보
- production code의 console.log
- TypeScript any
- 한 커밋에서 과도하게 많은 파일 변경
- 새 API route의 auth 검증 누락훅은 단순한 안전망이 아니다. 같은 세션에서 훅이 실패하면 AI가 실패 출력을 읽고 수정하므로, 프로젝트가 실제로 강제하는 규칙을 즉시 피드백으로 돌려준다.
4. 의사결정 프로토콜
프로토콜은 코드 스타일이 아니라 판단 방식을 통제한다. 특히 요구사항이 모호하거나 위험할 때 유용하다.
가장 실용적인 방식은 신뢰도 게이트다. 작업 전 네 항목을 0~1로 점수화하고, 하나라도 0.7 미만이면 구현하지 않고 질문하게 한다.
| 차원 | 질문 |
|---|---|
| Scope | 무엇을 납품해야 하는지 명확한가 |
| Target | 관련 코드 영역을 충분히 이해했는가 |
| Output | 검증 가능한 수용 기준을 정의했는가 |
| Risk | 실패하거나 깨질 수 있는 지점을 식별했는가 |
또 다른 유용한 규칙은 계획 이탈 프로토콜이다.
| 상황 | 행동 |
|---|---|
| 사소한 누락 import·타입 발견 | 수정하고 기록 |
| 기존 버그 발견 | 범위 안이면 수정, 아니면 기록 |
| 아키텍처 변경 필요 | 중단하고 질문 |
| 요청 밖 기능 아이디어 | 구현하지 않고 후속 항목으로 기록 |
점진적 도입 순서
처음부터 완벽한 프레임워크를 만들 필요는 없다. 실제 마찰에서 규칙을 뽑아내야 오래 간다.
- 첫날: 짧은
CLAUDE.md를 만든다. 스택, 5~10개 핵심 규칙, 세부 문서 위치만 적는다. - 첫 주: AI가 같은 실수를 두 번 이상 반복할 때마다
rules/파일에 예시와 반례를 추가한다. - 2~3주차: 계속 어기는 규칙을 pre-commit 훅으로 옮긴다. 비밀정보와 테스트 실패는 차단하고, 오탐이 많은 항목은 경고로 시작한다.
- 둘째 달 이후: 요구사항 오해, 범위 확장, 보안 리뷰 누락 같은 상위 실패가 보이면 전문 에이전트와 프로토콜을 추가한다.
무엇을 규칙으로 만들까
규칙은 두 가지를 보완해야 한다. 하나는 팀의 약점, 다른 하나는 AI의 반복적 성향이다.
- 백엔드 보안에 약한 팀이면 인증, 권한, 입력 검증, 비밀정보 탐지를 강화한다.
- UI 일관성이 약하면 컴포넌트 예시, 접근성 체크, 시각 회귀 테스트를 넣는다.
- AI가
any를 자주 쓰면 타입 패턴과 훅을 추가한다. - AI가 요구 밖 리팩터링을 자주 하면 파일 범위와 변경량 제한을 둔다.
반대로 AI가 이미 잘하는 기본 문법이나 너무 일반적인 모범 사례를 길게 적을 필요는 없다. 규칙은 “AI 기본 출력”과 “팀이 코드 리뷰에서 받아들일 출력” 사이의 간격을 줄이는 데 집중해야 한다.
주기적으로 줄여야 한다
거버넌스도 부풀면 성능을 해친다. 규칙이 많아질수록 토큰을 쓰고, 서로 충돌하고, AI가 진짜 중요한 지시를 놓칠 수 있다.
분기마다 각 규칙·훅·에이전트에 대해 아래 질문을 던진다.
- 최근 실제로 쓰였는가?
- 어떤 반복 문제를 해결했는가?
- 더 단순하게 만들 수 있는가?
- 현재 아키텍처와 여전히 맞는가?
- 다른 규칙과 충돌하지 않는가?
AI 보조 개발 거버넌스의 핵심은 AI를 더 강하게 통제하는 것이 아니라, 좋은 엔지니어링 판단을 매번 반복 가능한 시스템으로 외부화하는 것이다.
관련 문서
- claude-code-tips-project-structure —
CLAUDE.md, skills, rules로 프로젝트 구조화하기 - claude-code-tips-best-practice — Claude Code 실전 운영 패턴
- agent-governance — 에이전트 실행 흐름의 권한·비용·정책 통제
- agent-harness — 에이전트 성능을 결정하는 하네스 설계 방법론
참고 자료
- AI-assisted development governance: A practical guide — LogRocket Blog (2026-05-09)