원문: walkinglabs/learn-harness-engineering · 수집일: 2026-08-23
핵심 요지
walkinglabs의 MIT 라이선스 오픈소스 코스(★13.7k, 포크 1.4k, 250 커밋, 수집 시점)로, “모델은 똑똑하고 하네스가 신뢰성을 만든다”는 명제를 강의 14개 + 프로젝트 8개로 체계화한다. 15개 언어 번역(한국어 포함)을 제공하며 문서 사이트는 https://walkinglabs.github.io/learn-harness-engineering/ 다.
핵심 주장:
- 세상 가장 강한 모델도 적절한 환경(하네스) 없이는 실제 엔지니어링 작업에서 실패한다 — “This isn’t a model problem. It’s a harness problem.” ^raw source:
2026-08-23-github-walkinglabs-learn-harness-engineering - 근거로 Anthropic 통제 실험을 인용: 동일 모델(Opus 4.5), 동일 프롬프트(“2D 레트로 게임 에디터 제작”)에서 하네스 없이는 200/6시간 만에 플레이 가능한 게임. OpenAI도 잘 하네스된 저장소에서 동일 모델이 “unreliable → reliable”로 정성적 전환한다고 보고.
- “The MODEL decides what code to write. The HARNESS governs when, where, and how it writes it.” — 하네스는 모델을 똑똑하게 만드는 게 아니라 출력을 신뢰할 수 있게 만든다.
하네스 5대 서브시스템
| 서브시스템 | 역할 | 예 |
|---|---|---|
| Instructions | 무엇을 어떤 순서로 할지 — 거대 파일 하나가 아니라 progressive disclosure | AGENTS.md, CLAUDE.md, docs/ |
| State | 한 일·진행 중·다음 일을 디스크에 영속화해 세션 간 연속성 확보 | progress.md, feature_list.json, git log |
| Verification | 통과하는 테스트만 증거 — 에이전트는 증명 없이 승리 선언 불가 | tests, lint, type-check, e2e |
| Scope | 한 번에 한 피처, 명시적 완료 정의, feature list 재작성 은폐 금지 | feature_list.json 경계 |
| Session Lifecycle | 시작 시 init.sh, 종료 시 clean-state 체크리스트와 handoff note | init.sh |
즉시 적용 퀵스타트로는 프로젝트 루트에 AGENTS.md·init.sh·feature_list.json·claude-progress.md 4파일만 두면 세션 안정성이 크게 개선된다고 주장하며, skills/harness-creator/ 스킬이 이 구조를 자동 스캐폴딩해 준다.
주요 내용
커리큘럼 (Phase 1→8). 문제 인식(L01-02/P01: 프롬프트만 vs rules-first 비교) → 저장소 구조화(L03-04/P02: repo가 single source of truth, progressive disclosure) → 세션 연결(L05-06/P03: 진행 로그 영속화·초기화 단계 분리) → 피드백·범위(L07-08/P04: 과잉실행 방지, feature list를 하네스 primitive로) → 검증(L09-10/P05: confidence ≠ correctness, 풀파이프라인 실행만 실검증) → 통합 캡스톤(L11-12/P06: 관측 가능성·깨끗한 핸드오프) → 루프(L13/P07) → 그래프(L14/P08). 모든 프로젝트는 동일한 Electron 개인 지식베이스 앱을 단계적으로 진화시키며 P(N+1) starter = P(N) solution 구조다.
Loop Engineering (2026-07 추가). L13 “Why You Need to Stop Prompting Your Agent” — 루프 엔지니어링 6 primitives(automations, worktrees, skills, connectors, sub-agents, external state), generator/evaluator 분리, 목표 루프·타이머 루프·maker-checker 루프를 단계 실험하는 P07. 코스의 정식화: “Harness engineering builds the vehicle. Loop engineering designs the road.”
Graph Engineering (2026-08 추가). L14 — prompt→context→loop→graph의 4계층 스택, 그래프의 4구성요소(nodes, edges, shared state, routing), 규모 확장 시 in-loop 체크포인트로 못 고치는 3가지 구조적 실패(Goodhart, 상위에 대한 실명, 충돌), orchestration tax와 “그래프를 그릴 가치가 있는 때”. “루프는 노드 1개짜리 그래프”라는 정식화가 loop-engineering 개념과 직접 이어진다.
Frontier Harness Design Breakdowns (2026-08 신섹션). 코스의 5-subsystem 프레임워크로 실제 제품 하네스 4종을 역설계:
- Pi — 최소 커널 + 프로그래매티블 확장 + context engineering
- Claude Code — 4계층 메모리, 5단계 compaction, hooks, sub-agent isolation
- Codex — 저장소가 source of truth, AGENTS.md 디렉터리 페이지, worktree isolation
- DeepSeek — “everything is a plugin”, capability seam, event pipeline
해석과 적용 메모
- 이 저장소는 볼트의 하네스 계열 노트(2026-05-24-agent-harness-engineering-survey의 ETCLOVG 7계층, 2026-04-19-anatomy-of-agent-harness)와 같은 주제를 학습자 친화적 커리큘럼으로 재포장한 것. 서베이 논문 대비 이론 깊이는 얕지만 5-subsystem 프레임이 실무 적용 관문으로 적합.
- 인용 1차 자료(OpenAI harness engineering 글, Anthropic 장기 실행 에이전트 하네스 글 2편, awesome-harness-engineering)는 이미 볼트에 관련 노트가 있는 것들과 겹치므로 교차 검증 지점이 됨.
- Frontier Breakdowns의 Claude Code·Codex·DeepSeek 해부는 deepseek-harness, 2026-08-15-x-deepseek-harness-developer-preview 등 기존 심층 노트와 대조해 보면 제품별 설계 차이를 빠르게 파악할 수 있다.
- L14의 “그래프를 그릴 가치가 있는 때” 판단 기준은 2026-07-19-loop-engineering-to-graph-engineering 에세이의 비판적 관점(앵커 없는 그래프는 순환적으로 실패)과 함께 읽으면 균형이 맞음.
누락·접근 제한
- README 후반부(Agent Session Lifecycle 도표 이후, Skills·Other Courses 섹션)는 webfetch 응답 잘림으로 미수집.
- 개별 강의 14편·프로젝트 8편의 본문은 미수집 — 필요시
docs/en/lectures/,docs/en/projects/에서 후속 인제스트 가능. - 스타/포크 수는 2026-08-23 수집 시점 값.
관련 노트
- moc-ai-agents-harness — 하네스 설계 전체 지도
- loop-engineering — L13/P07이 다루는 루프 엔지니어링 개념
- 2026-05-24-agent-harness-engineering-survey — 같은 주제의 학술 서베이 (ETCLOVG)
- 2026-07-19-loop-engineering-to-graph-engineering — L14의 그래프 전환론에 대한 비판적 에세이
- deepseek-harness — Frontier Breakdowns 중 DeepSeek 편과 대조 가능한 심층 분석