프롬프트와 컨텍스트를 넘어, AI 에이전트를 위한 하네스 엔지니어링

2026년 3월 14일 · 약 8분

AI Research Engineer, Brain Crew

TL;DR

AI 에이전트가 복잡한 프로덕션 환경에서 안정적으로 동작하려면 프롬프트와 컨텍스트 설계만으로는 부족합니다. 하네스 엔지니어링(Harness Engineering)은 에이전트를 감싸는 전체 환경—저장소 구조, CI/CD, 린터, 외부 도구 연결, 피드백 루프—을 설계하는 새로운 엔지니어링 패러다임입니다. OpenAI의 실험에서 하네스만 제대로 구축했을 뿐인데 AI가 백만 라인의 프로덕션 소프트웨어를 완성했으며, 이는 엔지니어의 역할이 "코드 작성"에서 "환경 설계"로 전환되고 있음을 보여줍니다. 프롬프트 엔지니어링이 "무엇을 물어볼까"에 집중한다면, 컨텍스트 엔지니어링은 "무엇을 보여줄까", 하네스 엔지니어링은 "전체 환경을 어떻게 설계할까"라는 질문에 답합니다.

Key Takeaways

하네스는 에이전트의 "운영체제"다: 린터, CI/CD, 아키텍처 가드레일, 외부 도구 연결 등 에이전트 바깥의 모든 제약과 피드백 장치가 하네스를 구성하며, 이것이 프롬프트보다 더 큰 영향을 미친다.
프롬프트 → 컨텍스트 → 하네스 순서로 범위가 확장된다: 프롬프트 엔지니어링이 "지시문 최적화"라면, 컨텍스트 엔지니어링은 "LLM이 보는 모든 정보 설계", 하네스 엔지니어링은 "에이전트를 감싸는 시스템 전체 설계"다.
컨텍스트는 많이 넣는다고 좋은 게 아니다: Context Poisoning, Distraction, Confusion 같은 실패 패턴이 존재하며, 컨텍스트 윈도우를 "딱 맞는 정보"로 채우는 것이 핵심이다(Karpathy의 정의).
MCP와 Agent Skills는 하네스의 핵심 구성 요소다: MCP(Model Context Protocol)는 외부 시스템 연결을, Agent Skills는 반복 작업의 재사용 가능한 지침화를 담당하며, 이 둘이 에이전트의 실행 환경을 구성한다.
엔지니어의 역할이 재정의되고 있다: 수동 코딩에서 벗어나 "에이전트가 자율적으로 소프트웨어를 구축할 수 있는 환경 설계"로 초점이 이동하며, 이는 단순한 도구 변화가 아닌 엔지니어링 패러다임의 전환이다.

상세 내용

하네스 엔지니어링의 정의와 등장 배경

AI 에이전트를 실제 운영 환경에 투입하면 흥미로운 현상이 발생합니다. 같은 모델을 사용하는데도 프로젝트 A에서는 완벽하게 동작하고, 프로젝트 B에서는 엉뚱한 결과를 내놓습니다. 프롬프트를 아무리 다듬어도 이 격차는 좁혀지지 않습니다. 원인은 대부분 에이전트를 "감싸는 환경"의 차이에 있습니다.

2026년 2월, OpenAI는 놀라운 실험 결과를 발표했습니다. 에이전트를 감싸는 환경만 제대로 구축했을 뿐인데, 수동으로 작성된 코드 없이 AI가 생성한 백만 개 라인에 달하는 프로덕션 소프트웨어를 완성했습니다. 이 결과는 모델 성능이 아닌 "환경 설계"가 에이전트의 실제 성과를 결정한다는 것을 보여줍니다.

**하네스(Harness)**는 AI 에이전트가 안정적으로 작업을 수행할 수 있도록 감싸는 스캐폴딩(scaffolding)이자 피드백 루프가 구축된 전체 환경을 의미합니다. 저장소 구조, CI 설정, 포맷 규칙, 패키지 관리자, 애플리케이션 프레임워크, 프로젝트 지시 사항, 외부 도구 연결, 린터 등 에이전트 바깥에서 동작하는 모든 시스템이 하네스에 포함됩니다. 이는 에이전트가 궤도를 이탈하지 않도록 돕는 기반 인프라 역할을 합니다.

**하네스 엔지니어링(Harness Engineering)**은 엔지니어의 주된 역할이 수동 코드 작성에서 벗어나, 에이전트가 소프트웨어를 자율적으로 구축하고 유지보수할 수 있도록 환경을 설계하고 의도를 명확히 지정하며 피드백 루프를 구축하는 작업으로 재정의된 것을 의미합니다.

프롬프트, 컨텍스트, 하네스의 관계

세 개념은 포함 관계를 이루며 안쪽부터 바깥쪽으로 확장됩니다:

구분	핵심 질문	설계 대상
프롬프트 엔지니어링	"무엇을 물어볼까?"	LLM에 전달하는 지시문
컨텍스트 엔지니어링	"무엇을 보여줄까?"	LLM이 추론 시점에 보는 모든 토큰
하네스 엔지니어링	"전체 환경을 어떻게 설계할까?"	에이전트 바깥의 제약, 피드백, 운영 시스템

비유를 들자면, 프롬프트 엔지니어링이 말에게 "오른쪽으로 돌아"라는 음성 명령을 내리는 것이라면, 컨텍스트 엔지니어링은 말에게 지도와 이정표를 보여주는 것이고, 하네스 엔지니어링은 고삐, 안장, 울타리, 도로 정비까지 합쳐서 말 열 마리를 동시에 안전하게 달리게 만드는 전체 설계에 해당합니다.

개념의 진화 과정

2023~2024: 프롬프트 엔지니어링 시대 ChatGPT에 질문 하나를 던지고 답변 하나를 받는 단순한 구조였습니다. 역할을 부여하고, 단계별로 지시하고, 예시를 넣는 것만으로 원하는 결과를 얻을 수 있었습니다.

2025 중반: 컨텍스트 엔지니어링의 부상 2025년 6월, 전 OpenAI 연구원 안드레이 카르파티(Andrej Karpathy)가 "프롬프트보다 컨텍스트 엔지니어링이 핵심"이라고 언급하면서 패러다임이 전환되었습니다. 단순히 질문을 잘 쓰는 것이 아니라, LLM이 추론할 때 "무엇을 보게 할지" 시스템 수준에서 관리하는 접근이 필요해졌습니다.

LangChain은 이를 컴퓨터에 비유합니다: "LLM은 CPU이고, 컨텍스트 윈도우는 RAM이다. 운영체제가 CPU의 RAM에 무엇을 올릴지 관리하듯, 컨텍스트 엔지니어링도 같은 역할을 한다."

2026년 2월: 하네스 엔지니어링의 등장 AI 에이전트가 본격적으로 운영 환경에 투입되면서 컨텍스트 설계만으로는 해결되지 않는 문제들이 드러났습니다. 팀 컨벤션 위반, 아키텍처 의존성 방향 문제, 병렬 실행 시 파일 충돌, 생성 코드의 점진적 품질 저하 등입니다. 이는 "모델에게 무엇을 보여줄까"가 아니라 "시스템이 무엇을 막고, 측정하고, 고칠 것인가"의 문제입니다.

해시코프(HashiCorp) 공동 창업자 미첼 하시모토(Mitchell Hashimoto)가 2026년 2월 5일 자신의 블로그에서 에이전트의 실수를 방지하는 장치를 쌓아가는 작업을 "하네스 엔지니어링"이라 명명했고, 며칠 뒤 OpenAI도 공식 보고서를 발표하면서 용어가 빠르게 확산되었습니다.

Harness Engineering Diagram

하네스의 핵심 구성 요소

하네스는 다음과 같은 요소들로 구성됩니다:

1. 저장소 구조와 컨벤션

폴더 구조, 네이밍 규칙, 코드 스타일 가이드
린터, 포매터 설정
아키텍처 가드레일(의존성 방향 검증 등)

2. CI/CD와 자동화 파이프라인

자동 테스트, 빌드, 배포 워크플로우
에이전트가 생성한 코드에 대한 즉각적인 피드백

3. 외부 도구 연결 (MCP)

이슈 트래커, 데이터베이스, API 등 외부 시스템과의 통합
Model Context Protocol을 통한 표준화된 연결

4. 재사용 가능한 작업 지침 (Agent Skills)

반복적인 작업 절차의 문서화
SKILL.md 형태로 작성된 실행 가능한 가이드

컨텍스트 엔지니어링: 정보 환경 설계

컨텍스트 엔지니어링은 LLM의 컨텍스트 윈도우에 "무엇을 넣고 무엇을 버릴지" 설계하는 작업입니다. 컨텍스트 윈도우가 수백만 토큰으로 확장되면서 "넣을 수 있는 공간"이 커졌지만, 정보량이 아니라 적합성이 핵심입니다.

컨텍스트 윈도우에 들어갈 수 있는 요소들:

시스템 프롬프트: 역할, 제약, 출력 형식
대화 이력: 이전 질문과 답변의 흐름
검색 문서: RAG로 가져온 관련 문서
도구 출력: API 응답, 코드 실행 결과
사용자 입력: 현재 질문과 첨부 파일
메모리: 장기 기억으로 주입하는 요약 정보

컨텍스트 실패 패턴:

Context Poisoning (컨텍스트 오염): 한 번 잘못 들어간 정보가 이후 대화 전체에 걸쳐 사실처럼 전달되는 현상
Context Distraction (컨텍스트 산만): 관련 없는 정보가 너무 많아 핵심 근거를 놓치는 현상 (2025년 연구에서 평균 45% 성능 저하)
Context Confusion (컨텍스트 혼란): 불필요한 정보가 모델의 판단에 영향을 미치는 현상

프롬프트 vs 컨텍스트 엔지니어링 비교:

고객 문의를 처리하는 CS 챗봇을 예로 들면:

프롬프트만 사용: "배송 관련 문의를 하면 조회 방법을 알려줘" → 일반적 응대는 가능하지만 실시간 데이터 접근 불가
컨텍스트 설계 추가: 주문 DB와 배송 API를 연결하고, 실시간 상태를 컨텍스트에 주입해 정확한 답변 생성

MCP: 외부 시스템 연결의 표준

Model Context Protocol(MCP)은 Claude Code 같은 AI 에이전트가 외부 데이터 소스나 도구에 접근할 수 있게 해주는 프로토콜입니다. 전동드릴에 비트를 바꿔 끼우듯, MCP 서버를 연결하면 에이전트가 접근할 수 있는 정보의 범위가 달라집니다.

MCP 서버 연결 방식:

HTTP 원격 서버 (권장):

claude mcp add --transport http notion https://mcp.notion.com/mcp

로컬 stdio 서버:

claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github

환경 변수 전달:

claude mcp add --transport stdio --env GITHUB_TOKEN=ghp_xxx github -- npx -y @modelcontextprotocol/server-github

적용 범위(Scope) 설정:

--scope local: 현재 프로젝트에서만 (기본값)
--scope project: 팀 공유 (.mcp.json 파일에 저장)
--scope user: 모든 프로젝트에서 사용

project 스코프를 사용하면 서버 정의는 팀과 공유하되, 인증 토큰은 각 개발자의 로컬 환경에서 관리하는 구조가 됩니다.

Agent Skills: 재사용 가능한 작업 지침

Agent Skills는 반복되는 작업 절차를 문서화하여 에이전트가 읽고 수행할 수 있게 만드는 방식입니다. Anthropic이 2025년 10월 발표하고 12월에 오픈 스탠다드로 공개한 이 개념은 SKILL.md 파일을 중심으로 작동합니다.

스킬 디렉터리 구조:

code-review/
├── SKILL.md              # 필수: 에이전트가 따를 지침
├── scripts/              # 선택: 실행 스크립트
│   └── run-lint.sh
├── references/           # 선택: 보조 문서
│   └── review-checklist.md
└── assets/               # 선택: 템플릿, 설정 파일
    └── comment-template.md

Progressive Disclosure 원칙: 스킬은 한꺼번에 로드되지 않고 세 단계로 읽힙니다:

Phase 1: Metadata (~100 tokens) - name, description만 읽음
Phase 2: Instructions (< 5000 tokens 권장) - SKILL.md 전체 읽음
Phase 3: Resources (필요한 만큼) - scripts, references 파일 읽음

SKILL.md 작성 예시:

---
name: api-test-runner
description: >-
  API 엔드포인트의 응답 상태, 스키마, 성능을 자동으로 검증한다.
  API 테스트, 엔드포인트 점검, 응답 검증이 필요할 때 사용한다.
---

## 목적
프로덕션 배포 전 API 엔드포인트의 정상 동작을 확인한다.

## 실행 방법
1. `scripts/run-api-test.sh` 실행
2. 실패 시 `references/troubleshooting.md` 참고

중요 작성 포인트:

description은 WHAT(무엇을 하는지)과 WHEN(언제 쓰는지)을 모두 포함
1/2인칭 표현("나는", "당신은") 피하고 3인칭으로 서술
name은 디렉터리 이름과 일치, 소문자-하이픈만 사용

실무 적용 시나리오

시나리오: 이슈 기반 코드 수정 자동화

프롬프트만 사용: "ISSUE-1234를 고쳐줘" → 이슈 내용을 모르므로 추가 설명 필요
컨텍스트 추가: GitHub API로 이슈 내용을 가져와 컨텍스트에 주입 → 이슈 내용 파악
하네스 구축:
- MCP로 GitHub 연결
- Agent Skill로 "이슈 분석 → 코드 수정 → 테스트 → PR 생성" 워크플로우 정의
- CI에서 자동 테스트 실행
- 린터로 코드 스타일 검증

결과: "ISSUE-1234를 고쳐줘"라는 한 문장으로 전체 프로세스가 자동 실행됩니다.

TL;DR​

Key Takeaways​

상세 내용​

하네스 엔지니어링의 정의와 등장 배경​

프롬프트, 컨텍스트, 하네스의 관계​

개념의 진화 과정​

하네스의 핵심 구성 요소​

컨텍스트 엔지니어링: 정보 환경 설계​

MCP: 외부 시스템 연결의 표준​

Agent Skills: 재사용 가능한 작업 지침​

실무 적용 시나리오​

References​