Awesome Harness Engineering

요약

ai-boost/awesome-harness-engineering는 AI 에이전트를 감싸는 harness를 모델과 분리된 독립 공학 분야로 규정하고, 관련 자료 385개를 문제 단위로 분류한 GitHub awesome-list다. harness는 모델을 감싸 도구와 verification, 상태를 제공하는 실행 환경을 뜻한다. 목록은 본문 8개 절로 나뉘며, 그중 Design Primitives가 12개 하위 절 218개 항목으로 가장 크다.

이 목록의 특징은 분류 기준에 있다. 대부분의 에이전트 목록이 OpenAI, Anthropic, Google 같은 벤더나 프레임워크 이름으로 자료를 묶는 반면, 이 목록은 harness가 푸는 문제로 묶는다. README는 그 원칙을 "Harness components organized by the problem they solve, not by vendor"라고 명시한다. 라이선스는 CC0-1.0으로, 목록 전체가 public domain에 놓여 있어 인용과 재배포에 제약이 없다.

배경

harness engineering이라는 이름은 2026년 상반기에 여러 조직에서 거의 동시에 등장했다. OpenAI, Anthropic, Google, Red Hat, Martin Fowler 진영, LangChain, deepset이 각각 같은 문제를 다른 어휘로 정리했고, 여기에 arXiv 논문이 정의와 분류를 붙이기 시작했다. 자료는 늘었으나 어디서부터 읽어야 하는지, 어떤 글이 같은 문제를 다루는지는 흩어져 있었다.

이 목록은 그 흩어짐을 정리하려는 시도다. README 첫 문단이 분야의 범위를 직접 규정한다. harness engineering은 컨텍스트 전달, 도구 인터페이스, 계획 산출물, verification 루프, 메모리 시스템, 샌드박스를 설계하는 분야이며, 이 scaffolding이 에이전트가 실제 과제에서 성공하는지 실패하는지를 결정한다는 것이다. scaffold는 모델 주위에 짜 놓은 보조 실행 구조를 뜻한다.

목록 전체를 관통하는 전제도 첫 화면에 놓여 있다. 여기 수록된 모든 구성 요소는 모델이 혼자 해내지 못하기에 존재하며, 좋은 harness는 그 구성 요소가 모델 발전으로 언젠가 불필요해질 것을 알고 설계된다는 것이다. 이 전제는 harness를 영구 자산이 아니라 현재 모델의 결함에 대응하는 한시적 구조물로 본다.

핵심 개념

harness는 모델 호출을 감싸는 런타임 층 전체를 가리킨다. 목록이 수록한 arXiv 2606.10106은 그 필요충분조건을 네 가지로 규정한다. agent loop, 도구 인터페이스, 컨텍스트 관리, 제어 메커니즘이다. agent loop는 모델 호출에서 도구 실행, 관찰로 이어지는 기본 순환을 뜻한다. 이 네 가지를 모두 갖추어야 harness이고, 하나라도 빠지면 생성기나 가드레일, 단순 도구 래퍼로 분류된다. 논문은 이 기준을 Claude Code, Codex CLI, Aider, Cline, OpenHands, SWE-agent에 적용해 판정한다.

design primitive는 harness를 구성하는 문제 단위 요소를 뜻한다. 이 목록은 그것을 12가지로 나누고, 각 자료를 벤더가 아니라 이 12가지 중 어디에 속하는지로 분류한다. 같은 회사의 문서라도 다루는 문제가 다르면 다른 절에 놓인다. 예를 들어 Anthropic의 Writing Effective Tools for Agents는 Tool Design에, Compaction 문서는 Context Delivery & Compaction에 들어간다.

compaction은 길어진 대화 이력을 요약으로 접어 컨텍스트 한계 안에서 세션을 이어가는 처리다. 목록은 이 처리를 harness의 핵심 관심사로 다루며, 서버 측 자동 compaction부터 에이전트가 스스로 시점을 고르는 방식까지 25개 항목을 모았다.

meta-harness는 harness 자체를 생성하거나 최적화하는 상위 도구를 뜻한다. 사람이 harness를 손으로 조율하는 대신, 실패 사례를 모아 harness 구성을 자동으로 고치는 계열이며 목록은 이를 별도 하위 절로 분리했다.

목록의 구조

최상위 구성과 규모

본문은 8개 절로 나뉜다. 각 절의 항목 수는 다음과 같다.

전체 링크 항목은 385개이고, Templates 절은 링크가 아니라 레포 안의 파일 4개를 표로 제시한다. 절 하나가 목록의 절반을 넘는 구조인데, Design Primitives 218개가 그렇다. 나머지 7개 절을 모두 더해도 167개다. 이 편중은 목록의 목적이 자료 수집이 아니라 문제 분해에 있음을 보여준다.

README는 zdoc.app을 통해 9개 언어 번역본을 연결한다. 독일어, 영어, 스페인어, 프랑스어, 일본어, 한국어, 포르투갈어, 러시아어, 중국어다. 감사의 글은 harness engineering 아이디어가 논의되고 다듬어진 자리로 linux.do 테크 커뮤니티를 든다.

목차와 본문 사이에 불일치가 하나 있다. 상단 Contents 목록에는 Production Infrastructure & Operations 절이 빠져 있으나, 본문에는 16개 항목을 가진 절로 실재한다. 목차를 따라 훑으면 운영 관련 자료를 통째로 놓친다.

분야를 정의한 문헌

Foundations 28개 항목은 harness engineering이 무엇인지를 각자 다른 어휘로 정의한 글을 모은다. 정의가 하나로 수렴하지는 않으나, 서로를 대체하기보다 보완한다. 주요 정의를 나란히 놓으면 다음과 같다.

마지막 항목은 공개 에이전트 시스템 70개를 실증 분석해 다섯 가지 아키텍처 패턴을 뽑아낸 논문이다. 목록은 이 연구를 harness 선택이 프레임워크 인기 투표에서 설계 트레이드오프 비교로 넘어가는 계기로 소개한다.

Foundations에는 실패 사례도 들어 있다. Anthropic의 2026년 4월 postmortem은 Claude Code 품질 저하의 원인을 세 가지 harness 수준 변경으로 추적한다. reasoning effort 기본값 하향, 오래된 세션에서 사고 이력을 계속 떨어뜨린 캐싱 최적화 버그, 지나치게 공격적인 축약 지시문이다. 프롬프트 문구와 캐시 헤더, 기본 파라미터 같은 사소해 보이는 조정이 겹쳐 눈에 보이는 성능 저하로 이어질 수 있음을 보여주는 사례다.

design primitive 12가지

Design Primitives는 harness를 12개 문제로 쪼갠다. 하위 절의 규모와 대표 항목은 다음과 같다.

가장 큰 두 하위 절은 Skills & MCP 32개와 Task Runners & Orchestration 31개다. 앞의 것은 에이전트에 능력을 붙이는 규약을, 뒤의 것은 여러 에이전트와 도구의 실행을 조율하는 층을 다룬다. 두 절을 합치면 63개로 Design Primitives의 약 29%를 차지한다.

Agent Loop 절은 이론과 구현을 함께 놓는다. ReAct 논문이 Thought, Action, Observation 순환의 원형을 제공하고, LangGraph는 그 순환을 타입이 붙은 상태와 조건부 간선, 체크포인트를 갖춘 방향 그래프로 모델링한다. LangChain의 미들웨어 글은 before_agent, before_model, wrap_model_call, wrap_tool_call, after_model, after_agent 여섯 개 훅으로 루프의 모든 단계를 가로채는 설계를 제시한다. 프롬프트로 부탁하는 대신 결정적 코드로 강제하는 방식이며, 개인정보 마스킹처럼 프롬프트에 맡길 수 없는 처리에 쓴다.

Context Delivery & Compaction 절은 컨텍스트를 압축 문제가 아니라 탐색 문제로 다시 보는 흐름을 담는다. Token Savior는 코드베이스를 함수와 클래스, 호출 그래프 단위로 인덱싱해 에이전트가 파일 전체를 읽는 대신 포인터로 이동하게 한다. Trellis는 비대해진 단일 지시 파일(instruction file)을 단계별로 필요한 규약과 태스크 명세, 세션 기록만 불러오는 구조로 대체한다. OpenViking은 메모리와 리소스, 스킬을 파일시스템 형태로 통합해 에이전트가 필요한 경로만 가져가게 한다.

Permissions & Authorization 절은 승인 피로 문제를 다룬다. Anthropic의 Claude Code Auto Mode 글은 사용자가 승인 요청의 93%를 그대로 승인한다는 관찰에서 출발한다. 승인 절차가 형식만 남았다는 뜻이다. 대안으로 제시된 것은 2단계 분류기로, 빠른 단일 토큰 판정을 먼저 돌리고 위험 표시가 붙은 행동에만 chain-of-thought 추론을 적용한다.

Human-in-the-Loop 절은 사람이 언제 개입해야 하는지를 계량한 자료를 모은다. AWS의 참고 구현은 민감한 tool call에 대한 승인 방식을 네 가지로 제시한다. 훅 기반 일괄 정책, 도구별 세밀 제어, Step Functions를 통한 비동기 외부 승인, MCP Elicitation을 이용한 규약 수준 실시간 승인이다. HiL-Bench는 잘 정의된 태스크에 현실적인 장애물을 3개에서 5개 주입하고 ask_human() 도구를 준 뒤, 에이전트가 도움을 요청할 시점을 아는지 측정한다.

참고 구현

Reference Implementations는 "각 항목에 왜 시간을 쓸 가치가 있는지 주석을 단다"는 원칙 아래 4개 하위 절로 나뉜다.

Tutorials 절의 Learn Harness Engineering은 이 wiki에도 별도 페이지가 있는 프로젝트 기반 강의 과정이다. 목록은 이를 각 모듈이 개념 요약 대신 동작하는 산출물을 만들어낸다는 이유로 추천한다.

Generators & Meta-Harnesses 절은 harness 조율을 사람 손에서 떼어내려는 시도를 모은다. Meta-Harness 논문은 지시문과 도구 정의, 컨텍스트 관리, 종료 조건 전체를 하나의 최적화 대상으로 묶고, 제안자 에이전트에게 과거 harness 후보와 점수, 실행 기록 전체를 파일시스템으로 열어준다. 진단용 컨텍스트가 이전 연구의 26,000 토큰에서 1,000만 토큰으로 늘어난 점이 핵심 차이다.

Demo Harnesses 절의 OpenHands는 런타임과 샌드박스 격리, 이벤트 스트림 메시지 버스, 에이전트 컨트롤러라는 3계층 구성으로 소개된다. 완성된 harness 하나를 통째로 읽고 싶을 때의 출발점 역할을 한다.

보안과 샌드박스

Security, Sandbox & Permissions는 33개 항목으로 Design Primitives를 뺀 절 가운데 가장 크다. 샌드박스 구현, prompt injection 방어, 인가 규약, 감사 도구가 함께 들어 있다.

샌드박스는 기동 시간과 상태 유지 방식으로 갈린다. E2B는 Firecracker microVM 기반으로 약 150ms 만에 기동하며 일회성 코드 실행에 맞춰져 있다. Daytona는 OCI 컨테이너 기반으로 90ms 미만에 기동하고 작업 디렉터리 상태를 기한 없이 유지해, 여러 세션에 걸쳐 같은 작업 공간을 쓰는 harness에 적합하다.

방어 자료 가운데 tldrsec/prompt-injection-defenses는 입력 검증, 도구 출력 정화, 카나리 토큰 등 실무 방어 기법의 목록으로 소개되며, 신뢰 경계를 점검하는 체크리스트 역할을 한다. OWASP LLM06:2025는 과도한 권한 부여, 불필요한 기능 노출, 승인 절차 부재를 excessive agency 위험으로 규정해 harness 권한 범위를 최소 권한 원칙과 대조할 기준을 제공한다.

Anthropic의 격리 관련 글은 모델 계층 방어만으로는 과잉 행동의 약 17%를 놓친다고 보고하며, 환경 격리가 1차 경계여야 한다고 주장한다. 허용 목록을 통한 데이터 유출 사례를 들어 가장 약한 지점이 샌드박스 자체가 아니라 그 주변의 harness 배관이라는 점을 짚는다.

평가와 검증

Evals & Verification 19개 항목은 벤치마크와 평가 harness를 함께 담는다. SWE-bench가 코딩 에이전트의 기준 벤치마크로, promptfoo와 DeepEval, Inspect AI가 자체 평가를 구성하는 도구로 들어 있다.

이 절에서 눈에 띄는 것은 평가 자체를 의심하는 자료들이다. AgentLens는 OpenHands trajectory 2,614건을 분석해 통과 사례의 최대 23.2%가 검증 없이 얻어걸린 통과였고, 과정 품질로 채점하면 모델 순위가 최대 5계단 이동한다고 보고한다. trajectory는 세션 하나의 실행 기록 전체를 뜻한다. Harness-Bench는 trajectory 5,194건을 근거로 에이전트 능력을 모델 단독이 아니라 모델과 harness의 조합 수준에서 보고해야 한다고 주장한다.

Anthropic의 인프라 노이즈 연구는 더 직접적이다. 컨테이너 자원 설정만 바꿔도 벤치마크 점수가 6%p 이상 흔들리며, 이 폭은 모델 사이의 격차를 넘는 경우가 있다. 지정 자원의 3배까지는 점수가 안정적이지만 그 위로는 에이전트가 전략 자체를 바꾼다. 자원 제한이 빡빡할 때와 넉넉할 때 측정하는 대상이 근본적으로 달라진다는 뜻이다.

운영 인프라

Production Infrastructure & Operations 16개 항목은 harness를 실제로 운영할 때 나오는 문제를 다룬다. Anthropic의 Claude Managed Agents 문서는 오케스트레이션 루프를 제공자 인프라에 두고 도구 실행만 고객 통제 샌드박스로 옮기는 배포 형태를 제시한다. AWS Agent Registry는 에이전트와 도구, 스킬, MCP 서버를 승인 절차와 감사 기록이 붙은 카탈로그로 관리한다.

비용도 이 절의 주제다. FinOps for Agents는 인프라 게이트웨이에서 강제하는 예산 통제 다섯 가지를 정의한다. 루프와 단계 상한, tool call 상한, 실행당 토큰 예산, 벽시계 시간 제한, 테넌트별 예산과 이상 알림이다. 비용 측정 단위를 소비 토큰이 아니라 수용된 결과 하나당 비용으로 옮기자는 제안도 함께 담긴다.

LangChain의 State of Agent Engineering 2026은 전문가 1,300명 이상을 대상으로 한 설문 결과를 담는다. 57.3%가 production에 에이전트를 두고 있고, 품질이 32%로 가장 큰 장벽이며, 89%가 관측 체계를 갖춘 반면 평가를 실제로 돌리는 곳은 52%에 그친다.

템플릿

Templates 절은 링크 대신 레포 안의 파일 4개를 제공한다. 목록 가운데 유일하게 곧바로 복사해 쓸 수 있는 산출물이다.

이 네 파일은 Foundations 절이 수록한 OpenAI의 장기 태스크 가이드와 같은 계보에 있다. 그 글이 Plan.md와 Implement.md, Documentation.md를 재사용 가능한 harness 산출물로 제안했고, Templates 절은 같은 성격의 파일을 레포 안에 직접 둔 형태다.

인접 목록

목록은 범위가 겹치는 다른 목록을 한 자리에 몰지 않고 세 곳에 나눠 배치한다. Related Awesome Lists 7개는 컨텍스트와 Claude Code, MCP 서버, 에이전트 프레임워크처럼 인접 주제를 다루는 목록이고, Adjacent Collections 6개는 harness를 정면으로 다루는 목록이며, 학술 서베이 계보는 Foundations에 들어간다.

harness가 성능을 좌우한다는 근거

목록이 "성능 레버는 모델 교체가 아니라 harness 설계에 있다"는 주장을 뒷받침하려고 모은 수치는 다음과 같다.

수치를 나란히 놓으면 두 가지가 드러난다. 첫째, harness만 바꿔 얻는 개선폭이 모델 세대 차이에 맞먹거나 그를 넘는 사례가 반복해서 나온다. statewright의 2/10에서 10/10, Deep Agents의 30위에서 5위 안쪽이 그렇다. 둘째, 개선의 성격이 두 가지로 나뉜다. 컨텍스트 관련 항목은 토큰 절감으로, 루프와 도구 관련 항목은 성공률 상승으로 나타난다.

production 사례도 같은 방향을 가리킨다. Meta의 Ranking Engineer Agent는 6시간짜리 태스크가 중간에 끊겨도 상태를 저장했다 재개하는 방식으로 여러 날에 걸친 파이프라인의 일관성을 유지한다. Microsoft의 Azure SRE Agent는 인시던트 35,000건 이상을 자율 처리했다. Meta와 Harvard의 Confucius Code Agent는 SWE-Bench-Pro에서 Resolve@1 59%를 기록했다. Stripe의 Minions는 주당 1,300건 이상의 PR을 내며, 결정적 코드 노드와 에이전트 하위 태스크를 번갈아 배치하는 청사진 방식과 500개 도구를 담은 중앙 MCP 서버로 운영된다.

수록 기준과 기여 규약

목록은 자신을 "디렉토리가 아니라 견해가 담긴 목록"으로 규정하고, 그 기준을 Contributing 절에 명시한다.

이 기준 덕분에 각 항목의 주석이 단순 소개를 넘어 판단을 담는다. 예를 들어 Skill Issue 항목의 주석은 대부분의 에이전트 실패가 모델 한계가 아니라 설정 문제라는 원문의 핵심 주장을 그대로 옮기고, MCP 서버를 너무 많이 붙이면 컨텍스트가 부풀어 오른다는 실무 지침까지 함께 적는다.

한계

awesome-list 특성상 각 항목에는 한두 문장의 주석만 붙는다. 실제 이해는 링크된 원본을 읽어야 하며, 이 wiki의 개별 페이지가 그 심화 역할을 맡는다.

링크가 전부 외부 URL이라 링크 부패 위험이 있다. 이 wiki는 웹 검색 금지 원칙에 따라 자동 수집을 하지 않으므로, 개별 자료를 파고들려면 사용자가 원본을 raw/로 옮겨야 한다.

2026년 상반기까지의 스냅샷이다. 수록 항목 다수가 2026년 2월에서 6월 사이 발표물이라 갱신 주기가 짧다. Contents 목록이 본문의 한 절을 반영하지 못한 것도 빠른 증분 갱신의 부작용으로 보인다.

수록 기준은 문서화되어 있으나 판정은 주관적이다. 항목 주석에 담긴 "가장 데이터로 뒷받침된 사례", "가장 실행 가능한 단일 페이지 종합" 같은 평가는 목록 관리자의 판단이며, 독자가 원본을 읽고 다시 판단할 여지를 남긴다.

핵심 용어

관련 페이지

이 목록은 wiki의 harness와 loop engineering 클러스터를 묶는 상위 인덱스 역할을 한다.

• Harness Engineering (Team Attention, 2026): 프롬프트에서 컨텍스트, harness로 이어지는 3단계 진화를 다룬 한국어 강의 자료
• Learn Harness Engineering: 이 목록의 Tutorials 절이 추천하는 프로젝트 기반 강의 과정
• Harness Updating Is Not Harness Benefit: Disentangling Evolution Capabilities in Self-Evolving LLM Agents: harness 갱신이 곧 이득인지를 통제 실험으로 분해
• You Can Learn AI Agent Harness & Loop Engineering In 19 Min | LLM Ops, Eval, Tracing, RAG: harness와 loop engineering의 관계를 정리
• Agent Lightning v1.0: Towards Harnessed Agentic RL: harness를 학습 대상으로 삼는 프레임워크
• Loop Engineering (Addy Osmani, 2026-06-07): 루프 설계로 무게중심을 옮기는 관점
• The Art of Loop Engineering (Sydney Runkle, 2026-06-16): 루프 설계 실무 정리
• 더 이상 Claude를 프롬프팅하지 않습니다 >> 하지만 프롬프트는 여전히 중요합니다: 프롬프트에서 컨텍스트, harness, 루프로 이어지는 흐름 정리
• The New SDLC With Vibe Coding: From ad-hoc prompting to Agentic Engineering: 에이전트를 모델과 harness의 합으로 보는 관점
• Effective Context Engineering for AI Agents: 이 목록 Context 절의 정본 문헌