ai-boost/awesome-harness-engineering

신뢰할 수 있는 AI 에이전트 하네스(harness)를 구축하기 위한 큐레이션된 리소스, 패턴 및 템플릿.

Deutsch | English | Español | Français | 日本語 | 한국어 | Português | Русский | 中文

**하네스 엔지니어링 (Harness engineering)**은 AI 에이전트를 둘러싸고 있어 해당 에이전트가 실제 작업에서 성공할지 실패할지를 결정하는 스캐폴딩(scaffolding) — 즉, 컨텍스트 전달, 도구 인터페이스, 계획 아티팩트, 검증 루프, 메모리 시스템, 샌드박스 —를 설계하는 학문입니다.

이 목록은 모델 자체가 아니라 하네스에 초점을 맞춥니다. 여기에 있는 모든 구성 요소는 모델 혼자 힘으로는 할 수 없기 때문에 존재하며, 최고의 하네스는 이러한 구성 요소들이 모델 개선과 함께 불필요해질 것임을 알면서 설계됩니다.

• 📐 기초 (Foundations)

• 🧩 디자인 프리미티브 (Design Primitives)

• 🔄 에이전트 루프 (Agent Loop)

• 🗺️ 계획 및 작업 분해 (Planning & Task Decomposition)

• 📦 컨텍스트 전달 및 압축 (Context Delivery & Compaction)

• 🔧 도구 설계 (Tool Design)

• 🔌 스킬 및 MCP (Skills & MCP)

• 🛡️ 권한 및 인증 (Permissions & Authorization)

• 🧠 메모리 및 상태 (Memory & State)

• ⚙️ 작업 실행기 및 오케스트레이션 (Task Runners & Orchestration)

• ✔️ 검증 및 CI 통합 (Verification & CI Integration)

• 👁️ 관측 가능성 및 추적 (Observability & Tracing)

• 🐛 디버깅 및 개발자 경험 (Debugging & Developer Experience)

• 🧑💼 휴먼-인-더-루프 (Human-in-the-Loop)

• 🔍 참고 구현 사례 (Reference Implementations)

• 🔒 보안, 샌드박스 및 권한 (Security, Sandbox & Permissions)

• ✅ 평가 및 검증 (Evals & Verification)

• 📋 템플릿 (Templates)

• 📚 관련 Awesome 리스트 (Related Awesome Lists)

• 🤝 기여 (Contributing)

하네스 엔지니어링이 무엇이며 왜 중요한지를 정의하는 정석적인 에세이들입니다.

• Harness Engineering — 하네스 엔지니어링 (Harness Engineering): 하네스 엔지니어링을 하나의 학문 분야로 정의한 OpenAI의 프레임워크입니다. 에이전트 우선 (agent-first) 세상에서 Codex 및 유사한 에이전트들이 안정적으로 작동할 수 있도록 하는 스캐폴딩 (scaffolding)을 설계하는 방법을 다룹니다.

• Unrolling the Codex Agent Loop — Codex 에이전트 루프 (agent loop)에 대한 OpenAI의 상세 분석입니다. 각 하네스 구성 요소를 노출하고 개선 가능한 지점을 제시합니다.

• Run Long-Horizon Tasks with Codex — 장기적 과제 계획 (long-horizon task planning)을 위한 OpenAI의 실무 가이드입니다. 재사용 가능한 하네스 산출물 (artifacts)로서 Plan.md, Implement.md, Documentation.md를 소개합니다.

• Building Effective Agents — 에이전트 아키텍처 (agent architecture)에 관한 Anthropic의 기초 가이드입니다. 워크플로우 (workflows)와 에이전트 (agents)를 언제 사용할 것인지, 그리고 프리미티브 (primitives)를 어떻게 조합할 것인지를 다룹니다.

• Harness Design for Long-Running Application Development — 지속적이고 다중 세션인 개발 과제를 위한 하네스 설계에 관한 Anthropic의 엔지니어링 블로그입니다. 핵심 통찰: 모든 하네스 구성 요소는 모델이 무언가를 할 수 없다고 가정하며, 그 가정은 유효 기간이 있습니다.

• Writing Effective Tools for Agents — 도구 인터페이스 (tool interface) 설계에 관한 Anthropic의 가이드입니다. 명명 규칙 (naming), 스키마 (schemas), 에러 표면 (error surfaces), 그리고 도구 설계가 곧 에이전트 UX라는 원칙을 다룹니다.

• Beyond Permission Prompts — 자연어 권한 텍스트에 의존하는 대신, 에이전트 하네스 내에 구조화된 권한 및 인가 (authorization) 시스템을 구축하는 방법에 관한 Anthropic의 견해입니다.

• Demystifying Evals for AI Agents — 에이전트 행동 평가를 위한 Anthropic의 프레임워크입니다. 무엇을 측정할 것인지, 평가 하네스 (eval harnesses)를 어떻게 구축할 것인지, 그리고 왜 에이전트에게 유닛 테스트 (unit-test) 스타일의 평가가 실패하는지를 다룹니다.

• What is an AI Agent? — 에이전트가 실제로 무엇인지에 대한 명확한 모델을 바탕으로 하네스 설계 결정을 고정하는 데 유용한 Anthropic의 정의적 글입니다.

• Agent Development Kit: Making it easy to build multi-agent applications — 멀티 에이전트 애플리케이션 구축을 용이하게 하기 위한 Google의 ADK 발표 및 설계 근거입니다. 프레임워크를 형성한 멀티 에이전트 토폴로지 (topology), 도구 등록 모델, 평가 파이프라인 (eval pipeline)을 설명합니다. Anthropic/OpenAI의 프레임워크에 Google의 프로덕션 관점을 더해 보완해 줍니다.

• Harness Engineering — Harness engineering(하네스 엔지니어링) 실무가 어떤 모습인지에 대한 Martin Fowler의 종합적 견해: 세 가지 맞물린 시스템 — context engineering (에이전트가 아는 정보를 큐레이션함), architectural constraints (결정론적 린터(linter) 및 구조적 테스트), 그리고 entropy management (문서 드리프트(documentation drift)를 복구하는 주기적 에이전트)로 구성됩니다. 개별 출력물을 검사하는 대신 에이전트 환경을 설계하고 유지 관리하는 하네스 엔지니어를 뜻하는 "humans on the loop" 프레임워크는 이 학문이 실제로 무엇을 수반하는지에 대한 가장 명확한 개념적 지도입니다.

• The Anatomy of an Agent Harness — 하네스를 구성하는 다섯 가지 프리미티브(primitives)에 대한 LangChain의 구조적 분석: filesystem (지속 가능한 상태 + 에이전트 협업 표면), code execution (사전 설계된 솔루션 없는 자율적 문제 해결), sandbox (격리 + 검증), memory (세션 간 지속성), 그리고 context management ("context rot"에 대비한 압축)입니다. co-evolution(공진화)에 대한 경고 — 특정 하네스로 학습된 모델은 해당 설계에 과적합(overfitted)될 수 있다는 점 — 는 왜 하네스 아키텍처의 선택이 즉각적인 작업을 넘어 지속적인 영향을 미치는지 설명해 줍니다.

• Building AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned — 터미널 네이티브 코딩 에이전트 하네스 설계에 관한 최초의 체계적인 실무자 논문: eager-construction scaffolding (첫 호출 지연 시간과 레이스 컨디션(race conditions)을 제거하기 위해 첫 메시지 전 모든 구성 요소를 사전 구축), compound multi-model architecture (실행, 추론, 비판 및 비전 작업을 위한 서로 다른 모델 인스턴스), 5계층 방어 심층(defense-in-depth) 안전성, 그리고 schema-filtered planning subagents (런타임 권한 확인 대신 도구 스키마를 통해 행동 제약 사항을 강제함)를 다룹니다. OpenDev를 구축하며 추출한 다섯 가지 교훈은 모든 서버 측 에이전트 하네스에 적용됩니다.

• 자연어 에이전트 하네스 (Natural-Language Agent Harnesses) — 에이전트 제어 로직을 공유된 지능형 하네스 런타임 (Intelligent Harness Runtime)에 의해 실행되는 휴대 가능한 자연어 아티팩트 (NLAHs)로 외부화할 것을 제안합니다. 이를 통해 하네스 설계가 맞춤형 컨트롤러 코드에 묻히는 대신, 연구되고 전송 및 재현될 수 있도록 합니다. 프레임워크 기본 설정에 흩어져 있거나 검사, 버전 관리 또는 전송이 불가능한 하드코딩된 컨트롤러 로직으로 인해 발생하는 하네스 취약성의 근본 원인을 직접적으로 해결합니다.

• Ranking Engineer Agent (REA): 광고 랭킹을 위한 Meta의 자율 AI 시스템 — 컨텍스트를 잃지 않고 중단된 6시간 작업을 재개할 수 있도록 '휴면 및 깨우기 (hibernate-and-wake)' 체크포인팅을 사용하는 다일(multi-day) ML 파이프라인 자동화를 위한 Meta의 프로덕션 하네스입니다. 개별 턴(turn)이 모델의 컨텍스트 제한을 초과할 수 있지만 전체 파이프라인은 며칠에 걸쳐 일관성을 유지해야 하는 과학적 워크플로를 위한 하네스 설계를 보여줍니다.

• AI 에이전트 강화하기: 새로운 ADK 통합 생태계 — 에이전트 개발 키트 (Agent Development Kit)의 2026년 업데이트로, 생태계 통합(Hugging Face, GitHub, Daytona, Notion 등)을 확장하고 오케스트레이션 하네스가 결정론 (determinism)이나 상태 일관성 (state coherence)을 잃지 않으면서 외부 서비스를 연결하는 참조 패턴을 제공합니다.

• 2026 에이전틱 코딩 트렌드 보고서 — 인프라 구성을 일급 최적화 변수 (first-class optimization variable)로 식별한 Anthropic의 산업 벤치마크입니다. 하네스 설정만으로도 벤치마크 점수가 5%포인트 이상 변동될 수 있습니다. 단일 에이전트에서 오케스트레이션된 멀티 에이전트 팀으로의 전환을 기록하며, 에이전트 프레임워크와 프로덕션 배포 인프라 사이의 간극을 메우는 "에이전틱 엔지니어링 플랫폼 (agentic engineering platform)" 카테고리를 소개합니다.

• 에이전틱 워크플로를 통한 Azure SRE 에이전트 구축 방법 — 35,000건 이상의 프로덕션 인시던트를 자율적으로 처리하여 Azure App Service의 완화 시간 (time-to-mitigation)을 40.5시간에서 3분으로 단축한 Microsoft 에이전트의 아키텍처 워크스루입니다.

인간 참여형 (human-in-the-loop) 거버넌스를 갖춘 단일 에이전트 하네스 (agent harness)로 MCP 도구, 텔레메트리 (telemetry), 코드 저장소, 그리고 장애 관리 플랫폼을 통합하는 과정을 문서화합니다. 2026년에 발표된 가장 데이터 기반적인 프로덕션 하네스 (production harness) 사례 연구입니다.

• 신뢰할 수 있는 AI 에이전트를 위한 컨텍스트 엔지니어링 (Context Engineering): Azure SRE 에이전트 구축 사례 — 100개 이상의 맞춤형 도구와 규정적인 프롬프트 (prescriptive prompt) 방식에서 SRE 에이전트를 위한 파일 시스템 기반 컨텍스트 엔지니어링 시스템으로 전환한 Microsoft의 기록입니다. 핵심 발견 사항: 모든 것(소스 코드, 런북 (runbooks), 쿼리 스키마, 과거 조사 노트)을 파일로 노출하고 에이전트가 read_file, grep, find, shell을 사용하게 하는 것이 특화된 도구들을 사용하는 것보다 성능이 뛰어났습니다 — 새로운 장애 발생 시 "의도 충족 (Intent Met)" 점수가 45%에서 75%로 상승했습니다.
• 하네스 엔지니어링 (Harness Engineering): AI 보조 개발을 위한 구조화된 워크플로우 — 하네스 엔지니어링에 대한 Red Hat의 기업 관점 (2026년 4월 7일): AI가 작업하는 환경을 설계할 때 AI는 더 나은 코드를 작성합니다. 자유 형식의 티켓 (free-form tickets)보다 구조화된 컨텍스트를 강조하며, MCP 통합(CI 상태, 배포 로그, 런타임 메트릭)을 실제 데이터 소스로 활용하여 에이전트의 도구 상자를 확장하고, 인간과 에이전트가 협업하는 방식을 조직하기 위한 4대 기둥 모델(vibes, specs, skills, agents)을 제시합니다.
• 코딩 에이전트 사용자를 위한 하네스 엔지니어링 — 코딩 에이전트 하네스에 대한 Birgitta Böckeler의 체계적인 멘탈 모델 (2026년 4월): 하네스를 출력이 인간의 눈에 도달하기 전에 스스로 수정하는 피드포워드 가이드 (feedforward guides) 및 피드백 센서 (feedback sensors)로 정의합니다. 계산적 제어 (computational controls, 예: linters, tests)와 추론적 제어 (inferential ones, 예: LLM-as-judge)를 구분하며, 하네스 가능성 (harnessability)이 기술 및 아키텍처 결정에서 일급 시민 (first-class criterion)이 되어야 한다고 주장합니다.
• AI 에이전트 구축을 위한 실무 가이드 — 프로덕션 배포 패턴을 실행 가능한 베스트 프랙티스로 요약한 OpenAI의 2026년 4월 종합 가이드: 단일 에이전트 대 다중 에이전트 오케스트레이션 (single-agent vs. multi-agent orchestration, 매니저 대

분산형 핸드오프 (decentralized handoffs)), 다대다 에이전트-도구 관계를 위한 도구 설계 (tool design), 그리고 입력 검증 (input validation), 출력 필터링 (output filtering), 도구 위험 등급 (tool-risk ratings), 인간 개입 트리거 (human-intervention triggers)를 결합한 계층적 가드레일 패턴 (layered guardrail patterns).

• 최근 Claude Code 품질 보고서 업데이트 — Anthropic의 투명한 2026년 4월 사후 분석 (postmortem) 보고서는 Claude Code의 품질 저하 원인을 세 가지 독립적인 하네스(harness) 수준의 변경 사항으로 추적합니다: 기본 추론 노력 (reasoning-effort) 하향 조정, 오래된 세션에서 사고 이력 (thinking history)을 지속적으로 삭제하는 캐싱 최적화 버그 (caching-optimization bug), 그리고 지나치게 공격적인 장황함 제한 (verbosity-limiting) 시스템 프롬프트입니다. 프롬프트 문구, 캐시 헤더, 기본 파라미터와 같이 겉보기에 사소한 하네스 조정이 어떻게 눈에 보이는 에이전트 퇴보 (agent regressions)로 누적될 수 있는지, 그리고 이를 격리하기 위해 필요한 엄격한 진단 프로세스를 이해하기 위한 필수 독서 자료입니다.

하네스 구성 요소는 벤더(vendor)가 아닌 해결하려는 문제에 따라 정리되었습니다.

• ReAct: 언어 모델에서의 추론과 행동의 시너지 (Synergizing Reasoning and Acting in Language Models) — 거의 모든 에이전트 하네스의 기초가 되는 사고/행동/관찰 (Thought/Action/Observation) 루프 구조를 정의한 기초 논문입니다. 루프가 왜 현재와 같은 구조로 설계되었는지, 그리고 각 하네스 구성 요소가 추론-행동 사이클의 어느 부분에 매핑되는지 이해하기 위한 필수 독서 자료입니다.
• Codex 에이전트 루프 풀기 (Unrolling the Codex Agent Loop) — 하나의 에이전트 루프 반복 내에서 발생하는 일(관찰, 계획, 행동, 검증)에 대한 정전적 분해 (canonical decomposition)입니다.
• LangGraph — 저수준 개념 (Low Level Concepts) — 에이전트 루프를 타입화된 상태 (typed state), 조건부 엣지 (conditional edges), 체크포인팅 (checkpointing)을 갖춘 유향 그래프 (directed graph)로 명시적으로 모델링합니다. 루프 제어 흐름 (loop control flow)에 대한 가장 구체적인 엔지니어링 처리 방식입니다: 종료 조건 구현, 도구 결과에 따른 분기, 재개를 위한 루프 중간 상태 유지 방법 등을 다룹니다.
• Codex 하네스 잠금 해제: 앱 서버 구축 방법 (Unlocking the Codex Harness: How We Built the App Server) — 모든 클라이언트 인터페이스에 Codex 하네스를 노출하는 Item/Turn/Thread 프로토콜 (stdio를 통한 JSON-RPC/JSONL)에 대한 OpenAI의 엔지니어링 심층 분석입니다.

승인 흐름(approval flows), 스트리밍 차분(streaming diffs), 그리고 스레드 지속성(thread persistence)이 왜 목적에 맞게 설계된 프로토콜을 요구하는지, 그리고 왜 MCP의 도구 중심 모델이 이러한 요구 사항에 불충분했는지에 대한 가장 직접적인 제3자(first-party) 설명입니다.

• Extended Thinking — Claude API Docs — 에이전트 루프(agent loops)에 확장된 사고(extended thinking)를 통합하기 위한 하네스(harness) 핵심 참조 자료:
  budget_tokens는 턴당 추론 깊이를 제어하며, 도구 결과(tool results)를 다시 전달할 때 사고 블록(thinking blocks)은 반드시 보존되어야 합니다 (이를 조용히 누락하면 다단계 추론이 깨집니다). 또한, 사고 모드(thinking mode)는 턴 중간에 변경될 수 없습니다. 확장된 사고를 어떠한 도구 사용 루프(tool-use loop)에 연결하기 전에 반드시 확인해야 할 필수 사항입니다.

• Improving Deep Agents with Harness Engineering — 모델 교체 없이 하네스(harness)의 변경만으로 코딩 에이전트를 Terminal Bench 2.0에서 30위에서 상위 5위로 끌어올린 LangChain의 사례 연구: 구조화된 검증 루프(structured verification loops), 컨텍스트 주입(context injection, 디렉토리 맵 + 시간 예산 경고), 루프 탐지 미들웨어(loop-detection middleware), 그리고 계획 및 검증 단계에 최대의 사고를 집중시키는 "추론 샌드위치(reasoning sandwich)"를 포함합니다. 이는 하네스 설계가 모델 성능이 아닌, 주요 성능 레버(performance lever)라는 점을 보여주는 가장 구체적으로 발표된 입증 사례입니다.

• How Middleware Lets You Customize Your Agent Harness — AgentMiddleware를 소개합니다: 여섯 가지의 조합 가능한 훅(composable hooks) (before_agent, before_model, wrap_model_call, wrap_tool_call, after_model, after_agent)