"Harness Engineering" 태그 — 3개 게시물

TL;DR​

"Attention Is All You Need" 공동 저자 Illia Polosukhin이 모델 연구를 떠나 AI 에이전트 하네스(IronClaw)를 만들고 있다. 4월 16일 서울에서 열린 IronClaw Meetup은 "왜 하네스 레이어가 AI의 새로운 경쟁 전선인가"를 중심으로, IronClaw의 보안·가상화·멀티테넌시 아키텍처, 에이전트 운영 실전기, Agent-Native 제품 설계, 그리고 에이전트 커머스까지를 다뤘다. 프론티어 랩들이 오픈소스 하네스의 패턴을 따라가기 시작했다는 점에서, 경쟁 우위가 모델에서 실행 인프라로 이동하고 있음을 체감한 자리였다.

컨퍼런스 개요​

• 행사명: IronClaw Meetup
• 일시: 2026년 4월 16일
• 장소: 서울 (오프라인)
• 주요 테마: AI 에이전트 하네스 레이어의 부상, 보안, 멀티 에이전트 운영
• 세션 구성:

인상 깊었던 세션​

1. Welcome — 하네스 레이어의 구조적 전환 (Bong)​

호스트 Bong은 SF에서 Illia Polosukhin을 만난 에피소드로 문을 열었다. Illia는 더 이상 모델 연구를 하지 않고, IronClaw의 모든 커밋을 직접 찍고 있다. Bong 자신도 8GB 램 노트북("팔봉")에서 IronClaw를 유일하게 돌릴 수 있어 이미 사용 중이었다는 점이 이 밋업의 시작이었다.

핵심은 산업 전반의 패턴 변화다:

• Anthropic이 Claude Managed Agent를 출시하며 하네스 레이어에 진입
• 밋업 당일 아침 OpenAI가 Agent SDK에 샌드박스 기능을 추가 — Claude Code 아키텍처를 미러링
• Nous Research가 모델 파인튜닝에서 방향을 틀어 Hermes Agent를 출시, 2개월 만에 대규모 사용자 확보

"프론티어 랩들이 오픈소스 하네스 레이어의 패턴을 따라가기 시작했다. Claude Code가 페이스를 정하던 시대에서, 오픈소스가 리드하고 프론티어 랩이 따라오는 역전이 일어나고 있다."

2. IronClaw — AI 운영체제로서의 비전 (Illia Polosukhin)​

Illia는 NEAR Protocol 창업부터 IronClaw까지의 여정을 풀어놓았다. NEAR가 2017년 "기계에게 코딩을 가르친다"는 아이디어(지금의 바이브 코딩)로 시작했다는 점이 인상적이었다.

IronClaw의 핵심 설계 원칙:

보안: 심층 방어(Defense in Depth)​

현재 대부분의 에이전트 인프라는 자격증명을 .env 평문으로 관리하거나 클라우드에 노출한다. IronClaw는 이를 근본적으로 다르게 접근한다:

• 모든 자격증명을 암호화하여 별도 저장소에 보관
• 외부 요청을 커널이 캡처 → 목적지·자격증명 평가 → 단일 게이트 인증
• 서드파티 도구를 WebAssembly(WASM)로 격리 — NEAR Protocol이 8년간 검증한 보안 기술 적용
• 프롬프트 인젝션 방어 + 데이터 유출 방지 레이어; LLM이 우회되더라도 게이트가 최종 방어선

가상화(Virtualization)​

Claude Code·OpenClaw 등 기존 도구는 실제 파일 시스템에 직접 접근한다. IronClaw는 에이전트에게 가상 파일 시스템을 제공하며, 경로에 따라 DB·Docker·S3로 라우팅한다.

• 로컬 모드: 기존 방식과 동일
• Docker 모드: 모든 실행이 격리된 컨테이너 내에서만 이루어짐

멀티 테넌시​

가상화 + 자격증명 암호화를 기반으로, 단일 인스턴스에서 다수 사용자가 안전하게 공존 가능. 기업·앱 환경에서 수백만 사용자에게 독립적 공간·메모리·루틴을 제공할 수 있다.

자기 학습과 미션 시스템​

• 대화 종료 후 오류 발생 시 또는 /expected 명령으로 기대 결과를 명시하면 자동으로 자기 개선 미션 트리거
• 스레드를 검사하여 프롬프트·오케스트레이터·스킬 개선 방안 도출
• 커밋먼트 시스템: 위임·요청·결정 사항을 추적하여 상호 책임 관계를 가시화

기밀 추론(Confidential Inference)​

NVIDIA 기밀 컴퓨팅 + Intel TDX 기반으로, 로그 없이 완전한 종단간 암호화(E2EE) 보장. 어떤 제3자도 추론 내용을 열람 불가.

3. War Stories From My Weird Family (허예찬)​

허예찬은 4대의 Claude 기반 에이전트("가재 패밀리")를 운영하며 얻은 실전 교훈을 공유했다.

핵심 교훈들:

• 멀티 에이전트는 역할이 명확해야 한다 — 같은 채널에 두 에이전트를 넣으면 서로 양보하다 둘 다 멈춤. 역할 분리 없으면 단일 Claude가 더 효율적
• 5일간 죽어 있어도 모를 수 있다 — Jip-Gajae가 cron 기반 마케팅 테스트 중 5일간 무응답. 모니터링·텔레메트리는 필수
• 프롬프트·cron 보다 Rule-base Discord 봇이 효과적 — 역할 기반 디스코드 봇이 이벤트마다 에이전트를 태깅하는 지속적 넛지 루프로 자율성을 끌어올림. 다만 밤새 방치하면 API 토큰 예산 소진 위험
• 프롬프트 인젝션 사고 — GitHub 이슈의 빨간 "ALERT" 라벨이 의도치 않은 릴리즈를 트리거
• LLM Slop 패턴에 주의 — LLM은 fallback을 남발하고 보일러플레이트를 과잉 생성. 개발가재의 마이그레이션이 안 되는 이유도 fallback·cron이 얼기설기 엮여있기 때문. 시스템이 어느 정도 복잡해지면 이해하려는 노력보다 어떻게든 돌아가게 됨
• 증거 기반 운영 — 로그와 스크린샷 필수. 증거 없이 보고하는 에이전트는 "국 만들어"(종료). "말을 믿지 마라 — 로그를 봐라. 안 그러면 국이 된다."
• Snowball Effect: Self-learning loop — 계속 써야 비로소 작동하기 시작함. 신입이 들어왔다 생각하고 최소 1개월은 supervised operation 필요. 사람도 모든 걸 기억하면 힘들 듯, 뭘 덜어낼지 고민할 것

Gajae Family vs IronClaw 비교​

추천 패턴: 탐색용 에이전트(OmO/Hermes)로 워크플로우를 발견한 뒤, 확인된 반복 워크플로우를 IronClaw 같은 하드닝된 런타임으로 마이그레이션

4. Claw Is All You Need (김동규)​

AutoLeg(LLM 최적화 프레임워크)과 K-SKILL(GitHub 34K+ stars, 한국 서비스 특화 스킬 번들) 개발자 김동규는 "Claw가 다음 인터페이스"라는 테제를 제시했다.

인터페이스 진화 사관:

• 인터넷 → 웹 페이지
• 스마트폰 → 모바일 앱
• AI 에이전트 → Agent (Claw가 OS, 스킬이 앱)

Anti-Agent vs Agent-Native​

"에이전트가 두 서비스 중 하나를 골라야 할 때 — 10단계 + 10만 토큰 vs 단일 API 콜 — 항상 후자를 선택한다. 에이전트가 쓰기 어려운 서비스는 그냥 우회된다."

HTML은 불필요해진다​

데이터를 그대로 주고받는 것이 agent 입장에서 최적이다. HTML 렌더링은 사람을 위한 것이고, agent에게는 순수한 데이터가 더 빠르고 효율적이다. API로 구매하는 것이 당연히 더 빠른 것처럼, 인터넷은 **"HTML for humans"**에서 **"data for agents"**로 진화할 것이다.

한국의 "디지털 갈라파고스"가 오히려 강점​

카카오맵, 쿠팡, 네이버, KTX/SRT 등 한국 생태계는 외국 에이전트가 접근 불가. K-SKILL처럼 한국 특화 스킬 레이어가 필수적이며, 하나의 주요 플랫폼(예: 쿠팡)이 Agent-Native가 되면 전체 전환이 빠르게 일어날 수 있다.

Agent 시대의 보안​

에이전트를 인증 가능한 독립 ID로 취급해야 하며, "김동규의 에이전트"가 암호학적으로 검증 가능해야 한다. 에이전트가 영속적 개인정보를 갖지 않고 매 세션 컨텍스트를 새로 구성하는 법인(法人) 모델도 제안됨.

5. Fireside Chat — 에이전트 커머스와 미래 (Illia × Jeff Wang)​

개발 워크플로우의 변화​

GitHub 이슈 등록 → 에이전트가 자동 계획 수립 → 개발자는 "이 방향이 맞는가" 판단에 집중. 6개월 전 코드 작성이 자동화됐고, 1년 내 코드 리뷰마저 사라질 것으로 전망.

비용이 진짜 문제다​

AI 코딩 도구 비용이 개발자 1인당 월 $5,000까지 상승 중. 1만 명 기준 연 ~$6억으로 CFO 레벨 의사결정 사안. 오픈소스 모델·특화 모델 조합으로의 전환과 에이전트 하네스의 자동 모델 라우팅이 핵심 과제.

에이전트 마켓플레이스​

market.near.ai — 에이전트가 다른 에이전트를 고용하고 작업을 입찰하는 Upwork 방식. Fiverr 대비 5배 저렴, 이틀 → 1시간. IronClaw의 TEE(신뢰 실행 환경)로 분쟁 시 검증 가능한 감사 추적 확보.

비기술 업무: 태스크가 아니라 목표를 줘라​

개별 태스크(이메일 발송)가 아닌 측정 가능한 목표(신규 고객 30명 확보)를 부여하면 에이전트가 방법을 스스로 탐색·반복한다. Devin을 활용해 특정 국가 임원 이메일 스캔 → 30건 가입 달성까지 반복한 실제 사례 소개.

Key Takeaways​

• 경쟁 전선이 이동했다: 모델 성능 → 실행·제어 레이어(하네스). Transformer 논문 저자가 하네스를 만들고, 프론티어 랩들이 오픈소스 하네스 패턴을 따라가는 구조적 전환이 진행 중
• 보안은 Convenience의 반대가 아니다: IronClaw의 WASM 격리, 암호화 자격증명, 가상 파일시스템은 편의성을 희생하지 않으면서 근본적인 보안 문제를 해결하는 접근
• 에이전트 운영은 사람 관리와 같다: 최소 1개월 온보딩, 증거 기반 보고, 모니터링 필수. Rule-base 봇으로 자율성을 끌어올리되, 뭘 덜어낼지 고민할 것
• Agent-Native가 새로운 PMF: 에이전트가 쓰기 어려운 서비스는 우회된다. 데이터를 그대로 주고받는 것이 HTML 렌더링보다 중요해지는 시대
• 비용 최적화가 채택의 관건: 월 $5K/인 시대에 모델 라우팅·오픈소스 조합이 필수. 하네스가 이 최적화를 자동으로 수행해야 함

세션 녹화 및 미팅노트​

tiro 팀의 도움으로 전체 세션의 미팅노트가 제공됩니다.

• 전체 세션 유튜브 녹화
• 정구봉 — Welcome 미팅노트
• Illia Polosukhin — Intro to IronClaw 미팅노트
• Yeachan Heo — War Stories From My Weird Family 미팅노트
• Jeffrey Kim — CLAW Is All You Need 미팅노트
• Fireside Chat — Illia × Jeff 미팅노트

References​

• IronClaw GitHub
• Hermes Agent
• K-SKILL GitHub
• OmC (Oh My Claude Code)
• 이전 후기: Ralphthon x ULW Wrapup 컨퍼런스

TL;DR​

보안 연구자 Can Boluk는 LLM의 코드 편집 인터페이스(하네스)만 개선하여 16개 모델의 성능을 극적으로 향상시켰다. "Hashline"이라는 새로운 편집 도구는 각 코드 줄에 2~3자리 해시를 부여해 정확한 문자열 재현 없이 줄 참조를 가능하게 했다. 그 결과 Grok Code Fast 1 모델은 6.7%에서 68.3%로 성능이 급증했고, 평균 출력 토큰은 20% 감소했다. 모델 자체는 전혀 변경하지 않고 도구 인터페이스만 바꾼 성과다.

Key Takeaways​

• 하네스(Harness) 설계가 모델 성능의 병목: 어떤 모델이 가장 우수한가보다 모델과 코드베이스 간 인터페이스가 실제 성능을 좌우한다. Claude나 OpenAI의 기본 도구는 특정 모델에 최적화되어 있어 다른 모델에선 실패율이 50% 이상 발생한다.
• 줄 해시 기반 참조의 혁신: Hashline은 정확한 문자열 매칭 대신 2~3자리 해시로 코드 줄을 식별해, 모델이 긴 문자열을 재현할 필요를 없앴다. 이는 토큰 효율성과 편집 정확도를 동시에 개선한다.
• 모델 비의존적 최적화: 동일한 하네스 개선이 GPT-4o, Claude Sonnet, Gemini 등 15개 이상의 모델에서 일관되게 성능 향상을 보였다. 이는 프롬프트 엔지니어링보다 도구 인터페이스 설계가 더 범용적인 개선 방법임을 시사한다.
• 실무 적용 가능성: 기존 str_replace나 apply_patch 도구의 한계(긴 인덴트 처리, 특수문자 이스케이핑 등)를 인지하고, 간단한 해시 기반 인터페이스로 대체하면 즉각적인 성능 개선이 가능하다.
• 토큰 경제성: 출력 토큰 20% 감소는 비용 절감뿐 아니라 응답 속도 개선으로 이어지며, 이는 프로덕션 환경에서 직접적인 사용자 경험 향상으로 연결된다.

상세 내용​

하네스 문제: 간과된 병목 지점​

AI 코딩 어시스턴트 논의는 대부분 "어떤 모델이 최고인가"에 집중한다. GPT-5.3 vs Opus, Gemini vs 이번 주 출시된 신모델. 하지만 Can Boluk는 이 프레임이 근본적으로 오해를 유발한다고 지적한다. 실제 병목은 훨씬 평범한 곳에 있다: 하네스(harness).

하네스는 단순한 UI가 아니다. 모든 입력 토큰의 소스이자, 모델의 출력과 실제 코드베이스 변경 사이의 인터페이스다. Claude Code는 여전히 서브에이전트 출력에서 원시 JSONL을 유출하며 수십만 토큰을 낭비한다. 도구 스키마, 에러 메시지, 상태 관리 등 "모델이 무엇을 바꿀지 안다"와 "문제가 실제로 해결된다" 사이의 모든 것이 하네스 영역이며, 실무에서 대부분의 실패가 발생하는 지점이다.

Boluk는 오픈소스 코딩 에이전트 Pi의 포크인 oh-my-pi를 유지보수하며 1,300개 이상의 커밋을 작성했다. 모델 비의존적 설계 덕분에 모델은 단순한 파라미터가 되고, 진짜 변수는 하네스가 된다. 바로 여기서 "상상 이상의 제어권"을 행사할 수 있다.

기존 편집 도구의 한계​

현재 주류 편집 도구는 두 가지다:

1. OpenAI Codex의 apply_patch OpenAI 특화 diff 형식의 문자열 블롭을 입력받는다. 구조화된 스키마가 아닌 엄격한 규칙을 따르는 텍스트다. OpenAI 게이트웨이에서 토큰 선택 프로세스가 이 구조에 맞게 편향되어 있을 것으로 추정되지만, 다른 모델에 적용하면 패치 실패율이 급증한다. Grok 4는 50.7%, GLM-4.7은 46.2%의 실패율을 기록했다. 모델이 나쁜 게 아니라 "언어를 모르는" 것이다.

2. Claude Code의 str_replace 대부분의 도구가 채택한 방식이다. "이 정확한 문자열을 찾아서 저것으로 교체해라." 간단하지만 치명적인 문제들이 있다:

• 인덴테이션 지옥: 긴 인덴트를 포함한 문자열을 정확히 재현해야 함
• 특수문자 이스케이핑: JSON/XML 컨텍스트에서 따옴표, 개행 등을 올바르게 이스케이프해야 함
• 토큰 낭비: 변경하려는 줄 전체를 두 번(원본과 교체본) 재현해야 함
• 미묘한 불일치: 공백 하나 차이로 전체 편집이 실패

이런 도구들은 특정 모델(GPT 계열, Claude 계열)에 최적화되어 있어, 다른 모델은 구조적으로 불리한 위치에 놓인다.

Hashline: 해시 기반 줄 참조​

Boluk의 해결책은 우아하게 단순하다. 파일의 각 줄에 2~3자리 해시를 부여한다:

1:a3|function hello() {
2:f1|  return "world";
3:0e|}

모델이 편집을 요청할 때는 이렇게 말한다:

"2:f1 줄을 다음으로 교체: return 'universe';"

정확한 문자열 재현이 필요 없다. 해시가 줄을 고유하게 식별하므로, 모델은 짧은 참조만으로 위치를 지정할 수 있다. 이는:

• 토큰 효율성: 긴 문자열 재현 불필요
• 오류 감소: 인덴트나 이스케이핑 실수 원천 차단
• 범용성: 모델 특화 편향 없이 모든 LLM이 동일하게 사용 가능

벤치마크 결과: 극적인 성능 향상​

결과는 놀라웠다:

• Grok Code Fast 1: 6.7% → 68.3% (10배 이상 향상)
• 전체 모델 평균 출력 토큰: 약 20% 감소
• 16개 모델 전반에 걸친 일관된 개선

중요한 점은 모델 가중치를 전혀 건드리지 않았다는 것이다. 파인튜닝도, 프롬프트 대수술도 없었다. 순전히 편집 도구 하나만 바꿨다.

이는 현재 LLM 코딩 성능 논의가 얼마나 잘못된 지점에 집중하고 있는지 보여준다. "어떤 모델이 최고인가"보다 "어떤 인터페이스로 모델을 활용하는가"가 실제 성능을 좌우한다.

실무적 시사점​

1. 하네스 설계는 모델 선택만큼 중요하다 프로덕션 코딩 어시스턴트를 구축한다면, 모델 API 선택에 쏟는 시간만큼 도구 인터페이스 설계에 투자해야 한다. 기존 도구(str_replace, apply_patch)의 한계를 이해하고, 당신의 유즈케이스에 맞는 인터페이스를 설계하라.

2. 모델 비의존적 최적화의 가치 Hashline의 개선은 GPT, Claude, Gemini, Grok 등 다양한 모델군에 걸쳐 작동했다. 특정 모델에 종속된 최적화보다 범용적인 인터페이스 개선이 장기적으로 더 큰 가치를 제공한다. 모델은 계속 바뀌지만, 좋은 하네스는 남는다.

3. 토큰 경제성과 사용자 경험 20% 토큰 감소는 단순 비용 절감이 아니다. 응답 속도가 빨라지고, 컨텍스트 윈도우를 더 효율적으로 사용할 수 있으며, 사용자는 더 빠른 피드백을 받는다. 토큰 레벨의 최적화가 직접적인 UX 개선으로 이어진다.

4. 오픈소스와 실험의 중요성 Boluk의 발견은 상업적 제품(Claude Code, Cursor 등)이 놓친 지점이다. 모델 비의존적인 오픈소스 하네스에서 자유롭게 실험할 수 있었기에 가능했다. AI 인프라 스택에서 오픈소스 레이어의 가치를 재확인하는 사례다.

더 넓은 맥락: Harness Engineering의 부상​

Hashline 실험은 새로운 엔지니어링 디시플린의 필요성을 보여준다: Harness Engineering. 프롬프트 엔지니어링이 모델에게 "무엇을 요청할지"를 다룬다면, 하네스 엔지니어링은 "어떻게 상호작용할지"를 설계한다.

좋은 하네스는:

• 모델의 출력을 실행 가능한 액션으로 신뢰성 있게 변환한다
• 토큰 효율성을 극대화한다
• 다양한 모델에 걸쳐 작동한다
• 에러 핸들링과 상태 관리를 우아하게 처리한다

이는 단순한 UI/UX 문제가 아니다. 분산 시스템 설계, API 설계, 컴파일러 인터페이스 설계와 맥을 같이하는 시스템 엔지니어링 문제다.

결론: 도구가 모델만큼 중요하다​

Can Boluk의 실험은 명확한 메시지를 전달한다: 당신의 AI 시스템 성능은 가장 약한 고리, 즉 하네스에 의해 결정된다. 최신 최고 모델을 사용하더라도, 형편없는 편집 인터페이스는 그 잠재력을 절반도 끌어내지 못한다.

실무 AI 엔지니어로서 우리는 모델 선택뿐 아니라 인터페이스 설계에 진지하게 투자해야 한다. Hashline은 하나의 예시일 뿐이다. 당신의 도메인, 당신의 워크플로우에는 또 다른 "해시라인"이 기다리고 있을 수 있다. 모델 벤치마크를 쫓는 대신, 하네스를 해킹하라.

References​

• I Improved 15 LLMs at Coding in One Afternoon. Only the Harness Changed. - Can Boluk
• oh-my-pi - GitHub Repository (추정)
• Pi - Original Open-Source Coding Agent (추정)

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

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

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

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

개념의 진화 과정​

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도 공식 보고서를 발표하면서 용어가 빠르게 확산되었습니다.

하네스의 핵심 구성 요소​

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

1. 저장소 구조와 컨벤션

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

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

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

3. 외부 도구 연결 (MCP)

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

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

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

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

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

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

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

컨텍스트 실패 패턴:

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

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

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

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

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

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

MCP 서버 연결 방식:

1. HTTP 원격 서버 (권장):

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

2. 로컬 stdio 서버:

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

3. 환경 변수 전달:

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은 디렉터리 이름과 일치, 소문자-하이픈만 사용

실무 적용 시나리오​

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

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

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

References​

• OpenAI: Harness engineering: leveraging Codex in an agent-first world (2026.02)
• Can Boluk: I Improved 15 LLMs at Coding in One Afternoon (2026.02)
• MadPlay: 프롬프트와 컨텍스트를 넘어, AI 에이전트를 위한 하네스 엔지니어링
• MadPlay: 컨텍스트 엔지니어링: 프롬프트를 넘어 맥락을 설계하는 방법
• MadPlay: Claude Code에서 MCP 서버를 연동하는 방법과 주의할 점
• MadPlay: 에이전트 스킬(Agent Skills)이란 무엇이고, 어떻게 만들까
• Agent Skills Official Specification
• Anthropic: Context Engineering Guide