코딩 에이전트 사용자를 위한 하네스 엔지니어링

게시일: 2026년 4월 3일 | 원문 작성일: 2026년 4월 2일 | 저자: Birgitta Böckeler | 원문 보기

• • •

이 글은 하네스 엔지니어링에 대한 초기 메모를 발전시킨 것이에요.

하네스(harness)라는 용어는 AI 에이전트에서 모델 자체를 제외한 모든 것을 의미하는 약칭으로 자리잡았어요. 즉, 에이전트 = 모델 + 하네스인 거죠. 매우 넓은 정의라서, 흔한 에이전트 카테고리별로 좁혀 생각할 필요가 있어요. 저는 여기서 좀 과감하게, 코딩 에이전트를 사용하는 맥락으로 한정해볼게요.

코딩 에이전트에서 하네스의 일부는 이미 내장되어 있어요: 시스템 프롬프트, 코드 검색 메커니즘, 심지어 정교한 오케스트레이션 시스템까지요. 하지만 코딩 에이전트는 우리 같은 사용자가 직접 외부 하네스를 만들 수 있도록 다양한 기능도 제공해요. 각자의 유즈케이스와 시스템에 맞춰서요.

원문 보기

잘 만들어진 외부 하네스는 두 가지 목표를 달성해요. 첫째, 에이전트가 처음부터 올바른 결과를 낼 확률을 높여요. 둘째, 사람이 보기 전에 문제를 알아서 잡아내는 피드백 루프를 만들어줘요. 리뷰 부담을 줄이고 시스템 품질을 높이는 게 궁극적인 목표예요. 토큰 낭비가 줄어드는 건 덤이고요.

원문 보기

• • •

피드포워드와 피드백 (Feedforward and Feedback)

코딩 에이전트를 하네싱하려면 두 가지가 모두 필요해요. 원치 않는 결과를 예측해서 방지하는 것, 그리고 센서를 배치해서 자동 교정이 이루어지게 만드는 것이에요.

• 가이드 (feedforward controls) — 에이전트의 행동을 예측하고, 행동하기 전에 방향을 잡아줘요. 첫 시도에서 좋은 결과를 낼 확률을 높여줘요.
• 센서 (feedback controls) — 에이전트가 행동한 후에 관찰하고 자동 교정을 도와요. 특히 LLM이 소화하기 좋은 형태로 신호를 만들면 강력해요. 예를 들어 커스텀 린터 메시지에 “이렇게 고쳐라”는 지침까지 담는 거예요. 일종의 긍정적 프롬프트 인젝션1이죠.

둘을 따로 떼어놓고 보면: 피드백만 있으면 에이전트가 같은 실수를 반복하고, 피드포워드만 있으면 에이전트가 규칙대로 움직이긴 하는데 그게 실제로 효과가 있는지는 알 길이 없어요.

연산적 vs 추론적 (Computational vs Inferential)

가이드와 센서에는 두 가지 실행 유형이 있어요.

• 연산적(Computational) — 결정론적이고 빨라요. CPU가 실행해요. 테스트, 린터, 타입 체커, 구조적 분석 등이에요. 밀리초에서 초 단위로 실행되고, 결과를 신뢰할 수 있어요.
• 추론적(Inferential) — 시맨틱 분석, AI 코드 리뷰, “LLM as judge” 같은 것들이에요. 보통 GPU나 NPU가 실행하죠. 더 느리고 비싸며, 결과의 변동성이 더 커요.

연산적 가이드는 결정론적 도구를 활용해 좋은 결과의 확률을 높여줘요. 연산적 센서는 저렴하고 빨라서 모든 변경마다 에이전트와 함께 돌릴 수 있어요. 추론적 컨트롤은 당연히 더 비싸고 결과도 들쭉날쭉하지만, 그만큼 풍부한 지침과 시맨틱 수준의 판단력을 보태줘요. 결과의 변동성에도 불구하고, 추론적 센서는 해당 작업에 맞는 적절한 모델과 함께 사용할 때 신뢰를 크게 높여줄 수 있어요.

예시

• • •

스티어링 루프 (The Steering Loop)

이 과정에서 사람의 역할은 하네스를 반복적으로 개선하면서 에이전트를 조종(steer)하는 거예요. 어떤 문제가 여러 번 발생하면, 피드포워드와 피드백 컨트롤을 개선해서 같은 문제가 다시 일어날 가능성을 줄이거나, 아예 재발을 막는 거예요.

스티어링 루프에서는 당연히 AI를 활용해서 하네스를 개선할 수도 있어요. 코딩 에이전트 덕분에 이제 커스텀 컨트롤이나 커스텀 정적 분석을 훨씬 저렴하게 만들 수 있게 됐거든요. 에이전트가 구조적 테스트 작성, 패턴 기반 규칙 초안 생성, 커스텀 린터 스캐폴딩을 도와줄 수 있어요. 심지어 코드베이스 고고학(기존 코드 분석)을 토대로 하우투 가이드까지 만들어줄 수 있고요.

• • •

타이밍: 품질을 왼쪽으로 (Timing: Keep Quality Left)

지속적 통합(CI)을 하는 팀이라면 테스트, 체크, 사람의 리뷰를 개발 타임라인 어디에 배치할지 늘 고민해왔어요. 비용, 속도, 중요도를 모두 따져야 하니까요. 지속적 배포(CD)를 지향한다면, 이상적으로는 모든 커밋 상태가 배포 가능하길 바라죠. 문제를 일찍 발견할수록 고치는 비용이 저렴하니까, 체크를 프로덕션까지의 경로에서 가능한 한 왼쪽에 배치하고 싶은 거예요. 새로운 추론적 센서를 포함한 피드백 센서들도 이 라이프사이클에 맞게 분배해야 해요.

변경 라이프사이클에서의 피드포워드와 피드백

• 합리적으로 빠르게 돌릴 수 있어서 통합 전에, 심지어 커밋 생성 전에도 실행해야 하는 건 뭘까요? (예: 린터, 빠른 테스트 스위트, 기본 코드 리뷰 에이전트)
• 빠른 컨트롤은 반복 실행하되, 비용이 커서 통합 후 파이프라인에서만 돌려야 하는 건 뭘까요? (예: 뮤테이션 테스팅4, 더 큰 그림을 고려할 수 있는 광범위한 코드 리뷰)

원문 보기

지속적 드리프트 및 건강 센서

• 어떤 종류의 드리프트가 점진적으로 누적되고, 변경 라이프사이클과 별개로 코드베이스를 상시 모니터링하는 센서를 필요로 할까요? (예: 데드 코드 탐지, 테스트 커버리지 품질 분석, 의존성 스캐너)
• 에이전트가 모니터링할 수 있는 런타임 피드백은 뭐가 있을까요? (예: SLO5가 악화되는 것을 감지해서 개선 제안하기, AI 심사관이 응답 품질을 지속 샘플링하고 로그 이상을 감지하기)

원문 보기

• • •

규제 카테고리 (Regulation Categories)

에이전트 하네스는 사이버네틱 거버너처럼 작동해서, 피드포워드와 피드백을 결합해 코드베이스를 원하는 상태로 규제해요. 하네스가 무엇을 규제하는지에 따라 이 원하는 상태를 여러 차원으로 구분하면 유용해요. 이렇게 나누면 카테고리마다 하네스 적용 가능성(harnessability)과 복잡도가 다르다는 점이 드러나고, “하네스”라는 다소 포괄적인 단어를 더 정확하게 쓸 수 있게 돼요.

현재 시점에서 유용하다고 생각하는 세 가지 카테고리는 다음과 같아요.

유지보수성 하네스 (Maintainability Harness)

이 글에서 드는 예시의 대부분은 내부 코드 품질과 유지보수성을 규제하는 것에 관한 거예요. 현재로서는 이 유형이 가장 쉬운데, 활용할 수 있는 기존 도구가 많기 때문이에요.

이런 유지보수성 하네스 아이디어들이 에이전트에 대한 신뢰를 얼마나 높여주는지 평가하기 위해, 이전에 정리했던 코딩 에이전트의 일반적인 실패 모드를 하나씩 대응시켜봤어요.

연산적 센서는 구조적인 문제를 신뢰성 있게 잡아내요: 중복 코드, 순환 복잡도, 누락된 테스트 커버리지, 아키텍처 드리프트, 스타일 위반 같은 것들이죠. 저렴하고, 검증되었고, 결정론적이에요.

LLM은 시맨틱 판단이 필요한 문제를 부분적으로 다룰 수 있어요: 의미적으로 중복된 코드, 불필요한 테스트, 무차별 대입식 수정, 과도하게 엔지니어링된 솔루션 같은 것들이요. 하지만 비싸고 확률적이에요. 매 커밋마다 돌리긴 어렵죠.

두 가지 모두 신뢰성 있게 잡아내지 못하는 영향이 더 큰 문제들도 있어요. 이슈의 오진, 과도한 엔지니어링과 불필요한 기능, 지시사항 오해 같은 것들이에요. 센서들이 가끔은 잡아내지만, 감독을 줄일 만큼 신뢰할 수 있는 수준은 아니에요. 게다가 사람이 원하는 것을 처음부터 명확히 정의하지 않았다면, 정확성 판단은 어떤 센서의 영역도 아니에요.

아키텍처 적합성 하네스 (Architecture Fitness Harness)

애플리케이션의 아키텍처 특성을 정의하고 체크하는 가이드와 센서를 묶은 거예요. 기본적으로 적합성 함수(Fitness Functions)라고 보면 돼요.

예시:

• 성능 요구사항을 피드포워드하는 스킬과, 에이전트가 성능을 개선했는지 악화시켰는지 피드백하는 성능 테스트
• 더 나은 관측 가능성(observability)을 위한 코딩 컨벤션(로깅 표준 같은)을 설명하는 스킬과, 에이전트에게 사용 가능했던 로그의 품질을 되돌아보도록 요청하는 디버깅 지침

행동 하네스 (Behaviour Harness)

이것이 방 안의 코끼리예요. 애플리케이션이 우리가 원하는 대로 동작하는지, 어떻게 안내하고 감지할 수 있을까요? 현재로서는, 코딩 에이전트에 높은 자율성을 부여하는 대부분의 사람들이 이렇게 하고 있어요:

• 피드포워드: 기능 명세 (짧은 프롬프트부터 여러 파일에 걸친 상세 설명까지 다양한 수준의 디테일)
• 피드백: AI가 생성한 테스트 스위트가 그린인지, 커버리지가 충분히 높은지 확인하고, 일부는 뮤테이션 테스팅으로 품질까지 모니터링해요. 여기에 수동 테스트를 더하는 거죠.

이 접근법은 AI가 생성한 테스트에 많은 믿음을 두고 있는데, 아직은 충분하지 않아요. 제 동료들 중 일부는 approved fixtures6 패턴으로 좋은 결과를 보고 있지만, 어떤 영역에서는 적용하기 쉽고 다른 영역에서는 어려워요. 맞는 곳에서 선택적으로 사용하는 거지, 테스트 품질 문제를 통째로 해결해주는 건 아니에요.

그래서 전체적으로, 감독과 수동 테스트를 충분히 줄여줄 만큼 신뢰를 높여주는 기능적 행동 하네스를 만들어내기까지는 아직 갈 길이 멀어요.

원문 보기

• • •

하네스 적용 가능성 (Harnessability)

모든 코드베이스가 똑같이 하네싱하기 좋은 건 아니에요. 강타입 언어로 작성된 코드베이스는 자연스럽게 타입 체크가 센서 역할을 해요. 명확한 모듈 경계가 있으면 아키텍처 제약 규칙을 세울 수 있고, Spring 같은 프레임워크는 에이전트가 굳이 신경 쓰지 않아도 되는 세부 사항을 알아서 처리해줘서 성공 확률을 높여주죠. 이런 속성이 없으면 그런 컨트롤을 만들 수조차 없어요.

이것은 그린필드(새 프로젝트)와 레거시에서 다르게 나타나요. 그린필드 팀은 처음부터 하네스 적용 가능성을 내장할 수 있어요. 기술 선택과 아키텍처 결정이 코드베이스가 얼마나 통제 가능한지를 결정하죠. 레거시 팀은, 특히 기술 부채가 많이 쌓인 애플리케이션의 경우, 더 어려운 문제에 직면해요. 하네스가 가장 절실한 곳이 하네스를 만들기 가장 힘든 곳이거든요.

• • •

하네스 템플릿 (Harness Templates)

대부분의 기업에는 필요한 것의 80%를 커버하는 몇 가지 공통 서비스 토폴로지가 있어요: API로 데이터를 제공하는 비즈니스 서비스, 이벤트 처리 서비스, 데이터 대시보드 같은 것들이죠. 성숙한 엔지니어링 조직에서는 이런 토폴로지가 이미 서비스 템플릿으로 코드화되어 있어요. 이것들이 미래에는 하네스 템플릿으로 진화할 수 있어요. 코딩 에이전트를 특정 토폴로지의 구조, 컨벤션, 기술 스택에 묶어두는 가이드와 센서의 번들이요. 어떤 하네스가 이미 나와 있는지를 기준 삼아, 팀이 기술 스택과 구조를 고르기 시작할 수도 있어요.

원문 보기

물론 서비스 템플릿과 비슷한 도전에 직면할 수 있어요. 팀이 템플릿을 가져다 쓰는 순간 업스트림의 개선사항과 동기화가 어긋나기 시작하죠. 하네스 템플릿도 버전 관리와 기여 방식 문제에 부딪힐 텐데, 가이드와 센서가 비결정론적이라 테스트하기도 까다로워서, 오히려 더 골치 아플 수 있어요.

• • •

사람의 역할 (The Role of the Human)

인간 개발자인 우리는 기술과 경험을 암묵적 하네스로서 모든 코드베이스에 가져가요. 컨벤션과 좋은 관행을 체화했고, 복잡함의 인지적 고통을 느꼈고, 우리 이름이 커밋에 찍힌다는 걸 알아요. 조직적 맥락도 지니고 있어요. 팀이 달성하려는 것, 어떤 기술 부채가 비즈니스 이유로 용인되는지, 이 특정 맥락에서 “좋은 코드”가 무엇을 의미하는지에 대한 감각이요. 우리는 작은 단계로, 인간적 속도로 나아가며, 그 속도 덕분에 경험이 자연스럽게 떠오르고 적용될 여유가 생겨요.

코딩 에이전트에게는 이런 게 없어요. 사회적 책임감도, 300줄짜리 함수에 대한 미적 거부감도, “우리는 여기서 그렇게 안 해”라는 직관도, 조직적 기억도 없어요. 어떤 컨벤션이 중요하고 어떤 게 그냥 습관인지, 기술적으로 올바른 솔루션이 팀이 하려는 것에 맞는지도 모르죠.

하네스는 인간 개발자의 경험을 외부화하고 명시화하려는 시도지만, 거기에도 한계가 있어요. 가이드, 센서, 자기 교정 루프의 일관된 시스템을 구축하는 것은 비싸기 때문에, 명확한 목표를 염두에 두고 우선순위를 정해야 해요. 좋은 하네스가 반드시 사람의 개입을 완전히 없애려 할 필요는 없어요. 오히려 우리의 개입이 가장 중요한 곳으로 향하게 만드는 데 집중해야 해요.

• • •

시작점, 그리고 열린 질문들

여기서 설명한 멘탈 모델은 실제로 이미 일어나고 있는 기법들을 설명하고, 앞으로 논의할 것들의 방향을 잡아줘요. 목표는 대화를 기능 수준 위로 끌어올리는 거예요. 스킬과 MCP7 서버 수준을 넘어, 에이전트 결과물을 진정으로 신뢰할 수 있게 해주는 컨트롤 시스템을 어떻게 전략적으로 설계할 것인지로 나아가는 거예요.

요즘 나오는 이야기들 중에서 하네스 관련 사례를 몇 가지 소개할게요:

• OpenAI 팀이 자신들의 하네스를 문서화했어요: 커스텀 린터와 구조적 테스트로 시행하는 계층형 아키텍처, 그리고 드리프트를 스캔하고 에이전트가 수정을 제안하게 하는 반복적인 “가비지 컬렉션”이에요. 그들의 결론: “우리가 지금 가장 고심하는 문제는 환경, 피드백 루프, 컨트롤 시스템을 설계하는 일이다.”
• Stripe의 미니언즈에 대한 글은 휴리스틱 기반으로 관련 린터를 실행하는 pre-push 훅 같은 사례를 소개해요. “피드백을 최대한 앞당기는 것”이 그들에게 얼마나 중요한지도 강조하고, “블루프린트”가 피드백 센서를 에이전트 워크플로에 어떻게 통합하는지도 보여줘요.
• 뮤테이션 테스팅과 구조적 테스팅은 과거에 충분히 활용되지 못했던 연산적 피드백 센서의 예시인데, 지금 부활하고 있어요.
• 코딩 에이전트에서의 LSP8와 코드 인텔리전스 통합에 대한 개발자들의 논의가 늘고 있는데, 이것들은 연산적 피드포워드 가이드의 예시예요.
• Thoughtworks 팀들이 연산적·추론적 센서 모두를 활용해서 아키텍처 드리프트에 대응하는 이야기를 듣고 있어요. 예를 들어 에이전트와 커스텀 린터의 조합으로 API 품질을 높이거나, “청소부 군대(janitor army)“로 코드 품질을 높이는 거예요.

아직 알아내야 할 것이 많아요. 이미 언급한 행동 하네스만이 아니에요. 하네스가 커질수록, 가이드와 센서가 동기화되고 서로 모순되지 않도록 일관성을 어떻게 유지할 수 있을까요? 지시와 피드백 신호가 다른 방향을 가리킬 때, 에이전트가 합리적인 트레이드오프를 하도록 얼마나 신뢰할 수 있을까요? 센서가 한 번도 작동하지 않는다면, 그건 품질이 높다는 뜻일까요, 아니면 탐지 메커니즘이 부족하다는 뜻일까요? 테스트에 코드 커버리지나 뮤테이션 테스팅이 있듯, 하네스의 커버리지와 품질을 가늠할 방법이 필요해요. 피드포워드와 피드백 컨트롤은 현재 딜리버리 단계 곳곳에 흩어져 있어요. 이걸 하나의 시스템으로 구성하고, 동기화하고, 전체를 파악해 다룰 수 있게 해주는 도구가 나온다면 큰 가치가 있을 거예요. 이 외부 하네스를 구축하는 것은 일회성 설정이 아닌, 하나의 지속적인 엔지니어링 실천으로 자리잡고 있어요.

• • •

감사의 말

지난 기술 레이더 미팅에서 활발한 토론을 함께해 준 도플러(Doppler) 팀에 진심으로 감사드려요. 특히 사이버네틱스를 언급해준 Kief Morris에게요. 하네스가 대체 무엇인지에 대해 대화를 나눠준 Ned Letcher, Chris Ford, Ben O’Mahoney, 그리고 행동 하네스에 대한 인사이트를 준 Matteo Vaccari에게 감사해요. 그리고 초안을 읽고 귀중한 피드백을 준 모든 분들에게도요: Christoph Burgmer, Jörn Dinkla, Michael Feathers, Karrtik Iyer, Swapnil Phulse, Paul Sobocinski, Zhenjia Zhou.

리서치, 기존 노트에서 관련 아이디어 가져오기, 문장 다듬기에 GenAI(Claude와 Claude Code)를 활용했어요.