하네스(Harness)를 초기에 적용하지 못한 것

신진형 · 에스엘파워 · 2026.06.17

처음엔 “좋은 AI 모델을 쓰면 다 되겠지”라고 생각했습니다. 한 달쯤 지나서야 깨달았습니다 — 결과를 결정하는 건 모델이 아니라, 그 모델을 감싸는 하네스였다는 것을요. 더 뼈아픈 건, 이게 처음 30분이면 깔 수 있는 장치였다는 사실입니다. 이 글은 “하네스가 대체 뭔지”, “왜 그게 모델보다 중요한지”, 그리고 “없이 시작하면 어떤 대가를 치르는지”를 처음부터 풀어 쓴 기록입니다.

하네스란 무엇인가 — 말과 마구

AI 에이전트를 분해해 보면 딱 두 부분입니다. 하나는 모델 — 제가 만든 게 아니고, 제가 바꿀 수도 없는, 그냥 호출해서 쓰는 AI입니다. 다른 하나는 그 모델을 둘러싼 나머지 전부 — 규칙 문서, 도구, 가드레일, 검사 스크립트, 피드백 루프입니다. 이 “모델을 제외한 전부”를 통틀어 **하네스(Harness)**라고 부릅니다.

비유하자면 모델은 경주마입니다. 빠르고 힘이 셉니다. 하지만 안장도 고삐도 없이 들판에 풀어놓으면, 그 힘은 아무 데로나 흩어집니다. 마구를 채워야 비로소 그 힘이 “내가 가려는 방향”으로 모입니다. 핵심 명제는 이 한 줄로 요약됩니다.

보통 AI + 좋은 하네스 > 좋은 AI + 나쁜 하네스

이 명제가 왜 중요하냐면, 둘 중 제가 통제할 수 있는 건 하네스 하나뿐이기 때문입니다. 모델은 제가 만들지 않습니다. 매달 알아서 좋아지긴 하지만, 그건 제가 기다려야 얻는 공짜 선물이지 제 노력으로 당기는 변수가 아닙니다. 반대로 하네스는 100% 제 손에 달려 있습니다. 그러니 “생산성을 올리고 싶다”는 욕구는 곧 “하네스를 갈아야 한다”는 결론으로 이어집니다. 모델을 기다리지 말고 마구를 손봐야 합니다. 저는 이 단순한 사실을 너무 늦게 알았습니다.

에이전트는 모델 + 하네스입니다(개념도). 모델은 못 바꾸지만 하네스는 전부 내 손에 있습니다. 같은 모델이라도 마구가 다르면 결과가 다릅니다.

하네스 없이 시작한 첫 달

2026년 4월, 모노레포를 세팅하고 곧장 기능을 찍어내기 시작했습니다. AI에게 “이거 만들어줘”라고 하면 코드가 나왔습니다. 빨라 보였습니다. 그런데 결과물의 품질이 들쭉날쭉했습니다. 어떤 세션은 테스트 없이 코드를 쏟아냈고, 어떤 세션은 이미 레포 안에 있는 유틸을 또 만들었고, 어떤 세션은 거대한 파일에 계속 코드를 덧붙였습니다. 같은 모델, 같은 프로젝트인데 결과의 편차가 컸습니다.

문제는 AI가 게을러서가 아니었습니다. 지켜야 할 규칙도, 그 규칙을 강제하는 장치도 없었기 때문입니다. 사람으로 이뤄진 팀이라면 코드리뷰·CI 파이프라인·컨벤션 문서가 그 역할을 묵묵히 합니다. 신입이 와도 그 안전망이 받쳐줍니다. AI 협업에는 그게 더더욱 절실한데, 저는 그걸 통째로 비워둔 채 한 달을 달렸습니다.

하네스는 두 종류의 장치다 — 가이드와 센서

5월에 들어서야 방법론을 갈아엎었습니다. 하네스를 두 종류로 나눠서 깔았습니다. 행동 전에 거는 것과, 행동 후에 거는 것입니다.

구분	거는 시점	역할	예시
가이드(Guides)	행동 전	”이렇게 해라 / 하지 마라”를 작업 시작 전에 읽힌다	프로젝트 규칙 문서, 코딩 컨벤션, 도메인 불변식, 위임 절차
센서(Sensors)	행동 후	”정말 됐는지”를 기계가 자동으로 확인한다	단위 테스트, 린터, 빌드, 완료 검증 게이트

비유하면 가이드는 운전 전에 외우는 교통법규이고, 센서는 도로에 박힌 과속 카메라입니다. 둘 다 있어야 합니다. 법규만 있고 카메라가 없으면 아무도 안 지키고, 카메라만 있고 법규가 없으면 무엇을 단속하는지 모릅니다. 그런데 여기서 가장 중요한 깨달음이 하나 더 있었습니다.

규칙은 문서로만 두면 안 지켜진다.

AI는 규칙 문서를 안 읽거나, 읽고도 다음 단계에서 잊습니다. 사람도 마찬가지입니다. 그래서 규칙을 단순한 “권고”로 두지 않고, 커밋 직전·파일 작성 직전에 끼어드는 검사 스크립트(훅)로 기술적으로 강제했습니다. 규칙을 어긴 작업은 아예 진행이 막히도록 말입니다. 예를 들어 “테스트 없이 핵심 코드를 쓰면 차단”, “거대 파일을 더 키우면 차단” 같은 식입니다. 이 강제집행의 구체적 작동 방식은 별도의 글에서 본격적으로 다룹니다.

어떻게 흘러갔나 — 하네스를 깐 순서

하네스는 한 번에 완성한 게 아닙니다. “이런 실패가 반복되네?” 하고 깨달을 때마다 거기에 맞는 장치를 하나씩 덧댔습니다. 실제 흐름을 단계로 펼치면 이렇습니다.

규칙 문서화 — 프로젝트 컨벤션·도메인 불변식·금지 사항을 문서로 적었습니다. AI가 매 세션 자동으로 읽도록 걸었습니다. (가이드의 시작)
“문서는 안 지켜진다” 자각 — 규칙을 적어둬도 AI가 건너뛰는 걸 보고, 권고로는 부족하다는 걸 인정했습니다.
센서 추가 — 테스트·린트·빌드 검사를 자동화해, 작업 후 기계가 통과 여부를 판정하게 했습니다.
강제 게이트(훅) 설치 — 규칙 위반 시 그 자리에서 차단하는 훅을 커밋·파일작성 직전에 끼웠습니다. 규칙이 비로소 “살아 움직이는 규칙”이 됐습니다.
구멍이 보일 때마다 보강 — 같은 실수가 반복되면 “하네스에 구멍이 있다”는 신호로 받아들이고, 그 자리에 새 센서를 댔습니다. 작업 크기에 따라 절차를 차등 적용하는 장치까지 추가됐습니다.

같은 모델, 다른 하네스 — 무엇이 달라지나

하네스가 결과를 가른다는 말이 추상적으로 들린다면, 같은 요청을 하네스 유무에 따라 비교해 보면 또렷해집니다. “어떤 업무 검증 로직을 추가해줘”라는 똑같은 지시를, 똑같은 모델에게 던졌을 때입니다.

하네스 없이	하네스와 함께
AI가 곧장 코드를 쏟아낸다. 테스트는 없다. 이미 레포에 있는 비슷한 유틸을 모르고 새로 짠다. 거대 파일에 또 한 덩어리를 덧붙인다. 그럴듯해 보이지만, 검증되지 않았고 중복이며 파일은 더 부풀었다.	먼저 “이미 있는지” 탐색하고(탐색 우선), 실패 테스트부터 쓰고(TDD 게이트), 파일이 한도를 넘으면 차단당해 나눈다(크기 게이트). 같은 모델인데, 마구가 행동의 순서와 하한선을 강제한다.

차이를 만든 건 모델의 IQ가 아닙니다. 모델을 둘러싼 장치입니다. 그래서 “더 좋은 모델이 나오면 해결되겠지”라는 기대는 절반만 맞습니다. 모델이 좋아지면 코드의 품질은 오르지만, 테스트 누락·중복·파일 비대화 같은 구조적 실패는 하네스가 없으면 좋은 모델에서도 똑같이 — 더 빠른 속도로 — 일어납니다.

늦게 깐 대가, 그리고 처음부터 했어야 할 일

첫 달의 혼란 — 들쭉날쭉한 품질, 중복 구현, 비대해지는 파일 — 은 대부분 하네스의 부재에서 왔습니다. 이 모든 걸 막을 최소 장치는 프로젝트 첫날 30분이면 세팅할 수 있는 규칙 몇 개였습니다. 파일 크기 한도 하나, “테스트 먼저” 규칙 하나, 이미 있는 걸 다시 짜지 말라는 탐색 우선 규칙 하나. 이 세 가지만 처음부터 강제했어도 나중에 들인 정리 비용의 상당 부분을 아꼈을 것입니다.

“나중에 규칙 만들면 되지”라는 생각이 정확히 그 비용을 만들었습니다. 그리고 그 “나중”은 항상 더 비싼 모습으로 — 이미 망가진 코드를 되돌리는 형태로 — 찾아왔습니다.

이 글은 SL.AIMS를 만들며 겪은 현장 회고 중 하나입니다. 전체 그림은 〈사례연구: SL.AIMS〉에, 하네스가 실제로 루프를 닫는 법은 〈루프를 닫다〉에, 그 위에 올린 역할별 에이전트 팀은 〈에이전트 팀을 늦게 만든 것〉에 있습니다.