Harness Engineering: AI 에이전트를 제대로 부리는 법

요즘 AI 개발 커뮤니티에서 Harness Engineering이라는 단어가 계속 나옵니다. 프롬프트 엔지니어링, 컨텍스트 엔지니어링 다음으로 나온 이 개념, 처음 들으면 뭔가 대단한 것처럼 느껴지지만 사실 핵심은 의외로 단순합니다. 그리고 이미 AI 코딩 에이전트를 쓰고 있는 분들이라면 어느 정도는 이미 하고 있는 것이기도 합니다.

이 글에서는 Harness Engineering이 뭔지, 왜 필요한지, 구체적으로 뭘 해야 하는지를 정리해 봤습니다.

---

Harness가 뭔데?

Harness는 영어로 "마구(馬具)"입니다. 말을 다룰 때 쓰는 고삐, 안장, 가죽끈 같은 장비를 말하죠.

AI 에이전트를 야생말이라고 한번 생각해 보세요. Claude, GPT, Gemini 같은 모델은 엄청나게 강력합니다. 하지만 그냥 풀어놓으면 어디로 달려갈지 모릅니다. 숲으로 달려가고, 작물을 밟아 버리고, 울타리를 부수고 도망칠 수 있죠. 힘이 강할수록 통제 없이는 더 위험합니다.

마구를 채운다고 말이 느려지나요? 아닙니다. 오히려 그 힘을 올바른 방향으로 집중시켜서 우리가 원하는 방향으로 빠르고 정확하게 일하게 만드는 겁니다. Harness Engineering은 바로 이 마구를 만드는 기술입니다.

정의를 한 줄로 하면 이렇습니다.

AI 에이전트가 자율적으로 일하되, 동시에 안전하게 통제할 수 있는 환경을 만드는 것

이 개념은 2026년 2월에 HashiCorp 창업자인 Mitchell Hashimoto가 처음 이름을 붙였습니다. AI 코딩 에이전트를 쓰다가 같은 실수를 계속 반복하는 걸 경험하고, 프롬프트에 "이렇게 하지 마"라고 써놔도 다음에 또 같은 실수를 하는 문제를 해결하기 위해 체계화한 개념이죠. 이름이 붙자마자 OpenAI, Anthropic, LangChain 등 업계 전체가 동조하면서 빠르게 퍼졌습니다.

---

왜 기존 방법으로는 부족한가?

Harness를 이해하려면, 왜 기존의 프롬프트 엔지니어링과 컨텍스트 엔지니어링만으로는 부족한지를 먼저 알아야 합니다.

프롬프트 엔지니어링의 한계

프롬프트 엔지니어링은 AI에게 말을 잘 거는 기술입니다. "계산기 만들어 줘" 대신 "공학용 계산기를 만들어 줘. 사인, 코사인을 지원하고 GUI로 만들어야 해"라고 구체적으로 요청하면 결과가 확 달라지죠.

하지만 프롬프트에는 천장이 있습니다. AI에게 "로그인 기능을 추가해 줘"라고 아무리 정교하게 써도, 우리 프로젝트의 기술 스택, 코드 구조, DB 스키마를 모르면 좋은 코드가 나올 수 없으니까요.

컨텍스트 엔지니어링의 한계

그래서 나온 게 컨텍스트 엔지니어링입니다. 프롬프트만 주는 게 아니라, 프로젝트 구조, 기존 코드, API 문서, 디자인 규칙까지 같이 제공하는 거죠. Anthropic의 정의로는 "AI가 일할 때 필요한 정보를 적절한 타이밍에 제공하는 기술"입니다.

그런데 컨텍스트를 아무리 잘 설계해도 해결 안 되는 문제가 있습니다. AI가 정보는 다 알고 있는데 그걸 가지고 엉뚱한 짓을 하는 경우입니다. 결제 시스템을 맡겼더니 갑자기 DB 스키마를 마음대로 바꾸거나, 신용카드 번호를 로그에 찍어 버리는 식이죠. 이건 정보의 문제가 아니라 규칙과 울타리의 문제입니다.

---

Harness Engineering의 핵심 철학

Harness Engineering에서 가장 중요한 문장은 이겁니다.

에이전트가 규칙을 어겼을 때, "더 잘해 봐"라고 프롬프트를 고치는 게 아니라,
그 실패가 구조적으로 반복 불가능하도록 Harness를 고치는 것

예를 들어 보겠습니다. AI 에이전트가 프론트엔드 코드에서 데이터베이스를 직접 호출했다고 하겠습니다. 일반적인 반응은 프롬프트에 "DB를 직접 호출하지 마"라는 문장을 추가하는 겁니다. 그런데 이러면 다음번에 또 실수합니다. 왜냐하면 프롬프트는 부탁이지 강제가 아니거든요.

Harness Engineering은 다르게 접근합니다. 아키텍처 테스트를 추가해서, 프론트엔드 폴더에서 DB를 임포트 하려는 순간 빌드가 실패하도록 만들어 버리는 거죠. 이렇게 하면 AI가 아무리 시도해도 그 실수는 구조적으로 불가능해집니다.

비유하자면 공장의 안전 시스템과 같습니다. 안전모를 안 쓰면 출입문 자체가 안 열리고, 기계에 손이 들어가려 하면 자동으로 멈추는 것처럼, 규칙이 사람의 판단에 의존하는 게 아니라 시스템에 내장되어 자동으로 강제되는 겁니다.

---

Prompt → Context → Harness, 흐름 정리

AI를 활용하는 방법은 계속 발전해 왔습니다. 이 흐름을 한번 정리해 보겠습니다.

단계	핵심	비유
Prompt Engineering	AI에게 말을 잘 거는 기술	말에게 명령하기
Context Engineering	AI에게 필요한 정보를 제공하는 기술	말에게 지도를 보여주기
Harness Engineering	AI가 실수할 수 없는 환경을 만드는 기술	말에게 마구를 채우기
Agentic Engineering	AI 에이전트의 추론과 워크플로우를 설계하는 기술	말 자체를 훈련시키기

이 네 가지는 순서대로 졸업하는 게 아닙니다. 전부 다 필요한 상호보완적인 축입니다. 말을 아무리 잘 훈련시켜도(Agentic) 마구 없이는(Harness) 밭을 갈 수 없고, 아무리 정교한 마구라도 말이 없으면 수레는 움직이지 않죠.

---

Harness의 네 가지 기둥

Harness Engineering은 크게 네 가지 요소로 구성됩니다.

1. 기계가 읽는 컨텍스트 파일

CLAUDE.md, agents.md, .cursorrules 같은 파일들입니다. 이것들은 단순한 문서가 아니라 AI가 실행하는 런타임 설정 파일입니다. 사람이 읽는 위키나 노션 문서와는 본질적으로 다릅니다.

AI 에이전트는 작업을 시작할 때 이 파일을 가장 먼저 읽습니다. 새 세션이 시작돼서 이전 내용을 잊어버려도, 이 파일은 항상 다시 읽히죠. 퇴사자가 아무리 바뀌어도 신규 입사자가 첫날 반드시 읽어야 하는 온보딩 문서가 있듯이, CLAUDE.md가 그 역할을 하는 겁니다.

예를 들어 이런 규칙을 넣습니다.

• 새로운 라이브러리를 도입하지 마
• 기존 API 패턴을 무조건 따라야 해
• DB는 반드시 ORM을 통해서만 접근해

한번 설정하면 모든 작업에 자동으로 적용되기 때문에 매번 프롬프트에 반복할 필요가 없어집니다.

여기서 중요한 원칙이 하나 있습니다. OpenAI팀이 처음에 거대한 agents.md 파일을 만들었다가 실패한 경험을 공유했는데, 1,000페이지 설명서가 아니라 지도를 줘야 한다는 겁니다. 보편적으로 항상 적용되는 핵심 내용만 넣고, 세부 내용은 별도 파일로 나눠서 필요할 때만 참조하게 하는 거죠.

그리고 Hashimoto가 만든 Ghostty의 agents.md를 보면, 처음부터 완벽하게 설계한 게 아닙니다. 에이전트가 실수할 때마다 한 줄씩 추가되면서 점진적으로 개선된 파일입니다.

2. 결정론적 CI/CD 게이트

규칙을 파일에 써 놓는 것만으로는 충분하지 않습니다. AI는 규칙을 읽고도 어길 수 있거든요. 그래서 시스템이 자동으로 강제하는 장치가 필요합니다.

• 린터(Linter): 코드의 맞춤법 검사기라고 생각하면 됩니다. 코드가 정해진 규칙을 어기면 자동으로 에러를 띄워줍니다.
• 구조적 테스트: "이 폴더의 코드는 저 폴더의 코드를 임포트 할 수 없다" 같은 의존성 규칙을 테스트로 강제하는 겁니다.
• 프리커밋 훅(Pre-commit Hook): 코드를 저장하기 전에 자동으로 검사를 돌립니다. 저장 버튼을 누르는 순간 "잠깐, 이거부터 확인하고 저장해"라고 하는 거죠.

여기서 Harness의 진짜 힘이 나옵니다. 자동 교정 루프입니다. 린터가 빨간 불을 켜면, 에이전트가 스스로 코드를 수정하기 시작합니다. 사람이 개입하지 않아도 됩니다. 말이 고삐에 의해 방향이 틀어지면 자연스럽게 올바른 방향으로 돌아오는 것과 같습니다.

Claude Code의 Hook 기능이 대표적인 예입니다. Claude가 코드를 저장하려는 순간 Hook이 자동으로 타입 검사와 문법 체크를 합니다. 에러가 있으면 Claude한테 다시 돌려보내고, Claude가 스스로 고칩니다. "잘 짜줘"라고 부탁하는 게 아니라, 못 짜면 저장 자체가 안 되는 구조를 만든 겁니다.

그리고 중요한 원칙이 하나 더 있습니다. "성공은 조용히, 실패만 시끄럽게"입니다. 테스트가 다 통과하면 아무 말도 하지 않습니다. 실패했을 때만 에이전트에게 알려주는 거죠. 통과한 테스트 결과 4,000줄을 다 보여주면 AI가 그걸 읽느라 정작 할 일을 잃어버리거든요.

3. 명시적 도구 경계 (최소 권한 원칙)

AI 에이전트가 어떤 도구를 쓸 수 있고, 어디까지 접근할 수 있는지를 명확하게 제한하는 겁니다.

영역	허용	차단
파일 시스템	src/ 폴더 읽기/쓰기	config/ 폴더는 읽기만 가능
API	내부 API 호출 가능	외부 서비스 호출 불가
데이터베이스	SELECT 가능	DROP TABLE 절대 불가
터미널	화이트리스트 명령만 가능	임의 명령 실행 불가

프롬프트로 "절대 DB를 삭제하지 마"라고 쓰는 것과 도구 경계를 설정하는 것의 차이가 뭔지 아시겠죠? 프롬프트는 부탁이고, 도구 경계는 물리적 차단입니다. 부탁은 어길 수 있지만, 물리적 제약은 어길 수 없습니다.

4. 지속적 피드백 루프 (가비지 컬렉션)

Martin Fowler는 이걸 가비지 컬렉션이라고 불렀습니다. 직역하면 쓰레기 청소죠.

이게 왜 필요할까요? AI 에이전트는 기존 코드를 참고해서 새 코드를 짭니다. 기존 코드에 나쁜 패턴이 있으면 그대로 따라 합니다. "아, 여기선 이렇게 하나 보다" 하고 복제하는 거죠. 이러면 나쁜 패턴이 눈덩이처럼 불어납니다.

그래서 주기적으로 돌아가는 청소 시스템이 필요합니다. 코딩 규칙 위반을 자동으로 감지하고, 중복 코드를 발견하고, 사용하지 않는 코드를 제거하고, 아키텍처 위반을 체크하는 거죠.

그리고 여기서 Harness가 진화합니다. 에이전트가 실수할 때마다 그 실수는 새로운 규칙이 됩니다. 린터 규칙이 추가되고, 테스트가 추가되고, 제약이 추가됩니다. 시간이 지날수록 시스템이 점점 더 견고해지는 거죠. 말이 한 번 넘으려 했던 울타리가 점점 더 높아져서, 두 번 다시 같은 실수를 할 수 없게 되는 겁니다.

---

실제로 이렇게 하는 팀이 있다

OpenAI: 코드 한 줄 안 쓰고 제품 배포

2026년 2월, OpenAI는 엔지니어 세 명이 AI 에이전트만으로 대규모 소프트웨어 제품을 만든 사례를 공식 블로그에 발표했습니다. 직접 코드를 한 줄도 쓰지 않았다고 합니다.

이게 가능했던 이유는 AI 모델이 강해서가 아니라, Harness가 잘 설계되어 있었기 때문입니다. 이 세 명이 실제로 한 일을 분석해 보면 위에서 설명한 네 가지 기둥 그대로입니다. agents.md로 지침서를 설계하고, CI/CD 게이트로 자동 검증 파이프라인을 구축하고, 도구 경계로 접근 범위를 제한하고, 피드백 루프로 지속적으로 개선하는 구조를 만든 거죠.

결국 이 사람들이 코드를 쓴 게 아니라 시스템을 만든 겁니다. 여기서 나온 유명한 말이 "인간은 조종한다, 에이전트는 실행한다"입니다. 이 조종이 바로 Harness입니다.

LangChain: 모델은 그대로, Harness만 바꿔서 25단계 상승

LangChain은 코딩 에이전트 벤치마크에서 모델을 바꾸지 않고 Harness만 개선했더니 30위권에서 5위권으로 25단계나 올라갔습니다. 모델은 그대로였고 Harness만 바뀌었습니다. AI 에이전트의 성능을 좌우하는 것은 모델의 지능이 아니라 Harness라는 걸 보여준 사례죠.

Anthropic: 장기 실행 에이전트의 실패 패턴 발견

Anthropic 연구팀은 Claude Code SDK를 사용해서 claude.ai 클론을 만드는 실험을 했습니다. 여기서 두 가지 반복되는 실패 패턴을 발견했죠.

첫 번째는 에이전트가 모든 걸 한 번에 해결하려고 달려들다가 컨텍스트가 바닥나서 절반만 구현되는 문제였습니다. 다음 세션이 시작됐을 때 어디까지 했는지 기억이 없으니까 처음부터 다시 파악하느라 시간을 허비하는 거죠.

두 번째는 에이전트가 조기 종료를 선언해 버리는 문제였습니다. 아직 한참 남았는데 "다 됐네" 하고 끝내 버리는 겁니다. 이거 AI 코딩 에이전트 써보신 분들은 공감하실 겁니다.

Anthropic의 해결 방법은 환경을 읽기 쉽게(legible) 만드는 것이었습니다. 프로젝트를 200개 이상의 Feature로 분해해서 JSON 파일에 기록하고, 각 Feature에 pass/fail 상태를 달아서, 에이전트가 새 세션을 시작할 때마다 전체 진행 상황을 빠르게 파악할 수 있게 한 거죠. 그리고 Puppeteer MCP나 Chrome DevTools 같은 도구를 연결해서 에이전트가 직접 End-to-End 테스트를 할 수 있게 했더니, 코드만 봐서는 발견하지 못했던 버그까지 잡아내기 시작했습니다.

---

사실 이미 쓰고 있었다

여기까지 읽으면서 "그거 내가 이미 하고 있는 건데?" 싶은 분들도 있을 겁니다. 맞습니다.

사실 우리가 Claude나 ChatGPT와 대화할 때, 이전 메시지를 기억하면서 이야기하는 것처럼 느껴지는 것도 Harness 덕분입니다. AI 모델은 기본적으로 텍스트를 넣으면 텍스트를 뱉는 함수일 뿐이에요. 혼자서는 이전 대화를 기억하지도 못하고, 파일을 읽지도 못하고, 인터넷에 접속하지도 못합니다. 대화 내용을 계속 모아서 매번 모델에게 새로 전달해 주는 루프 자체가 이미 Harness인 겁니다.

CLAUDE.md 파일을 만들어서 프로젝트 규칙을 정리해 본 적이 있다면, 프리커밋 훅으로 자동 검사를 돌려본 적이 있다면, 이미 Harness Engineering을 하고 있었던 겁니다. 이름만 새로 붙었을 뿐이죠.

---

지금 당장 해볼 수 있는 것

너무 거창하게 생각할 필요 없습니다. 시작은 딱 두 가지면 충분합니다.

첫 번째, CLAUDE.md 또는 agents.md 작성: 프로젝트의 기술 스택, 코드 규칙, 절대 하면 안 되는 것들을 정리합니다. 처음부터 완벽하게 쓸 필요 없습니다. 에이전트가 실수할 때마다 한 줄씩 추가하면 됩니다.

두 번째, 프리커밋 훅 설정: 코드를 저장하기 전에 린터와 테스트가 자동으로 돌아가게 합니다. 에이전트가 규칙을 어기면 저장 자체가 안 되는 구조를 만드는 거죠.

그리고 기억해야 할 마인드셋이 있습니다. 한 번에 완벽하게 하려고 하지 말 것. 에이전트가 실제로 실패한 경우에만 그 케이스를 모아서 Harness를 조금씩 개선하면 됩니다. 아이디어가 아직 모호하거나 검증되지 않았다면 Harness를 구축하는 것보다 결과물을 빠르게 만들어내는 게 먼저입니다.

그리고 하나 더, Garbage In, Garbage Out입니다. 문제 정의나 기획 자체가 별로면 아무리 Harness를 거쳐도 좋은 결과물이 나오지 않습니다. Harness는 좋은 걸 더 잘 만들게 도와주는 것이지, 별로인 걸 좋게 만들어 주는 마법이 아닙니다.

---

앞으로 Harness는 어떻게 될까?

강화학습의 창시자 Richard Sutton은 "모델이 똑똑해질수록 Harness는 더 단순해져야 한다"라고 이야기했습니다. 모델이 업그레이드될 때마다 하드코딩된 규칙을 계속 추가하고 있다면, 흐름을 거슬러 가고 있는 겁니다. 에이전트가 스스로 판단할 수 있는 걸 우리가 억지로 제약하는 거니까요.

Vercel도 비슷한 경험을 공유했습니다. 정교한 전용 도구를 여러 개 만들어서 에이전트에 달아줬더니 오히려 성능이 떨어지고, 도구를 단 하나의 범용 Bash 명령으로 줄였더니 3.5배 빨라지고 성공률이 80%에서 100%로 올라갔다는 겁니다. 모델은 자기가 이미 잘 아는 범용 도구를 쓸 때 훨씬 잘 동작한다는 거죠.

언젠가는 에이전트가 스스로 Harness Engineering을 하는 시대가 올 겁니다. "내가 일을 잘하기 위한 환경 구성부터 먼저 살펴보고, 설정한 다음에 작업을 시작할게"라는 식으로요. 지금은 그렇게 하지 않기 때문에 Harness Engineering이 중요한 거지, 앞으로는 방향이 바뀔 수 있습니다.

---

마무리

Harness Engineering을 한 문장으로 요약하면 이렇습니다.

AI 에이전트가 실수했을 때, 프롬프트를 고치지 마세요
Harness를 고치세요

프롬프트는 부탁이고, Harness는 강제입니다. "넘지 마"라고 소리치는 대신 울타리를 더 높이 세우는 것. 그 실패가 구조적으로 반복 불가능하도록 시스템을 바꾸는 것. 이게 Harness Engineering의 핵심입니다.

개발자의 역할이 바뀌고 있습니다. 코드를 직접 작성하는 것에서, AI가 코드를 올바르게 작성할 수 있는 환경을 설계하는 것으로요. 코딩 능력이 필요 없어지는 게 아니라, 더 높은 차원의 능력이 요구되는 겁니다. 공을 직접 차는 선수에서 전술을 짜고 팀을 운영하는 감독으로 한 단계 올라가는 거죠.