AI 에이전트(AI agent)를 오래 쓰다 보면 자동화하고 싶은 순간이 늘어난다.

매번 같은 설명을 붙이기 귀찮고, 검증 명령도 반복되고, 로컬 변경 확정(commit)과 원격 반영(push) 앞에서 같은 확인을 다시 하게 된다.

그때 바로 자동화를 키우면, 일이 끝났다는 기준보다 실행 속도만 먼저 커진다.

이 글에서 말하는 작업 하네스(harness)는 일이 끝났다고 말하는 조건을 묶어두는 구조다.

여기서는 왜 자동화보다 하네스를 먼저 둬야 하는지와 자기 작업에 붙일 여섯 칸짜리 템플릿을 정리한다.

하네스 엔지니어링을 작업, 기준, 검증, 기록, 재시도, 승인 흐름으로 보여주는 다이어그램.

하네스 엔지니어링은 AI 에이전트를 믿는 방식이 아니라, 에이전트가 한 일을 다시 보게 만드는 방식이다.

하네스는 자동화와 다르다

자동화는 일을 대신 움직인다.

예를 들어 릴리스 노트 작성, 테스트 실행, 문서 색인 데이터(index) 갱신, 변경 확정(commit), 배포(deploy)로 이어지는 흐름을 자동화한다. 잘 만들면 속도도 빨라진다.

하지만 그 흐름이 왜 맞는지, 어디서 멈춰야 하는지, 실패했을 때 무엇을 다시 봐야 하는지가 없으면 자동화는 위험해진다.

하네스는 일을 대신 끝내는 장치가 아니라, 일이 끝났다고 말하는 조건을 묶는 장치다. 작업이 어디서 시작되고, 어떤 기준을 따라야 하며, 무엇을 검증해야 하고, 실패하면 어디로 돌아와야 하는지를 고정한다.

예를 들어 고객 문서 릴리스를 준비한다고 해보자. 단순 자동화라면 “문서 생성 -> 공개 파일 저장 -> 빌드(build) -> 원격 반영(push)”을 한 줄로 연결하고 싶어진다.

하네스는 다르게 묻는다.

이 문서는 공개해도 되는가?
필요한 공개 파일(asset)은 실제 경로에 저장됐는가?
본문의 주장과 제목, 설명 문구(description)가 같은 약속을 하는가?
관련 검증 명령은 통과했는가?
실패하면 어디서 멈추고 무엇을 보고할 것인가?
원격 반영(push)은 누가 승인했는가?

이 질문들이 있어야 에이전트 작업을 나중에 다시 본다.

최소 하네스는 여섯 칸이면 충분하다.

작업: 무엇을 끝내는가
기준: 무엇을 읽고 판단하는가
검증: 어떤 증거로 확인하는가
기록: 무엇을 남기는가
재시도: 실패하면 어디서 다시 보는가
승인: 밖으로 나가기 전에 누가 멈추는가

도구 이름은 이 칸을 채우는 방법일 뿐이다. 중요한 것은 특정 파일명이나 훅 이름이 아니라, 작업 흐름 안에서 이 여섯 질문이 빠지지 않는 것이다.

여섯 칸으로 나눈다

나는 에이전트 하네스를 만들 때 여섯 칸으로 나누어 본다.

첫째, 작업이다.

에이전트가 지금 무엇을 하는지 작게 고정한다. “문서 릴리스를 처리해줘”는 너무 넓다. “API 변경 안내서를 만들고, 고객 문서 기준에 맞는 공개 파일을 붙이고, 관련 검증 스크립트를 통과시킨다”처럼 끝을 판단해야 한다.

둘째, 기준이다.

기준은 대화 중에 떠오르는 선호가 아니라 다시 읽는 파일이나 명령이어야 한다. 고객 문서라면 API 계약(API contract), 용어집, 릴리스 정책, 기존 문서의 톤이 기준이 된다. 코드라면 테스트, 정적 검사(lint), API 계약, 디자인 시스템이 기준이 된다.

셋째, 검증이다.

검증은 “괜찮아 보인다”가 아니다. 어떤 명령이 통과했는지, 어떤 화면을 봤는지, 어떤 파일이 생겼는지 확인해야 한다. 에이전트가 “수정했다”고 말하는 것과 “검증됐다”고 말하는 것은 다르다.

넷째, 기록이다.

긴 작업은 대화창에만 남기면 흔들린다. 어떤 결정을 했고, 어떤 명령이 실패했고, 어떤 파일을 바꿨는지 짧게 남겨야 한다. 이 기록은 다음 세션이나 다음 사람이 다시 이어받는 기준이 된다.

다섯째, 재시도다.

에이전트 작업은 한 번에 맞지 않는다. 중요한 것은 재시도 구조다. 실패 원인이 이미지 품질인지, 파일 저장 경로인지, 구조 규칙(schema) 오류인지, 배포 환경인지 구분되어야 한다. 그래야 같은 일을 처음부터 다시 하지 않는다.

여섯째, 승인이다.

변경 확정(commit), 원격 반영(push), 배포(deploy), 운영 데이터베이스(production DB) 변경, 공개 발행처럼 밖으로 나가는 일은 승인 경계가 필요하다. 하네스가 좋으면 에이전트가 승인을 “통과 의례”처럼 묻지 않는다. 무엇을 바꾸고, 어디로 보내고, 어떻게 되돌리는지 보여준 뒤 멈춘다.

이 여섯 칸을 한 줄로 놓으면 이렇게 된다.

작업 -> 기준 -> 검증 -> 기록 -> 재시도 -> 승인

이 흐름이 있어야 에이전트가 한 일이 결과물이 아니라 작업 단위가 된다.

하네스가 없으면 완료가 흐려진다

하네스가 없는 에이전트 반복 작업(agent loop)에서는 완료의 의미가 자주 흐려진다.

예를 들어 에이전트가 다이어그램 이미지를 만들었다고 하자. 화면에는 이미지가 보인다. 하지만 그 이미지가 실제 프로젝트 파일로 저장되지 않았다면 공개 문서는 그 이미지를 참조할 수 없다.

이때 “다이어그램 이미지를 만들었다”와 “문서가 참조하는 파일(asset)을 공개 가능한 위치에 저장했다”는 다른 말이다.

하네스가 없으면 이 차이가 대화 중에 사라진다. 사용자는 결과를 본 것 같고, 에이전트는 작업을 끝낸 것 같고, 실제 저장소(repo)에는 필요한 파일이 없다. 나중에 빌드(build)나 문서 릴리스 검사에서야 문제가 드러난다.

그래서 좋은 하네스는 중간 결과를 완료처럼 말하지 못하게 한다.

생성됨: 대화 화면에서 다이어그램 이미지가 보임
저장됨: 문서 공개 파일(asset) 경로에 PNG가 있음
참조됨: 문서 메타데이터(metadata)와 본문이 그 파일을 가리킴
검증됨: 관련 검증 스크립트가 통과함
공개됨: 승인된 원격 반영(push)과 배포 뒤 화면 확인(live smoke)이 끝남

이렇게 상태를 나누면 “어디까지 됐고 어디서 막혔는지”가 보인다.

작은 하네스가 먼저다

처음부터 큰 에이전트 플랫폼을 만들 필요는 없다.

오히려 처음에는 작은 하네스가 낫다. 자주 반복되고, 실패하면 비용이 큰 작업 하나를 고른다.

예를 들어 이런 작업이 좋다.

  • 고객 문서 릴리스
  • 운영 환경(production) 배포
  • 고객 데이터가 섞인 문서 요약
  • 데이터베이스 변경(DB migration)
  • 대량 파일 정리
  • 외부 원격 반영(remote push)

그다음 각 작업에 세 가지만 붙인다.

시작 기준: 무엇을 읽고 시작하는가
중단 조건: 무엇이 없으면 멈추는가
완료 증거: 어떤 파일, 명령, URL, 로그가 남아야 하는가

이 정도만 있어도 에이전트 작업은 훨씬 덜 흔들린다.

예를 들어 고객 문서 릴리스 하네스라면 “공개 문서가 참조하는 이미지와 첨부 파일은 실제 공개 파일(asset)로 저장되어야 한다”는 중단 조건을 둔다. 이미지 생성 도구가 화면에 결과만 보여주고 파일을 남기지 못하면, 그 자리에서 멈추고 사람에게 알려야 한다. 임시 캡처나 보이지 않는 파일로 몰래 대체하면 안 된다.

이 조건은 작업을 느리게 만들기도 한다. 하지만 느려지는 것이 목적이 아니라, 공개 문서 릴리스라는 경계에서 증거 없는 완료를 막는 것이 목적이다.

규칙과 검사는 하네스의 일부다

하네스는 한 가지 도구가 아니다.

반복 기준은 에이전트가 매번 읽는 규칙 파일에 남긴다. Codex 환경에서는 그 예가 AGENTS.md다. “외부 공개 변경은 승인 전에는 로컬에서 멈춘다”, “원격 반영(push)과 배포(deploy)는 확인 후 한다” 같은 반복 조건은 대화보다 파일에 두는 편이 낫다.

실행 경계 검사는 특정 순간을 확인한다. Hook은 그 역할을 하는 방법 중 하나다. 위험한 명령 앞에서 멈추고, 종료 전에 검증 누락을 알리고, 공개 파일에서 비밀값(secret)처럼 보이는 문자열을 찾는다.

컨텍스트 정리는 긴 작업에서 현재 상태를 다시 넣어준다. 세션이 길어졌을 때 목표, 결정, 변경 파일, 실패한 명령, 남은 일을 짧게 남겨야 다음 판단이 흔들리지 않는다.

이 셋은 따로 보이지만 같은 방향을 향한다.

규칙 파일은 기준을 남긴다.
실행 경계 검사는 멈출 지점을 다시 표시한다.
컨텍스트 정리는 다음 판단에 필요한 상태를 다시 넣는다.

이 셋을 작업 흐름에 맞게 묶으면 하네스가 된다.

하네스는 사람의 판단을 없애지 않는다

좋은 하네스는 사람을 빼는 장치가 아니다.

오히려 사람이 판단해야 하는 순간을 더 잘 보이게 만든다.

에이전트가 알아서 빌드(build)를 돌릴 수는 있다. 하지만 공개 배포를 할지, 문서의 주장 수위가 적절한지, 비공개(private) 정보가 정말 제거됐는지, 실패한 검증을 무시해도 되는지는 사람이 봐야 한다.

하네스가 하는 일은 그 판단을 숨기지 않는 것이다.

그래서 하네스의 성공 기준은 “완전 자동으로 끝났다”가 아니다. “어디까지 자동으로 했고, 어디서 사람에게 넘겼고, 무엇을 근거로 넘겼는지 보인다”다.

에이전트 작업은 점점 길어지고 복잡해질 것이다. 모델 성능이 좋아질수록 더 많은 일을 맡기고 싶어진다. 하지만 일이 길어질수록 더 필요한 것은 무조건적인 자동화가 아니다.

작업을 작게 고정하고, 기준을 파일로 남기고, 검증을 실제 명령으로 확인하고, 실패를 기록하고, 재시도를 가능하게 만들고, 밖으로 나가기 전에 승인 경계를 세우는 것.

그게 내가 말하는 하네스 엔지니어링이다.

시리즈 연결