AI 에이전트에게 일 맡겨봤더니 제대로 작동하게 만드는 건 지시 구조였어요

ChatGPT든 Claude든 AI 에이전트를 써보신 적 있으신가요? 처음엔 잘 따라오는 것 같다가, 어느 순간 엉뚱한 결과를 내놓거나 예전에 이미 고친 실수를 다시 반복하는 경험 있으시죠? 프롬프트를 아무리 정교하게 써도 해결되지 않는 문제예요. 바로 이 지점에서 필요한 게 **하네스 엔지니어링(Harness Engineering)**입니다.

하네스 엔지니어링이란 무엇인가요?

하네스(Harness)는 원래 말(馬)에 장착하는 마구를 뜻합니다. 말의 힘을 안전하게 제어하고, 원하는 방향으로 이끌기 위한 도구죠. 말이 아무리 빠르고 힘이 세도, 마구 없이 벌판에 풀어 놓으면 어떻게 될까요? 밭을 갈아야 하는데 갑자기 옆집 논으로 달려가거나, 마차를 끌어야 하는데 갑자기 멈춰버리죠. AI 에이전트도 똑같습니다. GPT든 Claude든 모델 자체는 이미 충분히 강력한데, 그냥 풀어 놓으면 같은 실수를 열 번씩 반복하거나 아키텍처를 무시하고 엉뚱한 방향으로 가버립니다.

에이전트가 올바르게 행동할 수밖에 없는 환경을 설계하는 기술입니다. 말 위에 안장을 얹는 것처럼, AI의 힘을 원하는 방향으로 이끄는 구조예요. 구글 딥마인드 엔지니어 필립 슈미드는 이렇게 비유했습니다. "모델은 CPU고, 하네스는 운영 체제다." 아무리 좋은 CPU도 운영 체제가 나쁘면 제대로 돌아가지 않듯, AI 모델이 아무리 뛰어나도 하네스가 부실하면 쓸 만한 결과물을 만들어낼 수 없습니다(유튜브).

HashiCorp 공동창립자 Mitchell Hashimoto가 2026년 2월 초 블로그에서 하네스 엔지니어링을 이렇게 정의했습니다: "에이전트가 실수할 때마다, 그 실수가 다시는 발생하지 않도록 엔지니어링하는 것." 프롬프트를 잘 쓰는 게 아니라, 에이전트가 실행되는 환경 자체를 설계하는 거죠.

프롬프트만 잘 쓰면 되지 않나요?

그렇지 않아요. 워크플로우를 아무리 잘 만들어도, 프롬프트를 아무리 정교하게 써도, 에이전트가 "그냥 무시"하는 경우가 생깁니다. 프롬프트는 결국 자연어입니다. 자연어로 된 지시는 강제력이 없습니다.

이메일로 비유하면 이렇습니다. 프롬프트 엔지니어링은 완벽한 이메일 한 통을 쓰는 기술이고, 컨텍스트 엔지니어링은 그 이메일에 필요한 첨부 파일을 전부 붙여주는 기술입니다. 하네스 엔지니어링은 한 발 더 나아가 그 사람이 일하는 사무실 전체를 설계하는 거예요. 책상 배치, 업무 규칙, 보고 체계, 실수했을 때 교정 프로세스까지 모두 포함합니다.

2023~2024년은 프롬프트 엔지니어링의 전성기, 2025년 중반에는 컨텍스트 엔지니어링이 부상했고, 2026년 2월에는 전체 환경 설계로 범위가 확장된 하네스 엔지니어링이 등장했습니다.

프롬프트는 한 번의 입력이고, 컨텍스트는 한 세션의 배경이고, 하네스는 영구적인 시스템입니다. 점점 더 지속적이고 구조적인 방향으로 가고 있는 거예요.

1인 사업자가 AI 에이전트를 쓸 때 왜 필요할까요?

혼자 일하면서 AI한테 콘텐츠 작성, 이메일 회신, 마케팅 초안 같은 업무를 맡겨본 적 있으시죠? 그런데 가끔 이런 문제가 생겨요.

• 똑같은 실수를 계속 반복함 (예: 출처 없이 숫자를 막 쓰거나, 과장된 표현 남발)
• 장시간 업무를 맡겼더니 중간에 엉뚱한 방향으로 빠짐
• 팀 컨벤션이나 브랜드 톤을 자꾸 무시함

이럴 때 하네스 엔지니어링이 필요합니다. 1인 창작자가 팀 수준의 생산성을 낼 수 있는 방법이기 때문입니다. 주제 선정, 최종 확인만 사람이 하고 나머지는 AI가 자율적으로 처리하게 만들 수 있거든요.

실제로 숏폼 콘텐츠 제작 파이프라인 사례에서는 주제 하나를 입력하면 약 30~40분 만에 자막까지 포함된 숏폼 영상이 완성됩니다.

실무에서는 어떻게 사용하나요?

이런 기술은 대기업만의 전유물이 아닙니다. 개인 작업자도 당장 적용할 수 있는 3단계 레벨을 소개합니다.

1. 🟢 Level 1: 규칙 파일 하나로 시작 (30분이면 충분)

Claude Code, Cursor, Windsurf 등 대부분의 AI 에이전트는 프로젝트 루트에 AGENTS.md(또는 CLAUDE.md) 파일이 있으면 매 작업마다 자동으로 읽습니다. 여기에 절대 금지(Non-Negotiable) 규칙을 적어두는 것이 하네스의 출발점입니다.

예를 들면 이런 식이에요.

## 규칙 (절대 지킬 것)
- 통계·숫자에는 반드시 출처 붙이기
- "무조건", "최고", "필수" 같은 과장 표현 금지
- 확실하지 않은 내용은 "~일 수 있습니다"로 표현
- 파일 삭제·덮어쓰기 전 반드시 사용자 확인
- 코드 수정 시 테스트 통과 여부 보고 필수

이 파일이 있으면 매번 프롬프트에 "출처 붙여줘", "과장하지 마"라고 반복 입력하지 않아도 됩니다. 규칙이 시스템 수준으로 고정되기 때문이에요. 콘텐츠 작업이라면 브랜드 톤 가이드, 코딩 작업이라면 코드 스타일과 금지 패턴을 적어두면 됩니다.

2. 🟡 Level 2: 생성자·검증자 분리 (1~2일)

같은 AI라도 역할을 나누면 품질이 올라갑니다. 한 대화창은 생성자(Generator) — 초안 작성에만 집중하고, 다른 대화창은 평가자(Evaluator) — 논리적 허점·사실 오류·톤 이탈을 찾는 역할로 나누는 거예요.

실제 운영 방식은 이렇습니다.

1. 생성자 창: AGENTS.md 규칙 + 작업 요청 (예: "뉴스레터 초안 써줘")
2. 평가자 창: 초안 붙여넣기 + "이 글의 사실 오류, 과장 표현, 구조 허점을 찾아줘"
3. 평가자 피드백을 생성자 창에 넣고 수정

사람이 개입하는 단계는 주제 선정과 최종 확인뿐, 나머지는 AI끼리 돌아가는 구조입니다. Stripe처럼 실제로 이 방식을 도입한 팀들은 매주 수백~수천 건의 작업을 이 루프로 처리하고 있어요.

3. 🔴 Level 3: 자동화 파이프라인 전체에 적용 (1~2주, 고급)

에이전트가 사람 없이 장시간 돌아가는 시스템이라면, 어디서 무슨 이유로 실패했는지 추적할 수 없으면 운영이 불가능합니다. 이 단계는 세 가지를 동시에 구축합니다.

① 로그 관찰성(Observability)

에이전트가 어떤 도구를 몇 번 호출했는지, 각 단계에 얼마나 걸렸는지, 어디서 멈췄는지를 전부 기록합니다. LangSmith, Langfuse 같은 도구를 쓰면 에이전트 실행 트레이스를 시각적으로 볼 수 있어요. "왜 이 결과가 나왔지?"를 나중에 재현할 수 있는 구조입니다.

② 입출력 미들웨어

에이전트와 도구 사이에 검증 레이어를 끼워 넣습니다. 입력 쪽에서는 허용된 도구·명령만 통과시키는 허용 목록(allowlist)을 두고, 출력 쪽에서는 형식 검사·할루시네이션 감지·길이 제한 등을 자동으로 걸러냅니다. API 게이트웨이처럼 에이전트 앞뒤로 얇은 레이어를 하나씩 쌓는 방식이에요.

③ 골든 테스트 세트

"이 입력을 주면 반드시 이 형태의 출력이 나와야 한다"는 기준 케이스를 20~50개 만들어 CI에 등록합니다. 모델이 바뀌거나 프롬프트를 수정해도, 기존에 잘 되던 케이스가 깨지면 자동으로 감지됩니다. LangChain이 Terminal Bench에서 모델 교체 없이 하네스만 개선해 30위권에서 5위권으로 올라간 것도 이 방식의 결과입니다.

1인 사업자라면 Level 1~2만으로도 충분합니다. Level 3은 에이전트가 하루 수백 건 이상 자율 실행되는 팀에 적합한 단계이고, 과도하게 적용하면 오히려 속도를 떨어뜨립니다.

실제로 어디서 쓰이나요?

2026년 2월, OpenAI Codex 팀은 엔지니어 3명이 5개월간 코드를 단 한 줄도 직접 타이핑하지 않고, 약 100만 줄 규모의 프로덕션 애플리케이션을 만들어냈습니다. 1,500개의 PR을 머지하면서 엔지니어 1인당 하루 평균 3.5개의 PR을 처리했고, 수작업 대비 약 10분의 1 시간에 완성했다고 밝혔습니다(openai.com).

LangChain은 코딩 에이전트 벤치마크 Terminal Bench 2.0에서 모델을 바꾸지 않고 하네스만 개선해 30위권에서 5위권으로 25단계를 뛰어올렸습니다(wikidocs.net).

Stripe의 개발자가 Slack에 "이 기능 만들어줘"라고 남기면, AI(Minions)가 알아서 코드를 짜고, 테스트를 통과시키고, 코드 리뷰 요청(PR)까지 올려 매주 1,000건 이상을 처리한다고 합니다(mindstudio.ai).

개발자가 아니어도 괜찮아요. 코드 대신 자연어로 AI의 행동을 정의하고, 여러 AI 에이전트가 협업하는 시스템을 구축할 수 있습니다. 프롬프트 엔지니어링이 "AI에게 잘 물어보는 법"이라면, 하네스 엔지니어링은 "AI가 자율적으로 일하는 시스템을 설계하는 법"입니다.

실수를 막는 3가지 핵심 요소

AI 에이전트 개발 과정에서 하네스를 실제로 구축하려면 공통으로 등장하는 핵심 구성 요소는 3가지입니다.

(1) 가드레일 (Guardrail): 경계선 긋기

가드레일이란, AI 에이전트의 입력과 출력 양쪽을 기술적으로 제어하여 설계된 목적 범위 밖의 동작을 사전에 차단하는 구조입니다. 가드레일이 없으면 에이전트는 사실과 다른 정보를 그럴듯하게 생성하는 할루시네이션이 발생할 수 있으며, 이는 서비스 품질 저하나 보안 사고로 직결됩니다.

예: "금지 명령어 리스트 만들어서 자동 차단", "출력 형식 검증기 추가"

(2) 피드백 루프: 실수하면 바로 고치기

하네스 엔지니어링은 짧은 실행 과정에서 자동으로 오류를 복구하여, 큰 방향에서 멀어지지 않고 긴 호흡의 태스크를 완료할 수 있게 해줍니다. 린터가 코드 스타일 위반을 잡아서 에이전트가 즉시 수정하고, CI가 테스트 실패를 알려서 에이전트가 자동으로 고치고, 구조적 테스트가 아키텍처 위반을 감지해서 되돌리게 하는 방식입니다.

예: "맞춤법 검사 후 자동 수정", "생성된 글이 출처 없으면 다시 쓰기"

(3) 지식 저장소: 기억 쌓기

에이전트 입장에서는 컨텍스트에서 접근 가능한 것만 존재합니다. Google Docs, 채팅 스레드, 사람 머릿속 지식은 시스템이 접근할 수 없습니다. 저장소 로컬의 버전 관리된 산출물(코드, 마크다운, 스키마, 실행 계획)만 AI가 볼 수 있습니다.

AGENTS.md를 백과사전처럼 쓰지 말고 목차로 쓰세요. 저장소의 지식 베이스는 구조화된 docs/ 디렉토리에 기록의 시스템으로 두고, 짧은 AGENTS.md(약 100줄)는 컨텍스트에 주입되어 주로 더 깊은 진실 출처로의 포인터 역할을 합니다.

예: 팀 규칙, 과거 실수 기록, 브랜드 톤 가이드를 문서로 정리해두기

(4) 엔트로피 관리: 작업 환경을 깨끗하게 유지하기

에이전트가 코드나 문서를 많이 생성할수록 작업 환경에 서서히 무질서가 쌓입니다. 문서와 코드가 안 맞고, 비슷한 기능의 중복 코드가 계속 생기고, 쓰지 않는 파일이 늘어나죠. 이를 방치하면 에이전트가 참고하는 기준 자체가 엉망이 되면서 작업 품질이 계속 떨어집니다.

그래서 하네스 엔지니어링에서는 정리 전담 에이전트를 주기적으로 돌립니다. 문서가 코드와 일치하는지 체크하는 에이전트, 아키텍처 규칙 위반을 찾는 에이전트처럼요. 마치 사무실 청소 담당자처럼, 에이전트가 일하는 환경을 지속적으로 깨끗하게 유지하는 역할입니다.

예: 주간 정리 에이전트 실행, 오래된 규칙 파일 정리, 사용하지 않는 파일 탐지

주의할 점은 없나요?

현실적으로 조심할 게 있습니다. OpenAI Codex 팀도 처음엔 하나의 거대한 AGENTS.md에 모든 규칙·설명·주의사항을 빼곡하게 넣었다가 완전히 실패했습니다. 이유는 세 가지였어요. 거대한 지시 파일이 실제 코드와 작업 내용을 밀어냈고, 에이전트가 의도적으로 탐색하는 대신 대충 패턴만 매칭하게 됐고, 아무도 관리하지 않으면서 옛날 규칙과 새 규칙이 뒤섞여 버렸습니다. OpenAI가 내린 결론은 **"1,000페이지의 매뉴얼이 아니라 지도를 줘라"**였습니다. 모든 규칙을 다 담는 대신, 필요한 문서의 위치만 알려주는 거죠(유튜브).

하네스를 과하게 쌓으면 오히려 역효과가 납니다. 규칙이 서로 충돌하고, 컨텍스트가 비대해지고, 에이전트가 뭘 따라야 할지 헷갈려하거든요. "최소한의 규칙으로 최대 효과"가 하네스 엔지니어링의 진짜 기술입니다. 에이전트를 과도하게 통제하려는 오버 엔지니어링이 가장 흔한 실패 요인입니다.

Mitchell Hashimoto는 완벽한 시스템을 처음부터 설계하려 하지 말라고 조언합니다. 대신 매주 금요일 20분만 투자해서 그 주에 에이전트가 실수한 것 하나를 골라 하네스에 반영하는 습관을 권합니다. 시간이 갈수록 에이전트가 점점 나아지는 구조가 만들어지거든요(유튜브).

AI를 믿지 못하겠다고 규칙을 100개씩 만들면 오히려 더 헷갈려해요. 자주 틀리는 것 3~5개만 막으세요.

하네스 엔지니어링은 AI에게 "착하게 행동해"라고 부탁하는 게 아니라, 잘못된 행동을 구조적으로 할 수 없게 만드는 설계예요. 프롬프트를 100번 고치는 시간에, 30분 투자해서 규칙 파일 하나 만들어보세요. 그게 진짜 AI 활용의 시작입니다.

자주 묻는 질문 (FAQ)

Q. 비개발자도 하네스 엔지니어링을 적용할 수 있나요?

A. 네. AI 도구를 사용할 때 작업 지침 문서를 만들고, 결과를 체크리스트로 검증하고, 작업 이력을 기록하는 것 자체가 하네스의 기본 원리입니다. 코딩 없이도 시작할 수 있습니다.

Q. 어떤 AI 도구에 적용할 수 있나요?

A. Claude Code, Cursor, Windsurf, GitHub Copilot 등 대부분의 AI 코딩 에이전트에 적용 가능합니다. 개념 자체는 도구에 종속되지 않으므로, 비코딩 AI 워크플로우에도 응용할 수 있습니다.

Q. 하네스는 어디에 만드나요?

A. 간단한 방법은 프로젝트 루트 폴더에 AGENTS.md 파일을 만들고, "금지 규칙", "출처 표기 규칙", "톤 가이드" 등을 마크다운으로 적는 거예요. 시스템 프롬프트에 붙여넣어도 됩니다.

Q. 모델이 바뀌면 하네스도 다시 만들어야 하나요?

A. 하네스 엔지니어링의 산출물(CLAUDE.md, 스킬 파일, 훅 스크립트)은 전부 코드 리포지토리에 커밋되는 파일입니다. 즉, 팀원이 바뀌어도, 모델이 바뀌어도, 축적된 하네스는 그대로 남습니다. 다만, 경량으로 유지해야 새 모델이 나와도 쉽게 적용할 수 있어요.

Q. 하네스 엔지니어링과 프롬프트 엔지니어링 중 뭐가 더 중요한가요?

A. 하네스 엔지니어링 안에 컨텍스트 엔지니어링이 있고, 그 안에 프롬프트 엔지니어링이 있습니다. 좋은 하네스는 여전히 좋은 컨텍스트를 요구하고, 좋은 컨텍스트는 여전히 좋은 프롬프트를 요구합니다. 둘 다 필요하지만, 장기 작업에는 하네스가 훨씬 중요해요.