하네스 엔지니어링

AI 에이전트 시대, 진짜 어려운 건 AI가 아니라 "환경"이다

doworld

2026년 03월 16일 · 0 분 소요

들어가며

OpenAI의 엔지니어링 팀이 5개월 동안 약 100만 줄의 프로덕션 코드를 만들었다. 놀라운 건 규모가 아니다. 수동으로 작성한 소스코드가 단 한 줄도 없다는 점이다.

소수의 엔지니어가 Codex 에이전트에게 작업을 지시하고, PR을 검토하고, CI 파이프라인을 관리했을 뿐이다. 애플리케이션 로직, 문서, CI 설정, 모니터링 설정까지 전부 AI 에이전트가 만들었다.

이 실험에서 OpenAI가 얻은 가장 중요한 교훈은 이것이다:

"어려운 건 AI 에이전트가 아니다. 에이전트가 일할 환경(harness)이 어렵다."

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

하네스 엔지니어링이란?

비유로 이해하기

"하네스(harness)"는 말에게 씌우는 마구(馬具)다. 말이 아무리 빠르고 강해도, 고삐 없이는 짐을 나를 수 없고 밭을 갈 수도 없다. 방향을 잡아주고, 힘을 전달하고, 안전하게 제어하는 것이 마구의 역할이다.

AI 에이전트도 마찬가지다.

- GPT-5든 Claude든, 에이전트 자체는 이미 충분히 강력하다

- 하지만 고삐 없이 풀어놓으면 엉뚱한 코드, 아키텍처 위반, 스타일 불일치가 쏟아진다

- 하네스 엔지니어링은 이 고삐를 설계하는 기술이다

정의

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

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

왜 지금 필요한가?

2025년의 전형적인 실패 패턴

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


문제들:
- 프로젝트 코딩 컨벤션 무시
- 이미 있는 유틸 함수를 중복 생성
- 아키텍처 레이어 경계를 넘나듦
- 테스트는 통과하지만 기존 모듈과 스타일이 불일치
- 3일 후, 다른 에이전트가 같은 파일을 다른 방식으로 수정

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

프롬프트 엔지니어링의 한계

"코딩 컨벤션을 지켜줘", "아키텍처 레이어를 위반하지 마" 같은 프롬프트를 아무리 정교하게 써도, 에이전트는 잊거나 무시한다. 프롬프트는 부탁이고, 하네스는 강제다.

프롬프트 엔지니어링: "이 규칙을 지켜주세요" (부탁)

하네스 엔지니어링: 규칙을 위반하면 CI가 실패한다 (강제)

LangChain 팀은 이를 정량적으로 증명했다. 에이전트 모델은 그대로 두고 하네스만 개선했더니, 벤치마크 성과가 52.8%에서 66.5%로 향상되었다. 순위로는 Top 30에서 Top 5로 뛰었다. 에이전트를 바꾸지 않고도, 환경을 바꾸는 것만으로 이 정도 차이가 난다.

하네스 엔지니어링의 3가지 핵심 기둥

1. 컨텍스트 엔지니어링 (Context Engineering)

"에이전트에게 추측시키지 말고, 읽게 하라"

AI 에이전트가 올바른 결과물을 만들려면, 프로젝트의 규칙과 상태를 알아야 한다. 컨텍스트 엔지니어링은 이 정보를 머신이 읽을 수 있는 형태로 구조화하는 것이다.

정적 컨텍스트: 규칙 파일

# AGENTS.md (또는 CLAUDE.md)

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

## 코딩 컨벤션
- 함수명: camelCase
- 파일명: kebab-case
- 테스트 파일: *.test.ts

## 금지 패턴
- console.log 사용 금지 (logger 사용)
- any 타입 사용 금지
- 인라인 스타일 금지

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

동적 컨텍스트: 실시간 상태

CI/CD 파이프라인 상태
로그, 메트릭, 에러 추적
현재 진행 중인 PR과 이슈
최근 변경된 파일과 그 이유

핵심 원칙: 저장소가 단일 진실 소스(Single Source of Truth)

모든 정보는 코드 저장소 안에 있어야 한다. 위키, 노션, 슬랙 대화에 흩어진 정보는 에이전트가 읽을 수 없다. 저장소에 넣어야 에이전트의 컨텍스트가 된다.

2. 아키텍처 제약 (Architectural Constraints)

"자유롭게 코드를 쓰되, 정해진 경계 안에서만"

컨텍스트가 "무엇을 해야 하는가"라면, 아키텍처 제약은 "무엇을 해서는 안 되는가"다.

의존성 방향 강제

OpenAI는 코드베이스의 의존성 방향을 이렇게 정의했다:

Types → Config → Repository → Service → Runtime → UI

UI는 Service를 호출할 수 있지만, Service는 UI를 참조할 수 없다
Repository는 Config를 읽을 수 있지만, Config는 Repository를 모른다
이 규칙을 위반하는 import가 있으면 **빌드가 실패**한다

이것은 프롬프트로 "지켜줘"라고 부탁하는 것이 아니다. 린터와 구조 테스트가 자동으로 차단하는 것이다.

구현 예시

// 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/');
    }
  });

  test('Service layer must not import from UI', () => {
    const serviceFiles = getFilesIn('src/service/');

    for (const file of serviceFiles) {
      const imports = getImports(file);
      expect(imports).not.toContainPath('src/ui/');
    }
  });
});

에이전트가 아무리 "이렇게 하는 게 더 효율적인데"라고 생각해도, 이 테스트가 실패하면 코드는 머지되지 않는다.

Pre-commit 훅

# .husky/pre-commit
npx lint-staged          # 코드 스타일 강제
npm run test:architecture  # 아키텍처 규칙 검증
npm run test:types         # 타입 안전성 확인

커밋 자체가 되지 않으므로, 잘못된 코드가 저장소에 들어갈 수 없다.

3. 엔트로피 관리 (Entropy Management)

"AI가 만든 코드는 시간이 지나면 부패한다"

Martin Fowler는 이 현상을 "코드 부패(code rot)"에 비유하면서, 하네스 엔지니어링의 엔트로피 관리를 프로그래밍 언어의 가비지 컬렉션(GC)에 빗대었다.

가비지 컬렉션이 메모리 누수를 자동으로 정리하듯, 엔트로피 관리는 코드베이스의 일관성 붕괴를 자동으로 탐지하고 복구한다.

왜 엔트로피가 증가하는가?

에이전트 A가 유틸 함수를 만들고, 에이전트 B가 같은 기능의 함수를 또 만든다. 에이전트 C는 이전 버전의 패턴을 사용한다. 10개의 에이전트가 동시에 작업하면, 각각은 올바르더라도 전체적으로는 불일치가 쌓인다.

대응 방법

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

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

실제 사례로 보는 하네스 엔지니어링

OpenAI: 100만 줄의 무인 코드

구성:

소수의 엔지니어 + 다수의 Codex 에이전트
모든 아키텍처 규칙을 머신 가독형 문서로 명세
관찰성(observability) 데이터로 에이전트 성과 모니터링
구조화된 PR 리뷰 워크플로우

결과:

5개월, 약 100만 줄의 프로덕션 베타 제품
수동 작성 코드 0줄
애플리케이션 로직 + 문서 + CI + 모니터링 전부 포함

핵심 교훈:

에이전트에게 "좋은 코드를 써줘"라고 하지 않았다. 대신 좋은 코드만 통과할 수 있는 환경을 만들었다.

Stripe: 주당 1,000개 PR

Stripe의 "Minions" 에이전트 시스템:

Slack에서 작업 요청
  → 에이전트가 자동으로 코드 작성
  → CI 파이프라인 통과 확인
  → PR 자동 생성
  → 인간 엔지니어가 최종 리뷰
  → 머지

주당 1,000개 이상의 PR이 이 파이프라인을 통해 머지된다. 핵심은 에이전트가 만든 코드가 기존 코드와 동일한 품질 게이트를 통과해야 한다는 점이다.

LangChain: 하네스 변경만으로 벤치마크 점프

LangChain 팀은 에이전트 모델(Claude, GPT)은 전혀 바꾸지 않고, 미들웨어 구조만 개선했다:

LocalContextMiddleware: 코드베이스 매핑 자동 생성
LoopDetectionMiddleware: 에이전트 반복 루프 감지 및 중단
ReasoningSandwichMiddleware: 추론 단계 최적화
PreCompletionChecklistMiddleware: 완료 전 검증 강제

결과: 벤치마크 52.8% → 66.5%, 순위 Top 30 → Top 5

이 사례가 증명하는 것: "더 좋은 AI"보다 "더 좋은 환경"이 성과를 좌우한다.

도입 가이드: 3단계로 시작하기

Level 1: 개인 프로젝트

가장 가성비 좋은 시작점이다.

# 1. CLAUDE.md (또는 AGENTS.md) 작성
프로젝트 규칙, 컨벤션, 금지 패턴 정의

# 2. Pre-commit 훅 설정
코드 스타일과 기본 규칙 자동 검증

# 3. 테스트 작성
에이전트가 만든 코드가 기존 테스트를 깨뜨리지 않는지 확인

이것만으로도 에이전트의 결과물 품질이 체감될 정도로 달라진다.

Level 2: 소규모 팀

# 1. AGENTS.md 고도화
아키텍처 다이어그램, 모듈 경계, 의존성 규칙 포함

# 2. CI 파이프라인에 아키텍처 테스트 추가
레이어 위반, 순환 의존성 자동 탐지

# 3. PR 검토 체크리스트
에이전트 생성 코드에 대한 표준 리뷰 절차 수립

# 4. 린터 규칙 강화
프로젝트 전용 커스텀 린터 규칙 추가

Level 3: 조직 규모

# 1. 미들웨어 레이어 구축
에이전트 요청/응답 파이프라인에 검증 단계 삽입

# 2. 관찰성(Observability) 시스템
에이전트 성과 메트릭 수집 및 대시보드

# 3. 엔트로피 관리 자동화
정리 에이전트 주기적 실행, 코드 건강도 리포트

# 4. 버전 관리된 하네스 설정
하네스 자체를 코드로 관리, 변경 이력 추적

흔한 실수 5가지

1. 과도한 제어 흐름 설계

에이전트의 모든 행동을 미리 정의하려는 유혹이 있다. 하지만 LLM은 빠르게 진화한다. 너무 세밀한 제어 흐름은 모델이 업데이트될 때마다 깨진다. 큰 경계만 정하고, 경계 안에서는 자유를 주는 것이 더 견고하다.

2. 정적 하네스

한 번 만들어놓고 방치하는 하네스는 금방 쓸모없어진다. 모델이 진화하면 하네스도 함께 진화해야 한다. 하네스 자체를 코드로 관리하고 버전 관리해야 하는 이유다.

3. 문서화 경시

"AGENTS.md 대충 써도 되겠지"는 위험한 생각이다. 에이전트는 당신의 의도를 추론하지 않는다. 명확하지 않으면 추측하고, 추측은 틀린다. 규칙 파일의 품질이 곧 에이전트 결과물의 품질이다.

4. 피드백 루프 부재

에이전트가 성공했는지 실패했는지 모르면 개선할 수 없다. 어떤 에이전트가 어떤 작업에서 어떤 이유로 실패했는지를 추적하고 기록해야 한다. 이 데이터가 하네스를 개선하는 연료다.

5. 저장소 밖에 정보 저장

"이건 노션에 있어", "그건 슬랙에서 공유했어" — 에이전트는 이런 정보에 접근할 수 없다. 저장소 안에 없으면 존재하지 않는 것이다.

프롬프트 엔지니어링 → 하네스 엔지니어링으로의 전환

2023~2024년의 키워드가 "프롬프트 엔지니어링"이었다면, 2025~2026년의 키워드는 "하네스 엔지니어링"이다.

프롬프트 엔지니어링:

AI에게 무엇을 하라고 말하는 기술
한 번의 대화, 한 번의 결과물에 집중
개인 스킬에 의존

하네스 엔지니어링:

AI가 올바르게 작동하는 환경을 만드는 기술
수천 번의 반복 실행에서 일관된 품질을 보장
시스템적이고 팀 전체에 적용

프롬프트 엔지니어링이 "좋은 질문하는 법"이라면, 하네스 엔지니어링은 "좋은 답만 나올 수밖에 없는 구조를 만드는 법"이다.

마치며

하네스 엔지니어링은 결국 개발자의 역할에 대한 질문이다.

"당신은 코드를 쓰는 사람인가, 코드가 만들어지는 환경을 설계하는 사람인가?"

AI 에이전트가 코드를 작성하는 속도와 품질은 계속 좋아질 것이다. 하지만 아무리 좋은 에이전트도 잘못된 환경에서는 잘못된 결과를 낸다. 반대로, 적절한 하네스 안에서는 평범한 에이전트도 놀라운 결과를 만든다.

2026년의 시니어 엔지니어에게 기대되는 역량은 더 이상 "복잡한 알고리즘을 얼마나 잘 구현하느냐"가 아니다. "AI 에이전트가 복잡한 시스템을 안정적으로 구축할 수 있는 환경을 얼마나 잘 설계하느냐"로 무게중심이 옮겨가고 있다.

코드를 쓰는 시대가 끝나는 게 아니다. 코드를 쓰는 방식이 바뀌는 것이다. 그리고 그 변화의 중심에 하네스 엔지니어링이 있다.

참고 자료

- OpenAI — 하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기

- Martin Fowler — Harness Engineering

- NxCode — Harness Engineering: The Complete Guide