AI 하네스 구축 실전 - 클로드 코드를 무인으로 돌리는 법

하네스는 자동화가 아니다

하네스(harness)는 원래 배선 다발을 뜻하는 말이다. 엔진이나 계기를 새로 만드는 물건이 아니라, 이미 있는 부품들을 하나의 계통으로 묶어 전원과 신호가 흐르게 하는 배선이다. AI 하네스도 똑같다. 모델을 새로 만들지 않는다. 이미 갖고 있는 스케줄러와 스크립트와 규칙 문서를 모델 주위에 배선해서, 사람이 앉아 있지 않아도 판단이 흐르게 만드는 것이다.

자동화와 갈라지는 지점은 하나다. 자동화는 정해진 순서를 그대로 실행한다. 하네스는 그 순서 안에 판단이 필요한 칸을 만들고, 그 칸에서 모델을 부른다.

내 경우 순서는 이미 돌고 있었다. 매일 정해진 시각에 스크립트를 깨우는 통로는 진작 뚫려 있었고, 그 통로로 지나가는 것은 Node 스크립트뿐이었다. 그래서 판단이 필요한 일 - 원고 검수, 중복 대조, 수치 해석 - 은 전부 손에 남아 있었다. 없던 것은 자동화가 아니라 그 안에서 모델을 부르는 한 줄이었다.

부품부터 센다

구축을 시작할 때 제일 먼저 한 일은 코딩이 아니라 재고 조사였다. 세어 보니 새로 만들 것보다 이어 붙일 것이 훨씬 많았다.

다섯 칸 중 나에게 진짜로 없던 것은 계측 하나뿐이었다. 통로도 규칙도 검사 절차도 다 있었고, 서로 연결돼 있지 않았을 뿐이다. 하네스 구축이 대체로 신축이 아니라 배선 공사가 되는 이유가 여기 있다.

그러니 순서는 이렇다. 지금 자기 PC에서 사람 손 없이 도는 일이 무엇인지 먼저 센다. 하나도 없다면 거기부터가 1단계고, 하나라도 있다면 그 통로에 모델을 태우는 것이 1단계다.

핵심은 한 줄이다

구조를 아무리 그려도 실제로 하네스를 작동시키는 것은 스케줄러가 부르는 명령 한 줄이다. 나머지는 전부 이 줄의 앞뒤에 붙는다. 배치 파일이 아니라 PowerShell로 적은 이유는 다음 절 04번에 있다.

$json = & claude -p "/마감 채널 수치를 확인해 데이터 파일을 갱신하고 build.mjs를 실행한다" `
    --model haiku `
    --add-dir "<작업 폴더 밖에서 읽어야 할 경로>" `
    --allowedTools "Read,Edit,Write,Glob,Grep,Bash(node *)" `
    --output-format json

무인 실행에서 걸리는 함정 일곱

여기가 이 글에서 제일 쓸모 있는 대목이다. 아래 일곱 개는 전부 첫 주에 실제로 밟은 것들이고, 하나같이 화면을 보고 있었으면 30초 만에 알아챘을 종류다. 무인 실행에서는 그 30초가 없다.

# 이렇게 쓰면 BOM이 붙어 나중에 파싱이 깨진다
$json | Set-Content -Path $out -Encoding UTF8

# BOM 없이 쓴다
[IO.File]::WriteAllText($out, ($json -join "`n"), (New-Object Text.UTF8Encoding $false))

게이트 - 위험한 일은 코드가 한다

무인 발행은 되돌리기 어렵다. 그래서 원칙을 한 줄로 못 박고 시작했다. 위험한 동작은 코드가 하고, 판단은 모델이 한다.

내 발행 루프에서 모델이 하는 일은 원고를 쓰고, 검사 절차를 불러 지적을 받고, 그 지적을 고치는 데까지다. 목록 카드 추가, 색인 재생성, 업로드처럼 한 번 나가면 주워 담기 힘든 동작은 전부 스크립트가 한다. 모델은 그 스크립트를 부를 뿐이고, 스크립트는 조건이 맞지 않으면 실행을 거절한다.

불합격에 별도 코드를 준 것이 생각보다 중요했다. 이걸 실패와 같은 칸에 넣으면 게이트가 제 일을 한 날에도 알림이 사고처럼 울린다. 며칠이면 알림을 무시하게 되고, 그때부터 계기판은 장식이 된다.

계측 - 재지 않으면 하네스가 아니다

계측은 별도 공사가 아니었다. 결과를 JSON으로 받게 해 두면 비용과 토큰과 모델 내역이 딸려 나온다. 실행 스크립트가 그걸 한곳에 쌓고, 계기판이 그 파일을 읽는다.

{
  "date": "2026-08-11",
  "task": "dashboard",
  "exit": 0,
  "durationMs": 42597,
  "model": "claude-haiku-4-5",
  "tokens": { "in": 33, "out": 975, "cacheRead": 128128 },
  "costUsd": 0.0466
}

쌓아 놓고 보니 예상과 가장 어긋난 값은 캐시였다. 글을 쓰는 루프 한 번의 내역은 이랬다.

새로 보낸 입력은 761토큰인데 캐시에서 읽은 것은 203만 토큰이다. 세 자릿수와 일곱 자릿수의 차이다. 무인 루프의 비용은 내가 프롬프트에 적는 글자 수가 아니라, 그 루프가 매 턴 다시 읽는 문맥의 크기가 정한다는 뜻이다. 프롬프트를 짧게 다듬는 것보다 루프가 읽어야 하는 파일 수를 줄이는 편이 훨씬 크게 듣는다.

실측 비용 - 등급 하나로 4.4배

닷새간 남은 실행 기록 열한 건이다. 개인 작업 규모라 표본이 작지만, 자릿수를 잡는 데는 충분했다.

읽을 것 세 가지

첫째, 등급만 바꿨더니 평균 0.0489달러로 내려갔다. 첫 실행의 4.4분의 1이다. 수치를 세어 파일에 적고 빌드 명령을 부르는 일에는 상위 등급이 필요하지 않았다. 실행마다 읽는 양이 조금씩 달라 엄밀한 통제 비교는 아니지만, 자릿수가 바뀌는 차이라 방향은 분명하다.

둘째, 판단이 많은 루프는 자릿수 자체가 다르다. 글을 쓰는 루프는 대시보드 루프의 50배가 넘는다. 이건 낭비가 아니라 일의 크기다. 여기서 줄일 것은 비용이 아니라 이 루프를 부르는 횟수이고, 그래서 게이트가 앞에 선다.

셋째, 모델이 없는 루프도 하네스다. 표기를 세어 고치는 루프에는 모델을 넣지 않았다. 비용이 0이고, 대신 규칙을 코드로 남김없이 적어야 한다. 이름이 AI 하네스라고 해서 모든 칸에 모델을 넣을 이유는 없다.

3단계로 시작하기

넉 달치 설계도를 그리는 것보다 스케줄러에 파일 하나를 거는 편이 빠르다. 위의 함정 일곱 중 다섯은 어차피 첫 주에 다 만난다.

마무리

닷새를 굴려 보고 남은 결론은 좀 심심하다. 하네스에서 제일 중요한 부품은 모델이 아니라 게이트와 계측이었다. 게이트가 없으면 사고가 조용히 발행되고, 계측이 없으면 멈춘 줄도 모른다. 모델은 그 사이에서 판단을 맡는 칸 하나일 뿐이고, 그 칸의 등급을 한 번 바꾸는 것으로 비용은 4.4배가 갈렸다.

그리고 시작점은 생각보다 앞에 있다. 새 도구를 알아보기 전에, 지금 자기 PC에서 사람 손 없이 도는 일이 무엇인지부터 세어 보는 편이 빠르다. 통로가 이미 뚫려 있다면 남은 일은 그 통로에 한 줄을 태우는 것뿐이다.