하네스 엔지니어링 - AI 에이전트 시대, 개발자의 새로운 역할

코드를 짜는 사람에서, 에이전트를 일하게 만드는 사람으로

OpenAI가 5개월 동안 100만 줄의 프로덕션 코드를 만들었다. 사람이 직접 작성한 애플리케이션 코드는 0줄이다. 3명(이후 7명)의 엔지니어가 Codex 에이전트만으로 내부 베타 제품을 구축했고, 약 1,500개의 PR을 머지했다.

이 실험에서 인간 엔지니어는 무엇을 했을까? 함수를 구현하거나 버그를 고치지 않았다. 대신 레포지토리 구조를 설계하고, 아키텍처 규칙을 정의하고, 린터와 테스트를 만들고, 에이전트가 막히는 지점을 발견하면 프롬프트를 고치는 대신 새로운 도구와 제약을 추가했다.

이것이 **하네스 엔지니어링(Harness Engineering)**이다.

Prompt → Context → Harness: 세 단계의 진화

하네스 엔지니어링을 이해하려면 AI 활용 방식의 진화 경로를 먼저 봐야 한다.

프롬프트 엔지니어링은 단일 LLM 호출에 보내는 텍스트 지시문을 최적화하는 일이다. "이렇게 말하면 더 좋은 답이 나온다"는 수준.

컨텍스트 엔지니어링은 한 단계 더 나아간다. 컨텍스트 윈도우 안에 들어가는 모든 것 — RAG로 가져온 문서, 도구 정의, 메시지 히스토리, 메모리 — 을 설계하는 일이다. "모델이 보게 할 토큰을 어떻게 큐레이션할 것인가"의 문제.

하네스 엔지니어링은 에이전트 바깥의 모든 것을 설계한다. CI 파이프라인, 평가 루프, 린팅 규칙, 관측성 인프라, 생명주기 관리까지. 프롬프트와 컨텍스트를 포함하되, 그것만으로는 부족하다는 인식에서 출발한다.

Google DeepMind의 Phil Schmid는 이렇게 표현했다.

모델은 CPU이고, 하네스는 운영체제다. 아무리 강력한 CPU라도 잘못 설계된 OS는 성능을 제한한다.

Mitchell Hashimoto(Terraform 창시자)가 2026년 2월 블로그 "My AI Adoption Journey"에서 이 용어를 정립했다. 핵심 정의는 이것이다: AI가 실수를 저질렀을 때 단순히 고쳐주는 것에 그치지 않고, 시스템적으로 그 실수가 다시는 발생하지 않도록 가이드라인과 도구를 설계하는 것.

하네스의 세 가지 축

OpenAI의 실험에서 드러난 하네스의 핵심 구성요소는 세 가지다.

1. 컨텍스트 엔지니어링

에이전트가 작업에 필요한 맥락을 스스로 찾아 읽을 수 있도록, 레포지토리 안에 지식을 구조화하는 것이다.

OpenAI는 처음에 하나의 거대한 AGENTS.md 파일을 만들었다. 실패했다. 컨텍스트 윈도우를 낭비하기 때문이다. 결국 88개의 개별 AGENTS.md 파일을 레포지토리 곳곳에 배치했다.

핵심 원칙은 AGENTS.md를 백과사전이 아니라 목차로 취급하는 것이다. 약 100줄 정도로 유지하고, 상세 설계 문서는 docs/ 디렉토리에 둔다. 에이전트는 목차를 읽고 필요한 문서를 찾아간다.

# AGENTS.md (목차 역할, ~100줄)
├── 프로젝트 개요
├── 아키텍처 계층 규칙 → docs/architecture.md
├── 코딩 컨벤션 → docs/conventions.md
├── 테스트 가이드 → docs/testing.md
├── 품질 지표 → docs/quality-scores.md
└── 기술 부채 목록 → docs/tech-debt.md

또한 Slack, Notion, 구두 합의 등 레포지토리 밖의 지식은 에이전트에게 보이지 않는다. 모든 중요한 결정과 패턴을 코드와 문서로 레포에 녹여야 한다. 레포지토리가 유일한 진실의 원천이 되어야 한다.

2. 아키텍처 제약

에이전트에게 "이렇게 해라"가 아니라 "이것만은 하지 마라"를 기계적으로 강제하는 것이다.

OpenAI는 각 비즈니스 도메인에 엄격한 의존성 레이어를 정의했다.

Types → Config → Repo → Service → Runtime → UI
 
규칙: 상위 레이어는 하위 레이어만 참조할 수 있다.
       UI가 Types를 직접 참조하는 것은 허용되지만,
       Types가 Service를 참조하는 것은 금지된다.

이 규칙을 커스텀 린터와 구조적 테스트가 CI에서 강제한다. 위반하는 PR은 자동으로 차단된다.

여기서 핵심적인 설계가 하나 더 있다. 린터 에러 메시지 자체가 수정 가이드 역할을 한다. 에이전트가 위반을 만났을 때, 에러 메시지를 읽고 스스로 고칠 수 있도록 메시지를 설계한 것이다.

❌ 기존: "Layer violation detected"
✅ 개선: "Layer violation: Runtime cannot import from UI.
         Move the shared type to Types layer (src/types/).
         See docs/architecture.md#layer-rules for details."

3. 가비지 컬렉션

에이전트가 코드를 생성하다 보면, 나쁜 패턴까지 복제하면서 아키텍처가 점점 흐트러진다. OpenAI는 이것을 **"AI slop"**이라고 불렀다.

해결책은 수동 정리가 아니다. "골든 원칙"을 레포에 인코딩하고, 백그라운드 Codex 태스크가 이탈을 감지하여 리팩토링 PR을 자동 생성하는 것이다. 사람이 금요일마다 AI가 남긴 기술 부채를 치우는 대신, 다른 AI가 매일 자동으로 치운다.

하네스는 1회성 설정이 아니다. 규칙을 코드화해서 매일 자동 적용하는 운영 체계에 가깝다.

하네스 엔지니어가 실제로 하는 일

"하네스 엔지니어"라는 직함의 공식 채용공고는 아직 없다. 하지만 기능적으로 동일한 역할은 이미 존재한다. 구체적으로 무엇을 하는지 정리하면 이렇다.

환경 설계

저장소를 에이전트 친화적으로 만든다. AGENTS.md를 목차로 두고, 구조화된 docs/를 진실의 원천으로 삼는다. 실행 계획, 설계 문서, 기술 부채, 품질 점수까지 저장소 안에 버전 관리한다. 에이전트가 사람 머릿속이 아니라 레포만 보고 일하게 만드는 것이 목표다.

도구 설계

에이전트가 사용할 도구의 수, 이름, 반환값을 신중하게 설계한다. Anthropic은 좋은 에이전트 도구의 원칙으로 다음을 제시했다.

Vercel의 실험이 이를 뒷받침한다. text-to-SQL 에이전트에서 도구의 80%를 제거하고 단일 bash 실행 도구만 남겼더니, 성공률이 80%에서 100%로 올라갔다. 단계 수, 토큰, 응답 시간도 함께 줄었다.

제약 설계

아키텍처 계층, 의존성 규칙, 타입/테스트/린트 규칙을 정의하고 도구로 강제한다. 핵심은 불변식만 강제하고 구현은 마이크로 매니징하지 않는 것이다. "이건 하면 안 된다"만 정하고, 구체적인 구현 방법은 에이전트에 맡긴다.

피드백 루프 설계

테스트 실패, 린트 에러, 관측 지표 악화가 발생했을 때 에이전트가 어떻게 대응하는지의 루프를 설계한다. 모든 에이전트 실패를 하네스 개선의 신호로 취급한다. 에이전트가 같은 실수를 반복하면, 프롬프트를 고치는 대신 린터 규칙이나 테스트를 추가한다.

장기 실행 에이전트를 위한 메모리와 핸드오프

Anthropic은 장기 실행 에이전트를 위한 초기화 에이전트 패턴을 도입했다.

1. 첫 컨텍스트 윈도우: 초기화 전용 프롬프트로 환경 셋업
2. init.sh 실행, 200개+ 기능 목록 생성 (모두 "failing" 표시)
3. progress 파일(JSON) 생성
4. 새 컨텍스트 윈도우가 열려도 progress 파일을 읽어 작업 이어감
5. git commit 로그로 진행 상황 추적

핵심 발견: 기능 추적에 Markdown보다 JSON이 효과적이다. 에이전트가 구조화된 데이터를 임의 편집할 가능성이 낮기 때문이다. 하네스 엔지니어는 사실상 **"AI 팀의 온보딩 시스템"**을 만드는 사람이다.

엔트로피 감소 루프

골든 원칙을 레포에 인코딩하고, 백그라운드 에이전트가 품질 점검과 리팩토링 PR을 자동으로 연다. 하네스는 한 번 설정하고 끝나는 것이 아니라, 지속적으로 운영되는 시스템이다.

실무 사례: 하네스가 만든 차이

OpenAI — 100만 줄, 수동 코드 0줄

핵심 슬로건: "Humans steer. Agents execute." 인간은 방향을 잡고, 에이전트가 실행한다.

Stripe — Minions 시스템

Stripe의 Minions 시스템은 주당 1,000개 이상의 머지된 PR을 생산한다. 개발자가 Slack에 태스크를 올리면, 에이전트가 격리된 개발 환경(devbox)에서 코드를 작성하고 CI를 통과시킨 뒤 인간 리뷰용 PR을 오픈한다.

MCP 서버를 통해 400개 이상의 내부 도구에 접근할 수 있지만, 세션당 약 15개 도구만 큐레이션하여 "토큰 마비"를 방지한다. 도구를 많이 주는 것이 아니라 적절히 주는 것이 하네스의 핵심이다.

KRAFTON — 모델이 아닌 하네스의 차이

한국의 KRAFTON은 자체 하네스 "Terminus-KIRA"를 사용해 TerminalBench 2.0에서 전 세계 2위(74.8% 정확도)를 달성했다. OpenAI(75.1%)와 0.3%p 차이. 같은 모델이라도 하네스에 따라 결과가 달라진다는 것을 입증한 사례다.

LangChain — 벤치마크로 증명하다

LangChain은 모델을 변경하지 않고 하네스 개선만으로 벤치마크 점수를 올렸다.

핵심 기법은 "reasoning sandwich" 패턴이다. 계획과 검증에는 더 많은 추론 컴퓨팅을 배분하고, 구현에는 적게 배분한다. 생각할 때는 깊게, 코드 칠 때는 빠르게.

Anthropic — Claude Code 하네스

초기화 에이전트와 코딩 에이전트를 분리하는 패턴을 도입했다. 긴 작업에서 컨텍스트 윈도우가 새로 열려도, progress 파일과 git 로그를 통해 작업이 이어지게 했다.

핵심 원칙 정리

여러 사례에서 공통적으로 뽑아낸 하네스 엔지니어링 원칙이다.

모델이 아니라 하네스가 경쟁력이다

모델은 점점 범용화되고 저렴해진다. 진짜 차별화는 에이전트가 일하는 환경에 있다. KRAFTON과 LangChain의 사례가 이를 증명한다.

AGENTS.md는 매뉴얼이 아니라 지도다

모든 것을 자세히 설명하려 하지 마라. 어디에 무엇이 있는지 알려주는 목차 역할에 집중하라. OpenAI는 하나의 거대한 AGENTS.md 대신 88개의 개별 파일을 사용했다.

불변식을 강제하되 구현은 맡겨라

린터와 테스트는 "이건 하면 안 된다"만 정한다. 구체적인 구현 방법은 에이전트의 자율에 맡긴다. 마이크로 매니징은 프롬프트에서든 하네스에서든 비효율적이다.

실패를 자산화하라

에이전트의 실패는 하네스의 결함이다. 실패 사례를 문서, 테스트, 도구 개선으로 반영해서 같은 문제가 재발하지 않게 만든다. "더 세게 프롬프트"하는 대신 새로운 제약을 추가한다.

레포지토리를 유일한 진실의 원천으로 만들어라

Slack에서 합의한 내용, Notion에 정리한 컨벤션, 구두로 전달한 결정 — 에이전트는 이 중 어느 것도 볼 수 없다. 중요한 모든 것을 레포에 녹여야 한다.

시장 동향

빅테크 AI 코드 생성 비율

채용 시장

2026년 3월 기준 "Harness Engineer"라는 직함의 채용공고는 아직 없다. 하지만 기능적으로 동일한 역할이 Agentic AI Specialist, AI Infrastructure Engineer 등의 이름으로 채용되고 있다. AI 엔지니어링 포지션은 전통 소프트웨어 엔지니어링 대비 300% 빠르게 성장 중이다.

국내 동향

**토스(Toss)**는 기술 블로그에서 하네스 엔지니어링을 조직 생산성의 저점을 높이는 메커니즘으로 소개했다. LLM 활용이 "개인의 직관 영역에 머물 수 없으며 팀이 설계하고 배포하는 시스템 영역"이 되어야 한다는 주장이다.

한국 최초 랄프톤(Ralph-ton) 해커톤에서는 13명의 엘리트 개발자가 첫날 하네스를 세팅하고, 에이전트를 밤새 자율 실행한 뒤, 다음 날 결과를 리뷰했다. 우승팀은 에이전트로 10만 줄의 코드를 생성했으며, 그 중 7만 줄이 테스트 코드였다.

한계와 열린 질문들

하네스 엔지니어링은 흥미로운 방향이지만, 비판도 존재한다.

Thoughtworks는 이 용어가 등장한 지 "2주 된 말"이라고 정리했다. 아직 표준화된 공식 직무명도 아니다. 다만 방향성은 명확하다.

하네스 도구 및 프레임워크

OpenAI는 Codex 하네스를 여러 제품에 재사용하기 위해 Codex App Server라는 JSON-RPC 기반 서버를 설계했다. CLI, VS Code 확장, 웹 앱, macOS 앱이 모두 동일한 하네스 위에서 돌아간다. 하네스 엔지니어링이 개별 앱마다 프롬프트를 새로 짜는 수준을 넘어, 재사용 가능한 에이전트 실행 환경을 설계하는 일까지 포괄함을 보여준다.

지금 할 수 있는 것

Martin Fowler 사이트에서는 이런 질문을 던졌다: 하네스가 **"새로운 서비스 템플릿"**이 될 것인가? 오늘날 팀이 골든 패스로 새 서비스를 스핀업하듯, 내일은 커스텀 린터, 구조적 테스트, AGENTS.md, 클린업 에이전트가 번들된 하네스 카탈로그에서 선택하게 될 수 있다.

거창한 시스템을 한 번에 구축할 필요는 없다. 지금 바로 시작할 수 있는 것들이 있다.

1. AGENTS.md(또는 CLAUDE.md) 작성하기 — 레포지토리의 구조, 규칙, 주요 패턴을 100줄 이내로 정리한다
2. 린터 에러 메시지를 에이전트 친화적으로 바꾸기 — "위반"만 알려주지 말고, 어떻게 고쳐야 하는지 메시지에 포함한다
3. 검증 가능한 단위로 작업 쪼개기 — 테스트로 성공/실패를 판단할 수 있는 작은 단위로 태스크를 나눈다
4. 에이전트 실패를 문서화하기 — 같은 실패가 반복되면 프롬프트가 아니라 제약을 추가한다
5. 레포 밖의 지식을 레포 안으로 옮기기 — Slack과 Notion에만 있는 컨벤션과 결정을 docs/에 정리한다

마무리

하네스 엔지니어링의 핵심 테제는 단순하다.

모델은 점점 범용화되고, 하네스가 에이전트의 성패를 결정한다.

깨끗한 코드를 직접 작성하는 능력보다, 에이전트가 올바른 코드를 생산할 수 있는 환경을 설계하는 능력이 더 중요해지고 있다. 코드를 짜는 사람에서, 에이전트를 일하게 만드는 사람으로. 역할의 전환은 이미 시작됐다.

참고 자료

• OpenAI - Harness Engineering
• Mitchell Hashimoto - My AI Adoption Journey
• Martin Fowler - Harness Engineering
• LangChain - Improving Deep Agents with Harness Engineering
• Anthropic - Effective Harnesses for Long-Running Agents
• 토스 기술 블로그 - 하네스를 통한 팀 생산성 향상