Harness engineering for coding agent users

3줄 요약

1. 이 글은 Thoughtworks의 Birgitta Böckeler가 2026년 4월 2일 Martin Fowler의 사이트에 올린 글로, 2월에 쓴 초기 메모를 정식 아티클로 확장한 것이다. 핵심 질문은 하나다 — 비결정적이고, 우리 맥락을 모르고, 토큰으로만 생각하는 LLM이 만든 코드를 어떻게 덜 감독하면서도 믿을 수 있는가.
2. 답은 에이전트 바깥에 하네스(harness) 를 두르는 것이다. 하네스는 두 종류의 장치로 이루어진다 — 행동하기 전에 방향을 잡는 가이드(피드포워드) 와, 행동한 뒤에 스스로 교정하게 하는 센서(피드백). 각각은 다시 결정적이고 빠른 연산형 과 의미를 판단하는 추론형 으로 갈린다.
3. 사람이 할 일은 이 하네스를 끊임없이 다듬는 조종 루프(steering loop) 다. 같은 문제가 반복되면 가이드·센서를 손봐 그 문제가 덜 일어나게 만든다. 하네스는 사람 개발자의 경험을 외부화·명시화하려는 시도이며, 사람의 입력을 없애기 위해서가 아니라 가장 중요한 곳으로 몰아주기 위해 짠다.

이 글은 “루프 엔지니어링” 연재의 다섯 번째 편이다. 바로 앞 4편(OpenAI)이 하네스 엔지니어링을 직접 실천한 생산자의 1차 사료 였다면, 이 5편은 같은 ‘하네스 엔지니어링’을 코딩 에이전트 사용자의 관점에서 멘탈 모델로 정리한 글이다. 둘은 정확히 한 쌍을 이룬다 — OpenAI가 “우리 환경은 이렇게 생겼다"를 보여 줬다면, Böckeler는 “그런 환경을 어떤 어휘로 사고하고 설계할 것인가"를 준다. 실제로 이 글은 OpenAI의 그 사례를 지금 담론의 출발점 가운데 하나로 직접 끌어온다. 앞선 1편(Addy Osmani)·2편(Firecrawl)·3편(Oracle)이 “루프를 설계하라"와 “그 루프란 무엇인가"를 다뤘다면, 4·5편은 그 루프를 감싸는 틀 전체 를 본다 — 한쪽은 사례로, 한쪽은 개념으로.

하네스란 무엇인가 — 경계가 다른 세 겹

“하네스"라는 말은 에이전트에서 모델을 뺀 나머지 전부 를 가리키는 약칭으로 떠올랐다. Agent = Model + Harness라는 등식이 그것이다. 다만 이 정의는 너무 넓어서, 저자는 코딩 에이전트를 쓰는 맥락으로 의미를 좁힌다.

코딩 에이전트에서 하네스의 일부는 이미 만들어져 들어와 있다 — 시스템 프롬프트, 코드 검색 메커니즘, 때로는 정교한 오케스트레이션까지. 하지만 코딩 에이전트는 사용자인 우리 에게도 자기 사례와 시스템에 맞춰 바깥 하네스(outer harness) 를 두를 많은 기능을 함께 준다. 그래서 같은 “하네스"라는 단어가 경계에 따라 다른 것을 뜻한다.

저자도 인정하듯 이 비유는 어느 정도 늘어난다 — 누군가는 “하네스 위에 하네스를 두르는 게 말이 되느냐, 개 안쪽에 하네스를 채워 봤느냐"고 꼬집었다. 그래도 단어가 사용 국면을 항해하는 데 쓸모 있다면 받아들이겠다는 것이 저자의 입장이다.

잘 만든 바깥 하네스는 두 가지를 동시에 노린다. 에이전트가 처음부터 제대로 해낼 확률을 높이고, 문제가 사람 눈에 닿기 전에 최대한 많이 스스로 교정하는 피드백 루프를 제공한다. 결과적으로 리뷰 부담을 줄이고 시스템 품질을 높이며, 덤으로 낭비되는 토큰까지 줄인다.

피드포워드와 피드백 — 가이드와 센서

에이전트를 하네스로 다스리려면 두 방향에서 접근한다. 원치 않는 출력을 미리 내다보고 막고, 행동 뒤에 스스로 교정하게 할 센서를 심는다.

• 가이드(피드포워드 제어) — 에이전트의 행동을 예측해, 행동하기 전에 방향을 잡는다. 첫 시도에서 좋은 결과를 낼 확률을 높인다.
• 센서(피드백 제어) — 행동한 뒤에 관찰하여 스스로 교정하게 돕는다. LLM이 소화하기 좋게 다듬은 신호를 낼 때 특히 강력하다. 예컨대 자기 교정 지시를 담은 커스텀 린터 메시지 — 긍정적인 종류의 프롬프트 주입인 셈이다.

둘 중 하나만 있으면 어떻게 될까. 피드백만 있으면 같은 실수를 끝없이 되풀이하는 에이전트가, 피드포워드만 있으면 규칙은 외우되 그게 통했는지 끝내 모르는 에이전트가 남는다.

연산형과 추론형

가이드와 센서는 각각 두 가지 실행 유형을 가진다.

• 연산형(Computational) — 결정적이고 빠르며 CPU가 돌린다. 테스트·린터·타입 체커·구조 분석. 밀리초~초 단위로 끝나고 결과가 믿을 만하다.
• 추론형(Inferential) — 의미 분석, AI 코드 리뷰, “심판으로서의 LLM”. 보통 GPU·NPU가 돌린다. 느리고 비싸며 결과가 더 비결정적이다.

연산형 가이드는 결정적 도구로 좋은 결과의 확률을 높이고, 연산형 센서는 충분히 싸고 빨라 변경마다 에이전트 곁에서 돌릴 수 있다. 추론형 제어는 더 비싸고 비결정적이지만, 풍부한 안내를 주는 동시에 의미 판단을 더한다. 비결정성에도 불구하고, 과제에 잘 맞는 강한 모델과 함께라면 추론형 센서는 오히려 신뢰를 끌어올린다.

한 사이드바에서 저자는 이렇게 정리한다 — 컨텍스트 엔지니어링 이 가이드와 센서를 에이전트에게 가용하게 만드는 수단이라면, 코딩 에이전트용 사용자 하네스를 짜는 일은 컨텍스트 엔지니어링의 한 특수한 형태다.

조종 루프 — 사람의 자리

이 모든 것에서 사람이 맡는 일은 하네스를 거듭 손봐 에이전트를 조종(steer) 하는 것이다. 어떤 문제가 여러 번 일어나면, 그 문제가 앞으로 덜 일어나거나 아예 막히도록 피드포워드·피드백 제어를 개선한다.

조종 루프 안에서는 하네스를 개선하는 데에도 물론 AI를 쓸 수 있다. 코딩 에이전트 덕에 커스텀 제어와 커스텀 정적 분석을 만드는 비용이 훨씬 싸졌다. 에이전트는 구조 테스트를 짜고, 관찰된 패턴에서 규칙 초안을 뽑고, 커스텀 린터를 세우고, 코드베이스 발굴로 하우투 가이드를 만드는 일을 거든다.

타이밍 — 품질을 왼쪽에 두라

지속적 통합을 해 온 팀은 늘 같은 도전을 마주해 왔다. 테스트·점검·사람 리뷰를, 비용·속도·중요도에 따라 개발 타임라인 위에 어떻게 흩뿌릴 것인가. 더 일찍 찾을수록 고치는 값이 싸므로, 점검은 가능한 한 프로덕션으로 가는 길의 왼쪽 에 두고 싶다. 새로 등장한 추론형 센서를 포함해, 피드백 센서도 생애주기 위에 그에 맞게 분산되어야 한다.

생애주기 분산은 두 갈래 질문으로 가른다. 무엇이 충분히 빨라서 통합 전, 심지어 커밋 전에도 돌릴 만한가 — 린터, 빠른 테스트 묶음, 기본 코드 리뷰 에이전트. 무엇이 더 비싸서 파이프라인에서 통합 후에만, 빠른 점검을 다시 돌리는 김에 함께 돌려야 하는가 — 뮤테이션 테스트, 큰 그림을 보는 폭넓은 코드 리뷰.

여기에 더해 변경 생애주기 바깥에서 상시 도는 센서도 있다. 천천히 쌓이는 드리프트 — 죽은 코드, 테스트 커버리지의 질적 저하, 의존성 위험 — 를 코드베이스에 대고 계속 감시하는 것이다. 런타임 피드백도 마찬가지다. 저하되는 SLO를 에이전트가 지켜보며 개선을 제안하거나, AI 심판이 응답 품질을 상시 표집하고 로그 이상을 표시한다.

무엇을 다스리는가 — 규제의 세 범주

에이전트 하네스는 사이버네틱스의 조절기(governor) 처럼 작동한다. 피드포워드와 피드백을 결합해 코드베이스를 바라는 상태로 규제한다. 다만 그 “바라는 상태"가 무엇이냐에 따라 하네스의 난이도와 복잡도가 달라지므로, 저자는 무엇을 규제하는가 로 범주를 가른다. 일반어인 “하네스"를 더 정밀하게 부르기 위한 어휘이기도 하다.

유지보수성 하네스

이 글의 거의 모든 예가 여기 속한다 — 내부 코드 품질과 유지보수성을 규제하는 것. 기존 도구가 풍부해 지금으로서는 가장 쉬운 종류다. 저자는 자기가 앞서 정리한 코딩 에이전트의 흔한 실패 양상 에 이 하네스를 대 봤다.

• 연산형 센서가 확실히 잡는 것: 중복 코드, 순환 복잡도, 빠진 테스트 커버리지, 아키텍처 드리프트, 스타일 위반. 싸고, 검증됐고, 결정적이다.
• 추론형이 부분적으로, 비싸게, 확률적으로 잡는 것: 의미적으로 중복인 코드, 불필요한 테스트, 억지 수정(brute-force fix), 과잉 설계. 매 커밋마다 돌릴 수는 없다.
• 어느 쪽도 확실히 못 잡는 것: 문제의 오진, 과잉 엔지니어링과 불필요한 기능, 잘못 이해한 지시. 사람이 애초에 원하는 바를 분명히 명시하지 않았다면, 정확성은 어떤 센서의 소관도 아니다.

아키텍처 적합성 하네스

애플리케이션의 아키텍처 특성을 정의하고 검사하는 가이드·센서다. 본질적으로 적합성 함수(Fitness Functions)다. 성능 요구를 피드포워드하는 스킬과 그 개선·저하를 되먹이는 성능 테스트, 또는 관측 가능성을 위한 로깅 표준을 기술하는 스킬과 가용 로그의 질을 에이전트에게 되돌아보게 하는 디버깅 지침 같은 것들이다.

행동 하네스

저자가 “방 안의 코끼리"라 부르는 부분이다 — 애플리케이션이 기능적으로 우리가 원하는 대로 동작하는지를 어떻게 안내하고 감지하는가. 높은 자율을 주는 사람들은 대개 이렇게 한다. 피드포워드로는 짧은 프롬프트부터 여러 파일에 걸친 명세까지 다양한 수준의 기능 명세 를 주고, 피드백으로는 AI가 생성한 테스트 묶음이 초록인지, 커버리지가 충분히 높은지, 때로는 뮤테이션 테스트로 그 질까지 확인한 뒤 수동 테스트와 결합한다.

문제는 이 방식이 AI가 생성한 테스트 에 너무 많은 믿음을 건다는 데 있다 — 아직 충분히 좋지 않다. 일부 동료는 approved fixtures 패턴으로 좋은 결과를 보지만, 잘 맞는 영역과 아닌 영역이 갈려 선택적으로만 쓴다. 테스트 품질 문제의 전면적 답은 아니다. 그래서 행동의 하네스는 감독과 수동 테스트를 줄일 만큼 신뢰를 끌어올릴 방법을 아직 한참 더 찾아야 하는 영역으로 남는다.

하네스 가능성과 주변 행동유도성

모든 코드베이스가 똑같이 하네스를 두르기 좋은 것은 아니다. 강타입 언어는 타입 검사를 센서로 자연히 갖고, 명확한 모듈 경계는 아키텍처 제약 규칙을 가능케 하며, Spring 같은 프레임워크는 에이전트가 신경 쓰지 않아도 될 세부를 추상화해 성공 확률을 은연중에 높인다. 그런 속성이 없으면 그런 제어 자체를 만들 수 없다.

동료 Ned Letcher는 환경을 더 하네스 가능하게 만드는 속성을 주변 행동유도성(ambient affordances) 이라 부른다 — “환경 안에서 작동하는 에이전트에게 환경을 읽히고, 항해 가능하고, 다룰 만하게 만드는 환경 자체의 구조적 속성.” 이것은 신규(greenfield)냐 레거시냐에 따라 다르게 펼쳐진다. 신규 팀은 첫날부터 하네스 가능성을 구워 넣을 수 있지만, 기술 부채가 쌓인 레거시 팀은 더 어려운 문제를 마주한다 — 하네스가 가장 필요한 곳이 가장 짓기 어렵다.

하네스 템플릿과 애시비의 법칙

대부분의 기업은 필요의 80%를 덮는 몇 가지 공통 서비스 위상(topology)을 가진다 — API로 데이터를 노출하는 비즈니스 서비스, 이벤트 처리 서비스, 데이터 대시보드. 성숙한 조직에서 이 위상들은 이미 서비스 템플릿으로 굳어 있다. 이것이 장차 하네스 템플릿 으로 진화할 수 있다. 어떤 위상의 구조·컨벤션·기술 스택에 에이전트를 묶는 가이드·센서 묶음 말이다. 팀은 이미 어떤 하네스가 준비돼 있는가 를 보고 기술 스택과 구조를 고르기 시작할지도 모른다.

애시비의 필요 다양성 법칙(Ashby’s Law of Requisite Variety)은 이 위상화를 뒷받침하는 또 하나의 논거다. 법칙은 말한다 — 조절기는 자기가 다스리는 시스템만큼의 다양성을 가져야 하며, 자기가 모델을 가진 것만 규제할 수 있다. LLM 코딩 에이전트는 거의 무엇이든 만들어 낼 수 있지만, 하나의 위상에 헌신하면 그 공간이 좁혀져 포괄적 하네스를 짜는 일이 더 해볼 만해진다. 위상을 정한다는 것은 다양성을 줄이는 수 다. 물론 서비스 템플릿이 겪던 문제 — 인스턴스화하는 순간부터 상류 개선과 어긋나기 시작하는 동기화·기여 문제 — 를 하네스 템플릿도 똑같이, 어쩌면 더 심하게 겪을 것이다. 비결정적 가이드·센서는 테스트하기 더 어렵기 때문이다.

사람의 역할

사람 개발자는 모든 코드베이스에 자신의 기량과 경험을 암묵적 하네스 로 들고 온다. 컨벤션과 좋은 관행을 흡수했고, 복잡성의 인지적 고통을 직접 느껴 봤고, 커밋에 내 이름이 달린다는 것을 안다. 조직적 정렬도 짊어진다 — 팀이 무엇을 이루려는지, 어떤 기술 부채가 사업상 용인되는지, 이 특정 맥락에서 “좋음"이 무엇인지. 우리는 작은 보폭으로, 사람의 속도로 나아가며, 그 경험이 발동해 적용될 사고의 여백을 만든다.

코딩 에이전트에게는 이 가운데 아무것도 없다. 사회적 책임감도, 300줄짜리 함수에 대한 미적 혐오도, “여기선 그렇게 안 해"라는 직관도, 조직적 기억도 없다. 어떤 컨벤션이 하중을 지탱하는 것이고 어떤 것이 그저 습관인지, 기술적으로 옳은 해법이 팀이 하려는 바에 맞는지 알지 못한다.

하네스는 사람 개발자의 경험이 식탁에 가져오는 것을 외부화·명시화하려는 시도이지만, 거기에는 한계가 있다. 가이드·센서·자기 교정 루프의 정합적 체계를 짓는 일은 비싸므로, 분명한 목표를 두고 우선순위를 매겨야 한다. 좋은 하네스는 반드시 사람의 입력을 완전히 없애려는 게 아니라, 우리 입력이 가장 중요한 곳으로 그것을 몰아주려는 것이다.

출발점, 그리고 열린 질문들

저자는 이 멘탈 모델이 이미 실무에서 벌어지는 기법들을 묘사하며, 아직 풀어야 할 것을 논의하는 틀이 되기를 바란다. 대화를 기능 수준 — 스킬과 MCP 서버 — 위로 끌어올려, 어떻게 제어의 체계를 전략적으로 설계해 에이전트의 산출에 진짜 확신을 가질 것인가 로 옮기는 것이 목표다.

지금 담론에서 끌어온 예들은 이렇다. OpenAI의 한 팀이 자기 하네스를 문서화했고 — 커스텀 린터와 구조 테스트로 강제되는 계층 아키텍처, 드리프트를 훑어 에이전트가 수정을 제안하는 상시 “가비지 컬렉션” — 그들의 결론은 “우리의 가장 어려운 도전은 이제 환경·피드백 루프·제어 시스템을 설계하는 데 모인다"였다. Stripe의 미니언(minions) 글은 휴리스틱으로 관련 린터를 고르는 pre-push 훅, “피드백을 왼쪽으로 밀기"의 중요성, 그리고 피드백 센서를 워크플로에 엮는 “청사진"을 보여 준다. 뮤테이션·구조 테스트는 그간 덜 쓰이던 연산형 피드백 센서인데 다시 떠오르고 있고, LSP와 코드 인텔리전스의 통합 — 연산형 피드포워드 가이드 — 을 둘러싼 잡담도 늘었다.

남은 질문은 행동 하네스만이 아니다. 하네스가 커질 때 가이드와 센서가 서로 모순되지 않게 정합성을 어떻게 유지하는가. 지시와 피드백 신호가 어긋날 때 에이전트의 합리적 절충을 어디까지 믿을 수 있는가. 센서가 한 번도 울리지 않는다면, 그것은 높은 품질의 신호인가 아니면 탐지 장치가 부실하다는 신호인가. 코드 커버리지와 뮤테이션 테스트가 테스트에 해 주는 것처럼, 하네스 커버리지와 질을 평가할 방법이 필요하다. 바깥 하네스를 짓는 일은 일회성 설정이 아니라 떠오르는 상시 엔지니어링 관행 이다.

가장 곱씹은 대목

내가 가장 오래 머문 것은 하네스를 사이버네틱스의 조절기 로 읽어 낸 틀이다. 피드포워드(가이드)와 피드백(센서)이라는 한 쌍, 그리고 그것을 연산형·추론형으로 다시 가르는 격자 — 이 단순한 2×2가 “스킬이냐 MCP냐 린터냐"로 흩어지던 도구 이야기를 단번에 한 좌표계 위에 올려놓는다. 4편(OpenAI)이 무엇을 했는가 의 풍부한 사례였다면, 이 글은 그 사례를 어디에 꽂아 읽을지 알려 주는 눈금자 다. 생산자의 1차 사료와 사용자의 멘탈 모델이 이렇게 한 쌍으로 맞물리는 일은 흔치 않다.

또 하나 의외였던 것은 애시비의 법칙을 위상화 의 논거로 끌어온 대목이다. “조절기는 자기가 모델을 가진 것만 규제할 수 있다"는 명제는, 무엇이든 만들어 내는 LLM 앞에서 포괄적 하네스가 왜 그토록 어려운지를 정확히 짚는다. 답이 역설적이다 — 덜 만들 수 있게 묶어야 더 잘 다스릴 수 있다. 하나의 위상에 헌신해 가능성의 공간을 좁히는 것이 곧 하네스를 짤 수 있게 하는 전제라는 것. 자유를 줄여 신뢰를 사는 이 거래는, 이 연재가 1편부터 되풀이해 온 결론 — 루프를 설계하라, 그리고 그 루프가 다룰 수 있는 모양으로 일을 빚어라 — 의 가장 이론적인 판본이다.

출처

Birgitta Böckeler (Thoughtworks), “Harness engineering for coding agent users”, martinfowler.com, 2026년 4월 2일. 2026년 2월 17일 초기 메모를 확장한 정식 아티클. 본문 도식 6점은 원문에서 인용했다. 원문: https://martinfowler.com/articles/harness-engineering.html