하네스 엔지니어링 (Harness Engineering)

AI가 「좋은 코드를 쓸 수밖에 없는 환경」을 설계한다

이 시리즈는 「AI 개발 규율의 진화」를 순서대로 해설합니다.

본 기사는 제4회: Harness Engineering입니다.

제3회 「Agentic Engineering」은 이쪽으로 → （링크）

지난 기사의 「다음」부터 시작하기

지난 Agentic Engineering에서, PEV 루프의 Verify (검증) 페이즈를 소개했다.

Plan → Execute → Verify
↑
여기서 무엇을 검증할 것인가?
...

사실 이 Verify를 「엔지니어가 매번 수동으로 하는 것」으로는 에이전트의 속도를 따라잡을 수 없다. 주당 1,000건의 PR을 엔지니어가 손으로 리뷰하는 것은 불가능하다.

검증을 자동화하고, 강제성을 갖게 하는 메커니즘이 필요하다. 그것이 하네스(Harness)다.

현실 세계의 비유

비행기의 체크리스트와 이륙 잠금

파일럿이 아무리 우수하더라도, 항공사는 파일럿의 「주의력」에만 안전을 맡기지 않는다.

• 이륙 전 체크리스트는 생략할 수 없다 (절차를 건너뛰면 시스템이 경고를 보낸다)
• 바퀴의 핀이 꽂힌 채로 이륙하려고 하면 물리적으로 잠긴다
• 엔진 온도가 규정치를 초과하면 자동으로 경고가 울린다

「조심해서 비행해 주세요」가 아니라, 조심하지 않으면 날 수 없는 시스템으로 되어 있다.

이것이 하네스의 발상이다.

에이전트에게 「보안을 의식해 주세요」라고 프롬프트(Prompt)로 부탁하는 것이 아니라, 보안 체크를 통과하지 않으면 머지(Merge)할 수 없는 CI를 설계한다. 에이전트에게 「테스트를 작성해 주세요」라고 매번 부탁하는 것이 아니라, 테스트 없이는 파이프라인이 멈추는 메커니즘을 만든다.

하네스 엔지니어링이란 무엇인가

「하네스 엔지니어링이란, AI 에이전트를 운영 환경에서 신뢰성 높게 동작시키기 위해, 그 에이전트를 둘러싼 환경·제약·피드백 루프를 설계하는 규율이다」

하네스는 에이전트 자체가 아니다. 에이전트를 구동하는 메커니즘 전체다.

어원

「하네스(Harness)」란 마구(굴레·안장·재갈)의 총칭이다.

• 🐴 말 ＝ AI 모델 (강력하지만, 목적지를 스스로는 모른다)
• 🎠 하네스 ＝ 그 모델을 적절하게 움직이기 위한 제어 시스템 전체
• 👤 기수 ＝ 하네스 엔지니어 (인간)

이것은 소프트웨어 엔지니어링이 인간에 대해 해왔던 일이다

이 부분이 중요한 관점이다. 하네스 엔지니어링은 완전히 새로운 발명이 아니다.

「실수를 하는 존재를, 환경 측에서 제어한다」 —— 이것은 소프트웨어 엔지니어링이 수십 년에 걸쳐 인간에 대해 해왔던 일 그 자체다.

인간이 일으키는 실수	해결책 (환경에 의한 강제)
테스트를 쓰는 것을 잊어버림	테스트 자동화·커버리지 임계치
...
전부, 근저에 있는 사상은 같다.

「인간은 확률적으로 실수를 한다. 그러므로 환경·메커니즘으로 결정론적으로 방지한다」

하네스 엔지니어링은 이 사상을 그대로 AI 에이전트에 적용한 것이다.

IaC의 사상과 완전히 같다

여기서 깨닫는 점이 있다. IaC (Infrastructure as Code)의 본질은 무엇인가. 인프라를 「인간이 손으로 만지는 것」에서 「코드로 선언하는 것」으로 바꾸는 것이다. 그 근저에 있는 사상은 「인간의 수작업 실수를 환경 레벨에서 배제하는 것」이다.

하네스 엔지니어링은 바로 같은 사상의 AI 에이전트 버전이다. 「에이전트가 조심해서 움직여 주길 바란다」에서 「에이전트가 조심할 수밖에 없는 환경을 선언적으로 정의한다」로의 전환 —— IaC가 인프라에 가져온 변화를, AI 에이전트의 세계에서도 반복하고 있다.

이전 규율과의 비교

시리즈를 통한 위치 설정을 정리한다.

관점	Prompt Engineering	Context Engineering	Agentic Engineering	Harness Engineering
스코프	1턴	1세션	태스크 사이클	시스템 전체
...
컴퓨터 사이언스(Computer Science)의 비유로 정리하면 이해하기 쉽다.

모델 ＝ CPU
컨텍스트 창 (Context Window) ＝ RAM
하네스 ＝ OS (Operating System)
...

OS 없이 CPU에서 직접 소프트웨어를 구동하지 않듯이, 하네스 (Harness) 없이 AI 에이전트를 실무에 투입해서는 안 된다.

하네스의 4가지 구성 요소

1. Guides (가이드)

에이전트가 "무엇을 알고 있는지"와 "무엇을 해도 되는지"를 방향 지어주는 문서군.

# AGENTS.md / CLAUDE.md 예시
## 아키텍처 제약 사항
- 신규 라이브러리 추가는 approved_deps.txt에 기재된 것만 가능
...

프롬프트로 "주의해"라고 말하는 것보다, 문서로서 명시하여 매번 읽히는 것이 더 확실하다.

2. Sensors (센서)

에이전트의 출력을 관측 및 검증하는 피드백 기구.

• 테스트, Lint, 타입 체크 (Type Check) 자동 실행
• 출력 스키마 (Output Schema)의 정합성 체크
• 아키텍처 드리프트 (Architecture Drift) 탐지기 (의도하지 않은 설계로부터의 이탈을 탐지)

3. Data Context Layer (데이터 컨텍스트 층)

에이전트가 추론에 사용하는 정보를 검증되었으며 신선도가 보장된 상태로 공급하는 층.

• 코드베이스 인덱스
• API 문서 및 사양서
• 기존 패턴의 샘플 코드
• 벡터 검색 (Vector Search) + 전체 텍스트 검색 (Full-text Search) 하이브리드 검색 기반

지난번 Context Engineering (컨텍스트 엔지니어링)과의 차이점은 "단발성 세션용"이 아니라 "여러 세션에 걸쳐 지속적으로 공급하는 기반"이라는 점이다.

4. Orchestration Logic (오케스트레이션 로직)

태스크를 순서대로 배치하고, 출력을 리뷰 게이트 (Review Gate)에 통과시키는 제어 흐름 (Control Flow).

• 태스크 분해 및 순서 지정
• Human-in-the-Loop 게이트 (승인 및 반려)
• 페이즈 게이트 (Phase Gate) (이전 단계가 PASS하지 않으면 다음으로 진행 불가)
• 에러 발생 시의 롤백 (Rollback) 및 재시도 로직

3층 구현 전략

제1층: Constraint Harness (제약 하네스)

실패를 사전에 방지 — 최우선으로 구현해야 할 예방적 제어.

# CI/CD 파이프라인 예시
gates:
- name: security-scan
...

"보안을 의식해"라고 프롬프트로 부탁하기 → 확률적인 준수

보안 스캔을 CI 게이트에 포함시키기 → 결정론적인 강제 집행

이 차이가 본질이다.

제2층: Feedback Loop (피드백 루프)

실패로부터 자기 수정 — 에러가 발생했을 때, 에이전트가 자율적으로 수정할 수 있는 메커니즘.

Verify (제1층)에서 FAIL
↓
에러 내용을 컨텍스트로 에이전트에게 전달
...

인간 엔지니어가 에러를 읽고 수정하는 것처럼, 에이전트도 에러를 문맥으로 받아들여 자기 수정을 수행한다.

단, 반드시 서킷 브레이커 (Circuit Breaker)를 구현해야 한다. 루프 상한선 없이 작동시키면 비용이 폭발하고, 동일한 실수를 반복하게 된다.

MAX_ATTEMPTS = 3
for attempt in range(MAX_ATTEMPTS):
    result = agent.execute(task, context=error_context)
...

"3회 실패 시 Human-in-the-Loop으로 전환하여 처리를 중단한다" —— 이 서킷 브레이커가 없는 피드백 루프는 실무에서 쓸 수 없다.

제3층: Quality Gate (품질 게이트)

사양과의 정합성을 지속적으로 검증 — 컨텍스트 리셋을 넘어 상태를 인계하는 메커니즘.

# progress.txt (에이전트가 매 세션 시작 시 읽는 파일)
## 완료됨
- [x] 사용자 인증 모듈 (auth/)
...

컨텍스트 윈도우 (Context Window)가 리셋되어도, 이 파일을 읽으면 "어디까지 끝났는지, 무엇을 결정했는지"를 이어받을 수 있다. 장기 가동되는 에이전트에게는 필수적인 패턴이다.

에이전트 네이티브 툴로의 진화

Claude Code를 사용하는 개발자에게는 이미 하네스 엔지니어링의 실천이 시작되었다.

CLAUDE.md가 Guide의 핵심이며, 스킬 시스템이 Orchestration Logic의 구현 형태다.

orchestrator skill (사양 분해 · 태스크 할당)
↓
spec-clarifier skill (모호성 제거)
...

각 스킬은 PASS/FAIL 수락 기준(Acceptance Criteria)을 가지며, 이전 단계의 스킬이 PASS하지 않으면 다음으로 진행하지 않는다. 이것이 페이즈 게이트(Phase Gate)로서의 하네스(Harness) 구현이다.

2026년: 하네스는 툴에 내포되기 시작했다

주목할 만한 동향이 있다. 2025년 말부터 등장한 Google Antigravity와 같은 에이전트 네이티브(Agent-native) IDE는, 이러한 오케스트레이션(Orchestration)이나 페이즈 게이트(Phase Gate)의 개념을 툴 레벨에서 내포하여 출시하고 있다.

기존의 접근 방식:
엔지니어가 CI 게이트(CI Gate), 가드레일(Guardrail), 페이즈 게이트(Phase Gate)를
처음부터 직접 설계 및 구현한다
...

하네스 엔지니어링(Harness Engineering)의 "설계 사상"을 이해하고 있다면, 어떤 툴을 사용하더라도 응용이 가능하다. 툴이 바뀌어도 컨셉은 변하지 않는다. 그렇기에 개념으로서 파악해 둘 가치가 있다.

실천 스타터 체크리스트

🔴 지금 바로 할 수 있는 것 (제약 하네스)

• CLAUDE.md 또는 AGENTS.md에 금지 작업을 명시한다
• CI/CD에 Lint와 타입 체크(Type Check)를 필수 게이트로 추가한다
• 테스트 커버리지(Test Coverage) 임계값을 설정하고 PR을 차단한다

🟡 다음 단계 (피드백 루프)

• PEV 루프의 Verify를 자동화한다
• 에이전트 에러를 로그에 남기고, 다음 세션에서 읽어들인다
• progress.txt를 통해 컨텍스트 리셋(Context Reset)을 넘어선 상태 지속을 구현한다

🟢 성숙 단계 (품질 게이트)

• 아키텍처 드리프트(Architecture Drift) 탐지기를 구현한다
• Human-in-the-Loop 리뷰 게이트를 설계한다
• 에이전트 간 핸드오프(Handoff) 사양을 artifacts/handoff/ 경로로 관리한다

요약

하네스 엔지니어링의 본질은 한 문장으로 집약된다.

"AI에게 좋은 코드를 써달라고 하는 것이 아니라, AI가 좋은 코드를 쓸 수밖에 없는 환경을 설계하는 것"

그리고 이것은 우리 엔지니어들이 인간 사이에서 계속해 온 일이다. "리뷰를 제대로 해줘"라고 계속 말하는 것보다 CODEOWNERS를 설정하고, "운영 환경을 수동으로 건드리지 마"라고 입으로 계속 말하는 것보다 IaC(Infrastructure as Code)로 관리하는 것——그 발상과 완전히 같다.

실수를 하는 존재(인간이든 AI든)를 환경과 시스템으로 제어한다.

이 원칙은 변하지 않았다. 제어 대상이 인간에서 AI 에이전트로 바뀌었을 뿐이다.

다음 기사에서는 이 하네스를 자동으로 계속 작동시키는 메커니즘을 설계하는 "루프 엔지니어링(Loop Engineering)"을 다룬다. 하네스가 "에이전트가 움직이는 환경"이라면, 루프는 "그 환경을 자율 주행시키는 시스템"이다.

시리즈 목록

• 【첫 번째 기사】 왜 "○○ 엔지니어링"은 계속해서 생겨나는가 (공개 예정)
• 제1회: Prompt Engineering
• 제2회: Context Engineering
• 제3회: Agentic Engineering
• [본 기사] 제4회: Harness Engineering
• 제5회: Loop Engineering (공개 예정)

Discussion