[Harness Engineering] 하네스 엔지니어링이란 무엇인가 ⋆ Blog * JackerLab

정의, 배경, 그리고 왜 지금 필요한가

2025년 8월, OpenAI 내부의 한 팀이 빈 저장소를 열었다. 그로부터 5개월 후, 이 저장소에는 약 100만 줄의 프로덕션 코드가 쌓여 있었다. 내부 사용자가 매일 쓰고, 외부 알파 테스터가 검증하고, 장애가 나면 수정되는 살아있는 제품이었다. 놀라운 것은 규모가 아니다. 인간이 직접 작성한 코드가 단 한 줄도 없다는 점이다.

3명의 엔지니어가 Codex 에이전트에게 작업을 지시하고, PR을 검토하고, CI 파이프라인을 관리했을 뿐이다. 그런데 이 실험에서 팀이 얻은 가장 중요한 교훈은 AI의 코딩 능력에 관한 것이 아니었다. 초기에 진행이 예상보다 느렸는데, 원인은 에이전트의 능력 부족이 아니라 에이전트가 일할 환경이 갖춰지지 않았기 때문이었다.

이 환경을 설계하는 분야가 하네스 엔지니어링(Harness Engineering)이다.

하네스의 어원과 정의

“하네스(Harness)”는 말에게 씌우는 마구(馬具)다. 고삐, 안장, 재갈, 등자로 이루어진 장비 전체를 뜻한다. 말은 빠르고 강하지만, 마구 없이는 짐을 나를 수도, 밭을 갈 수도, 기수의 의도대로 움직일 수도 없다. 마구는 말의 능력을 제한하는 것이 아니라, 그 힘을 원하는 방향으로 전달하고 제어하는 장치다.

AI 에이전트도 같은 상황이다. GPT-5든 Claude든, 2026년의 프론티어 모델은 이미 코드를 쓰고, 테스트를 만들고, 버그를 찾아 수정하는 능력을 갖추고 있다. 문제는 고삐 없이 풀어놓았을 때 벌어지는 일이다.

개발자: "결제 모듈 만들어줘"
에이전트: (코드 생성)

결과:
- 프로젝트 코딩 컨벤션 무시
- 이미 있는 유틸 함수를 중복 생성
- 데이터베이스를 UI 레이어에서 직접 호출
- 3일 후, 다른 에이전트가 같은 파일을 다른 방식으로 수정

에이전트 하나가 한 번 작업하는 건 어떻게든 된다. 문제는 규모가 커질 때다. 10개의 에이전트가 동시에 100개의 파일을 수정하면, 제약 없이는 카오스가 된다.

하네스 엔지니어링(Harness Engineering): AI 에이전트가 대규모로 안정적이고 일관된 결과물을 만들어내도록 환경, 제약, 피드백 루프를 설계하는 엔지니어링 분야

핵심은 에이전트를 바꾸는 것이 아니라 환경을 바꾸는 것이다.

프롬프트는 부탁이고, 하네스는 강제다

“프롬프트 엔지니어링이랑 뭐가 다른가요?”라는 질문이 자연스럽게 나온다.

차이는 명확하다.

프롬프트 엔지니어링:
  "코딩 컨벤션을 지켜주세요"         → 부탁
  "아키텍처 레이어를 위반하지 마세요"   → 부탁
  "테스트를 꼭 작성해주세요"          → 부탁

하네스 엔지니어링:
  컨벤션 위반 → 린터가 차단           → 강제
  레이어 위반 → 아키텍처 테스트 실패    → 강제
  테스트 누락 → CI 파이프라인 실패      → 강제

프롬프트는 아무리 정교하게 작성해도, 에이전트가 잊거나 무시하거나 자기 나름의 해석을 적용할 수 있다. 하네스는 규칙을 위반하면 코드가 저장소에 들어갈 수 없게 만드는 구조적 장치다.

그렇다고 프롬프트가 쓸모없다는 말이 아니다. 좋은 프롬프트는 에이전트가 올바른 방향을 향하게 하고, 좋은 하네스는 잘못된 방향으로 가는 것 자체를 불가능하게 만든다. 하네스 엔지니어링은 프롬프트 엔지니어링을 대체하는 것이 아니라, 그 위에 구조적 안전장치를 쌓는 것이다.

LangChain 팀이 이를 정량적으로 증명했다. 에이전트 모델은 그대로 두고 하네스(미들웨어 구조)만 개선했더니, 벤치마크 성과가 52.8%에서 66.5%로 향상되었다. 순위로는 Top 30에서 Top 5. 같은 모델, 같은 프롬프트, 다른 하네스, 극적으로 다른 결과.

왜 지금 필요한가

AI 코딩 도구의 3단계 진화

AI가 코드에 관여하는 방식은 빠르게 진화해왔고, 각 단계는 이전보다 더 빠르게 전환되었다.

단계	방식	인간의 역할	대표 도구
Phase 1	자동완성	코드의 주도권은 인간	GitHub Copilot
Phase 2	페어 프로그래밍	AI와 함께 작성	Cursor, Windsurf
Phase 3	에이전트 위임	인간은 관리, AI가 실행	Codex, Claude Code

Phase 3에서 개발자는 여러 에이전트에게 작업을 분배하고, 에이전트들이 자율적으로 코드를 작성·테스트·배포한다. OpenClaw 프로젝트의 Peter Steinberger는 이 전환의 극단을 보여준다. 1인 개발자가 월 6,600건 이상의 커밋을 올리며, 5~10개 에이전트를 동시에 운영하고, 자신이 읽지 않은 코드를 배포한다.

코드 이후의 병목

그런데 역설적인 일이 벌어지고 있다. AI가 코드 생성 속도를 극적으로 높였는데, 오히려 문제가 더 커진 것이다.

2026년 3월 Harness(DevOps 플랫폼)의 보고서에 따르면, AI 코딩 도구가 개발 속도를 높였지만 테스트·보안·배포 등 후속 파이프라인이 따라가지 못하면서 배포 불안정성이 증가하고 있다. 73%의 팀이 표준화된 서비스 템플릿이나 골든 패스가 거의 없다고 응답했다.

고속도로에서 차가 300km/h로 달리는데, 톨게이트는 여전히 수동 정산인 상황이다. 코드 생성만 빨라져서는 소용없다. 그 코드를 안전하게 테스트하고 배포하는 전체 시스템이 함께 현대화되어야 한다.

하네스의 3가지 핵심 기둥

하네스 엔지니어링은 크게 세 가지 영역으로 구성된다. 각 기둥은 이 시리즈의 Part 2(2~5편)에서 코드 예시와 함께 깊이 다룰 예정이지만, 여기서 전체 그림을 먼저 잡아둔다.

1. 컨텍스트 엔지니어링 — “무엇을 해야 하는가”

에이전트에게 프로젝트의 규칙과 상태를 머신이 읽을 수 있는 형태로 제공하는 것이다.

# AGENTS.md (또는 CLAUDE.md) — 에이전트의 "입사 첫날 문서"

## 아키텍처 규칙
- 모든 API는 /api/v1/ 하위에 위치
- DB 접근은 반드시 Repository 레이어를 통해서만
- UI 컴포넌트에서 직접 API 호출 금지

## 코딩 컨벤션
- 함수명: camelCase / 파일명: kebab-case
- console.log 금지 (logger 사용)
- any 타입 사용 금지

이 파일은 에이전트가 작업 시작 시 자동으로 로드된다. 사람에게 온보딩 문서를 주듯, 에이전트에게도 “첫날 읽어야 할 문서”를 주는 것이다.

핵심 원칙은 **저장소가 단일 진실 소스(Single Source of Truth)**가 되어야 한다는 것이다. 위키, 노션, 슬랙에 흩어진 정보는 에이전트가 읽을 수 없다. 에이전트의 관점에서, 실행 중 컨텍스트 안에서 접근할 수 없는 것은 존재하지 않는 것과 같다.

2. 아키텍처 제약 — “무엇을 해서는 안 되는가”

컨텍스트가 방향을 알려준다면, 아키텍처 제약은 경계를 강제한다.

// architecture.test.ts — 레이어 위반 자동 차단

describe('Architecture constraints', () => {
  test('UI layer must not import from Repository', () => {
    const uiFiles = getFilesIn('src/ui/');
    for (const file of uiFiles) {
      const imports = getImports(file);
      expect(imports).not.toContainPath('src/repository/');
    }
  });
});

# .husky/pre-commit — 커밋 자체를 막는 게이트
npx lint-staged            # 코드 스타일 강제
npm run test:architecture   # 아키텍처 규칙 검증
npm run test:types          # 타입 안전성 확인

에이전트가 아무리 “이렇게 하는 게 더 효율적인데”라고 판단해도, 이 테스트가 실패하면 코드는 저장소에 들어갈 수 없다. 프롬프트로 “지켜줘”라고 부탁하는 것이 아니라, 린터와 테스트가 자동으로 차단하는 것이다.

OpenAI는 이를 의존성 방향 강제로 구현했다:

Types → Config → Repository → Service → Runtime → UI
(역방향 의존은 빌드가 실패한다)

3. 엔트로피 관리 — “시간이 지나도 일관성을 유지하라”

에이전트 A가 유틸 함수를 만들고, 에이전트 B가 같은 기능의 함수를 또 만든다. 에이전트 C는 이전 버전의 패턴을 사용한다. 개별적으로는 올바르지만, 전체적으로는 불일치가 쌓인다. Martin Fowler는 이를 “코드 부패(code rot)”에 비유하며, 하네스의 엔트로피 관리를 프로그래밍 언어의 가비지 컬렉션(GC)에 빗대었다.

정리 에이전트(Cleanup Agent)를 주기적으로 실행:
  1. 중복 함수/모듈 탐지
  2. 문서와 코드의 불일치 발견
  3. 사용되지 않는 코드 식별
  4. 네이밍 패턴 위반 스캔
  5. 순환 의존성 감지

이것은 한 번 설정하면 끝이 아니다. 지속적이고 반복적인 프로세스다.

세 거인이 독립적으로 같은 결론에 도달했다

하네스 엔지니어링이 특정 회사의 마케팅 용어가 아님을 보여주는 증거가 있다. 서로 다른 조직이 독립적으로 같은 문제에 부딪히고, 같은 해법에 수렴했다.

조직	시기	초점	핵심 교훈
Anthropic	2025.11	장기 실행 에이전트의 세션 간 상태 관리	초기화 에이전트 + 코딩 에이전트 2단계 구조, 기능 목록 JSON으로 진행 추적
OpenAI	2026.02	에이전트만으로 프로덕션 제품 구축	지도 vs 매뉴얼, 기계적 강제, 관찰 가능성 시스템
Stripe	2026	대규모 에이전트 운영	Minions 시스템으로 주당 1,000+ PR, 기존 코드와 동일한 품질 게이트 통과

Anthropic은 “에이전트가 교대 근무에서 매번 기억을 잃는 엔지니어와 같다”는 문제를 해결하려 했고, OpenAI는 “인간이 코드를 안 쓰고도 프로덕션을 만들 수 있는가”를 실험했고, Stripe는 “대규모 에이전트 운영을 기존 품질 기준으로 유지할 수 있는가”를 검증했다. 질문은 달랐지만 답은 같았다. 환경을 설계하라.

Mitchell Hashimoto(HashiCorp 공동 창업자)는 이를 한 문장으로 압축했다. “에이전트가 실수할 때마다, 그 실수를 다시는 하지 않도록 해결책을 엔지니어링하라.”