Harness Engineering: AI 코딩 에이전트를 위한 환경 설계

AI 코딩 에이전트로 개발하다 보면 반복되는 경험이 하나 있습니다. 프롬프트를 아무리 잘 써봐야 에이전트가 프로젝트 맥락을 놓치고, 아키텍처는 무시한 채 엉뚱한 코드를 만들어내는 거죠. 사람이 뒤에서 계속 수습하느라 바쁩니다 😅

왜 이런 걸까요? 모델이 멍청해서? 아닙니다. 에이전트가 일할 수 있는 환경 자체가 안 갖춰져 있어서 그렇습니다. OpenAI가 최근 발표한 Harness Engineering이라는 글이 딱 이 지점을 짚는데요. 이번 글에서 그 내용을 정리해 보겠습니다.

Harness란 무엇인가

Harness는 말 그대로 “마구(馬具)“예요. 말의 힘을 제어해서 원하는 방향으로 이끄는 장치처럼, AI 에이전트를 둘러싸는 제약 조건과 피드백 시스템 전체를 가리킵니다.

구체적으로 보면 이런 것들이 harness에 해당해요.

• 문서화 — AGENTS.md나 CLAUDE.md 같은 프로젝트 컨텍스트 파일
• 아키텍처 제약 — 의존성 레이어링, 모듈 경계 규칙
• 피드백 루프 — 린터, 타입 체커, 테스트 스위트, pre-commit hook
• 생명주기 관리 — CI/CD 파이프라인, PR 검증 자동화

그동안 “어떤 모델을 쓸까”, “프롬프트를 어떻게 쓸까”에 논의가 집중됐다면, harness engineering은 “에이전트가 일하는 환경을 어떻게 설계할까”로 관점을 바꿉니다. 그냥 설정 작업이 아니라 하나의 엔지니어링 분야죠.

세 가지 핵심 기둥

OpenAI는 harness engineering을 세 가지 기둥으로 설명합니다.

Context Engineering부터 볼까요. 에이전트 입장에서 컨텍스트 안에 없는 정보는 존재하지 않는 것과 같습니다. Google Docs에 정리해둔 설계 문서, Slack에서 공유한 결정 사항, 팀원 머릿속에만 있는 컨벤션… 에이전트는 이런 걸 볼 수 없어요. 프로젝트의 규칙과 지식을 레포지토리 안에 기계가 읽을 수 있는 형태로 옮겨야 합니다. AGENTS.md에 빌드 명령어를 적고, API 계약을 코드로 정의하고, 스타일 가이드를 린터 규칙으로 변환하는 게 전부 context engineering입니다.

다음은 Architectural Constraints입니다. 에이전트에게 자유를 많이 줄수록 예측 불가능한 결과가 나옵니다. 오히려 제약을 걸어야 에이전트가 더 잘 작동하죠. 의존성 레이어를 Types → Config → Repo → Service → Runtime → UI처럼 단방향으로 강제하면 에이전트가 탐색할 솔루션 공간이 줄어듭니다. 선택지가 줄어드니까 올바른 답을 찾을 확률이 높아지는 거예요. 이런 규칙은 구조적 테스트나 린터로 기계적으로 검증합니다.

마지막은 Entropy Management입니다. 에이전트가 코드를 많이 생성할수록 코드베이스의 무질서도가 올라갑니다. 문서와 코드가 안 맞고, 비슷한 기능의 중복 코드가 늘어나고, 안 쓰는 임포트가 쌓이죠. 방치하면 에이전트의 작업 품질이 계속 떨어집니다. 그래서 문서-코드 일관성 검증, 패턴 위반 스캔, 순환 의존성 감사를 수행하는 별도의 정리 에이전트가 필요합니다.

레포지토리가 유일한 진실의 원천

harness engineering에서 가장 중요한 원칙이 뭐냐고요? 레포지토리가 유일한 진실의 원천(single source of truth)이 되어야 한다는 겁니다.

사람은 Confluence 문서를 읽다가 Slack에서 추가 맥락을 얻고, 옆자리 동료한테 물어볼 수도 있잖아요. 에이전트는 그게 안 됩니다. 레포지토리 안에 있는 것만 봐요. 레포 밖의 정보는 에이전트에게 없는 거나 마찬가지죠.

이건 “문서를 잘 쓰라”는 수준의 이야기가 아닙니다. 프로젝트의 모든 지식을 버전 관리되는 아티팩트로 전환하라는 뜻이에요. 아키텍처 결정 기록(ADR)을 코드 옆에 두고, 시스템 관계를 다이어그램 대신 코드로 정의하고, 워크플로우를 설명 문서 대신 실행 가능한 스크립트로 만드는 거죠.

AGENTS.md는 백과사전이 아니라 목차

AGENTS.md를 처음 만들 때 흔히 하는 실수가 있어요. 프로젝트에 대한 모든 걸 한 파일에 다 쏟아붓는 겁니다. 파일 구조, API 명세, 배포 절차, 코딩 컨벤션… 전부 넣다 보면 수백 줄짜리 거대한 문서가 되죠.

OpenAI는 AGENTS.md를 약 100줄 정도의 짧은 목차(table of contents)로 유지하라고 합니다. 전체 그림을 보여주는 맵 역할만 하고, 실제 지식은 docs/ 디렉토리에 나눠서 정리하는 거예요.

# 프로젝트 컨텍스트

## 빌드 & 테스트
빌드/테스트 명령어와 CI 설정은 docs/build.md 참조

## 아키텍처
시스템 구조와 의존성 레이어는 docs/architecture.md 참조

## 코딩 컨벤션
코딩 스타일과 패턴은 docs/conventions.md 참조

## API 계약
엔드포인트 명세는 docs/api/ 디렉토리 참조

이러면 에이전트가 필요한 정보만 골라서 읽을 수 있고, 뭔가 바뀌었을 때 해당 문서만 고치면 되니까 관리가 수월합니다. docs/ 디렉토리에는 아키텍처 맵, 실행 계획, 설계 사양 같은 것들을 체계적으로 정리해 두면 됩니다.

에이전트와 CI/CD의 통합

harness의 진가는 CI/CD랑 연결될 때 드러납니다. 에이전트가 코드를 짜고 PR을 올리면 CI 파이프라인이 검증합니다. 테스트가 실패하면 에이전트가 다시 수정하고, 린터가 경고를 내면 에이전트가 코드를 고치고. 기준을 충족할 때까지 이 과정이 반복되죠.

사람이 코드 리뷰하는 것과 비슷한데, 기계적으로 검증 가능한 부분을 자동화한다는 점이 다릅니다. 클로드 코드 GitHub Actions를 쓰면 이런 워크플로우를 이미 만들 수 있어요. PR이 올라오면 자동으로 코드 리뷰하고, 이슈에 @claude를 태그하면 수정 PR을 만들어주거든요.

Hooks까지 더하면 에이전트 동작을 더 세밀하게 조절할 수 있습니다. 코드 수정 후 포매터를 자동으로 돌리거나, 특정 디렉토리의 파일 수정을 아예 막아버리는 식으로 결정론적인 규칙을 harness에 넣을 수 있어요.

관측성: 에이전트도 로그를 봐야 한다

놓치기 쉬운 영역이 관측성(observability)입니다. 에이전트가 프로덕션 버그를 고치려면 로그, 메트릭, 트레이스에 접근할 수 있어야 하거든요.

로그에서 에러 패턴을 잡아내고, 메트릭에서 성능이 떨어지는 구간을 찾고, 트레이스에서 요청 흐름을 따라가며 원인을 추적하는 겁니다. 프로덕션 버그를 격리된 환경에서 재현하는 것까지 에이전트가 할 수 있죠.

그러려면 관측성 도구의 데이터를 에이전트가 읽을 수 있게 열어줘야 합니다. 로그 검색 API를 만들거나, 메트릭 쿼리 도구를 에이전트에 연결하는 식이에요.

OpenAI의 실험 결과

말은 그럴듯한데, 실제로 될까요? OpenAI가 공개한 실험 결과를 보면 꽤 놀랍습니다.

2025년 8월 말에 빈 레포지토리 하나로 시작했대요. Codex CLI와 GPT-5로 초기 스캐폴드를 만들고, 그 뒤로는 모든 코드를 에이전트가 작성했습니다. 인간은 코드를 한 줄도 직접 안 쓴다는 원칙이었죠.

5개월 뒤에 약 100만 줄의 코드와 1,500개 PR이 쌓여 있었습니다. 엔지니어는 고작 3명이었고 1인당 하루 평균 3.5개 PR을 처리했어요. 이 엔지니어들이 한 일은 코드 작성이 아니라 에이전트가 일할 환경을 설계하고, 결과를 검증하고, harness를 고치는 것이었습니다.

LangChain의 사례: 모델보다 harness가 중요하다

harness가 얼마나 중요한지 보여주는 좋은 사례가 LangChain입니다.

LangChain 팀은 Terminal Bench 2.0이라는 코딩 벤치마크에서 모델을 하나도 안 바꾸고 harness만 손봐서 성능을 52.8%에서 66.5%로 올렸어요. Top 30에서 Top 5로 순위가 뛴 거죠.

뭘 바꿨을까요?

• LocalContextMiddleware — 코드베이스 매핑을 제공해서 에이전트가 프로젝트 구조를 파악할 수 있게 함
• LoopDetectionMiddleware — 에이전트가 같은 실수를 반복하는 루프에 빠지는 걸 감지하고 중단
• ReasoningSandwichMiddleware — 컴퓨팅 자원을 효율적으로 배분
• PreCompletionChecklistMiddleware — 작업 완료 전에 검증 목록을 강제 실행

이 미들웨어들은 필요에 따라 조합해서 쓸 수 있습니다. 모델을 더 똑똑하게 만든 게 아니라, 이미 가진 능력을 제대로 쓸 수 있는 환경을 만들어준 거예요.

단계별 도입 가이드

처음부터 완벽하게 만들 필요는 없습니다. 점진적으로 도입하면 돼요.

Level 1은 개인 수준이에요. CLAUDE.md나 .cursorrules 같은 컨텍스트 파일 만들고, pre-commit hook 설정하고, 테스트 스위트 갖추면 됩니다. 1~2시간이면 충분하고, 이것만으로도 에이전트가 내놓는 결과물이 확 달라져요.

Level 2는 팀 수준입니다. AGENTS.md에 팀 컨벤션을 정리하고, CI에서 아키텍처 규칙을 검증하고, 프롬프트 템플릿을 공유합니다. 1~2일 걸리는데, 팀원 누가 에이전트를 돌려도 비슷한 품질이 나오게 됩니다.

Level 3은 프로덕션 수준이에요. 커스텀 미들웨어를 만들고, 관측성 도구를 에이전트와 연결하고, 엔트로피 관리용 정리 에이전트까지 운영합니다. 1~2주 걸리지만, 에이전트가 프로덕션급 작업을 혼자서 처리할 수 있는 환경이 완성됩니다.

흔히 저지르는 실수들

harness를 구축할 때 빠지기 쉬운 함정들이 있습니다.

AGENTS.md를 모호하게 쓰는 게 대표적이에요. “코드 품질을 유지하세요”라고 쓰면 에이전트가 뭘 해야 할지 모릅니다. “함수는 50줄을 넘기지 않으며, 모든 public 함수에는 JSDoc을 작성합니다”처럼 검증 가능한 규칙을 적어야 해요.

피드백 루프가 아예 없는 경우도 많습니다. 에이전트가 코드를 짰는데 맞는지 틀린지 확인할 방법이 없으면 어떻게 될까요? 자기가 맞다고 가정하고 그냥 계속 진행합니다. 테스트, 린터, 타입 체커 같은 자동 피드백은 필수예요.

팀원 머릿속에만 있는 지식을 문서화 안 하는 것도 문제죠. “그건 다들 아는 거잖아”라고 넘기는 암묵지가 쌓일수록 에이전트 실수가 늘어납니다.

반대로 에이전트의 모든 행동을 스크립트로 통제하려는 것도 안 좋습니다. 방향만 잡아주고 실행은 에이전트한테 맡기세요.

그리고 harness를 한 번 만들어 놓고 방치하면 안 됩니다. 모델은 계속 발전하고 프로젝트도 계속 바뀌니까요. harness도 같이 진화시켜야 합니다.

엔지니어의 역할은 어떻게 달라지나

harness engineering이 가리키는 가장 큰 변화는 엔지니어 역할의 전환입니다. 코드를 직접 짜는 사람에서, 에이전트가 잘 일할 수 있는 환경을 만드는 사람으로요.

Martin Fowler는 이걸 “AI 기반 소프트웨어 개발 핵심에 대한 가치 있는 프레이밍”이라고 평했습니다. 서로 다른 팀들이 독립적으로 같은 결론에 도달하고 있다는 것도 방향이 맞다는 신호겠죠.

물론 당장 모든 프로젝트에 적용할 수 있는 건 아닙니다. 하지만 AI 코딩 에이전트를 실무에서 쓰고 있다면, 프롬프트 다듬는 시간을 에이전트의 작업 환경 정비에 투자하는 게 더 나을 수 있습니다.

마치며

한 문장으로 정리하면요. 더 좋은 프롬프트가 아니라 더 좋은 환경이 더 좋은 결과를 만듭니다.

Level 1부터 시작해 보세요. CLAUDE.md 작성 가이드를 참고해서 프로젝트 컨텍스트 파일부터 만들고, 린터와 테스트 스위트를 점검하는 것만으로도 에이전트가 내놓는 결과물이 달라질 겁니다. 특히 피드백 루프를 강화하고 싶다면 스펙 주도 개발도 함께 살펴보세요. 테스트와 타입으로 에이전트의 작업 범위를 정밀하게 제어하는 방법을 다룹니다. 에이전트가 일하는 환경을 설계하는 것, 그것도 엔지니어링이니까요.

Unlocking the Codex Harness와 Unrolling the Codex Agent Loop도 같이 보면 좋아요.