OpenAI가 100만 줄 코드를 에이전트로만 만든 비밀, 하네스 엔지니어링 5가지 원칙

요즘 “하네스”라는 단어가 자주 등장합니다. OpenAI가 공개한 블로그가 이 개념을 명확히 정의해줬습니다. 에이전트 시대에 엔지니어가 실제로 무엇을 해야 하는지 정리합니다.

하네스(Harness)는 AI 에이전트가 실제 세상에 영향을 미칠 수 있게 만드는 도구 껍데기입니다. 추론 모델이 두뇌라면 하네스는 손발입니다. 파일을 읽고, 코드를 고치고, 테스트를 돌리고, 배포까지 하는 모든 행위가 하네스 안에서 일어납니다.

OpenAI 내부 팀은 2025년 8월 말 빈 저장소에서 시작해 100만 줄짜리 신제품을 Codex 에이전트로만 만들었습니다. 사람이 직접 코드를 쓰지 않는 조건이었습니다. 수작업 대비 10분의 1 시간이 걸렸다고 밝혔습니다. 이 과정에서 깨달은 원칙이 아래 5가지입니다.

에이전트가 못 보는 지식은 존재하지 않는 것과 같다

Codex 입장에서 실행 중 접근 못하는 정보는 없는 정보나 마찬가지입니다. Google Docs에 있는 기획 문서, Slack에서 합의한 아키텍처 방향, 누군가 머릿속에만 가진 암묵지 전부 보이지 않습니다. 3개월 뒤 합류하는 신입에게 보이지 않는 것과 동일한 상황입니다.

그래서 팀은 모든 결정을 저장소 안 마크다운과 스키마와 실행 계획서(ExecPlan)로 밀어넣었습니다.

• ExecPlan은 PLANS.md에 정의된 자기 완결형 설계 문서
• 초보자가 읽고 끝까지 구현할 수 있어야 통과 기준을 충족
• Codex 단일 프롬프트로 7시간 이상 연속 작업한 사례도 존재
• matklad의 ARCHITECTURE.md 개념을 에이전트용으로 확장한 구조

”더 노력해” 대신 “무슨 능력이 부족한가”를 물어야 한다

초기에 에이전트 속도가 기대보다 느렸습니다. 원인은 모델 성능이 아니라 환경이 덜 갖춰져 있었기 때문입니다. 실패할 때마다 “어떤 능력이 빠져 있고, 어떻게 에이전트가 읽고 검증할 수 있게 만들 것인가”를 질문했습니다.

• 외부 라이브러리 대신 직접 만든 동시성 헬퍼로 OpenTelemetry와 100% 연동
• 업계에서 흔히 이야기하는 “지루한 기술”이 에이전트에게 유리 (API 안정성과 학습 데이터 표현도가 높기 때문)

문서가 아니라 기계적 강제가 코드 일관성을 지킨다

문서만으로는 에이전트가 생성한 코드베이스의 일관성이 무너졌습니다. 그래서 팀은 구현을 세세히 지시하는 대신 불변 규칙만 기계적으로 강제하는 방식을 택했습니다. 데이터 경계에서 파싱을 반드시 하도록 했지만, 어떤 라이브러리를 쓸지는 에이전트에게 맡겼습니다. 아키텍처도 계층형 도메인 구조로 고정하고 의존성 방향을 린터로 검증합니다.

• 비즈니스 도메인마다 Providers → Service → Runtime → UI 고정 레이어
• Types와 Config와 Repo가 하위에서 공유되는 교차 관심사 구조
• 커스텀 린터와 구조 테스트가 위반 시 즉시 빌드를 실패시킴
• 린터 자체도 Codex가 작성

에이전트에게 눈을 달아주면 6시간도 혼자 일한다

Chrome DevTools Protocol을 에이전트 런타임에 연결해서 DOM 스냅샷, 스크린샷, 네비게이션 기능을 Codex에 제공했습니다. 작업 전후 스냅샷을 비교하고, 런타임 이벤트를 관찰한 뒤, 수정 사항을 적용하는 루프를 깨끗해질 때까지 반복하는 구조입니다.

관측 도구도 동일한 방식으로 붙였습니다. git worktree마다 임시 관측 스택이 뜨고 작업이 끝나면 사라집니다.

• Victoria Logs(LogQL)와 Victoria Metrics(PromQL)로 에이전트가 직접 로그와 지표 조회
• “서비스 시작이 800ms 안에 끝나게 하라” 같은 프롬프트가 실행 가능해짐
• 단일 Codex 실행이 6시간 넘게 한 작업에 집중하는 경우도 정기적으로 관찰

지도를 주되 1,000 페이지 매뉴얼은 주지 마라

맥락 관리가 에이전트 효과를 좌우합니다. 처음에 거대한 AGENTS.md 하나에 전부 담는 방식을 시도했지만 실패했습니다. matklad가 2021년에 쓴 ARCHITECTURE.md 개념이 여기서 빛을 발했습니다. 프로젝트 전체 구조를 짧게 조감하되 자주 바뀌지 않는 것만 담는 원칙입니다. 에이전트에게도 동일하게 적용됩니다.

• ARCHITECTURE.md는 코드맵이지 코드 지도책이 아님
• 아키텍처 불변 규칙은 “무언가가 없다”는 형태로 표현될 때가 많음
• 경계(boundary)를 명시하면 그 뒤 구현을 모두 제약하는 효과

아직 풀리지 않은 질문

이런 Codex 팀에게도 아직 풀리지 않은 질문이 있습니다. 에이전트만으로 만든 시스템이 수년간 아키텍처 일관성을 유지할 수 있는지는 아무도 모릅니다. 모델이 계속 발전하면 이 체계 자체가 어떻게 바뀔지도 미지수입니다.

한 가지는 분명합니다. 코드를 잘 쓰는 시대는 끝나고 있고, 환경을 잘 설계하는 시대가 시작됐습니다.