하네스 엔지니어링 배우기 - 신뢰할 수 있는 AI 코딩 에이전트를 만드는 5개 서브시스템
목차
개요
learn-harness-engineering는 신뢰할 수 있는 AI 코딩 에이전트 시스템을 구축하는 방법을 가르치는 오픈소스 강좌입니다. 이 저장소는 12개의 강의(lecture), 6개의 실습 프로젝트(project), 그리고 자료 라이브러리로 구성됩니다. 초점은 “하네스 엔지니어링(harness engineering)”, 즉 AI 에이전트가 일관되고 검증 가능한 결과를 내도록 만드는 환경과 구조에 있습니다.
핵심 전제는 명확합니다. “모델은 똑똑하지만, 하네스가 모델을 신뢰할 수 있게 만든다(The model is smart, the harness makes it reliable).” 잘 설계된 하네스는 에이전트를 불안정한 출력을 내는 도구에서, 여러 세션에 걸쳐 실제 엔지니어링 작업을 완수하는 시스템으로 바꿉니다.
강좌가 인용하는 통제 실험이 이를 뒷받침합니다. Anthropic의 실험에서 동일한 모델(Opus 4.5)이 게임 에디터를 만들 때, 하네스 구조가 없으면 실패하고 있으면 성공했습니다. 모델이 바뀐 것이 아니라, 작업을 다스리는 환경이 극적으로 개선되었기 때문입니다.
핵심 내용
하네스의 5개 서브시스템
강좌는 서로 연결된 다섯 가지 구성 요소를 강조합니다.
| 서브시스템 | 역할 |
|---|---|
| Instructions | AGENTS.md, CLAUDE.md 등 점진적 공개 파일로 무엇을 어떤 순서로 할지 지시 |
| State | progress.md, 피처 목록, git 히스토리로 세션 간 진행 상황 유지 |
| Verification | 테스트, 린팅, 타입 체크, 엔드투엔드 파이프라인으로 실행 가능한 증거 확보 |
| Scope | 한 번에 하나의 피처로 제한하고 명시적 “완료” 정의 부여 |
| Session Lifecycle | 초기화, 실행, 정리 단계로 각 세션을 구조화 |
이 다섯 가지는 독립적으로 존재하지 않고 상호 보완적으로 작동합니다. 지시가 방향을 주고, 상태가 연속성을 보장하며, 검증이 결과를 증명하고, 범위가 과욕을 막으며, 세션 수명 주기가 매 작업을 깔끔하게 마무리합니다.
핵심 원칙
강좌가 다루는 원칙은 다음과 같습니다.
첫째, 제약 기반 설계입니다. 에이전트에 무제한 자율성을 주는 대신, 명시적 규칙과 경계로 할 수 있는 것과 없는 것을 정의합니다. 이는 과신이나 범위 확장에서 비롯되는 오류를 막습니다.
둘째, 상태 관리입니다. 장기 세션과 다단계 작업 전반에 걸쳐 맥락을 유지합니다. “기록의 원천으로서의 저장소(repository as system of record)” 접근은 에이전트가 오랜 기간 작업할 때 연속성을 보장합니다.
셋째, 테스트를 통한 검증입니다. 엔드투엔드 테스트와 자기 점검 메커니즘이 결과를 검증합니다. 에이전트가 왜 성급하게 성공을 선언하는지, 그리고 이를 어떻게 막을지를 다룹니다.
넷째, 관측 가능성(observability)입니다. 내장된 모니터링과 디버깅 기능으로 개발자가 에이전트 동작을 실시간으로 이해할 수 있습니다.
다섯째, 클린 상태 프로토콜입니다. 모든 세션은 깔끔하게 종료되어, 누적된 오류나 오염된 컨텍스트가 다음 실행으로 넘어가지 않게 해야 합니다.
강의 구성
12개 강의는 개념을 다룹니다.
| 강의 | 주제 |
|---|---|
| L01-L02 | 문제 정의와 기초 개념 |
| L03-L04 | 저장소 구조와 점진적 정보 공개 |
| L05-L06 | 다중 세션 연속성과 초기화 |
| L07-L08 | 범위 경계와 기계 판독 가능한 피처 목록 |
| L09-L10 | 검증 격차와 엔드투엔드 테스트 |
| L11-L12 | 관측 가능성과 세션 정리 |
6개 프로젝트는 Electron 기반 개인 지식 베이스 앱을 각 단계마다 발전시키며 진행됩니다. P01은 프롬프트 전용 방식과 규칙 우선(rules-first) 방식을 비교합니다. P02는 에이전트가 읽기 좋은 작업 공간으로 재구성합니다. P03은 다중 세션 연속성을, P04는 런타임 피드백과 범위 제어를, P05는 자기 검증 메커니즘을 다룹니다. P06은 전체 하네스를 통합하는 캡스톤 프로젝트입니다.
자료 라이브러리는 즉시 적용 가능한 다국어 템플릿을 제공합니다. AGENTS.md와 CLAUDE.md 템플릿, feature_list.json 구조, init.sh 초기화 스크립트, 검증 체크리스트가 포함되며 13개 언어로 제공됩니다.
의미와 시사점
이 강좌의 메시지는 모델 성능 경쟁에 가려진 실용적 진실을 짚습니다. 에이전트의 신뢰성은 모델을 더 똑똑하게 만드는 것이 아니라, 모델을 둘러싼 환경을 체계적으로 설계하는 데서 나온다는 것입니다. 이미 코딩 에이전트를 사용하는 엔지니어와 에이전트 환경 설계를 연구하는 사람을 주 대상으로 합니다.
특히 “왜 에이전트가 성급하게 작업 완료를 선언하는가”라는 문제를 정면으로 다루는 점이 인상적입니다. 검증 격차를 메우는 엔드투엔드 테스트와 자기 점검은 실무에서 곧바로 통하는 처방입니다.
결론
learn-harness-engineering는 하네스 엔지니어링을 Instructions, State, Verification, Scope, Session Lifecycle의 다섯 서브시스템으로 정리합니다. 12개 강의, 6개 프로젝트, 다국어 템플릿 라이브러리를 통해 개념부터 실습까지 체계적으로 안내합니다. “모델은 똑똑하지만 하네스가 신뢰성을 만든다”는 전제 아래, 에이전트의 신뢰성을 환경 설계의 문제로 재정의한 실용적 커리큘럼입니다.