OpenAI Harness Engineering: 인간이 한 줄도 안 쓴 100만 줄짜리 제품, Codex 가 어떻게 만들었나

목차

1. 개요
2. 배경
3. 핵심 내용
   • 엔지니어의 역할 재정의
   • 애플리케이션 가독성 강화
   • 지식 베이스로서의 레포
   • 아키텍처와 취향의 강제
   • 엔트로피와 가비지 컬렉션
4. 의미와 시사점
5. 결론
6. Reference

개요

OpenAI 가 다섯 달 동안 “인간이 직접 작성한 코드 라인 0” 이라는 제약을 두고 내부 베타 제품을 개발한 결과를 공개했다. 2025년 8월 말 빈 git 저장소에서 시작해, 다섯 달 만에 약 100만 줄, 1,500개의 PR, 평일 기준 엔지니어 1인당 하루 3.5 PR 속도를 달성했다. 앱 로직, 테스트, CI 설정, 문서, 관측성, 내부 툴 모두 Codex 가 작성했다. 인간 엔지니어 3명에서 시작해 7명까지 확장됐는데 생산성은 오히려 증가했다. 이 글은 OpenAI 가 정리한 “harness engineering” 의 핵심 원칙을 정리한 글이다.

배경

OpenAI 팀은 “SW 엔지니어링 팀의 주된 업무가 코드 작성이 아니라 환경 설계, 의도 명세, 피드백 루프 구축으로 바뀐다면 무엇이 깨지고 무엇이 까다로워지는지” 를 확인하고 싶었다고 한다. 즉 “Humans guide. Agents execute.” 라는 원칙 위에서, 인간의 유일한 희소 자원인 시간과 주의력을 어떻게 극대화할지를 실험했다. 초기 commit 부터 Codex CLI(GPT-5) 가 레포 골격, CI, 패키지 매니저 설정, 심지어 AGENTS.md 까지 생성했다.

핵심 내용

엔지니어의 역할 재정의

초기에는 진척이 느렸다. 원인은 Codex 의 무능이 아니라 “환경의 미정의” 였다. 에이전트가 고수준 목표를 향해 나아갈 도구, 추상화, 내부 구조가 부재했던 것이다. 그래서 인간 엔지니어의 주된 업무는 “에이전트가 유용한 일을 하도록 만들기” 가 됐다.

실무에서는 다음과 같이 동작한다. 인간은 거의 모든 상호작용을 프롬프트로 한다. 엔지니어가 태스크를 기술하고 에이전트를 실행시켜 PR 을 열게 한다. Codex 에게 자기 변경을 로컬에서 리뷰시키고, 추가 리뷰는 로컬·클라우드에서 다른 에이전트를 호출해 수행한다. 인간/에이전트 리뷰어가 모두 만족할 때까지 루프를 돈다(실질적으로 Ralph Wiggum Loop). Codex 는 gh, 로컬 스크립트, 레포에 내장된 skill 같은 표준 dev 툴을 직접 호출한다. 인간이 CLI 에 직접 복붙하는 일은 사라졌다.

애플리케이션 가독성 강화

코드 생산성이 오를수록 병목은 인간의 QA 역량으로 옮겨갔다. 팀은 “인간 시간과 주의력” 이라는 고정 제약을 풀기 위해 앱 UI, 로그, 메트릭을 Codex 가 직접 읽을 수 있게 만들었다.

• git worktree 단위로 앱을 부팅 가능하게 만들어, Codex 가 변경마다 격리된 인스턴스를 띄울 수 있도록 했다.
• Chrome DevTools 프로토콜을 에이전트 런타임에 연결하고, DOM 스냅샷·스크린샷·내비게이션을 다룰 스킬을 갖춰, Codex 가 버그를 재현하고 수정 검증을 UI 동작 기반으로 수행한다.
• 관측성 스택(Vector → Victoria Logs/Metrics/Traces)을 worktree 단위 ephemeral 환경으로 노출해, Codex 가 LogQL/PromQL/TraceQL 로 쿼리한다.

이 덕분에 “서비스 부팅을 800ms 미만으로 줄여” 같은 프롬프트가 다룰 수 있는 작업이 된다. Codex 한 번의 실행이 6시간 이상 단일 태스크에 매달리는 경우도 드물지 않다고 한다.

지식 베이스로서의 레포

컨텍스트 관리가 가장 큰 도전이었다. 초기에 시도한 “one big AGENTS.md” 는 예측 가능한 방식으로 실패했다. 컨텍스트가 한정된 자원인데 거대한 instructions 파일이 진짜 태스크와 코드, 문서 공간을 밀어냈고, 모든 것이 “중요” 라고 표기되니 아무것도 중요하지 않게 됐다. 결국 모놀리식 매뉴얼은 만료된 규칙의 무덤이 됐다.

해법은 AGENTS.md 를 백과사전이 아니라 “index” 로 다루는 것이다.

AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│   ├── index.md
│   ├── core-beliefs.md
│   └── ...
├── exec-plans/
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── generated/
│   └── db-schema.md
├── product-specs/
│   ├── index.md
│   └── ...
├── references/
│   ├── design-system-reference-llms.txt
│   ├── nixpacks-llms.txt
│   └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md

AGENTS.md 는 약 100줄, 주된 역할은 “지도(map)” 다. 디자인 문서는 인덱싱되고 verification 상태가 함께 기록된다. 계획(plans)은 1급 산출물로 다룬다. 작은 변경은 가벼운 plan, 복잡한 작업은 진행 로그와 결정 기록을 담은 execution plan 으로 남기고 레포에 커밋된다. 린터와 CI 가 지식 베이스의 최신성, 교차 링크, 구조 정합성을 기계적으로 검증한다. recurring “doc-gardening” 에이전트가 실제 코드 동작과 어긋난 문서를 찾아 PR 을 연다.

핵심 원칙은 “에이전트가 실행 중에 컨텍스트로 가져올 수 없는 것은 존재하지 않는다” 다. Google Docs, Slack 스레드, 사람의 머릿속 암묵지는 시스템에 비가시적이다. 모든 합의는 레포에 마크다운으로 박혀야 한다.

아키텍처와 취향의 강제

문서만으로는 일관성을 유지할 수 없다. 팀은 마이크로매니지 대신 “invariants” 를 enforce 하는 방식을 택했다. 예: Codex 가 경계에서 데이터 구조를 parse 하도록 요구하지만, 어떤 라이브러리를 쓸지는 강제하지 않는다(모델은 Zod 를 선호하는 듯하다).

비즈니스 도메인은 다음과 같이 엄격한 레이어 그래프로 분할된다.

Types → Config → Repo, Providers → Service → Runtime → UI

종횡 관심사(auth, connectors, telemetry, feature flags)는 Providers 라는 단일 명시적 인터페이스로만 진입한다. 이 규칙은 Codex 가 직접 생성한 커스텀 린터와 구조 테스트로 기계적으로 강제된다. 린트 메시지에는 remediation 지시까지 포함시켜 에이전트가 자동 수정할 수 있게 했다.

영역	강제 방식
도메인 경계	커스텀 린터 + 구조 테스트
데이터 검증	parse-at-the-boundary 강제
로깅	구조화 로깅 정적 검사
명명 규약	schema/type 네이밍 린트
파일 크기	상한 린트
플랫폼 신뢰성	플랫폼별 lint 규칙

전통적으로는 엔지니어 수백 명 규모에 도달해야 도입되는 아키텍처 강제다. 하지만 에이전트 코딩에서는 “속도가 아키텍처 부패 없이 유지되도록” 하기 위해 초기 단계의 필수 조건이다.

또한 PR 수명이 짧고, 머지 게이트는 최소만 막는다. 플레이키 테스트는 보통 후속 재실행으로 해결한다. 에이전트 처리량이 인간 주의를 압도하는 시스템에서는 “고치는 비용” 이 싸고 “기다리는 비용” 이 크다.

엔트로피와 가비지 컬렉션

자율 에이전트의 또 다른 문제는 “이미 존재하는 패턴을 복제” 한다는 점이다. 불균질한 패턴이라도 그대로 확산되므로 시간이 지나면 drift 가 누적된다. 초기에는 매주 금요일(주 20%) 을 “AI 쓰레기 청소” 에 썼지만 스케일하지 않았다.

해법은 “golden principles” 를 레포에 코드화하고 청소를 상시 프로세스로 만드는 것이다.

원칙 예시	의도
손수 만든 헬퍼 대신 공유 유틸 패키지 선호	invariant 를 중앙화
“YOLO 스타일” 데이터 탐색 금지	경계에서 검증 또는 타입드 SDK 사용

규칙적인 cadence 로 백그라운드 Codex 작업이 drift 를 스캔하고, quality score 를 업데이트하며, 타깃 리팩토 PR 을 자동으로 연다. 대부분의 PR 은 1분 이내 리뷰되어 자동 머지된다. 저자는 이를 “기술 부채는 고이자 대출” 이라 표현한다. 한꺼번에 갚는 것보다 매일 작은 청소가 압도적으로 싸다는 의미다.

의미와 시사점

이 글의 핵심 명제는 두 가지다. 첫째, 에이전트가 코드를 “많이” 쓰는 것이 곧 성공이 아니다. 실제 사용자가 매일 쓰는 제품으로 검증돼야 한다는 점에서 OpenAI 팀은 이 함정을 의식적으로 피했다. 둘째, 인간의 일은 코드 작성에서 “환경 설계, 의도 명세, 피드백 루프 구축”으로 이동한다.

실무적으로는 다음 체크리스트가 도출된다.

영역	권장
컨텍스트 관리	AGENTS.md 는 인덱스, 본체는 docs/ 구조화
UI 검증	DevTools 프로토콜로 에이전트가 UI 직접 검증
관측성	LogQL/PromQL 로 에이전트가 직접 쿼리
아키텍처	도메인 레이어 그래프 + 커스텀 린터
청소	golden principles + 백그라운드 리팩토 PR

“Slack 에 적힌 내용은 에이전트에게 없다” 라는 원칙은 인간 협업 문서화에도 그대로 적용된다. 새 동료가 3개월 뒤 합류했을 때 못 보는 정보는 에이전트도 못 본다.

결론

OpenAI 의 harness engineering 실험은 “에이전트 코딩이 실제로 1M LOC, 1,500 PR 규모로 굴러가려면 무엇이 필요한가” 에 대한 첫 대규모 사례 보고다. 결론은 모델이 똑똑해질수록 인간이 해야 할 진짜 일은 “레포가 에이전트에게 명확하게 읽히도록 만드는 것” 이라는 점이다. 이는 골든 원칙의 코드화, 도메인 경계의 기계적 강제, doc-gardening 같은 상시 청소 프로세스로 구체화된다. 결국 코드의 디스플린은 줄어들지 않고, 그 디스플린이 “코드 작성” 에서 “scaffolding” 으로 옮겨갔을 뿐이다.

Reference

• Harness Engineering - OpenAI