JYP Garden

하네스 엔지니어링 종합 레퍼런스

Properties1
tagssource, harness-engineering, agentic-architecture, ai-tech-trend, knowledge

8 min read

하네스 엔지니어링 종합 레퍼런스

Source: docs/references/HARNESS_ENGINEERING_REFERENCE.md (seed 문서, raw/ 저장 생략) Type: local (교육자료 제작용 종합 레퍼런스, 수집 기준일 2026-04-15) By: 편집팀 (Martin Fowler, Anthropic Engineering, OpenAI Engineering, Stripe Dev Blog, HumanLayer 등 종합) Valid as of: 2026-04-15

핵심 Takeaway

  • Agent = Model + Harness — 모델은 추론, 하네스는 환경·툴·안전 담당. 모델 없이 하네스도 없고, 하네스 없이 에이전트도 없다 (출처: §1.1)
  • Guides(피드포워드) + Sensors(피드백) — 행동 전 조향과 행동 후 관찰의 2축 제어. Keep Quality Left로 수정 비용 최소화 (출처: §2.1-2.3)
  • Initializer + Coding Agent 패턴: 초기화 에이전트가 진행 파일·피처 목록 설정 → Coding 에이전트가 세션마다 상태 픽업해 한 피처씩 완주 (출처: §3.4, §11.3)
  • Blueprints(Stripe): 결정론적 노드와 에이전틱 노드 명시적 분리. “LLM을 제한된 박스에 → 시스템 전체 신뢰성 복합” (출처: §11.2)
  • 2026 패러다임 전환: Prompt → Context → Harness Engineering — “시스템이 모델을 운영한다” (출처: §0.2, §11.2)

상세 요약

Chapter 0 — 왜 하네스 엔지니어링인가

바이브코딩(Vibe Coding)은 Andrej Karpathy가 2025년 2월 창시. 급속 확산 후 한계 노출: AI 생성 코드 보안 취약점 45%, 코드 중복 48% 증가, 신뢰율 3%만이 높음. 경험 많은 개발자가 AI 사용 시 19% 더 느려짐(METR 2025). (Valid as of: 2026-04-15)

Prompt Engineering (2022–2024): 단일 모델 호출 최적화
Context Engineering (2025): 모델이 보는 것 관리
Harness Engineering (2026): 에이전트 실행 전체 환경 설계

Karpathy는 “바이브코딩”을 퇴역시키고 **에이전틱 엔지니어링(Agentic Engineering)**을 후속으로 제시: 개발자는 99%의 시간에 코드를 직접 작성하지 않고 에이전트를 오케스트레이션.

참고: harness-engineering

Chapter 1 — 하네스 엔지니어링 정의

핵심 공식: Agent = Model + Harness

  • Model(뇌): 추론, 텍스트 생성
  • Harness(운영체제): 환경 인식, 툴 오케스트레이션, 에러 복구, 안전 제약

Cobus Greyling의 컴퓨터 아날로지: CPU=LLM, RAM=컨텍스트 창, OS=하네스.

2026년 핵심 전환: 모델이 기존 프레임워크 역할 80% 흡수. 남은 20%(영속성, 결정론적 재실행, 비용 제어, 옵저버빌리티, 에러 복구)가 하네스 영역.

두 겹의 하네스(martin-fowler): Builder Harness(코딩 에이전트 제작사 구축) + User Harness(사용자 직접 구축). 두 목표: ① 첫 시도 성공률 향상 ② 자가 수정 피드백 루프로 인간 도달 전 이슈 수정.

Chapter 2 — Guides & Sensors

guides-sensors 참조.

Keep Quality Left: 품질 검사를 개발 라이프사이클의 가능한 왼쪽(이른 시점)에 배치할수록 수정 비용 낮아짐.

실행 유형: Computational(결정론적, 빠름·저렴, 테스트/린터) vs Inferential(비결정론적, 느리고 비쌈, AI 코드 리뷰).

인간 역할은 하네스를 반복적으로 개선하는 스티어링 루프 — 이슈 반복 시 피드포워드/피드백 컨트롤 추가.

Chapter 3 — 하네스 6개 핵심 컴포넌트

  1. Tool Integration Layer — MCP 표준, 3계층 권한(읽기전용/상태변경/명시적 승인). 추론과 권한 집행 분리.
  2. Memory & State Management — 세션 컨텍스트 / Skills+Playbooks / CLAUDE.md(영속) 3유형. Anthropic: 진행 파일+git으로 세션 간 브릿지.
  3. Context Engineering — 동적 컨텍스트 큐레이션. Big Prompt Chaos 방지 → Structured Context 4레이어(Commands/Skills/Memory/Subagents). 컨텍스트 창 0-50%/50-70%/70-90%/90%+ 4단계 관리.
  4. Planning & Decomposition — initializer-coding-agent 패턴.
  5. Verification & Guardrails — 권한 경계·유효성 검사·아키텍처 제약·속도 제한. LangChain 실험: 하네스 변경만으로 52.8%→66.5% 성능 향상.
  6. Modularity & Extensibility — 플러그형 컴포넌트, 독립 교체 가능.

Chapter 6 — CLAUDE.md / AGENTS.md 실전 가이드

ETH Zurich 연구(138개 에이전트파일, 2026): LLM 자동 생성 파일 → 성능 악화+비용 20%↑. 인간 직접 작성 → ~4% 향상. 코드베이스 개요·디렉토리 목록은 효과 없음.

작성 원칙: 자동 생성 금지 / Less is more(60줄 이하) / 점진적 공개(Skills로 분리) / 장기 진실만.

Chapter 10 — 에이전트 워크플로우 5패턴

Prompt Chaining → Routing → Parallelization → Orchestrator-Workers → Evaluator-Optimizer.

Anthropic 3원칙: 단순성 유지 / 투명성 우선 / ACI(에이전트-컴퓨터 인터페이스) 신중 설계.

Chapter 11 — 사례 연구

openai-codex 팀: 7명, 5개월, ~100만 줄 코드, 인간 작성 코드 0줄. 핵심: AGENTS.md + 커스텀 린터 + 엔트로피 관리. “에이전트는 어렵지 않다. 하네스가 어렵다.” — Ryan Lopopolo.

stripe Minions: 주당 1,000+ PR. blueprints 패턴. Shift Left — Pre-push 훅 1초 미만, CI 최대 2번.

anthropic 장기 실행 에이전트: claude.ai 클론 실험 → initializer-coding-agent 패턴 도출.

Chapter 14 — 실전 구축 로드맵

Step 1: 권한 매니페스트 → Step 2: CLAUDE.md → Step 3: 피드백 루프 → Step 4: 가드레일 → Step 5: 옵저버빌리티 → Step 6: 인간 체크포인트.

점진적 도입: Phase 1(기초: CLAUDE.md+hooks) → Phase 2(심화: Commands+Skills) → Phase 3(자동화: Subagents+MCP) → Phase 4(오케스트레이션: Agent Teams+CI).

연결되는 위키 페이지

그래프 뷰