하네스가 있으면 결과가 달라진다: 같은 모델을 다른 시스템으로 돌릴 때

같은 모델을 써도 결과가 다르게 나오는 순간이 있습니다. 한 세션에서는 그럴듯한 초안만 남기고 끝납니다. 다른 세션에서는 파일을 읽고 계획을 세웁니다. 수정하고 테스트한 뒤 배포 증거까지 남깁니다. 모델이 달라진 것이 아닙니다. 모델을 감싼 환경이 달라진 것입니다.

나는 이 차이를 하네스라고 부릅니다. 하네스는 에이전트가 작업을 시작하기 전에 읽어야 할 파일을 정합니다. 지켜야 할 금지선과 완료를 증명할 테스트도 정합니다. 실패했을 때의 재시도 규칙, 커밋과 배포 순서까지 묶은 외부 구조입니다. 모델의 지능을 대체하지는 않지만, 지능이 헛돌지 않게 붙잡습니다.

하네스가 없을 때 AI 작업은 대화 품질에 많이 의존합니다. 사용자가 잘 설명하면 잘하고, 설명이 빠지면 추측합니다. 하네스가 있으면 반복 설명의 일부가 시스템으로 내려갑니다. 같은 요청이 들어와도 에이전트는 먼저 규칙을 읽고, 완료 기준을 확인하고, 검증 없이 끝내지 못합니다.

핵심 정리

1. 01하네스는 모델의 내부 능력이 아니라 작업의 외부 조건을 설계하는 일입니다.
2. 02하네스가 없으면 결과는 프롬프트 품질과 세션 운에 흔들리고, 하네스가 있으면 읽기, 실행, 검증, 기록의 순서가 고정됩니다.
3. 03좋은 하네스는 에이전트에게 자유를 빼앗는 것이 아니라 실패 비용이 큰 지점에서만 강한 경계를 둡니다.
4. 04작은 팀에게 하네스는 사람을 더 뽑기 전, 같은 AI 사용 시간을 더 믿을 수 있게 만드는 레버입니다.

용어 정리

하네스

에이전트가 일하는 환경을 감싸는 규칙, 도구, 검증, 기록 구조입니다.

system

완료 기준

작업이 끝났다고 말할 수 있는 증거입니다. 빌드, 테스트, 스모크, 배포 로그가 여기에 들어갑니다.

DoD

가드레일

위험한 명령, 잘못된 파일 수정, 권한 없는 배포처럼 실패 비용이 큰 행동을 막는 경계입니다.

guardrail

증거물

모델의 말이 아니라 실제 실행 결과입니다. 로그, 스크린샷, URL, SQL 적용 결과처럼 재확인 가능한 자료를 뜻합니다.

evidence

하네스가 없을 때 생기는 흔한 결과

하네스 없는 AI 작업은 초반 속도가 빠릅니다. 사용자가 요구를 말하면 모델은 바로 답을 냅니다. 코드를 고치고, 글을 쓰고, 명령을 제안합니다. 작은 작업에서는 이 속도가 장점입니다. 다만 작업이 여러 파일, 여러 도구, 여러 검증 단계를 건드리기 시작하면 문제가 보입니다.

첫 번째 문제는 읽기 순서다. 모델이 어떤 파일을 먼저 봐야 하는지 모르기 때문에 가까운 파일이나 검색에 걸린 파일만 보고 판단합니다. 프로젝트의 실제 규칙은 CLAUDE.md와 ROADMAP.md에 흩어져 있습니다. docs/ADR과 기존 구현 패턴에도 남아 있다. 프롬프트에 안 적으면 놓치기 쉽습니다. 사용자는 나중에 "그건 이미 정해둔 건데"라고 말하게 됩니다.

두 번째 문제는 완료 선언입니다. 모델은 산출물을 만들면 끝났다고 느끼기 쉽습니다. 다만 사용자에게 필요한 것은 파일 생성이 아니라 작동하는 결과입니다. 빌드가 되는지, 타입이 맞는지, 라이브에서 보이는지, 예약 글이면 미래 날짜까지 숨겨지는지 확인해야 합니다. 하네스가 없으면 이 검증은 자주 생략됩니다.

세 번째 문제는 복구입니다. 긴 작업 중 실패가 나면 어디까지 진행됐는지 흐려집니다. 파일은 몇 개 바뀌었고, 어떤 명령은 성공했고, 어떤 것은 실패했는지 세션 대화 안에만 남습니다. 다음 세션이 이어받으려면 다시 읽고 추측해야 합니다. 결국 사람이 작업장을 정리하는 시간이 생깁니다.

하네스는 모델을 작게 만드는 대신 작업을 크게 만듭니다

하네스를 만들면 모델이 답답해질 것처럼 느껴질 수 있습니다. 실제로는 반대에 가깝다. 모델이 추측해야 할 부분을 줄이면, 더 큰 작업을 맡길 수 있습니다. "알아서 해줘"가 아니라 "이 경계 안에서 자유롭게 해줘"가 됩니다.

예를 들어 블로그 글 하나를 쓰는 작업도 하네스 전후가 다릅니다. 하네스가 없으면 제목과 본문이 한 대화 안에서 섞입니다. 이미지, 배포, D1 반영도 같은 흐름에 뒤엉킵니다. 중간에 이미지 경로가 틀리거나, raw markdown table이 남거나, 미래 글이 라이브에 새는 문제가 생길 수 있습니다. 하네스가 있으면 글 유형 판정과 필수 골격이 먼저 잡힙니다. 선택 컴포넌트와 이미지 생성이 뒤따릅니다. anti-AI verify, R2 업로드, D1 seed도 순서로 남습니다.

코드 작업도 마찬가지입니다. 하네스는 "수정해" 앞에 "무엇을 읽고, 무엇을 건드리지 말고, 어떤 테스트로 끝낼지"를 둡니다. 이 정보는 모델을 제한하는 것이 아니라 작업의 좌표를 줍니다. 좌표가 있으면 모델은 더 과감하게 움직일 수 있습니다. 모르는 경계 때문에 멈추는 시간이 줄어듭니다.

중요한 것은 하네스를 모든 일을 다 통제하는 관료제로 만들지 않는 것입니다. 작은 오탈자 수정에 10단계 절차가 필요하지는 않습니다. 하네스는 실패 비용과 반복 빈도가 높은 작업에 먼저 붙여야 합니다. 배포와 데이터베이스가 우선입니다. 고객 영향, 다중 파일 변경, 장기 예약 발행처럼 나중에 틀리면 비싼 작업도 먼저 붙여야 합니다.

결과 차이는 최종 품질보다 복구 가능성에서 먼저 보입니다

하네스의 효과는 항상 더 멋진 결과로 바로 보이지 않습니다. 오히려 처음에는 느려 보입니다. 파일을 더 읽고, 계획을 더 세우고, 명령을 더 돌리기 때문입니다. 다만 작업이 길어지면 차이는 복구 가능성에서 먼저 나타납니다. 중간에 실패해도 어디서 실패했는지 남습니다.

복구 가능성은 작은 팀에게 매우 중요합니다. 혼자 여러 일을 굴릴 때는 한 세션이 끝난 뒤 며칠 후 다시 이어받는 일이 많습니다. 하네스가 없으면 지난 대화의 분위기를 다시 떠올려야 합니다. 하네스가 있으면 상태 파일과 커밋이 남습니다. 체크리스트와 evidence artifact도 다음 세션의 출발점이 됩니다.

이 구조는 사람의 리뷰도 바꿉니다. "괜찮아 보이네"가 아니라 "DoD가 닫혔나"를 봅니다. 모델이 스스로 잘했다고 말하는지보다, 증거가 남아 있는지를 봅니다. 하네스는 AI를 믿기 위한 장치가 아니라, AI를 덜 믿어도 일을 진행할 수 있게 만드는 장치입니다.

물론 하네스도 실패합니다. 잘못된 완료 기준을 넣으면 엉뚱한 증거를 모읍니다. 너무 많은 규칙을 넣으면 모델이 중요한 일을 놓칩니다. 오래된 문서를 읽게 하면 과거의 결정을 현재로 가져옵니다. 이 때문에 하네스 자체도 관리 대상입니다. 작업이 끝난 뒤 무엇이 유효했고 무엇이 과했는지 갱신해야 합니다.

좋은 하네스는 팀의 일하는 방식을 남깁니다

하네스의 최종 가치는 자동화보다 지식 보존에 있습니다. 한 사람이 잘하던 작업 방식을 파일과 절차로 남기면, 다음 에이전트와 다음 사람이 같은 기준에서 출발합니다. 프롬프트 실력이 개인 머릿속에만 있지 않고 레포 안에 쌓입니다.

이 때문에 하네스 엔지니어링은 AI 시대의 운영 문서 작성에 가깝습니다. 단, 사람이 읽기 좋은 문서에서 끝나지 않습니다. 에이전트가 실제로 읽고, 명령으로 검증하고, 실패하면 멈출 수 있어야 합니다. 문서와 실행이 연결될 때 하네스가 됩니다.

같은 모델을 써도 어떤 팀은 결과물을 쌓고, 어떤 팀은 대화만 쌓습니다. 차이는 모델 선택보다 외부 구조에서 생깁니다. 하네스가 있다는 것은 AI에게 일을 맡기는 것이 아니라, 일이 끝났다고 말할 수 있는 조건을 먼저 만든다는 뜻입니다.