테스트 하네스가 테스트 대상을 외부로부터 감싸고 실행 환경을 제어하듯, 에이전트 오케스트레이션 시스템 역시 견고한 하네스가 필요하다. 하네스 없이 개별 에이전트만 늘려가는 방식은 위험하다. 어떤 에이전트가 어떤 권한으로 무엇을 실행했는지 추적이 되지 않을뿐더러, 에이전트의 작은 실수가 전체 프로젝트의 안정성을 해칠 수 있기 때문이다. 완성도 높은 에이전트 시스템은 세 겹의 하네스 구조로 설계되어야 한다.
이 세 겹의 구조는 **물리적 경계(Permission), 공통 규칙(AGENTS.md), 그리고 실행 제어(Orchestrator)**로 나뉜다. 이들이 유기적으로 맞물릴 때 비로소 에이전트는 우리가 의도한 안전한 울타리 안에서 최대의 성능을 발휘한다. 시리즈의 마지막 편에서는 이 하네스 구조를 실전에 적용하는 구체적인 레시피와 최종 체크리스트를 정리한다.
하네스의 세 겹 구조: 경계, 픽스처, 실행
첫 번째 겹은 권한을 통한 경계 하네스다. 이는 에이전트가 물리적으로 할 수 있는 일과 없는 일을 강제하는 가장 확실한 수단이다. 외부 네트워크 접근을 제한하거나 특정 디렉토리 수정을 금지하는 설정을 통해, 에이전트가 프롬프트의 오류나 모델의 환각으로 인해 예기치 못한 행동을 하는 것을 원천 봉쇄한다.
두 번째 겹은 AGENTS.md를 통한 픽스처 하네스다. 테스트 코드에서 환경을 초기화하는 픽스처처럼, AGENTS.md는 프로젝트에 참여하는 모든 에이전트가 공통으로 지켜야 할 헌법을 정의한다. “테스트 삭제 금지”, “토큰 출력 금지”, “검증 없이 완료 보고 금지” 같은 규칙을 에이전트마다 일일이 적어주는 대신, 중앙에서 관리하여 모든 에이전트의 사고방식을 동기화한다.
세 번째 겹은 오케스트레이터에 의한 실행 하네스다. OMO는 작업을 단계로 나누고, 어느 지점에서 병렬화하고, 어떤 실패가 발생했을 때 누구에게 넘길지 결정한다. 이 실행 하네스가 없으면 좋은 에이전트들이 모여도 작업은 즉흥적으로 흐른다. 좋은 팀도 일정표가 없으면 회의가 길어진다. 에이전트도 크게 다르지 않다.
실전 레시피: 블로그 업데이트
가장 작은 레시피는 블로그 글 업데이트다. 이 작업은 API, 토큰, 문체, 발행 상태가 모두 얽혀 있어서 하네스 예제로 좋다. 잘못 만들면 글은 잘 써놓고 상태를 바꾸거나, 토큰을 로그에 남기거나, 전체 metadata를 덮어쓴다. 자동화가 아니라 사고 자동 생성기다.
1. command: /blog update <slug>
2. skill: blog-write 규칙 로드
3. tool: GET /api/posts/[slug]
4. writer: content 수정안 생성
5. tool: PATCH /api/posts/[slug] with changed fields only
6. verifier: GET 재조회로 slug/status/content 확인여기서 AGENTS.md에는 “토큰 출력 금지”, “publish는 명시 요청이 있을 때만”, “PATCH에는 변경 필드만” 같은 규칙을 둔다. permission은 writer에게 파일 수정 권한을 주더라도 publisher 역할은 별도로 분리한다. OMO는 explore나 reviewer를 필요한 시점에 호출해 현재 글 구조와 누락된 섹션을 확인한다.
실전 레시피: 라이브러리 도입
두 번째 레시피는 외부 라이브러리 도입이다. 이 작업은 내부 패턴과 외부 문서가 동시에 필요하다. explore는 현재 코드베이스의 유사 구현을 찾고, librarian은 공식 문서와 public example을 조사한다. builder는 두 결과를 합쳐 최소 변경을 만들고, reviewer는 번들 크기, 타입 안정성, 에러 처리, 테스트 누락을 본다.
parallel:
explore -> 내부 사용 패턴, 테스트 위치, 네이밍 규칙
librarian -> 공식 문서, 버전별 주의점, 실제 사용 예시
then:
builder -> 구현
verifier -> lint/typecheck/test/build
reviewer -> 설계와 보안 위험 확인이 레시피에서 중요한 것은 병렬화 이후의 합성 단계다. 두 에이전트가 각각 좋은 답을 냈더라도 그대로 합치면 충돌할 수 있다. 공식 문서가 권장하는 방식이 우리 코드베이스의 에러 처리 정책과 맞지 않을 수도 있고, public example이 과하게 단순화되어 있을 수도 있다. 오케스트레이터는 결과를 합치되, 결정은 프로젝트 제약 안에서 내려야 한다.
실전 레시피: 위험한 변경
인증, 결제, 배포, 데이터 삭제처럼 위험한 변경은 처음부터 느리게 설계해야 한다. 여기서는 builder가 바로 수정하기 전에 oracle이나 security reviewer가 먼저 위험 지점을 짚는 편이 좋다. 또한 destructive tool이나 MCP는 ask 또는 별도 command 뒤에만 열어둔다.
1. planner: 변경 범위와 위험 목록 작성
2. oracle/security: 설계와 권한 위험 검토
3. builder: 제한된 범위에서 구현
4. verifier: 테스트와 수동 검증 항목 확인
5. reviewer: 변경 diff와 운영 위험 재검토위험한 변경에서 가장 나쁜 패턴은 “일단 고치고 나중에 검토”다. 에이전트는 빠르게 움직이기 때문에 잘못된 방향으로도 빠르게 간다. 그래서 위험한 작업일수록 구현 전 검토와 구현 후 검토를 나누는 편이 안전하다. 느린 것처럼 보이지만, 롤백보다 빠르다.
최종 체크리스트: 완성도 점검
시스템을 운영하기 전에 아래 항목을 확인한다.
- 각 에이전트의 책임이 한 문장으로 설명되는가?
- reviewer와 builder의 권한이 분리되어 있는가?
- AGENTS.md에 공통 금지 규칙이 있는가?
- command는 반복 절차와 검증 단계를 포함하는가?
- skill은 도메인 지식을 중복 없이 담고 있는가?
- MCP나 외부 API tool은 역할별로 제한되어 있는가?
- 실패 시 재시도 횟수와 중단 조건이 있는가?
- 최종 완료 보고 전에 실제 검증 결과가 있는가?
이 체크리스트가 길어 보인다면 정상이다. 자동화는 버튼 하나로 시작되지만, 운영 가능한 자동화는 버튼 뒤에 있는 수많은 작은 제약으로 만들어진다. 좋은 하네스는 에이전트를 불신해서 만드는 것이 아니다. 오히려 에이전트가 잘할 수 있는 환경을 만들어주기 위해 필요한 울타리다.
댓글
댓글을 불러오는 중...