Harness Engineering: 코딩 에이전트의 환경을 설계하는 12개 논제와 플레이북 모음

9bow · 8월 14, 2026, 11:00오전

Harness Engineering 소개

같은 모델과 같은 코딩 에이전트를 쓰는데도 조직마다 결과물의 수준이 갈립니다. 모델을 바꾸거나 프롬프트를 다듬는 것 말고 어떤 레버가 남아 있는지는 대개 각 팀의 경험담으로만 돌아다닙니다. 조직이 실제로 요구하는 신뢰성과 보안, 호환성, 유지보수성, 성능, 운영 가능성 같은 비기능 요구사항은 어느 모델 가중치에도 들어 있지 않기 때문에, 그 요구사항을 에이전트가 꺼내 쓸 수 있는 형태로 옮기는 일은 결국 조직이 직접 해야 합니다.

Harness Engineering은 그 일을 하나의 실천으로 정리한 문서 저장소입니다. Ryan Lopopolo가 자신의 글과 발표, 인터뷰, 공개 포스트를 근거로 엮은 선집이자 현장 가이드이며, 동시에 코딩 에이전트에게 그대로 물릴 수 있는 컨텍스트 번들입니다. 저자가 정의하는 하네스 엔지니어링은 "에이전트 주변의 환경을 다듬어 에이전트의 출력을 개선하는 실천" 이고, 선택한 모델과 코딩 에이전트는 블랙박스로 고정한 상태에서 외부 레버 두 개인 컨텍스트와 도구, 그리고 그 둘을 둘러싼 환경만 개선합니다.

저장소는 12개 논제와 3종의 적용 절차, 그리고 출처 라이브러리로 구성되어 있습니다. 진입점인 저장소의 AGENTS.md 가 작업 성격에 따라 읽을 문서를 지정하기 때문에, 사람이 처음부터 끝까지 읽는 책으로도 쓰이고 에이전트가 필요한 논제만 꺼내 가는 검색 대상으로도 쓰입니다. 본 게시물에서는 이 저장소가 정의하는 하네스의 범위, 12개 논제의 요지, 저장소 구조와 라우팅 방식, 그리고 저자가 스스로 밝힌 근거의 한계를 정리합니다.

Harness Engineering이 정의하는 하네스

저자가 저장소 첫 줄에 인용해 둔 자신의 발언은 이 저장소의 존재 이유를 그대로 설명합니다. "대부분의 사람들은 자기 에이전트를 내 글과 트윗, 팟캐스트, 강연에 그냥 가리키기만 해도 에이전트의 출력을 100배 개선할 수 있다는 걸 모른다." 100배라는 수치는 저자 본인의 주장이며 저장소에 그 수치를 재현하는 측정값은 없습니다. 다만 그 주장의 형태가 저장소의 설계를 결정했습니다. 이 저장소는 사람이 읽는 산문이면서, 에이전트가 대상 시스템과 함께 읽도록 만들어진 자료입니다.

하네스가 감당해야 할 범위도 명시되어 있습니다. 작업자는 의도를 복원할 수 있어야 하고, 실제 시스템을 조작할 수 있어야 하고, 권한을 존중해야 하고, 결과를 증명할 수 있어야 하며, 다음 실행이 더 나은 조건에서 시작하도록 남겨 두어야 합니다. 환경의 중심 목적은 조직의 비기능 요구사항을 실어 나르는 것이고, 여기에는 그 요구사항을 어떻게 우선순위 매기고 절충하고 충족할지에 관한 로컬 결정까지 포함됩니다.

이 지점을 설명하는 비유로 저자는 프로세스 데이터의 빙산을 씁니다. 일반 모델 가중치에는 조직의 프로세스 데이터 중 수면 위로 보이는 끝부분만 들어 있습니다. 수면 아래에는 현재 운영 상태, 로컬 온톨로지, 품질 기준, 절차, 예외 처리 이력, 권한 관계가 잠겨 있고, 특정 업무를 하려면 에이전트에게 바로 이 부분이 필요합니다. 조직은 이 사적이고 계속 변하는 데이터가 일반 모델 가중치에 들어 있으리라고 전제할 수 없고, 어느 부분이 중요한지 에이전트가 알아서 직관하리라고 기대할 수도 없습니다. 하네스 엔지니어링은 그 데이터를 유능한 작업자에게 컨텍스트와 도구로 건네주는 마지막 구간의 작업입니다.

Harness Engineering의 12개 논제

논제 목록은 저장소의 docs/ 에 각각 별도 디렉토리로 전개되어 있고, 각 논제 페이지는 저자의 글과 강연, 구현 증거, 관련 연구로 논지를 발전시킵니다.

논제	요지
작업자를 고정하라	한 채택 주기 동안 모델과 코딩 에이전트를 블랙박스로 취급하고, 작업자가 바뀔 때 환경과 사람의 기대치를 다시 검증한다
사적 프로세스 데이터의 빙산에 배치하라	큰 응용 기회는 사적이고 변하는 프로세스 데이터에 의존하는 제도적 업무에 있다
한 에이전트에게 업무 전체를 주라	하나의 주 실행 흐름이 분해와 실행, 통합, 증명, 안전한 종료를 소유한다
컨텍스트를 적시에 라우팅하라	큰 탐색 가능한 지식 저장소와 작은 활성 작업 집합을 함께 유지한다
능력을 읽고 조작할 수 있게 만들라	도구는 발견, 선택, 호출, 해석, 복구, 실제 시스템 검증의 루프 전체를 통과해야 쓸 수 있다
저장소가 에이전트를 가르치게 하라	에이전트가 읽는 코드는 프롬프트 재료가 되며, 반복 구조와 예시, 타입, 실행 가능한 제약이 기준을 전달한다
명시된 권한 안에서 자율성을 최대화하라	능력과 권한을 별도 계약으로 두고, 되돌릴 수 있는 환경에서는 넓게 움직이게 한다
실제 환경에서 결과를 증명하라	통과한 검사는 그 검사가 주장하는 것만 증명하며, 브라우저 여정과 트레이스, 카나리는 서로 다른 루프를 닫는다
피드백을 인프라로 바꾸라	궤적 증거와 리뷰, 장애가 드러낸 교훈을 가장 이른 항구적 소유자에게 옮긴다
일관성을 보존하고 수명 위험을 소유하라	구현이 흔해질수록 미래의 일관성과 수명 소유가 희소해진다
알려진 업무는 연속 루프로 돌려라	신호와 증명, 권한이 갖춰진 업무는 저장소가 소유하는 루프로 넘기고, 미해결 제품 발명은 전면 작업으로 남긴다
측정된 효과를 기준으로 최적화하라	토큰과 코드 줄 수, 에이전트 수, 검사 수는 입력이며, 희소한 사람의 주의당 유용한 결과를 최적화한다

논제 사이의 관계도 문서에 드러납니다. 예를 들어 컨텍스트 라우팅 논제는 큰 지식 저장소와 작은 활성 작업 집합을 함께 두라고 요구하는데, 이 저장소 자체가 그 규칙을 자기 구조에 적용한 사례입니다.

Harness Engineering의 저장소 구조와 라우팅

저장소의 ARCHITECTURE.md 는 이 저장소를 "검색에 최적화된 컨텍스트 번들(a retrieval-optimized context bundle)" 로 규정합니다. 루트가 실천을 소개하고 독자를 라우팅하며, 에이전트 가이드가 대상별 결정을 라우팅하고, 논제 색인이 발전된 논지를 명명하며, 플레이북이 그것을 절차로 바꾸고, 출처 라이브러리가 근거를 보존합니다. 각 계층은 다음 깊이를 가리키기만 하고 그 계층의 일을 반복하지 않습니다.

에이전트가 이 저장소를 소비할 때 따르는 작업 루프는 여섯 단계로 정해져 있습니다. 대상의 지침과 아키텍처를 먼저 읽고, 대상의 실제 도메인 모델과 매니페스트, 도구, 테스트, 권한, 운영 이력을 조사하고, 로컬 증거만으로 해결되지 않는 지배적 결정을 이름 붙이고, 그때 논제 하나를 골라 읽습니다. 그다음은 대상 로컬의 사실이 구현을 지배하게 두고, 파일 배치나 정책, 버전 고정, 픽스처를 복사하지 않은 채 개념만 적응시키며, 마지막으로 대상 시스템의 자체 검사와 관찰 가능한 사용자 여정으로 결과를 검증합니다. 미해결 결정이 남아 있지 않으면 논제를 읽지 않고 그대로 진행하라는 지시도 함께 붙어 있습니다.

이 구조에서 흥미로운 규칙은 활성 작업 집합을 일부러 작게 유지한다는 점입니다. 원본 코퍼스는 기본 작업 집합에 포함되지 않으며, 사례와 1차 출처는 더 깊은 추론이나 주장 추적, 귀속이 필요할 때만 열립니다. 대상 시스템에 이 저장소를 컨텍스트로 붙일 때는 저장소를 읽기 전용으로 취급하라는 조건도 명시되어 있습니다.

Harness Engineering의 플레이북과 평가 절차

논제가 주장이라면 플레이북은 그 주장을 실행 절차로 바꾼 부분입니다. 저장소는 세 가지를 제공합니다.

업무	절차
경계가 뚜렷한 대표 업무 하나의 하네스를 개선	`playbooks/improve-harness.md`
저장소 전체에서 여러 여정과 소유 경계를 검토	`playbooks/repository-review.md`
조건을 비교하거나 시간에 따른 변화를 측정	`evals/`

첫 번째 절차는 대표 궤적 하나를 관찰해 가장 이른 실패 핸드오프를 찾고, 그 소유 경계에서 승인된 최소 개입을 되돌릴 수 있는 형태로 적용한 뒤, 새로 실행해 유지·수정·제거를 결정하는 루프입니다. 개입의 가치가 불분명하면 개입을 뺀 조건으로도 시험하라는 조건이 붙어 있습니다.

근거의 상태를 저자가 직접 밝혀 둔 대목은 이 저장소를 평가할 때 중요합니다. 플레이북 색인은 앞의 두 절차가 이 선집을 위해 구성된 편집적 종합이며 Ryan이 발표한 플레이북이 아니라고 적고, 저장소에 두 절차의 종단간 적용 기록이 아직 없다고 명시합니다. 반면 평가 쪽에는 evals/artichoke-state-modeling.md 처럼 공개된 종단 사례가 들어 있어, 주장과 검증된 사례가 저장소 안에서 구분되어 있습니다.

Harness Engineering과 기존 접근의 비교

이 저장소의 위치는 무엇을 바꾸려 하는지로 갈립니다. 세 접근의 대상이 서로 다릅니다.

접근	바꾸는 대상	이 저장소에서의 취급
모델·에이전트 교체	작업자 자체	한 채택 주기 동안 고정하고, 교체 시점에만 환경을 재검증
프롬프트 수정	한 번의 요청 문구	희소한 프롬프트 뒤의 결과를 복원하는 것은 에이전트의 몫으로 둠
하네스 엔지니어링	컨텍스트, 도구, 주변 환경	저장소가 다루는 범위 전체

계보도 문서에 정리되어 있습니다. matklad의 아키텍처 관련 글, Artichoke의 살아 있는 아키텍처, "Parse, don't validate", Strangler Fig 패턴을 앞선 영향으로 들고 있고, Birgitta Böckeler가 Martin Fowler 사이트에 쓴 글은 Ryan의 2026년 2월 11일 에세이 이후에 나온 다른 관점의 정리로 분류합니다. 출처로는 OpenAI가 공개한 "Harness engineering: leveraging Codex in an agent-first world" 를 들고 있으며, 봇 접근이 막힌 환경을 위한 fetch 헬퍼 스크립트도 저장소에 함께 두었습니다.

Harness Engineering은 누구에게 유용한가

바로 붙여 쓸 코드나 도구를 찾는 경우에는 맞지 않습니다. 저장소의 실행 코드는 출처를 받아오고 검증하는 보조 스크립트 정도이고, 나머지는 전부 산문과 절차 문서입니다. 도입 결정을 벤치마크 수치로 정당화해야 하는 상황에도 근거가 부족합니다. 앞서 적었듯 저자 본인이 두 플레이북에 종단간 적용 기록이 없다고 밝혀 두었습니다.

반대로 사내에서 코딩 에이전트를 이미 굴리고 있는데 결과 품질이 담당자마다 갈리는 조직에는 읽을 값이 있습니다. 무엇을 문서로 남겨야 하고 무엇을 도구로 만들어야 하는지, 권한을 능력과 어떻게 분리해야 하는지, 어떤 증거가 어떤 주장을 닫는지를 12개 축으로 갈라 두었기 때문입니다. 저장소를 에이전트에게 컨텍스트로 물릴 수 있는 형태로 만들려는 팀이라면, 이 저장소 자체가 그 형식의 예시라는 점도 함께 참고할 수 있습니다.

Harness Engineering 사용법

사람이 읽을 때는 루트 문서로 실천을 파악한 뒤 논제 색인에서 필요한 항목으로 들어가고, 적용이 목적이면 플레이북 색인에서 절차를 고릅니다. 에이전트에게 쓸 때는 개선하려는 시스템과 함께 이 저장소를 컨텍스트로 지정하고, AGENTS.md 가 작업을 관련 논지와 사례, 증명으로 라우팅하게 둡니다.

git clone https://github.com/lopopolo/harness-engineering.git

저장소를 대상 시스템의 작업 디렉토리 옆에 두고, 에이전트에게 대상 저장소의 지침을 먼저 읽은 다음 이 저장소의 AGENTS.md 를 참조하도록 지시하는 방식입니다. 이때 이 저장소는 읽기 전용이며, 파일 배치나 정책, 버전 고정을 그대로 복사하지 말라는 조건이 문서에 명시되어 있습니다.

Harness Engineering의 라이선스

저장소가 직접 작성한 자료는 CC BY 4.0로 공개되어 있어 출처를 밝히면 자유롭게 활용할 수 있습니다. 저장소에는 다른 저작자의 출처 자료도 함께 들어 있어, 그 자료의 귀속과 권리 범위는 COPYING.md 에 별도로 정리되어 있습니다.

Harness Engineering 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

이 도구를 직접 설치해 사용해보셨다면, 파이토치 한국 사용자 모임 회원들을 위해 경험이나 팁을 댓글로 남겨주세요!