Learn Harness Engineering 소개
Learn Harness Engineering은 AI 코딩 에이전트(coding agent)를 둘러싼 작업 환경을 어떻게 설계해야 모델이 실제 저장소에서 신뢰할 수 있게 동작하는지를 다루는 프로젝트 기반 강의입니다. 강력한 모델에 과제를 맡겨 본 사람이라면 익숙한 장면이 있습니다. 에이전트가 파일을 읽고 코드를 작성하며 그럴듯하게 진행하다가, 어느 순간 한 단계를 건너뛰고 테스트를 깨뜨린 채 "완료했습니다"라고 선언합니다. 강의는 이것을 모델의 문제가 아니라 하네스(harness)의 문제로 규정하고, 그 환경을 직접 만드는 방법을 가르칩니다.
여기서 말하는 하네스는 더 나은 프롬프트가 아니라, 모델이 그 안에서 작동하는 시스템 전체를 가리킵니다. 무엇을 어떤 순서로 할지 알려주는 지침, 무엇을 했고 무엇이 남았는지 디스크에 기록하는 상태, 통과한 테스트만 증거로 인정하는 검증, 한 번에 하나의 기능만 다루도록 제약하는 범위, 세션을 시작하고 깨끗하게 마무리하는 수명주기까지를 포함합니다. 모델은 어떤 코드를 쓸지 결정하고, 하네스는 그 코드를 언제 어디에 어떻게 쓸지를 통제합니다.
강의는 OpenAI의 Harness engineering: leveraging Codex in an agent-first world 와 Anthropic의 Effective harnesses for long-running agents, Harness design for long-running application development 같은 1차 자료를 참고 출처로 명시하고, 이를 12개의 이론 강의와 6개의 실습 프로젝트, 그리고 바로 가져다 쓸 수 있는 리소스 라이브러리로 정리했습니다. 한국어를 포함한 14개 언어로 번역되어 있어, 영어가 익숙하지 않아도 같은 내용을 모국어로 따라갈 수 있습니다.
Learn Harness Engineering이 정의하는 하네스의 다섯 가지 구성요소
강의는 하네스를 다섯 개의 하위 시스템으로 나눕니다. 각 시스템은 하나의 역할만 맡으며, 이 다섯 가지가 맞물려 에이전트의 동작을 통제합니다.
THE HARNESS PATTERN
===================
You --> 과제 부여 --> 에이전트가 하네스 파일을 읽음 --> 에이전트 실행
|
하네스가 모든 단계를 통제:
|
+--> 지침(Instructions): 무엇을, 어떤 순서로
+--> 범위(Scope): 한 번에 한 기능, 과욕 금지
+--> 상태(State): 진행 로그, 기능 목록, git 이력
+--> 검증(Verification): 테스트, 린트, 타입 체크
+--> 수명주기(Lifecycle): 시작 시 초기화, 끝에 클린 상태
|
v
검증을 통과해야만
에이전트가 멈춘다
- 지침(Instructions): 에이전트가 무엇을 어떤 순서로 해야 하는지, 시작 전에 무엇을 읽어야 하는지를 알려줍니다. 하나의 거대한 파일이 아니라, 에이전트가 필요할 때 찾아 들어가는 점진적 공개(progressive disclosure) 구조를 권합니다.
- 상태(State): 무엇이 끝났고 무엇이 진행 중이며 다음은 무엇인지를 디스크에 기록해, 다음 세션이 지난 세션이 멈춘 지점에서 이어가도록 합니다.
- 검증(Verification): 통과하는 테스트 스위트만 증거로 인정합니다. 에이전트는 실행 가능한 증거 없이 작업이 끝났다고 선언할 수 없습니다.
- 범위(Scope): 한 번에 하나의 기능만 다루도록 제약합니다. 세 가지를 절반씩 끝내거나 미완성을 숨기려 기능 목록을 고쳐 쓰는 일을 막습니다.
- 세션 수명주기(Session Lifecycle): 시작 시 환경을 초기화하고, 끝에 정리하며, 다음 세션을 위한 깨끗한 재시작 경로를 남깁니다.
두 번째 강의(L02)에서는 같은 하네스를 "주방" 비유로 다시 풀어 다섯 구역으로 설명합니다. 위 개요의 다섯 요소와 강조하는 축은 조금 다르지만, 모델 바깥의 엔지니어링 인프라 전체가 모델의 역량을 실제로 얼마나 끌어내는지를 좌우한다는 결론은 같습니다.
| 하위 시스템 | 주방 비유 | 핵심 역할 |
|---|---|---|
| 지시(Instructions) | 레시피 선반 | AGENTS.md/CLAUDE.md 에 프로젝트 개요, 기술 스택과 버전, 첫 실행 명령, 협상 불가 제약을 명시 |
| 도구(Tools) | 칼 랙 | 에이전트에 충분한 도구 접근권을 주되 최소 권한 원칙을 지킴 |
| 환경(Environment) | 가스레인지 | 의존성 잠금과 런타임 버전, 재현성을 확보 (lockfile, .python-version, Docker) |
| 상태(State) | 준비 스테이션 | PROGRESS.md 로 완료, 진행, 차단을 추적하고 세션 간 인계 |
| 피드백(Feedback) | 품질 확인 창 | AGENTS.md 에 검증 명령을 나열, 다섯 중 투자 대비 효과가 가장 큼 |
강의가 핵심 근거로 드는 사례 중 하나는 Anthropic이 공개한 하네스 설계 실험입니다. 같은 모델(Opus 4.5)에 "레벨 에디터와 스프라이트 에디터, 엔티티 동작, 플레이 가능한 테스트 모드를 갖춘 2D 레트로 게임 메이커를 만들어라" (원문: "Create a 2D retro game maker with features including a level editor, sprite editor, entity behaviors, and a playable test mode.")라는 한 문장 프롬프트를 주었을 때, 단일 에이전트로 돌린 경우 20분 동안 9달러를 쓰고도 핵심 기능이 동작하지 않았습니다. 반면 플래너와 제너레이터, 이밸류에이터(planner, generator, evaluator)로 구성된 세 에이전트 하네스를 붙이자, 같은 프롬프트가 16개 기능과 10개 스프린트 분량의 명세로 확장되며 6시간에 200달러를 들여 훨씬 완성도 높은 애플리케이션으로 이어졌습니다. 모델은 그대로였고 바뀐 것은 하네스뿐이라는 점이 강의의 출발점입니다.
Learn Harness Engineering의 강의 구성
강의는 순서대로 진행하도록 설계되어 있으며, 12개의 강의는 각각 하나의 핵심 질문에 답합니다. "강력한 모델이 왜 실제 과제에서 실패하는가"(L01)에서 시작해, 저장소를 단일 진실 원천(single source of truth)으로 삼는 이유(L03), 거대한 단일 지침 파일이 실패하는 이유(L04), 장기 작업이 연속성을 잃는 이유(L05), 에이전트가 너무 일찍 "완료"를 선언하는 이유(L09), 전체 파이프라인 실행만이 진짜 검증인 이유(L10), 모든 세션이 깨끗한 상태로 끝나야 하는 이유(L12)까지를 단계적으로 다룹니다.
이론에 이어지는 6개의 실습 프로젝트는 모두 같은 결과물 위에서 진행됩니다. 각 프로젝트의 해답이 다음 프로젝트의 시작점이 되어, 학습자가 하네스 기술을 쌓아 가는 동안 애플리케이션도 함께 진화합니다.
| 프로젝트 | 하는 일 | 적용하는 하네스 메커니즘 |
|---|---|---|
| P01 | 같은 과제를 프롬프트만으로, 그리고 규칙 우선으로 두 번 실행해 비교 | 최소 하네스: AGENTS.md + init.sh + feature_list.json |
| P02 | 에이전트가 읽을 수 있도록 저장소를 재구성 | 에이전트가 읽는 워크스페이스 + 영속 상태 파일 |
| P03 | 에이전트가 멈춘 지점에서 이어가도록 구성 | 진행 로그 + 세션 핸드오프 + 다중 세션 연속성 |
| P04 | 에이전트가 과하거나 부족하게 일하지 않도록 제어 | 런타임 피드백 + 범위 제어 + 증분 인덱싱 |
| P05 | 에이전트가 스스로 작업을 검증하도록 구성 | 자기 검증 + 근거 기반 Q&A + 증거 기반 완료 |
| P06 | 처음부터 완전한 하네스를 구축 (캡스톤) | 모든 메커니즘 + 관측 가능성 + 절제(ablation) 연구 |
Learn Harness Engineering의 캡스톤 프로젝트
여섯 개의 프로젝트는 모두 하나의 제품을 중심으로 돕니다. 바로 Electron 기반의 개인 지식 베이스(knowledge base) 데스크톱 앱 입니다. 이 앱은 로컬 문서를 가져오고, 문서 라이브러리를 관리하며, 문서를 처리해 색인하고, 가져온 내용에 대해 AI 기반 질의응답을 수행한 뒤, 인용과 함께 근거 있는 답변을 돌려주는 다섯 가지 핵심 기능을 갖습니다.
이 제품이 선택된 이유는 실용적 가치가 분명하면서도, 하네스 도입 전후의 차이를 관찰하기에 충분한 실제 제품 수준의 복잡도를 갖기 때문입니다. 각 프로젝트의 시작/해답 코드는 그 진화 단계에 해당하는 Electron 앱의 완전한 사본이며, P(N+1)의 시작점은 P(N)의 해답에서 파생됩니다.
Learn Harness Engineering 바로 적용하기
12개 강의를 모두 읽기 전에도 가치를 얻을 수 있습니다. 이미 실제 프로젝트에서 코딩 에이전트를 쓰고 있다면, 프롬프트만 던지는 대신 무엇을 할지, 무엇을 했는지, 어떻게 검증할지를 정의한 구조화된 파일 묶음을 저장소 안에 두는 것이 출발점입니다. 이 파일들이 저장소 안에 있으므로 모든 세션이 같은 상태에서 시작합니다.
YOUR PROJECT ROOT
├── AGENTS.md <-- 에이전트의 운영 매뉴얼
├── CLAUDE.md <-- (Claude Code를 쓸 경우의 대안)
├── init.sh <-- 설치 + 검증 + 시작을 실행
├── feature_list.json <-- 어떤 기능이 있고 무엇이 끝났는지
├── claude-progress.md <-- 매 세션 무슨 일이 있었는지
└── src/ <-- 실제 코드
리소스 라이브러리에서 이 시작 템플릿을 받아 프로젝트에 그대로 넣기만 하면, 프롬프트만으로 돌릴 때보다 세션이 한층 안정적이 됩니다. 저장소에는 직접 자신의 프로젝트용 하네스를 몇 분 만에 구성해 주는 skills/harness-creator/ 스킬도 포함되어 있습니다. 강의 사이트 자체는 VitePress로 만들어졌고, npm install 후 npm run docs:dev 로 로컬에서 미리 볼 수 있습니다.
Learn Harness Engineering의 한국어 강의 사이트
강의는 한국어로 완역되어 있어, 홈페이지부터 개별 강의, 리소스 라이브러리까지 한국어로 읽을 수 있습니다. 아래는 한국어 사이트의 홈페이지, 강의 01 본문, 리소스 모음 화면입니다.
한국어 사이트에는 핵심 개념의 한국어와 영어 대응을 정리한 용어집도 함께 제공되어, 하네스(harness)나 검증(verification) 같은 용어가 낯설어도 따라갈 수 있습니다. 강의는 Claude Code나 Codex처럼 파일 편집과 명령 실행, 다단계 작업을 지원하는 코딩 에이전트가 최소 하나 있어야 프로젝트를 실제로 완주할 수 있다는 점을 전제로 합니다.
Learn Harness Engineering의 라이선스
Learn Harness Engineering은 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
Learn Harness Engineering 한국어 강의 사이트
Learn Harness Engineering 프로젝트 GitHub 저장소
더 읽어보기
-
Agentic Harness Engineering(AHE): 관측 가능성 기반 코딩 에이전트 하네스의 자동 진화 프레임워크에 대한 연구
-
Harness: 도메인 프롬프트 입력로부터 Claude Code 에이전트 팀과 스킬을 자동 생성하는 메타 스킬
-
OpenAI가 공개한, 소프트웨어 개발 주기별 AI 네이티브 엔지니어링 팀 구축 가이드 (feat. Codex)
-
Context Hub: AI 코딩 에이전트의 API 환각을 막는 버전 관리 문서 허브 (feat. Andrew Ng)
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. 
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 