에이전트가 일할 하네스 만들기
에이전트에게 무엇을 시킬지보다, 에이전트가 일할 하네스부터 만들었습니다.
처음 겪은 문제
AI 코딩 도구(Claude Code)를 쓰면 분명히 빨라집니다. 그런데 며칠 쓰다 보면 같은 문제가 반복됐습니다. 지난주에 한 번 설명한 걸 이번 주에 또 설명하고 있고, 같은 일을 시켜도 그때그때 결과 모양이 다르고, 무엇보다 "다 했습니다"라고 하는데 실제로는 안 되어 있는 경우가 생겼습니다.
프롬프트를 잘 쓰는 문제가 아니라, 에이전트가 일할 하네스(harness)가 없는 문제였습니다 — 규칙·도구·검증을 갖춘 실행 층 말입니다.
사람 신입이 들어와도 똑같습니다. 매번 말로 알려주면 그때만 됩니다. 대신 업무 규칙을 문서로 두고, 결재 없이는 못 나가게 하고, 끝났다고 하면 결과물을 확인합니다. AI에게 필요한 것도 같았습니다. 지시를 잘하는 대신 규칙과 관문을 환경 쪽에 심어두면, 매번 사람이 다시 확인하지 않아도 됩니다.
정한 원칙 세 가지
- 들어오는 문을 하나로 만든다.이슈는 제 발견, AI의 자동 탐지, 테스터 시트 — 여러 길로 들어옵니다. 이 모든 경로가 같은 스킬 하나를 거치게 강제했습니다. 문이 하나면 품질은 한 곳에서만 지키면 됩니다.
- "했다"는 말을 그대로 믿지 않는다.가장 중요한 장치입니다. 하루에 잘못된 완료 보고가 네 번 나온 날, 원인을 보니 잘못된 보고는 파일이 아니라 말과 문서로 나가고 있었는데 검사 장치는 파일 쓰기만 보고 있었습니다. 그래서 근거 없는 보고는 그 자리에서 막고 다시 확인시키는 훅을 넣었습니다.
- 원칙은 기억에 맡기지 않는다.대화가 길어지면 원칙이 흐려집니다. 매 턴마다 핵심 원칙과 "되묻지 말고 합리적으로 판단해 진행하라"는 기본값을 자동으로 다시 넣도록 했습니다.
무엇을 만들었나
- QA 작업 환경 — 구조를 이루는 부품은 규칙 21개, 스킬 21개, 플레이북 19개, 세션 훅 6개, 하위 에이전트 3종. 세션이 끝나면 회고 스킬이 배운 것을 규칙·문서로 되먹여, 환경이 쓸수록 나아집니다.
- 이 하네스에서 만든 도구 — 개인 업무를 통째로 맡는 업무 관리 도구도 이 위에서 만들어 매일 운영합니다.
- 쓰다가 갈아엎은 이력 — 처음엔 작업을 하위 워크스페이스에 발주하는 구조로 만들었는데, 실제로 써보니 과했습니다. 두 달 뒤 그 모델을 걷어내고 직접 수행 + 필요할 때만 병렬로 단순화했습니다. 폐기한 것과 그 이유를 문서에 남겨뒀습니다.
장치를 관리하는 장치
어떤 에이전트가 어떤 작업을 하든 같은 규칙, 같은 관문을 지나갑니다.
그런데 쓰다 보니 하네스 자체가 관리 대상이라는 걸 배웠습니다.
- 규칙의 증식을 막는 게이트.제 기록을 세어보니 규칙은 추가만 쌓이고 삭제는 한 번도 없었습니다 — 비대해지면 아무도 안 읽습니다. 그래서 새 규칙에 "왜 규칙이어야 하는가" 한 줄이 없으면 등록이 차단되게 했고, 그 한 줄이 나중에 퇴역 판단의 근거가 됩니다.
- 검사 장치를 검사하는 테스트."다 했다" 검사기의 첫 판은 멀쩡한 결과물까지 절반쯤 막았습니다. 실제로 겪은 문장만 모아 회귀 테스트를 만들어 검사기 자체를 검증하고, 검사기가 죽으면 하네스 전체가 멈춘 적이 있어 생존 확인 절차도 넣었습니다.
- 빠져나가는 길이 곧 원하는 행동."자료가 없다"는 보고를 차단할 때 우회를 어렵게 만드는 대신, 어디를 봤는지 같은 문장에 적으면 통과하게 설계했습니다. 차단을 피하려는 행동이 그대로 좋은 보고가 됩니다.
- 개입이 필요한 일은 닫힌 목록으로.사람 확인이 필요한 행동을 문서 발행·이슈 등록·운영 설정 변경 등 6종의 목록으로 명문화하고, 목록 밖에서는 되묻지 말고 합리적 가정으로 진행하게 했습니다. 나누는 기준은 하나 — 잘못되면 되돌릴 수 있는가.
측정해서 설계를 바꾼 기록
특히 도움이 된 건 제 방식이 맞는지 제 기록으로 확인해본 것이었습니다. 대규모 검증이 끝난 뒤 제가 남긴 기록을 전수로 다시 읽어봤더니 이런 패턴이 나왔습니다.
그래서 설계 목표를 바꿨습니다. "정해진 항목을 정확히 확인하게 만들기"가 아니라 "확인하는 동안 본 것을 버리지 않게 만들기"로요.
같은 문서에서 제가 처음 적었던 수치 하나는 다시 세어보니 재현되지 않았습니다. "막힌 항목 거의 전부(93%)가 풀리는 조건까지 함께 적었다"라고 썼는데, 세는 기준을 어떻게 잡느냐에 따라 47~72% 사이로 갈렸습니다.
원인은 지시문이 내용만 요구하고 형식을 강제하지 않은 것이었습니다. 사람이 읽으면 같은 말인데 기계로 세면 안 잡힙니다. 문서에 정정 내용을 그대로 남기고, 여기서 "글로 요구하면 절반만 지켜진다. 그러니 입력 칸으로 받아야 한다"는 결론을 얻었습니다.
남은 것
이 환경은 완성된 게 아니라 계속 고쳐 쓰는 중입니다. 규칙이 늘어날수록 서로 부딪히는 곳이 생기고, 그때마다 무엇을 남기고 무엇을 버릴지 판단해야 합니다. 지금까지 배운 건 장치를 늘리는 것보다 어긋났을 때 어디서 걸리는지가 분명한 게 낫다는 것입니다.