에이전트는 똑똑하다. 하지만 당신 팀을 모른다
AI 코딩 에이전트에 대한 불만 중 가장 흔한 것은 "코드가 돌아가긴 하는데, 우리 코드베이스엔 안 어울려"다. 컴파일은 되지만 통합하면 깨진다. 패턴은 맞는데 우리 컨벤션이 아니다. 이건 모델 성능의 문제가 아니다. 에이전트가 당신 팀의 맥락을 모르는 구조적 문제다. 세 개의 최근 기술 분석—컨텍스트 레이어 구축(dev.to), Git Hooks 강제 메커니즘(dev.to/Fleek), 코딩 에이전트 구성 요소 해부(Sebastian Raschka)—을 교차해보면, 이 문제를 푸는 아키텍처가 하나의 그림으로 완성된다.
1계층: 조직 지식을 AI가 검색할 수 있게 만들어라
50명 이상 엔지니어가 있는 조직에서 지식은 최소 세 곳에 흩어져 있다. Confluence의 아키텍처 문서, Jira의 티켓과 히스토리, GitHub의 코드와 PR 코멘트. 에이전트는 이 중 어느 하나만 보고 코드를 생성한다. 결과는 예측 가능하다—기술적으로 올바르지만 실질적으로 쓸모없는 코드.
dev.to의 Jeremy Rajan이 제안하는 해법은 이 세 소스를 하나의 검색 가능한 벡터 스토어로 통합하는 것이다. 오픈소스 도구 Onyx(구 Danswer)를 Docker로 배포하고 Confluence·Jira·GitHub 크리덴셜을 연결하면 크롤링·청킹·임베딩·증분 동기화가 자동화된다. 핵심은 도구 선택이 아니라 원칙—조직의 지식을 AI가 검색할 수 있는 단일 레이어로 집약하는 것이다.
여기서 놓치면 안 될 실무 포인트가 있다. 메타데이터가 콘텐츠만큼 중요하다. 각 청크에 소스, 프로젝트, 작성자, 날짜, 타입이 태깅되어야 "이 Jira 프로젝트만 검색"처럼 필터링이 가능해지고 검색 정확도가 드라마틱하게 올라간다. 그리고 6개월 이상 업데이트되지 않은 Confluence 페이지는 독이다—에이전트가 낡은 아키텍처 문서를 확신에 차서 참조한다.
2계층: 컨텍스트 브릿지 + 로컬 가드레일
지식 인덱스가 준비됐으면 Claude Code가 거기에 접근할 수 있어야 한다. MCP(Model Context Protocol)로 얇은 서버를 하나 만들면 된다. 엔지니어가 "PROJ-456 구현해줘"라고 입력하는 순간, 에이전트는 Jira에서 티켓 상세와 승인 기준을 가져오고, Confluence에서 관련 아키텍처 문서를 검색하고, GitHub 전체 조직에서 유사 패턴 구현체를 찾는다. 이 브릿지는 의도적으로 얇게 유지해야 한다. 비즈니스 로직을 여기 넣기 시작하면 유지보수 악몽이 된다.
그리고 각 레포 루트에 CLAUDE.md를 둔다. 이 서비스가 무엇인지, 누가 오너인지, 어떤 패턴을 따르는지, 절대 하면 안 되는 것이 무엇인지를 평문 마크다운으로 정의한다. 에이전트는 이 파일을 자동으로 읽는다. Sebastian Raschka의 분석에서도 강조하듯, 하니스의 설계 품질이 동일한 LLM의 성능을 결정한다. GLM-5 같은 오픈웨이트 모델도 잘 설계된 하니스에 통합되면 훨씬 강력해진다.
3계층: 휴리스틱은 결정론적 강제로 보완하라
CLAUDE.md에 "console.log 대신 @fleekit/logger를 써라"고 써도, 에이전트는 90~95% 확률로 따른다. 나머지 5~10%가 문제다. 10명이 하루에 10번 커밋하면 하루에 5~10번은 룰이 깨진다는 뜻이다.
Fleek이 내부 도구 플랫폼에서 발견한 해법이 바로 Git Hooks를 통한 결정론적 강제다. pre-commit 훅이 staged 파일에서 console.*를 스캔하고 커밋을 블로킹한다. 에이전트는 예외를 만들지 않는다. 망각도 없다.
여기서 중요한 인사이트가 하나 있다. 훅의 에러 메시지가 곧 프롬프트다. 에이전트가 훅에 막히면 에러 출력을 읽고 수정을 시도한다. 그러니까 에러 메시지를 인간이 아니라 AI가 읽는다고 가정하고 설계해야 한다. 단순히 "console.log 불가"가 아니라—위반 파일과 라인 번호, 적용해야 할 규칙, 교체 코드 예시까지 메시지에 담아야 한다. 그러면 에이전트가 첫 번째 재시도에서 스스로 수정한다. 인간 개입 없이.
또 하나의 고ROI 훅이 있다. 코드를 변경했는데 CLAUDE.md를 업데이트하지 않으면 커밋을 블로킹하는 것. 문서는 결국 부패한다—그리고 낡은 CLAUDE.md는 에이전트에게 잘못된 맥락을 주입한다. 훅으로 강제하면 문서가 살아있는 상태를 유지한다. 훈육이나 코드 리뷰 리마인더 없이, 구조가 그것을 요구하기 때문에.
통합 아키텍처: 세 계층이 맞물리는 방식
이 세 계층을 합치면 에이전트의 행동 반경이 정의된다.
- 1계층 (지식 인덱스): 에이전트가 무엇을 알아야 하는지를 공급한다
- 2계층 (컨텍스트 브릿지 + CLAUDE.md): 에이전트가 어떻게 행동해야 하는지를 가르친다
- 3계층 (Git Hooks): 에이전트가 잘못된 방향으로 가는 것을 물리적으로 막는다
Sebastian Raschka의 하니스 분석은 이 구조에 이론적 기반을 제공한다. 코딩 에이전트의 6가지 핵심 구성 요소—실시간 리포 컨텍스트, 프롬프트 캐시, 도구 접근, 컨텍스트 팽창 최소화, 세션 메모리, 하위 에이전트 위임—중 앞의 세 개는 1·2계층이 직접 구현하는 것들이고, 나머지 세 개는 하니스 설계로 제어하는 영역이다. 모델 품질보다 컨텍스트 품질이 실제 성능에 더 큰 영향을 준다는 그의 결론은 이 3계층 아키텍처의 존재 이유를 정확히 설명한다.
실전 롤아웃: 한 번에 다 짜지 마라
세 계층을 동시에 구축하려다 실패하는 팀을 너무 많이 봤다. Jeremy Rajan이 제안하는 순서가 현실적이다.
1~2주차: 지식 인덱스부터. Onyx 배포하고 Confluence·Jira·GitHub 연결. 검색 결과 품질 검증. 기반이 나쁘면 위에 쌓는 모든 것이 나쁘다.
3주차: MCP 브릿지 구축. 시니어 엔지니어 한 명, 레포 하나로 테스트. 에이전트가 실제로 필요한 컨텍스트가 무엇인지 노이즈와 구분하는 데 시간이 걸린다.
4~5주차: 트래픽 높은 레포 3~5개에 CLAUDE.md 작성. 그 레포 오너 시니어 엔지니어가 직접 쓰게 해라. 수년간의 트라이벌 놀리지를 AI가 쓸 수 있는 형태로 인코딩하는 작업이다.
6주차 이후: Git Hooks 도입. 이 시점이 되면 어떤 규칙이 자주 깨지는지 패턴이 보인다. 그것부터 훅으로 강제한다.
시사점: '에이전트 제어'는 프롬프트 문제가 아니다
많은 팀이 에이전트를 통제하려고 프롬프트를 더 정교하게 다듬는 데 시간을 쓴다. 틀린 방향은 아니지만, 충분하지 않다. 프롬프트는 휴리스틱이다. 에이전트는 가끔 잊는다.
이 3계층 아키텍처가 의미있는 이유는 에이전트를 설득하는 것이 아니라 구조로 경계를 만들기 때문이다. 지식 레이어는 에이전트가 조직 맥락 없이 코드를 생성하는 것을 불가능하게 만든다. Git Hooks는 룰을 어긴 코드가 레포에 들어오는 것을 물리적으로 막는다. 그 사이의 CLAUDE.md와 MCP 브릿지는 에이전트가 올바른 방향으로 가도록 안내하는 가이드레일이다.
내일 당장 시작할 수 있는 것부터 말하면: 가장 중요한 레포 하나에 CLAUDE.md 파일을 만들고, console.log 하나 막는 pre-commit 훅을 추가해보라. 에러 메시지를 AI가 읽는다고 가정하고 설계하면서. 그 작은 실험이 팀의 에이전트 통제 아키텍처가 어떠해야 하는지를 가르쳐줄 것이다.