버즈빌 제품 리드가 AI 코딩 에이전트(Claude Code)를 통제하기 위해 구축한 5겹 하네스 시스템을 에이전트 본인이 1인칭으로 설명한 글이다. 스탠딩 오더, 스킬, 메모리, 권한, 훅 다섯 레이어가 각각 다른 단계에서 다른 종류의 실수를 차단하며, 리뷰어가 포맷·타입·프로세스 대신 "이 해법이 맞는가?"에만 집중할 수 있는 환경을 만든다.
핵심 포인트- 레이어 1 스탠딩 오더(CLAUDE.md): 항상 참인 컨벤션·제약·아키텍처 결정을 모아 에이전트가 매 세션 먼저 읽게 한다. 각 규칙은 실제로 문제가 생겼기 때문에 존재하며 레포와 함께 버전 관리된다.
- 레이어 2 스킬: brainstorming, systematic debugging, verification, brand, illustration, dashboard 등 작업 종류별 필수 플레이북. 합리화로 빠져나갈 수 없는 강제 사항.
- 레이어 3 메모리: 세션을 넘나드는 학습 보존. 포트, 타이포그래피 패턴, i18n 함정, 완료 마일스톤 등 한 번 풀면 다시 안 풀어도 되는 지식을 축적한다.
- 레이어 4 권한: 약 150개 명령어 화이트리스트. 목록에 없으면 명시적 승인 필요. 처음부터 설정하지 않고 사용하면서 자연스럽게 수렴하며 감사 추적이 된다.
- 레이어 5 훅: 3개 체크포인트(명령어 전 가드, 편집 후 포맷/린트/타입체크, 턴 종료 전 스톱 게이트). 성공하면 침묵, 실패하면 즉각적이고 구체적인 피드백이 원칙.
상세 정리- 스탠딩 오더 예시: CSS 변수 var(--bzv-color-theme-*) 직접 사용 강제, 사용자 요청 시에만 커밋, 개발 서버 포트 고정, next-mdx-remote 금지(React 버전 충돌). 모든 규칙이 실제 사고 후 추가됐다.
- 스킬 필수성 근거: 스킬이 없으면 에이전트가 수백만 개 일반 코드베이스의 학습 데이터로 회귀한다. "이건 간단해서 스킬이 필요 없다"는 합리화를 구조적으로 차단하는 게 핵심 설계 의도다.
- 메모리 구체 예시: next-i18next의 t()가 string | null을 반환해 strict string prop에 느낌표(!) 단언이 필요하다는 사실, 로케일 JSON 변경 후 HMR이 SSG 번역을 재로드 못 해 서버 완전 재시작이 필요하다는 사실 등이 축적된다.
- 권한 설계 철학: 프로덕션 레포는 엄격하게, 플레이그라운드 레포는 느슨하게 운영. 화이트리스트를 보면 에이전트가 시간 경과에 따라 어떤 작업을 수행했는지 자연스럽게 감사 추적이 된다.
- 편집 후 훅 구조: Prettier가 파일을 자동 포맷하고, ESLint가 수정 가능한 것을 자동 수정하며, TypeScript 타입체크는 백그라운드 비동기로 실행해 임시 파일에 결과를 저장한다. 오류 없으면 출력이 전혀 없다.
- 스톱 게이트: 에이전트가 턴을 끝내려 할 때 임시 파일을 확인해 타입 에러가 있으면 exit code 2로 차단. 해결 전까지 리뷰어에게 응답을 넘길 수 없다.
- 가드 예시: rm -rf /, git push --force, git reset --hard, drop table, truncate table 등 파괴적 명령어 패턴을 사전에 차단. 완전히 못 하게 막는 게 아니라 멈추고 질문하게 만드는 장치다.
- 도입 순서 권장: 스탠딩 오더(10분) → 스킬(각 수 분) → 권한(자연 축적) → 메모리(자동) → 훅(30분). 훅은 나머지 4개 레이어가 갖춰진 후에 진정한 효과를 발휘한다.
- 최종 결과: Max는 포맷 문제, 타입 에러, 프로세스 준수를 신경 쓰지 않고 설계 결정과 엣지 케이스에만 집중한다. 모든 사소한 것은 자동화됐다.
왜 읽나AI 코딩 에이전트를 팀 실무에 도입하면서 신뢰할 수 있는 제어 구조를 만들려는 개발자·팀 리드에게 즉시 참고할 수 있는 5-레이어 운영 프레임워크.
버즈빌·
AWS Architecture·
flex·