AI 에이전트에게 코드를 맡기려면 에이전트만 있어선 안 된다. 규칙을 매 세션 주입하는 지시 문서, 반복 작업의 절차를 담은 스킬, 모델이 잊더라도 검증을 강제하는 훅, 작업을 박제하는 기록. 이런 스케폴딩을 통째로 하네스(harness) 라 부른다. 에이전트가 신뢰할 수 있게 일하게 만드는 건 모델 성능이 아니라 이 하네스다.
내 하네스는 5개월에 걸쳐 우연히 쌓였다. 3월에 규칙 문서 한 장으로 시작해, 4월에 검증 훅과 스킬, 5월에 스킬 라이브러리, 6월에 기록 규율. 어느 날 전체를 점검했더니, 핵심 안전장치 하나가 두 달째 죽어 있었다. 아무도 몰랐다.
좋은 의도가 안전장치를 죽였다
문제의 시작은 합리적인 정리였다. 에이전트 설정 파일(settings.json)에는 머신별 절대경로가 박혀 있었고, 그걸 공개 저장소에 올리지 않으려고 git 추적에서 뺐다. 타당한 결정이다.
그런데 그 파일 안에 파일을 수정할 때마다 eslint·tsc를 자동으로 돌리는 훅이 살고 있었다. 추적을 빼면서 그 훅이 같이 고아가 됐다. 게다가 gitignore는 이미 추적 중인 파일을 추적 해제하지 않는다. git rm --cached까지 해야 완결된다. 그래서 “무시 목록에 있는데 여전히 추적되는” 좀비 상태가 남았고, 설정의 실제 내용은 비워진 채 흔적만 남았다.
결과는 조용한 격하였다. 검증이 “훅이 자동으로 강제한다”에서 “모델이 검증 스킬 부르기를 기억한다”로 내려앉았다. 모델이 기억하는 한 코드는 여전히 대체로 검증됐다. 하지만 강제력은 사라졌고, 비결정적인 “기억”이 그 자리를 메웠다. 관측가능성 글에서 말한 무음 실패가 하네스에서도 똑같이 났다. 깨진 게 아니라 조용히 약해졌고, 약해진 건 빨간불을 켜지 않는다.
두 달 묵은 거짓
점검하다 드리프트를 하나 더 찾았다. README가 “규칙 문서는 영문 + 한글 두 벌”이라고 적고 있었는데, 한글 쪽 파일은 두 달 전에 이미 삭제됐고 규칙은 한국어 단일본으로 통합돼 있었다. 문서가 두 달째 거짓을 말하고 있었던 것이다.
두 사고의 뿌리는 같다. 변경은 했는데, 그 변경을 가리키는 문서를 안 고쳤다. 파일을 지웠으면 그걸 참조하는 README를, 훅을 옮겼으면 “훅이 동작 중”이라던 메모리를 같이 고쳐야 했다. 안 고치면 코드와 문서가 갈라지고, 그 틈에서 조용한 거짓이 자란다. AI 하네스 얘기처럼 들리지만, 이건 모든 코드베이스가 앓는 병이다. 주석이, README가, 설정 문서가 실제와 어긋나는 그 병.
강제력을 잃지 않고 덜어낸다
통합의 목표는 단순 삭제가 아니었다. 규칙 문서는 어느새 1,200줄을 넘겨 신호가 잡음에 묻혀 있었지만, 규칙 한 줄 한 줄이 보안·정합성 불변식이라 함부로 지우면 강제력이 깨진다. 그래서 공식을 세웠다. 불변 규칙은 한 줄 요약으로 상시 문서에, 긴 예제 코드는 스킬의 참조 파일로, 도메인 전용 규칙은 그 위치에 중첩 문서로. 규칙은 하나도 빼지 않고 분량만 줄였다.
성장 압력도 손봤다. “교훈을 깨달으면 문서에 보강하라”는 기존 습관은 좋지만, 그대로 두면 방금 줄인 문서가 다시 비대해진다. 막는 대신 흘려보냈다. 보강 지침을 “무엇을 어디에 두는가” 배치 기준과 묶어, 새 교훈이 올바른 자리로 가게 했다. 좋은 습관을 끄는 게 아니라 라우팅하는 것이다.
마지막으로 빠져 있던 CI 게이트를 채워, 로컬 훅 → CI 게이트 → 배포의 3중 안전망을 닫았다. 이때 한 가지를 배웠다. 게이트를 켜기 전 “프론트에 타입 에러가 십수 개 있다”는 메모리를 믿고 정리부터 하려 했는데, 직접 돌려보니 전부 그린이었다. 메모리도 문서도 믿지 말고 baseline은 실측한다. 방금 본 그 드리프트가 메모리에도 끼어 있었던 것이다.
그래서
하네스를 점검하며 배운 건 AI에 관한 게 아니었다. 좋은 의도의 정리가 안전장치를 조용히 떼어낼 수 있다는 것, 변경과 그 변경을 가리키는 문서가 어긋나면 거짓이 쌓인다는 것, 그리고 기억과 문서는 틀리니 중요한 상태는 실측해야 한다는 것. 도구를 늘리는 일과 도구가 거짓말하지 않게 지키는 일은 다른 작업이고, 후자가 훨씬 어렵다. AI가 코드를 더 빨리 짤수록, 그 코드를 받는 하네스가 정직한지가 더 중요해진다.