Harness Engineering이란? 에이전트가 코드 짜는 시대, 개발자의 진짜 역할 재정의 (개념·구조·실전 체크리스트)

"AI가 코드를 짜준다는데, 그러면 나는 뭘 해야 하지?"
이 질문에 대한 가장 구체적인 답이 2025년 2월, OpenAI 블로그에 올라왔습니다.
오늘 글은 그 답 — Harness Engineering — 의 개념부터 실전 적용 구조까지, '에이전트 시대에 개발자가 정확히 무엇을 설계해야 하는지'를 매뉴얼 형태로 정리합니다.

"소프트웨어 엔지니어의 주된 역할은 더 이상 코드를 직접 작성하는 것이 아니라, 환경을 설계하고 의도를 명세하며, 에이전트가 신뢰성 있게 일할 수 있는 피드백 루프를 구축하는 것이다."
— OpenAI, Harness Engineering: Leveraging Codex in an Agent-First World (2026.02.11)

1) Harness Engineering이란? — 한 문장 정의부터
2) 왜 지금 이 개념이 등장했는가 — 배경과 맥락
3) 하네스의 3대 구성요소 (비교표 포함)
4) 실전 구조: 저장소를 어떻게 설계하는가
5) Antigravity 등 에이전트 퍼스트 도구에서의 적용 포인트
6) 초급/중급 개발자를 위한 적용 체크리스트
Q&A 1) 코드를 직접 안 짜면 실력이 떨어지지 않나요?
Q&A 2) 1인 개발자도 하네스 설계가 필요한가요?
Q&A 3) 기존 프로젝트에도 적용할 수 있나요?

엔지니어가 AI 에이전트 주변에 환경(화살표, 가드레일, 문서, 린터)을 설계하는 미니멀한 디자인

1) Harness Engineering이란? — 한 문장 정의부터

Harness Engineering은 "AI 에이전트가 신뢰성 있게 코드를 작성·유지할 수 있도록, 그 주변 환경(도구·규칙·문서·피드백 루프)을 설계하는 엔지니어링 분야"입니다. 여기서 "하네스(harness)"는 말 그대로 '마구(馬具)' — 말(에이전트)이 올바른 방향으로 힘을 발휘하도록 잡아주는 장치에 비유할 수 있습니다.

이 용어는 2026년 2월 11일 OpenAI가 공개한 블로그 포스트 "Harness engineering: leveraging Codex in an agent-first world"에서 공식적으로 등장했습니다. OpenAI 내부 팀이 5개월간 사람이 직접 작성한 코드 0줄로 약 100만 줄 규모의 실제 제품을 만들며 얻은 교훈을 정리한 것이 핵심입니다.

핵심 전제는 명확합니다. "사람은 방향을 제시하고(Steer), 에이전트는 실행한다(Execute)." 그렇다면 엔지니어의 역할은 코드를 타이핑하는 것이 아니라, 에이전트가 올바르게 실행할 수 있는 환경 자체를 만드는 일이 됩니다. 그 환경을 설계하는 행위가 바로 Harness Engineering입니다.

2) 왜 지금 이 개념이 등장했는가 — 배경과 맥락

AI 코딩 도구는 이미 몇 년 전부터 존재했습니다. GitHub Copilot, Cursor, Claude Code 등이 자동완성과 코드 생성을 도와왔죠. 그런데 왜 지금 "하네스"라는 별도의 엔지니어링 개념이 필요해진 걸까요?

이유는 에이전트의 자율성 수준이 근본적으로 달라졌기 때문입니다. 기존 도구가 "사람이 코드를 쓸 때 옆에서 도와주는 보조자"였다면, OpenAI Codex나 Google Antigravity의 에이전트는 "프롬프트 하나로 버그 재현 → 수정 → 테스트 → PR 오픈 → 리뷰 응답 → 병합까지 스스로 수행하는 독립 실행자"입니다. OpenAI의 실험에서는 단일 Codex 실행이 한 작업에 6시간 이상 지속되는 경우도 있었고, 대부분 엔지니어가 자는 동안 진행됐습니다.

자율성이 높아지면 당연히 문제도 커집니다. 에이전트는 저장소에 이미 존재하는 패턴을 복제하는데, 그 패턴이 최적이 아니어도 그대로 따릅니다. 시간이 지나면 아키텍처 드리프트(drift)가 발생하고, 코드 품질이 조용히 무너집니다. OpenAI 팀도 초기에는 매주 금요일(업무 시간의 20%)을 "AI 슬롭 정리"에 투입했다고 고백합니다. 이런 문제를 수동이 아니라 시스템으로 해결하는 것 — 그것이 Harness Engineering이 탄생한 직접적인 계기입니다.

3) 하네스의 3대 구성요소 (비교표 포함)

Martin Fowler의 분석에 따르면, OpenAI 팀의 하네스는 크게 세 가지 카테고리로 분류할 수 있습니다. 결정론적(deterministic) 방법과 LLM 기반 방법이 혼합되어 있다는 점이 중요합니다.

구성요소	핵심 역할	구체적 실천 방법	비유
① 컨텍스트 엔지니어링 (Context Engineering)	에이전트에게 "지도"를 주는 것. 1000페이지 매뉴얼이 아니라 목차와 포인터를 제공	· AGENTS.md를 ~100줄 목차로 유지 · docs/ 디렉터리를 단일 출처(SSOT)로 운영 · 로그/메트릭/DOM을 에이전트가 직접 읽을 수 있게 노출 · 슬랙 합의도 문서로 저장소에 커밋	신입 온보딩 문서
② 아키텍처 제약 (Architectural Constraints)	에이전트가 지켜야 할 "울타리"를 코드로 강제	· 도메인별 레이어 구조 + 의존성 방향 고정 · 커스텀 린터 & 구조 테스트로 위반 차단 · 린트 에러 메시지에 수정 방법을 포함(에이전트 컨텍스트에 주입) · "경계에서 파싱(parse, don't validate)" 원칙 강제	도로의 가드레일
③ 가비지 컬렉션 (Garbage Collection)	에이전트가 만든 엔트로피를 주기적으로 청소	· 백그라운드 에이전트가 정기 스캔 → 편차 탐지 → 리팩터링 PR 자동 오픈 · 품질 등급(Quality Score) 도메인별 추적 · 문서 ↔ 코드 불일치를 감지하는 "doc-gardening" 에이전트 운영	자동 청소 로봇

핵심 통찰은 이렇습니다. 세 요소 중 하나라도 빠지면 하네스가 작동하지 않습니다. 컨텍스트만 잘 줘도 제약이 없으면 에이전트가 매번 다른 방식으로 코드를 짜고, 제약을 걸어도 가비지 컬렉션이 없으면 시간이 지나며 조용히 무너집니다.

Context Engineering(지도 아이콘), Architectural Constraints(가드레일 아이콘), Garbage Collection(재활용 아이콘)이 AI 에이전트를 중심으로 순환하는 구조

4) 실전 구조: 저장소를 어떻게 설계하는가

OpenAI 팀이 공개한 저장소 지식 구조는 다음과 같습니다. 이 구조 자체가 하네스의 뼈대입니다.

AGENTS.md              ← 에이전트 진입점. ~100줄. "목차" 역할만 수행
ARCHITECTURE.md        ← 도메인 구조·패키지 레이어 상위 지도
docs/
├── design-docs/       ← 설계 문서 카탈로그 (검증 상태 표시)
│   ├── index.md
│   ├── core-beliefs.md  ← 에이전트 퍼스트 운영 원칙
│   └── ...
├── exec-plans/        ← 실행 계획 (진행 상황 + 의사결정 로그)
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── generated/         ← 자동 생성 문서 (DB 스키마 등)
├── product-specs/     ← 제품 명세
├── references/        ← 외부 참조 (디자인 시스템, 프레임워크 등)
├── QUALITY_SCORE.md   ← 도메인별 품질 등급 추적
├── RELIABILITY.md     ← 신뢰성 요구사항
└── SECURITY.md        ← 보안 규칙

이 구조에서 가장 중요한 설계 원칙은 "점진적 공개(Progressive Disclosure)"입니다. 에이전트는 AGENTS.md라는 짧은 진입점에서 시작해, 필요한 정보를 단계적으로 찾아갑니다. 처음부터 모든 정보를 컨텍스트에 밀어 넣지 않습니다. OpenAI 팀은 초기에 거대한 AGENTS.md 하나에 모든 지침을 담았다가 실패했다고 합니다. 컨텍스트 윈도우는 한정 자원이기 때문에, 정보가 많을수록 오히려 에이전트가 핵심을 놓치게 됩니다.

또 하나의 핵심 원칙은 "에이전트가 접근할 수 없는 정보는 존재하지 않는 것과 같다"입니다. Google Docs에 있는 회의록, Slack에서 합의한 아키텍처 결정, 누군가의 머릿속에만 있는 컨벤션 — 이런 것들은 저장소에 커밋되지 않으면 에이전트에게는 없는 것입니다. 마치 신입 엔지니어가 3개월 후에 합류했을 때 모르는 것과 동일합니다.

5) Antigravity 등 에이전트 퍼스트 도구에서의 적용 포인트

Harness Engineering은 특정 도구에 종속된 개념이 아닙니다. 다만, 에이전트의 자율성이 높은 환경일수록 하네스 설계의 효과가 극대화됩니다. 현재 사용하시는 Google Antigravity와 연결해서 생각해보겠습니다.

Antigravity는 Google이 2025년 11월에 공개한 에이전트 퍼스트 개발 플랫폼으로, 네 가지 핵심 원칙 — Trust(신뢰), Autonomy(자율성), Feedback(피드백), Self-improvement(자기 개선) — 을 중심으로 설계되었습니다. 에이전트가 코드를 작성하고, 터미널에서 localhost를 실행하고, 브라우저를 직접 조작해 테스트까지 수행하는 구조입니다.

Antigravity를 쓸 때 Harness Engineering 관점에서 챙겨야 할 포인트는 다음과 같습니다.

컨텍스트 설계 → Antigravity의 Knowledge 기능과 연결. Antigravity는 에이전트가 과거 작업에서 학습한 내용을 Knowledge Base에 저장하는 기능을 내장하고 있습니다. 여기에 프로젝트의 AGENTS.md, ARCHITECTURE.md, 핵심 설계 원칙을 등록해두면 에이전트가 매 작업마다 일관된 맥락을 갖고 시작합니다.

아키텍처 제약 → 린터·테스트를 저장소에 포함. Antigravity의 에이전트는 터미널을 직접 사용합니다. 저장소에 커스텀 린터와 구조 테스트가 있으면, 에이전트가 코드를 작성한 뒤 자동으로 실행해 위반 여부를 확인합니다. 린트 에러 메시지에 수정 방법을 자연어로 포함시키면, 에이전트가 스스로 문제를 해결할 수 있습니다.

피드백 루프 → Antigravity의 Artifact + 댓글 기능 활용. Antigravity는 에이전트의 작업 결과를 구현 계획, 워크스루, 스크린샷 등의 Artifact로 보여주며, 사용자가 Google Docs처럼 인라인 댓글로 피드백을 줄 수 있습니다. 이 피드백이 에이전트 실행에 자동 반영됩니다. 하네스 관점에서 보면, 이것이 바로 "사람의 취향을 시스템에 인코딩하는 경로"입니다.

6) 초급/중급 개발자를 위한 적용 체크리스트

OpenAI 팀은 5개월간 전담으로 하네스를 구축했지만, 모든 요소를 한꺼번에 도입할 필요는 없습니다. 아래 체크리스트를 위에서부터 하나씩 적용해보세요.

[컨텍스트 설계 — 가장 먼저]
□ AGENTS.md (또는 동등한 진입점 문서)를 100줄 이내로 작성했는가?
□ 프로젝트의 디렉터리 구조·핵심 규칙·참조 문서 위치가 명시되어 있는가?
□ Slack/회의에서 결정된 사항이 저장소 docs/에 커밋되어 있는가?
□ "에이전트가 이 저장소만 보고 작업할 수 있는가?" 기준으로 점검했는가?

[아키텍처 제약 — 다음 단계]
□ 의존성 방향(어떤 모듈이 어떤 모듈을 참조할 수 있는지)이 문서화되어 있는가?
□ 최소 1개 이상의 린터/포맷터가 CI에서 자동 실행되는가?
□ 린트 에러 메시지에 "왜 틀렸고 어떻게 고쳐야 하는지"가 자연어로 포함되어 있는가?
□ 파일 크기 제한, 네이밍 규칙 등 기계적으로 강제할 수 있는 규칙이 있는가?

[가비지 컬렉션 — 안정화 단계]
□ 문서와 코드의 불일치를 주기적으로 점검하는 프로세스가 있는가?
□ 품질 등급(Quality Score)을 도메인/모듈별로 추적하고 있는가?
□ 기술 부채를 "한 번에 몰아 처리"가 아니라 "매일 조금씩" 해결하고 있는가?

Context, Constraints, Garbage Collection 세 섹션으로 구성된 체크박스 항목

Q&A 1) 코드를 직접 안 짜면 실력이 떨어지지 않나요?

이 질문은 가장 자연스러운 우려입니다. 핵심은 "코드를 안 짜는 것"이 아니라 "코드를 짜는 행위의 추상화 레벨이 올라가는 것"이라는 점입니다. 하네스를 설계하려면 아키텍처, 의존성 관리, 테스트 전략, 관측 도구에 대한 이해가 오히려 더 깊어야 합니다. OpenAI 팀도 "에이전트가 막히면, 해결책은 '더 열심히 시도해봐'가 아니라 '어떤 능력이 부족한가?'를 찾는 것"이라고 강조합니다. 이 판단력은 코드를 이해하지 못하면 가질 수 없습니다.

Q&A 2) 1인 개발자도 하네스 설계가 필요한가요?

오히려 1인 개발자일수록 효과가 큽니다. OpenAI 실험의 핵심 메시지는 "인간의 시간과 주의력이 가장 희소한 자원"이라는 것입니다. 혼자 개발한다면 그 희소성은 극대화됩니다. 전체 하네스를 구축할 필요는 없지만, AGENTS.md 하나와 기본 린터 설정만으로도 에이전트의 출력 일관성이 크게 달라집니다. 작게 시작하되, "에이전트가 이 저장소만 보고 내 의도대로 작업할 수 있는가?"를 기준으로 하나씩 추가해가면 됩니다.

Q&A 3) 기존 프로젝트에도 적용할 수 있나요?

가능하지만 난이도가 다릅니다. Martin Fowler는 이를 "한 번도 정적 분석 도구를 돌려본 적 없는 코드베이스에 처음 돌렸을 때 경고에 파묻히는 상황"에 비유합니다. 기존 프로젝트에 하네스를 전면 적용하려면 비표준화된 구조와 누적된 엔트로피를 먼저 정리해야 하므로, 비용 대비 효과를 따져야 합니다. 권장 접근법은 새로운 모듈이나 기능 단위부터 하네스 원칙을 적용하고, 점진적으로 범위를 넓히는 것입니다.

Harness Engineering은 단순한 유행어가 아닙니다. AI 에이전트의 자율성이 높아지는 현실에서, 개발자의 역할이 "코드 작성자"에서 "에이전트가 일할 수 있는 환경의 설계자"로 이동하고 있다는 구조적 변화를 설명하는 프레임워크입니다. 오늘 당장 AGENTS.md 하나를 만들어보는 것 — 그것이 하네스 설계의 첫걸음입니다.

CTA: 댓글로 현재 사용 중인 AI 코딩 도구와 가장 큰 불편점을 남겨주세요. 도구별 AGENTS.md 템플릿을 정리해서 공유하겠습니다.