AI 에이전트에게 "부탁"을 그만두는 법: IT 에이전시가 하네스 엔지니어링으로 바꾼 것들

한줄 요약

프롬프트는 부탁이고, 하네스는 구조다. 에이전시가 AI를 제대로 쓰려면 구조를 설계해야 한다.

본문

하네스 엔지니어링은 AI 에이전트가 실행되는 환경 자체를 설계해 출력을 강제하는 시스템 설계 기법이다. IT 개발 에이전시 입장에서 이 개념은 단순한 기술 트렌드가 아니다. 클라이언트 프로젝트마다 스택이 다르고, 팀원마다 AI 활용 방식이 제각각이며, 실수 한 번이 납기와 신뢰에 직결되는 환경에서 "에이전트가 가끔 규칙을 무시한다"는 문제는 용납하기 어렵다.

---

왜 프롬프트만으로는 에이전시 현장에서 부족한가

에이전시 개발 환경은 단일 제품팀과 다르다. 동시에 서너 개 프로젝트가 돌아가고, 각각 다른 프레임워크와 컨벤션을 사용한다. 이 상황에서 AI 에이전트에게 "이 프로젝트는 이렇게 해야 해"라고 매번 프롬프트로 설명하는 방식은 스케일이 안 된다.

더 근본적인 문제가 있다. 프롬프트는 자연어고, 자연어 지시에는 강제력이 없다. 위험한 명령을 실행하지 말라고 강조해도, 에이전트는 상황에 따라 그냥 실행한다. 외주 개발에서 이런 예측 불가능성은 곧 리스크다. 클라이언트 코드베이스에서 복구 불가한 작업이 실행된다면 책임은 에이전시가 진다.

해결 방향은 프롬프트를 더 잘 쓰는 게 아니라, 에이전트가 나쁜 선택을 아예 할 수 없도록 실행 환경을 구조화하는 것이다.

에이전시가 하네스를 설계할 때 챙겨야 할 3가지 레이어

하네스는 크게 세 층으로 나눌 수 있다.

첫 번째 레이어는 시스템 레벨 가드레일이다. 에이전트가 도구를 실행하기 직전, 파일을 수정한 직후 같은 생명주기 시점에 셸 스크립트나 별도 판단 로직을 끼워 넣는다. 이 레이어는 프롬프트를 읽지 않는다. 에이전트가 무슨 말을 듣든 상관없이 특정 조건이 감지되면 차단하거나 자동으로 교정한다. 건물 스프링클러처럼, 누가 작동시키든 화재가 감지되면 터진다.

두 번째 레이어는 컨벤션 문서다. 스택 정보, 금지 행동, 코딩 규칙을 담은 문서를 에이전트에게 제공한다. 에이전시 환경에서 중요한 포인트는 이 문서가 프로젝트별로 달라야 하되, 에이전트별로 중복 작성하면 안 된다는 것이다. React 프로젝트용, Vue 프로젝트용, 각각의 상태 관리 조합까지 모듈 단위로 분리해 두고 조합하는 방식이 유지보수에 유리하다. 그래야 스택이 바뀌는 프로젝트에서도 핵심 규칙을 재활용할 수 있다.

세 번째 레이어는 에이전트 역할 정의다. 구현 담당, 코드 리뷰 담당, 테스트 생성 담당처럼 역할을 분리하면 각 에이전트가 처리하는 범위가 명확해진다. 에이전시 팀원들이 AI를 쓸 때 "어떤 에이전트에 어떤 작업을 맡겨야 하는가"가 표준화된다.

세 레이어 중 첫 번째가 유일하게 강제력을 갖는다. 나머지 두 개는 에이전트가 더 잘 따르도록 돕는 도구일 뿐이다.

에이전시 팀에 배포할 때 반드시 풀어야 하는 문제

혼자 쓰는 설정은 팀에 그대로 적용되지 않는다. 에이전시에서 이 문제를 자주 겪는다.

한 명이 설정을 잘 만들어도, 팀원 다섯 명이 각자 복사해 쓰기 시작하면 두 달 뒤에는 다섯 개의 다른 버전이 존재한다. 가드레일 스크립트를 업데이트해도 각 프로젝트에 복사된 구버전은 그대로다. 이 동기화 문제를 해결하지 않으면 하네스가 있어도 없는 것과 같다.

실용적인 접근법 두 가지가 있다. 하나는 설정을 패키지나 플러그인 형태로 배포해 설치 한 번으로 최신 상태를 유지하는 방식이다. 다른 하나는 세션 시작 시점에 중앙 저장소에서 최신 버전을 자동으로 가져오는 훅을 심는 방식이다. 어떤 방법이든 핵심은 "사람이 직접 동기화하지 않아도 되는 구조"다.

멀티모델 환경이 에이전시에 주는 실질적 이점

에이전시가 특정 AI 도구 하나에만 의존하는 건 장기적으로 리스크다. 클라이언트 요구나 도구 비용에 따라 유연하게 전환할 수 있어야 한다.

여기서 중요한 건 하네스가 특정 모델에 종속되지 않아야 한다는 것이다. Claude를 쓰든, OpenAI 기반 도구를 쓰든, Cursor를 쓰든 동일한 가드레일이 적용되고 동일한 컨벤션 문서를 읽는 구조라면, 도구를 바꿔도 에이전시의 품질 기준은 유지된다.

멀티모델 전략의 또 다른 활용은 검증이다. 한 모델이 만든 구현 계획이나 코드를 다른 모델에게 비판하게 하는 방식이다. 같은 편향을 공유하는 단일 모델보다 다른 시각에서 검증받은 결과물이 더 견고하다. 에이전시 입장에서 이건 QA 비용을 줄이는 실용적인 방법이기도 하다.

사고 모델을 단순하게 유지해야 하는 이유

에이전트에게 복잡한 사고 절차를 요구할수록 역설적으로 결과가 나빠지는 경우가 있다. 단계가 많을수록 각 단계의 경계가 모호해지고, 모호한 경계에서 에이전트는 판단 비용을 낭비한다.

에이전시 맥락에서 이건 비용 문제다. 간단한 수정 작업에 불필요한 분석 절차를 거치면 토큰 비용이 올라가고 속도가 느려진다. 실패했을 때 어디로 돌아갈지, 몇 번 실패하면 사람에게 판단을 넘길지를 명시적으로 정의한 사고 모델이 복잡한 단계보다 훨씬 실용적이다.

에이전시가 AI를 도입하는 목적은 생산성이다. 그 생산성은 프롬프트를 정교하게 다듬는 데서 오지 않는다. 에이전트가 예측 가능하게 동작하고, 실수를 시스템이 잡아주며, 팀 전체가 같은 기준으로 AI를 쓰는 구조를 만드는 데서 온다.