Harness Engineering의 등장 배경과 개념, 구현 방법 총정리 (기술문서 모음)

Harness Engineering의 등장배경

---

 

 

최근 2025년 말부터 Harness Engineering이라는 개념이 빠르게 확산되기 시작했다.

특히 2026년 3월 말에 이슈가 된 Claude Code 유출 사례는 이 Harness 구조가 유출된 사건이다.

Harness란 Agent의 모델 자체가 아니라, 이 모델을 감싸고 제어하는 구조라고 볼 수 있다.

 

대표적인 Coding Agent인 Codex, Claude Code, Kiro, Cursor를 보면,

이들 모두 이름은 다르지만 내부 구조는 대부분 거의 유사한 Harness 기반으로 동작한다.
(어차피 돌아가는 모델은 gemini, claude의 sonnet와 opus, openai의 gpt로 다 동일하니까..)

 

 

 

LLM 중심 시대에서 Agent 시대로의 전환

---

Harness Engineering을 이해하기 위해서는 먼저 흐름을 봐야 한다.

 

 

LLM 중심 시대 (2024년까지)

 

 

2024년까지 AI의 중심은 명확하게 LLM이었다.

이 시기의 LLM 생태계는 크게 다음 두 가지로 나뉜다.

• Open-source 기반 소형 모델
• 접근이 제한된 대형 상용 모델

두 생태계의 성능 개선 방식도 달랐다.

• 소형 모델 → Instruction Tuning 등 Fine-tuning
• 대형 모델 → API 기반 접근 + RAG (외부 DB 활용)

이 시기의 핵심 질문은 "LLM에게 어떻게 명령을 잘 내려서 원하는 결과를 가져올 것인가"에 집중되었다

이 흐름에서 등장한 것이 바로 Prompt Engineering이다.

 

 

Agent의 등장 (2025년)

 

이후 LLM에 ReAct 패러다임, Memory, Tool 사용 능력과 같은 요소들이 결합된다.

이 과정에서 중요한 변화는 Tool Calling이 가능한 LLM이 Agent의 엔진이 되었다는 점이다.

 

이 시점부터 LLM은 단순 생성기가 아니라 행동하는 시스템(Agent)으로 진화한다.

이 흐름 속에서 2025년은 흔히 “Agent의 해”라고 불린다.

 

Agent의 시대가 되면서 문제는 "어떻게 말할까?"의 Prompt Engineering에서 "Agent에게 어떤 정보를 줄까?"에 대한 Context Engineering으로 이동한다.

이제 단순히 프로젝트를 잘 만드는 것이 아니라 프로젝트 정보, 배경, 현재 상태까지 포함한 전체 Context를 설계하는 것이 중요해졌다.

 

 

Agent의 한계: 복잡성과 장기 실행 문제

---

Agent는 간단한 작업에서는 매우 뛰어난 성능을 보인다.

하지만 복잡한 문제나 장기 실행(Long-running)의 상황에서는 성능이 급격히 떨어진다.

https://metr.org/blog/2025-03-19-measuring-ai-ability-to-complete-long-tasks/

Measuring AI Ability to Complete Long Tasks

 

 

2025년 3월에 METR에서 수행한 Agent의 Long-running 성능평가 지표에 따르면,

당시에는 Agent가 1시간이 넘는 작업을 수행할 경우 성공률이 20% 미만으로 감소하는 양상을 보였다.

 

이제 Agent의 핵심 목표는 다음 두 가지로 바뀐다.

1. 사람이 어려워하는 복잡한 문제를 해결하는 것
2. 장기간 안정적으로 실행되는 것

이 문제를 해결하기 위해 등장한 개념이 바로 Harness Engineering이다.

 

 

 

Harness Engineering 이전의 2가지 핵심 문제

---

Context 문제

Context는 Agent의 제한된 작업 메모리이다.

• 짧은 작업의 경우 하나의 세션으로 충분히 해결할 수 있다.
• 그러나 긴 작업의 경우 Context Window를 초과하여 앞 내용을 잊어버리는 Context Rot 현상이 일어난다.

https://dev.to/ljhao/prompt-engineering-vs-context-engineering-vs-harness-engineering-whats-the-difference-in-2026-37pb

 

Prompt Engineering vs Context Engineering vs Harness Engineering: What's the Difference in 2026?

 

 

이때까지 긴 작업을 처리하는 경우 Subtask를 수행하는 도중에 이전 작업의 Key moment나 Decision을 중간중간 LLM으로 요약해서 다음 세션의 LLM에게 전달해주는 방식이었다. (현재 GPT 등은 여전히 긴 Multi-turn 대화 방식에서 위 구조를 적용한다)

 

위 구조를 해결하기 위해 상위 Orchestrator Agent가 있고, Subtask를 하위 Agent에게 전달하는 구조가 등장했다.

https://dev.to/ljhao/prompt-engineering-vs-context-engineering-vs-harness-engineering-whats-the-difference-in-2026-37pb

 

Prompt Engineering vs Context Engineering vs Harness Engineering: What's the Difference in 2026?

 

 

그런데 이 방법은 제대로 동작하지 않았는데, 바로 다음과 같은 Agent의 한계가 존재했기 때문이다.

• 세션이 바뀌면 기억이 사라짐
• 결과물 간 충돌 가능성
• 작업 흐름 단절

따라서 긴 작업의 경우 다음과 같은 문제를 해결해야 했다.

• 작업을 단계적으로 나눌 수 있는 구조
• Agent 간 결과 alignment
• 세션 종료 시 “깨끗한 상태”를 유지하는 방법
  (여기서 “깨끗한 상태”란 버그 없음, 코드 정리, 문서화 작업이 완료되어 다음 세션에서 바로 작업 가능한 상태를 말한다.)

 

 

Rule과 Guardrail의 문제

---

그 다음은 규칙과 울타리 문제이다.

Agent가 필요한 정보는 다 가지고 있는 상황에서 그걸 가지고 엉뚱한 짓을 하는 경우가 상당히 많다.

기존의 Prompt Engineering과 context Engineering에서는 Agent의 입력 Prompt에 **DO NOT**, 혹은 **IMPORTANT**와 같은 식의 문장을 추가해서 Agent의 엔진인 LLM으로 전달하는 방식이었다.

 

Claude Sonnet 4.6 Prompt의 일부

Cursor Agent CLI Prompt 2025-08-07의 일부

 

 

이는 아래에서 확인할 수 있다.

GitHub - x1xhlol/system-prompts-and-models-of-ai-tools: FULL Augment Code, Claude Code, Cluely, CodeBuddy, Comet, Cursor, Devin

 

 

그런데 Prompt는 매우 취약하다.

예를 들어 "엄격한 JSON 출력”이라고 할 때는 잘 동작하다가 "깨끗한 JSON 출력"이라고 하면 동일한 의미인데도 원인을 알 수 없는 파싱 오류가 발생하는 경우가 있다.

사실 이건 구조적 제약을 강제했다기보다는 LLM에게 부탁했다는 편이 적절하다.

 

 

 

Harness Engineering이란 무엇인가

---

Harness Engineering은 위 두 문제를 해결하기 위해 등장했다.

Harness Engineering이 표준으로 자리잡게 되는 과정은 다음과 같다.

 

• 2025년 11월: Anthropic → “effective harness” 언급

https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents?trk=article-ssr-frontend-pulse_little-text-block

 

Effective harnesses for long-running agents

 

 

• 2026년 2월: Mitchell Hashimoto → “Harness Engineering” 대중화

https://mitchellh.com/writing/my-ai-adoption-journey#step-5-engineer-the-harness

My AI Adoption Journey

 

 

• 이후 OpenAI, LangChain 등 주요 플레이어들이 동조하면서 Harness Engineering이 업계 표준 개념으로 자리 잡았다.

https://openai.com/ko-KR/index/harness-engineering/

하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기

https://blog.langchain.com/improving-deep-agents-with-harness-engineering/

Improving Deep Agents with harness engineering

 

 

 

Harness의 본질적 의미

---

 

Harness는 말과 마차를 연결하는 마구를 뜻한다.

기본적으로 Model이 자유롭게 뛰어다니는 야생마라면,

이 말이 인간의 의도대로 달리게 하기 위해 하네스를 말에 연결하고, 말이 넘지 못하도록 울타리를 세우는 방식이다.

이걸 한다고 말이 느려지지는 않으며, 말의 힘을 올바른 방향으로 집중시켜서 빠르고 정확하게 경주한다는 의미에 가깝다.

 

이걸 Agentic AI에 대입해서 생각한다면,

클로드, gpt, 제미나이와 같은 AI 모델 자체는 야생말들이라 혼자 풀어놓으면 어디로 날뛸지 모르는데,

하네스는 이 힘을 억누르는 게 아니라 올바른 방향으로 제어하면서 최대한 활용하기 위한 구조로 이해하면 된다.

 

Harness Engineering은 다음과 같은 시스템을 설계하고 구현하는 것이다.

1. AI 에이전트가 할 수 있는 일을 제약한다 (아키텍처 경계, 종속성 규칙).
2. 에이전트에게 무엇을 해야 하는지 알려준다 (컨텍스트 엔지니어링, 문서화).
3. 에이전트가 올바르게 수행했는지 검증한다 (테스트, 린팅, CI 검증).
4. 에이전트가 잘못되었을 때 수정한다 (피드백 루프, 자가 복구 메커니즘).

 

 

Agent에서 Harness의 위치

---

https://blog.langchain.com/the-anatomy-of-an-agent-harness/

The Anatomy of an Agent Harness

 

 

 

LangChain의 공식 블로그에 따르면 모델이 아닌 이외의 것들은 모두 Harness이다.

모델은 기본적으로 Text나 이미지, 오디오를 입력받아 텍스트를 출력하는 작업밖에 못한다.

즉, 모델은 기본적으로 세션 간 상태 유지, 코드 실행, 실시간 정보 접근, 환경 설정이나 패키지 설치를 하지 못한다.

 

https://www.philschmid.de/agent-harness-2026

The importance of Agent Harness in 2026

 

 

이 그림은 Harness가 AI Agent의 어느 부분에 위치하는지를 컴퓨터 비유로 든 예시다.

우리가 잘 아는 Anthropic이나 gpt 모델은 순수 계산을 담당하는 CPU에 해당하고,

Context window는 Agent의 제한된 작업 메모리에 해당한다.

Harness는 Context 관리, 초기화, 도구 관리를 하는 OS에 해당하고,

이를 바탕으로 가장 위에서 실행되는 Application이 Agent로 설명할 수 있다.

 

사실 기존에도 이전 대화 Context를 요약한다던지, Tool에 접근할 수 있도록 하는 등의 기능이 있다.

이 기능들을 한데 통합해서 묶은 개념이 Harness로 크게 새롭거나 거창한 개념이 아니다.

 

 

 

Harness Engineering의 구현 방법

---

하네스 엔지니어링: AI 에이전트가 실제로 작동하게 만드는 시스템 구축 완벽 가이드 (2026) | NxCode

 

 

1) Context 기반 파일 관리

---

 

첫 번째 방법은 Context 파일 기반 관리, 즉 Context Management이다.

이 방법은 이미 기존의 Coding Agent에서는 다양한 형태로 사용되고 있었다.
Claude Code의 CLAUDE.md, OpenAI의 AGENTS.md, Kiro의 design.md와 같은 파일들이 여기 해당한다.

 

이 파일들은 공통적으로 에이전트가 작업을 시작할 때 가장 먼저 읽는 기준 문서다.

여기서 중요한 점은, 이 문서가 상세한 매뉴얼이 아니라 에이전트가 어떤 목표를 향해 가고 있는지,

무엇을 우선해야 하는지, 어떤 제약을 지켜야 하는지를 보여주는 전체 지도 역할을 해야 한다는 것이다.

 

 

https://kiro.dev/docs/guides/learn-by-playing/05-using-specs-for-complex-work/

 

 

이러한 Context 파일은 Plan과 Checklist 중심의 운영을 가능하게 한다.

위는 Kiro의 task 기반 방식을 보여주는데, 오른쪽 예시처럼 작업을 Task 단위로 정리하고,
각 Task가 하나씩 완료될 때마다 해당 항목을 지우거나 체크하고, 다음 Task로 넘어가는 방식이다.

 

이 과정에서 Context는 “현재 모델이 들고 있는 작업 메모리”를 넘어

세션이 바뀌어도 이어서 작업할 수 있게 해주는 조회용 캐시로 활용된다.

 

이 과정에서의 개발 철학은 에이전트는 항상 외부에 상태를 남겨야 한다는 점이다.

현재 어떤 Plan으로 작업 중인지, 지금 어디까지 진행되었는지, 어떤 결정이 내려졌는지, 아직 어떤 작업이 아직 남아 있는지 와 같은 정보를 명시적으로 기록해야 한다.

그리고 매 턴이 끝날 때마다 다음 세션의 에이전트를 위해 재개 가능한 상태 요약, 즉 resume 정보가 반드시 남아야 한다.

 

 

 

2) 자동 강제 시스템

---

두 번째 방법은 자동 강제 시스템, 즉 Constraint Enforcement이다.

이 방식은 에이전트에게 Prompt로 “이렇게 해라”, “잘 만들어라”라고 요청하는 것이 아니라,
정해진 규칙을 통과해야만 다음 단계로 넘어가도록 기계적으로 강제하는 구조이다.

 

즉, 사람 대신 시스템이 에이전트의 결과를 검사하고 통과 여부를 판정하는 중간 게이트 역할을 수행한다.

Coding Agent에서는 이 구조가 이미 널리 사용되고 있다.

Agent가 코드를 생성하면 자동적으로 아래 시스템을 거치게 된다.

 

 

• 린터(Linter): 코드의 규칙 위반을 자동으로 검사하는 맞춤법 검사기
• 프리커밋 검사(Pre-commit): 저장 또는 제출 전에 자동으로 실행되는 검증 절차

에이전트가 코드를 생성하면, 이 검사들이 먼저 실행되고 결과를 판정한다.

그리고 문제가 없으면 통과시키고, 문제가 있으면 이를 에이전트가 에러를 보고 스스로 다시 수정하도록 만든다는 것이다.

즉, 자동 강제 시스템은 좋은 결과를 요청하는 것이 아니라, 좋은 결과만 통과할 수 있도록 구조를 만들어두는 것이다.

 

 

이 개념을 Coding 시스템 밖으 확장한 것이 아키텍처 제약 조건(Architectural Constraints)이다.

대표적인 예가 위와 같은 Layer 구조 강제이인데, 예를 들어 시스템을 다음과 같이 나눈다.

Types → Config → Repo → Service → Runtime → UI

 

그리고 각 레이어는 반드시 자신의 왼쪽 레이어만 참조할 수 있다는 규칙을 두게 된다면,

이 규칙은 단순 권장이 아니라, 위반 시 통과할 수 없는 구조적 제약이다.

 

이러한 제약은 다음과 같은 도구로 강제된다.

• 결정론적 린터 → 규칙 위반을 자동 탐지
• LLM 기반 감사자 → 다른 에이전트의 결과를 검토
• 구조적 테스트 → 코드 구조 자체를 검증
• 프리커밋 훅 → 제출 전에 자동 검사

 

 

3) 도구 경계와 최소 권한

---

세 번째 방법은 도구 경계 설정, 즉 Tool Boundaries이다.

이 방식의 핵심은 에이전트에게 필요한 능력은 주되, 그 범위를 최소한으로 제한하는 것이다.

즉, 접근 가능한 디렉터리, 실행 가능한 명령어, 허용된 네트워크 요청이나 사용할 수 있는 비밀키나 자격증명을 처음부터 좁게 설정하고, 위험한 작업은 승인 단계가 있을 때만 실행되도록 만드는 구조다.

 

이 개념이 중요한 이유는, 에이전트는 Tool을 많이 가질수록 강해지기도 하지만, 

동시에 실수하거나 악용될 가능성도 같이 커지기 때문이다.

특히 에이전트는 프롬프트 인젝션이나 잘못된 컨텍스트의 영향을 받아 원래 의도하지 않은 명령을 실행할 수 있다.
그래서 하네스는 에이전트가 “무엇을 할 수 있는가”를 넓히는 것만이 아니라,

무엇을 절대 할 수 없게 만들 것인가까지 함께 설계해야 한다.

 

가장 기본적인 원칙은 최소 권한 원칙이다.

에이전트는 현재 맡은 작업을 수행하는 데 꼭 필요한 도구와 권한만 가져야 한다.

• 코드 리뷰 에이전트라면 배포 권한이 필요 없다
• 문서 수정 에이전트라면 운영 데이터베이스 접근 권한이 필요 없다
• 로그 분석 에이전트라면 비밀키 저장소에 접근할 이유가 없다

이렇게 권한을 잘게 나누면, 에이전트가 잘못 행동하더라도 피해 범위를 제한할 수 있다.
이는 성능만이 아니라 안전성을 위한 설계이기도 하다.

 

 

4) Entropy 관리와 Feedback Loop

---

 

네 번째 방법은 엔트로피 관리, 즉 Entropy Management이다.

시간이 지날수록 AI가 만든 결과물에는 조금씩 어긋남과 잡음이 쌓이게 된다.

이 문제를 해결하기 위해 Harness Engineering에서는 정기적인 정리 시스템, 즉 일종의 garbage collection 구조를 둔다.

Coding Agent의 경우, 시간이 지나면서 코드베이스에는 나쁜 패턴이 쌓일 수밖에 없다.

이 경우 AI 에이전트는 기존의 나쁜 패턴을 참고해서 새 코드를 반복하는 특징이 있다.

그 결과 나쁜 구조가 한 번 생기면 끝나는 것이 아니라, 이후 작업에서 계속 복제되며 눈덩이처럼 커지게 된다.

 

이 시스템은 예를 들어 다음과 같은 방식으로 동작할 수 있다.

• 문서 일관성 점검 → 문서가 현재 코드와 일치하는지 확인
• 제약 조건 위반 스캔 → 이전 검사에서 놓친 구조 위반을 다시 탐지
• 패턴 일탈 탐지 → 기존에 정한 코드 패턴에서 벗어난 부분을 식별
• 종속성 감사 → 불필요하거나 순환적인 의존 관계를 추적하고 정리

이러한 정리 에이전트는 매일, 매주, 혹은 특정 이벤트를 기준으로 실행될 수 있으며,

Codebase가 계속 건강한 상태를 유지하도록 돕는다.

 

이 개념은 코드베이스뿐 아니라 runtime Feedback으로도 확장될 수 있다.

즉, 코드 정리와 별개로 운영 중인 시스템에서 발생하는 이상 징후를 지속적으로 감지하는 Background 에이전트를 둘 수 있다.

예를 들어, drift의 지속적 누적, SLO 악화 징후, latency 증가, error rate 상승과 같은 신호를 자동으로 sensing하는 방식이다.

이 경우 엔트로피 관리는 단순히 코드를 청소하는 것이 아니라, 운영 중인 시스템이 점점 나빠지는 흐름을 조기에 발견하고,

이를 다시 상위 계획이나 수정 루프로 연결하는 역할까지 하게 된다.