AI 에이전트 외주 개발, 프롬프트 말고 시스템으로 통제해야 하는 이유

한줄 요약

AI 에이전트를 외주 프로젝트에 쓰려면 프롬프트가 아니라 실행 환경 자체를 설계해야 한다.

클라이언트 프로젝트에 AI 에이전트를 붙이면 생기는 첫 번째 문제

IT 에이전시가 AI 에이전트를 실무 프로젝트에 투입할 때, 가장 먼저 마주치는 문제는 "에이전트가 지시를 무시한다"는 것이다.

명세서에 "절대 하지 말 것"이라고 굵은 글씨로 적어도, 에이전트는 가끔 그냥 한다. 프롬프트는 결국 자연어 요청이다. 강제력이 없다. 클라이언트 코드베이스에 돌이키기 어려운 변경이 일어난 뒤에야 뒤늦게 알게 되는 구조다.

에이전시 입장에서 이건 단순한 불편함이 아니다. 납품 품질의 문제고, 신뢰의 문제다. 그래서 프롬프트를 다듬는 것보다 에이전트가 실행되는 환경을 설계하는 쪽으로 방향을 바꿔야 한다.

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

에이전트에게 정교한 절차를 부여할수록, 역설적으로 작동이 불안정해진다. 단계가 많아질수록 에이전트는 "지금 어떤 단계인지 판단하는 데" 자원을 쓰고, 실제 작업보다 절차 해석에 더 집중하게 된다.

에이전시가 실무에서 쓸 수 있는 구조는 단순할수록 좋다. 예를 들어 네 단계로 충분하다.

• 읽기: 코드베이스를 먼저 파악한다. 기억이 아닌 실제 파일을 읽는다.
• 실행: 관찰한 패턴을 따라 구현한다. 최소한의 변경만 한다.
• 검증: 린터와 테스트를 사람 눈이 아닌 도구로 돌린다.
• 복구: 검증 실패 시 원인을 분석하고 읽기 단계로 돌아간다. 같은 이유로 반복 실패하면 사람에게 판단을 넘긴다.

여기서 핵심은 마지막 단계다. 실패했을 때 어디로 돌아갈지 명확히 정의되지 않은 절차는 실무에서 쓸 수 없다.

프로젝트마다 스택이 다를 때, 규칙을 어떻게 관리할 것인가

에이전시는 동시에 여러 클라이언트 프로젝트를 진행한다. A 프로젝트는 Vue와 Pinia를 쓰고, B 프로젝트는 React와 Zustand를 쓰며, 신규 프로젝트는 Nuxt와 Tailwind 조합이다.

에이전트 규칙 파일에 특정 스택 컨벤션이 하드코딩되어 있으면 프로젝트마다 별도 파일을 관리해야 한다. 버전이 맞지 않거나 업데이트가 누락되는 건 시간 문제다.

해결책은 컨벤션을 모듈 단위로 분리하는 것이다. 프레임워크, 상태 관리, 스타일링, 테스팅을 독립된 파일로 나눠두고, 각 프로젝트에서 조합해서 쓰는 구조다. 에이전트 사고 모델과 워크플로우는 동일하게 유지하면서 스택 설정만 교체한다. 이렇게 하면 규칙을 수정할 때 한 곳만 고쳐도 전체 프로젝트에 반영된다.

멀티모델 환경도 고려해야 한다. 한 프로젝트에 Claude와 Codex를 함께 투입하는 경우, 어떤 모델이든 읽을 수 있는 공용 설정 파일이 있어야 컨벤션이 통일된다. 특정 모델 전용 포맷에만 의존하면 도구를 바꿀 때마다 규칙 파일을 새로 써야 한다.

---

프롬프트 한계를 넘으려면: 하네스 엔지니어링이란 무엇인가

하네스 엔지니어링은 에이전트가 실행되는 환경 자체를 설계하는 접근법이다. 프롬프트로 부탁하는 게 아니라, 에이전트 생명주기의 특정 시점에 시스템 레벨 동작을 강제로 끼워 넣는다.

구체적으로는 이렇게 작동한다. 에이전트가 명령을 실행하기 직전, 셸 스크립트나 LLM 판단 로직이 먼저 실행되어 위험한 동작을 차단한다. 파일이 수정된 직후, 린터와 포매터가 자동으로 실행된다. 세션이 압축되기 전, 현재 작업 상태가 스냅샷으로 기록된다. 에이전트가 "잘 됐다"고 판단해도, 품질 검증 도구가 독립적으로 최종 확인한다.

프롬프트와 하네스의 차이를 쉽게 이해하려면 이렇게 생각하면 된다. 프롬프트는 "금연" 표지판이다. 대부분은 따르지만 강제력은 없다. 하네스는 건물의 소방 스프링클러다. 누가 무엇을 하든 조건이 충족되면 자동으로 작동한다.

에이전시 실무에서 하네스가 중요한 이유는 명확하다. 프롬프트를 잘 쓰는 팀원이 있는 날도 있고 없는 날도 있다. 하지만 시스템 레벨 가드레일은 팀원이 누구든, 어떤 모델을 쓰든 동일하게 적용된다.

주의할 점이 하나 있다. 하네스를 처음 도입할 때 "나중에 채우자"고 빈 스크립트를 만들어 두는 경우가 많다. 비어 있는 하네스는 없는 것과 다름없다. 차단 로직, 자동 수정 로직, 품질 게이트까지 실제로 동작하도록 채워야 의미가 있다.

에이전시에서 AI 에이전트 도입을 성숙시키는 순서

도입 초기에는 프롬프트를 정교하게 다듬는 데 집중하게 된다. 그다음에는 워크플로우를 정의하고, 단계별로 자동화하려 한다. 그리고 팀으로 확장하면 스택 모듈화와 설정 동기화 문제를 만난다. 마지막으로 신뢰할 수 있는 아웃풋을 반복적으로 내려면 하네스 설계가 필요하다는 걸 깨닫게 된다.

각 단계를 건너뛸 수 없다. 하네스를 처음부터 완성하려 하면 과도한 설계가 되고, 프롬프트 단계에 머물면 품질 일관성을 보장할 수 없다.

에이전시가 AI를 도구로 쓰는 것과, AI를 팀원처럼 운용하는 것 사이의 차이는 여기서 갈린다. 도구는 사람이 매번 점검하면 된다. 팀원은 시스템이 통제해야 한다.