지난 글까지 오면서 AI 에이전트에게 일을 시키는 이야기를 계속 했습니다. 그런데 3주쯤 지나니 문제가 옮겨갔습니다. 어떻게 시킬까가 아니라 틀렸을 때 어떻게 걸러낼까가 훨씬 어려웠습니다.
찾아보니 이 영역에 이미 이름이 있었습니다. 하네스 엔지니어링(harness engineering)입니다.
먼저 정확한 뜻부터 짚겠습니다. 하네스는 원래 마구·안전벨트를 뜻하지만, AI에서는 그보다 넓습니다. 클로드 코드를 만든 앤트로픽은 에이전트 SDK 문서에서 하네스를 모델을 호출하고 그 도구 요청을 실제 인프라로 연결해 주는 실행 루프로 설명합니다. 클로드 코드 자체가 하나의 하네스인 셈입니다. 우아한형제들 기술블로그는 팀 단위로 하네스를 구축한 사례에서 이를 “AI가 길을 잃지 않고 안정적으로 일하도록 외부 통제 환경을 구축하는 것”으로 정리하고, 그 구성으로 규칙(Rules)과 스킬(Skills)을 듭니다.
정리하면 하네스는 네 가지쯤을 포함합니다. 실행 루프 / 규칙 / 반복 작업용 스킬 / 검증 장치. 안전장치는 그중 하나일 뿐입니다.
제가 만든 건 넷 중 검증 장치 쪽에 치우쳐 있습니다. 설계를 잘해서가 아니라 사고가 거기서 났기 때문입니다. 개발자가 아닌 사람이 AI에게 일을 맡기면 어디서 터지는지, 그리고 그때마다 무엇을 만들게 되는지를 3주치 기록으로 적습니다.
하네스 엔지니어링으로 막게 된 사고 네 가지
지어낸 예시가 아니라 이 블로그를 만들면서 실제로 난 일들입니다.
하나. 페이지 하나가 통째로 지워졌습니다. 문의 페이지를 손보라고 시켰는데 내용이 전부 비워졌습니다. 미리 백업을 만들게 해 둔 덕에 몇 분 만에 되돌렸습니다.
가운데 있는 파일이 그때 저를 살린 백업입니다. 지금은 되돌릴 수 없는 작업 전에 항상 이 폴더에 원본이 먼저 저장됩니다.
둘. 같은 실수를 세 번 반복했습니다. 글의 특정 기준 하나가 계속 어긋난 채로 올라갔고, 세 번째에야 알아챘습니다. 그때 제가 더 조심하는 대신 검수 도구에 경고 항목을 추가하게 했습니다.
셋. 깨진 그림이 그대로 발행됐습니다. 다이어그램에서 상자들이 겹치고 연결선이 뭉개진 채로 공개돼 있었습니다. 검수 도구는 이미지가 몇 장인지, 설명 문구가 있는지는 봤지만 그림이 제대로 그려졌는지는 아무도 보지 않았습니다.
넷. 그리고 제일 무서웠던 것 — 안전장치가 꺼져 있었습니다. 이건 따로 적겠습니다.
에러가 안 나는 실패가 제일 무섭습니다
글의 구조를 강제하는 검사를 만들어 뒀습니다. 조건을 어기면 검수가 실패하고 업로드가 막히는 장치죠. 잘 돌아간다고 믿고 몇 주를 보냈습니다.
그런데 새 글을 만드는 절차서에 항목 하나가 빠져 있더군요. 그 항목이 없으면 글이 기본값으로 만들어지고, 기본값에서는 그 검사가 아예 적용되지 않습니다. 장치는 켜져 있는데 검사 대상이 하나도 없었던 셈입니다.
장치가 제대로 돌 때는 이렇게 걸립니다. 아래는 같은 검사가 실제로 글을 막아 세운 화면입니다.
맨 아래 붉은 표시가 “첫 소제목이 이론 정의라서 실패”입니다. 이 한 줄이 떠야 정상인데, 그동안은 이 줄 자체가 아예 안 나오고 있었습니다.
에러도 경고도 없었습니다. 화면에는 늘 “통과”만 떴습니다. 뭔가 잘못됐다는 신호가 어디에도 없었기 때문에, 찾으려고 뒤지기 전까지는 알 방법이 없었습니다. 한 번 점검해 보니 같은 종류의 어긋남이 다섯 군데서 나왔습니다. 글감 목록을 만드는 설정도 그중 하나였는데, 제가 가장 많이 써 온 주제를 구조적으로 추천할 수 없는 상태였습니다. 발행한 글의 절반이 그 주제인데도 그랬습니다.
실패가 시끄러우면 고치면 됩니다. 조용한 실패는 있는지조차 모릅니다. 3주 동안 배운 것 중 이게 제일 컸습니다.
이 조용한 실패가 어떤 모양으로 오는지는 따로 일주일을 기록해 봤습니다. 다섯 건 전부 에러 없이 그럴듯한 숫자로 왔죠 — 할루시네이션은 에러로 오지 않습니다에 정리했습니다.
사람을 고치지 말고 장치를 고칩니다
사고가 날 때마다 제 반응은 처음엔 “다음엔 조심해야지”였습니다. 그런데 같은 실수가 세 번 반복되니 생각이 바뀌더군요. 세 번 틀렸다는 건 주의력 문제가 아니라 틀릴 수 있게 열려 있다는 뜻이었습니다.
그래서 규칙을 하나 세웠습니다. 반복된 실수는 검사 항목으로 승격시킨다. 지금 돌아가는 장치들은 전부 그렇게 생겼죠.
- 되돌릴 수 없는 작업 전에는 원본을 먼저 백업한다. 백업에 실패하면 작업 자체를 중단한다
- 이미 공개된 글을 고칠 때는 발행 상태를 건드리지 않는다
- 그림은 상자가 겹치거나 글자가 밀려나면 파일로 저장조차 하지 않는다
- 작업을 마칠 때마다 장치가 실제로 살아 있는지 점검한다
마지막 항목이 앞의 세 개보다 중요합니다. 장치를 만드는 것보다 장치가 켜져 있는지 확인하는 절차가 없어서 사고가 났기 때문입니다.
지금은 검사가 63개까지 늘었고, 한 번 도는 데 1초 남짓입니다. 사고가 날 때마다 하나씩 붙인 결과입니다.
앞에서 하네스 엔지니어링이 네 가지를 포함한다고 했는데, 이 목록을 만들다 보니 나머지 셋도 자연스럽게 따라왔습니다. 반복 절차는 스킬로 묶었고(검수, 글감 선정, 마무리 점검), 지켜야 할 원칙은 프로젝트 규칙 파일 하나에 모았습니다. 처음부터 “하네스를 설계하자”고 시작한 게 아니라, 사고를 막으려고 하나씩 붙이다 보니 그 모양이 됐습니다. 순서가 거꾸로였던 셈인데, 개발자가 아닌 입장에서는 이 순서가 오히려 현실적이었습니다.
자동 검사와 사람 눈은 서로를 못 대신합니다
깨진 그림 사고 뒤에 검사 도구를 만들었더니, 반대 방향 사례가 바로 나왔습니다.
제가 눈으로 보고 “이 그래프는 글자가 잘렸다”고 판단한 그림이 있었습니다. 검사를 돌려 보니 정상이었습니다. 저장할 때 여백을 자동으로 넓혀 담는 설정 때문에 실제로는 안 잘렸던 겁니다. 제 눈이 틀렸고 도구가 맞았습니다.
반대로 검사를 통과한 그림이 답답하거나 뜻이 안 통하는 건 도구가 절대 못 잡습니다. 그래서 지금은 둘 다 씁니다. 도구는 겹침·잘림 같은 기하학적 파손을 잡고, 사람은 “이게 말이 되나”를 봅니다. 어느 한쪽만 믿으면 그쪽이 못 보는 종류의 사고가 그대로 나갑니다.
7일 뒤 — 하네스 엔지니어링이 실제로 뭘 막았나
이 글을 쓴 뒤 일주일을 더 굴렸습니다. 장치가 정말 일했는지 숫자로 남겨둡니다.
늘어난 것
| 항목 | 7/22 | 7/29 |
|---|---|---|
| 자동 검사(테스트) | 66개 | 92개 |
| 코드 커버리지 | 측정 안 함 | 62% |
| 검수 게이트 | 23개 | 23개 |
커버리지를 처음 재본 게 가장 컸습니다. 테스트가 66개나 있으니 괜찮은 줄 알았는데, 재보니 7개 모듈은 테스트가 한 번도 안 건드리고 있었습니다. 그중 하나가 업로드 흐름 전체를 조율하는 진입점이었죠. “테스트가 있다”와 “무엇을 덮는지 안다”는 다른 얘기였습니다.
실제로 걸린 것들
일주일 동안 장치가 잡아낸 것 중 기억에 남는 세 가지입니다.
함수가 반환값 개수를 거짓말하고 있었습니다. 값을 두 개 준다고 선언해놓고 실제로는 세 개를 주고 있었습니다. 테스트 66개가 전부 통과했고, 제가 그 함수를 직접 고치면서도 못 봤습니다. 타입 검사기를 붙이고 나서야 나왔죠.
검사기 하나가 통과 불가능한 조건을 걸고 있었습니다. 리포트 50개를 세어보니 같은 경고가 51번 떴더군요. 원인은 글이 아니라 검사였습니다. 한글 키워드는 영문 주소에 들어갈 수가 없는데 그걸 검사하고 있었습니다. 매번 뜨는 경고는 경고가 아니라 소음이고, 소음은 진짜 경고를 덮습니다.
되돌릴 수 없는 작업 직전에 두 번 멈췄습니다. 한 번은 사이트 이미지를 지우려다 그중 넷이 파비콘이라는 걸 발견했고, 한 번은 라이브 글의 그림이 사라질 뻔한 걸 가드가 막았습니다.
배운 것 하나 — 게이트를 일부러 부숴봐야 합니다
테스트가 통과한다고 그 테스트가 뭔가를 지킨다는 뜻은 아닙니다. 그래서 개인정보 차단 코드를 일부러 무력화해봤습니다.
차단 코드 무력화 → 해당 테스트가 정확히 실패 ✅
원래대로 복구 → 다시 통과 ✅
이때서야 그게 진짜 장치라는 걸 알았습니다. 통과만 보고 있었으면 껍데기여도 몰랐겠죠. 위에서 “가끔 장치가 살아 있는지 확인하라”고 썼는데, 확인하는 방법이 바로 이겁니다.
코드를 모르는 사람에게도 그대로 옮겨갑니다
여기까지가 블로그 이야기지만, 구조는 도구와 상관없습니다. 앤트로픽도 에이전트 설계 문서에서 자율성을 늘릴수록 검증과 안전장치를 같이 늘려야 한다고 씁니다. 규모만 다르지 방향은 같습니다.
AI에게 반복 업무를 맡길 생각이라면, 거창한 준비 없이 하네스 엔지니어링을 시작하는 순서는 이렇습니다.
- 되돌릴 수 있게 만들어 놓고 시작하세요. 백업 없이 맡기는 건 맡기는 게 아니라 거는 겁니다.
- 무엇이 되면 실패인지를 먼저 문장으로 적으세요. 성공 조건보다 실패 조건이 검사로 만들기 쉽습니다.
- 같은 실수가 두 번 나오면 그때 장치로 만드세요. 처음부터 다 막으려 들면 아무것도 못 합니다.
- 가끔 장치가 살아 있는지 확인하세요. 이게 빠지면 나머지 셋이 조용히 무력해집니다.
3주 전의 저는 AI에게 무엇을 시킬지 고민했습니다. 지금은 AI가 틀렸을 때 어디서 걸릴지를 설계합니다. 하네스 엔지니어링이라는 말을 몰랐어도 결국 하게 됐을 일입니다. 이 블로그를 만들기 시작했을 때와 비교하면 그게 제일 크게 바뀐 부분입니다.
다음 글에서는 이 네 가지 중 규칙 쪽을 자세히 다룹니다. 매번 말로 지시하던 것을 파일로 옮긴 기록인데, 프롬프트 엔지니어링을 7일 해 본 결과로 정리했습니다.
