하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기
목차
개요
OpenAI의 기술 스태프 멤버 Ryan Lopopolo는 지난 5개월 동안 사람이 코드 라인을 전혀 직접 작성하지 않고 소프트웨어 제품의 내부 베타를 구축하고 출시한 실험을 공개했다. 이 제품은 내부 일일 사용자와 외부 알파 테스터를 두고 출시, 배포, 고장, 수리가 진행되는 실제 서비스다. 다른 점은 애플리케이션 로직, 테스트, CI 구성, 문서화, 관측 가능성, 내부 툴링 등 모든 코드 라인이 Codex에 의해 작성되었다는 것이다. 수작업으로 작성했을 때 걸렸을 시간의 약 1/10 정도로 작성된 것으로 추정한다.
이 글의 핵심 메시지는 명확하다. 소프트웨어 엔지니어링 팀의 주된 업무가 더 이상 코드 작성이 아니라, 환경을 설계하고 의도를 명시하며 에이전트가 안정적으로 작업할 수 있는 피드백 루프를 구축하는 것으로 바뀐다는 점이다. 이러한 작업을 저자는 하네스 엔지니어링(harness engineering)이라고 부른다.
사람이 조정하고 에이전트가 수행
빈 리포지터리에 대한 첫 커밋은 2025년 8월 말에 이루어졌다. 초기 스캐폴드인 리포지터리 구조, CI 구성, 서식 지정 규칙, 패키지 관리자 설정, 애플리케이션 프레임워크는 소수의 기존 템플릿을 바탕으로 GPT-5를 사용해 Codex CLI에서 생성되었다. 에이전트에게 작업 방법을 알려주는 초기 AGENTS.md 파일도 Codex가 직접 작성했다. 시스템을 뒷받침할 사람이 작성한 기존 코드는 없었고, 처음부터 리포지터리는 에이전트에 의해 형성되었다.
5개월 후 리포지터리에는 애플리케이션 로직, 인프라, 툴링, 문서화, 내부 개발자 유틸리티 전반에 걸쳐 약 백만 라인의 코드가 포함되었다. 그 기간 동안 Codex를 이끄는 단 세 명의 엔지니어로 구성된 소규모 팀이 약 1,500개의 pull request를 열고 병합했다. 이는 엔지니어 1인당 하루 평균 3.5개의 PR 처리량에 해당하며, 팀이 7명으로 성장하면서 처리량은 오히려 증가했다. 중요한 점은 단지 출력을 위한 출력이 아니라, 매일 사용하는 내부 파워 유저를 포함해 수백 명이 실제로 사용해 왔다는 것이다.
개발 과정 전반에 걸쳐 사람은 코드에 직접 기여한 적이 없다. 이것이 “수동으로 작성한 코드가 없다”는 팀의 핵심 철학이 되었다.
핵심 실천
엔지니어의 역할 재정의
사람이 직접 코딩을 하지 않기 때문에 시스템, 스캐폴딩, 레버리지에 중점을 둔 다른 종류의 엔지니어링 작업이 필요했다. 초기 진행은 예상보다 더뎠는데, 이는 Codex의 역량 부족이 아니라 환경이 제대로 갖춰지지 않았기 때문이다. 에이전트가 상위 목표를 달성하기 위한 도구, 추상화, 내부 구조가 부족했던 것이다.
실제로는 큰 목표를 더 작은 빌딩 블록인 설계, 코드, 검토, 테스트 등으로 세분화하고, 에이전트가 이 블록을 구성하도록 유도한 다음 더 복잡한 작업을 해결하는 깊이 우선 방식이었다. 실패했을 때 “더욱 분발”하는 것으로는 문제가 해결되지 않았다. 진전을 이룰 유일한 방법이 Codex가 일을 하도록 만드는 것이었기 때문에, 엔지니어들은 “어떤 기능이 누락되어 있으며, 에이전트가 읽고 실행하기 쉽게 만들려면 어떻게 해야 할까”를 계속 고민했다.
사람은 거의 전적으로 프롬프트를 통해 시스템과 상호작용한다. PR을 완료하기 위해 Codex에게 로컬에서 자체 변경 사항을 검토하고, 로컬과 클라우드에서 특정 에이전트 검토를 추가로 요청하며, 사람이나 에이전트가 준 피드백에 응답하고, 모든 에이전트 검토자가 만족할 때까지 반복하도록 지시한다. 이는 사실상 랄프 위검 루프(Ralph Wiggum Loop)다. Codex는 사람이 복사하여 붙여넣지 않아도 gh, 로컬 스크립트, 리포지터리 내장 스킬 같은 표준 개발 도구를 직접 사용해 컨텍스트를 수집한다. 사람이 pull request를 검토할 수는 있지만 반드시 필요한 작업은 아니며, 시간이 지나면서 거의 모든 검토를 에이전트 간 처리로 전환해 왔다.
애플리케이션의 가독성 향상
코드 처리량이 증가하면서 인적 QA 역량에 병목이 발생했다. 사람의 시간과 주의력이 고정된 제약이었기 때문에, 애플리케이션 UI, 로그, 앱 메트릭 등을 Codex가 직접 읽고 이해할 수 있도록 만드는 데 집중했다.
예를 들어 git worktree별로 앱을 부팅할 수 있게 하여 Codex가 변경 사항마다 하나의 인스턴스를 실행하고 제어하도록 했다. 또한 Chrome DevTools Protocol을 에이전트 런타임에 연결하고 DOM 스냅샷, 스크린샷, 탐색 작업을 위한 스킬을 만들었다. 이를 통해 Codex는 버그를 재현하고 수정 사항을 검증하며 UI 동작에 대해 직접 추론할 수 있었다.
관측 가능성 툴링에서도 마찬가지였다. 로그, 메트릭, 추적은 각 워크트리에 대해 일시적으로 유지되는 로컬 관측 가능성 스택을 통해 Codex에 노출된다. Codex는 완전히 격리된 앱 버전에서 작업하며, 작업이 끝나면 로그와 메트릭은 삭제된다. 에이전트는 LogQL로 로그를, PromQL로 메트릭을 쿼리할 수 있다. 이러한 컨텍스트가 주어지면 “서비스 시작이 800ms 이내에 완료”되도록 하거나 “네 가지 핵심 사용자 여정에서 어떤 스팬도 2초를 초과하지 않도록” 하는 프롬프트를 다루기 쉬워진다. 한 번의 Codex 실행으로 6시간 이상, 종종 사람이 잠자는 동안 한 가지 작업을 수행하는 경우도 많다.
리포지터리 지식을 기록 시스템으로
컨텍스트 관리는 에이전트가 크고 복잡한 작업을 효과적으로 수행하는 데 가장 큰 과제 중 하나다. 초기에 얻은 교훈은 간단했다. Codex에 1,000페이지의 설명서가 아니라 지도를 제공해야 한다는 것이다.
“하나의 큰 AGENTS.md” 접근은 예측 가능한 방식으로 실패했다.
| 실패 양상 | 내용 |
|---|---|
| 컨텍스트는 희소 리소스 | 거대한 지침 파일이 작업과 코드를 복잡하게 만들어 에이전트가 핵심 제약을 놓치거나 잘못된 제약에 최적화한다 |
| 지침이 너무 많으면 지침이 아니다 | 모든 것이 중요하면 중요한 것은 없으며, 에이전트는 의도적 탐색 대신 로컬 패턴 매칭을 한다 |
| 순식간에 낡는다 | 획일적 매뉴얼은 낡은 규칙의 무덤이 되고 아무도 유지관리하지 않는다 |
| 확인하기 어렵다 | 단일 블롭은 커버리지, 신선도, 소유권, 교차 연결 같은 기계적 점검에 부적합해 드리프트가 불가피하다 |
따라서 AGENTS.md를 백과사전이 아니라 목차로 취급한다. 리포지터리의 지식 베이스는 기록 시스템으로 취급되는 구조화된 docs/ 디렉터리에 있다. 약 100라인의 짧은 AGENTS.md만 컨텍스트에 삽입되어 주로 지도 역할을 하며, 더 깊고 신뢰할 수 있는 정보 소스를 가리킨다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
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
│ ├── new-user-onboarding.md
│ └── ...
├── references/
│ ├── design-system-reference-llms.txt
│ ├── nixpacks-llms.txt
│ ├── uv-llms.txt
│ └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md
설계 문서는 검증 상태와 에이전트 우선 운영 원칙을 정의하는 핵심 신념을 포함해 분류되고 색인화된다. 아키텍처 문서는 도메인과 패키지 레이어링의 최상위 지도를 제공한다. 품질 문서는 각 제품 도메인과 아키텍처 레이어에 등급을 매기고 시간이 지남에 따라 격차를 추적한다. 계획은 일급 아티팩트로 간주된다. 간단한 변경에는 일시적이고 단순한 계획을 쓰고, 복잡한 작업은 진행 상황과 의사결정 로그가 포함된 실행 계획으로 리포지터리에 저장한다.
이를 기계적으로 시행한다. 전용 린터와 CI 작업이 지식 베이스가 최신이고 교차 링크되어 있으며 올바르게 구성되어 있는지 검증한다. 반복 실행되는 doc-gardening 에이전트가 실제 코드 동작을 반영하지 않는 오래된 문서를 검토하고 수정용 pull request를 연다.
아키텍처와 취향의 기계적 강제
문서화만으로는 에이전트가 생성한 코드베이스를 완전히 일관되게 유지할 수 없다. 구현을 세세하게 관리하지 않고 불변 조건을 강제함으로써, 기초를 튼튼히 유지하면서 에이전트가 빠르게 출시하도록 한다. 예를 들어 Codex가 경계에서 데이터 형태를 파싱하기를 원했지만 그 방법은 구체적으로 명시하지 않았다. 모델은 Zod를 선호하는 것으로 보이지만 특정 라이브러리를 지정하지는 않았다.
에이전트는 엄격한 경계와 예측 가능한 구조를 갖춘 환경에서 가장 효과적이므로, 엄격한 아키텍처 모델을 중심으로 애플리케이션을 구축했다. 각 비즈니스 도메인은 엄격하게 검증된 종속성 방향과 제한된 허용 에지 집합을 사용해 고정된 계층으로 나뉜다. 각 도메인 내에서 코드는 Types에서 Config, Repo, Service, Runtime, UI로 이어지는 고정된 레이어를 통해서만 전달될 수 있다. 인증, 커넥터, 텔레메트리, 기능 플래그 같은 교차 관심사는 Providers라는 하나의 명시적 인터페이스를 통해서만 유입된다. 그 외 모든 것은 허용되지 않으며 기계적으로 강제된다.
이러한 제약은 Codex가 생성한 맞춤형 린터와 구조적 테스트로 적용된다. 맞춤형 린트로 구조화된 로깅, 스키마와 유형의 명명 규칙, 파일 크기 제한, 플랫폼별 안정성 요구 사항을 정적으로 적용한다. 린트가 맞춤형이므로 오류 메시지를 작성해 에이전트 컨텍스트에 수정 지침을 주입한다. 사람 중심 워크플로에서는 이러한 규칙이 지나치게 세세하게 느껴질 수 있지만, 에이전트를 쓰면 한 번 인코딩된 규칙이 한꺼번에 어디에나 적용되어 효과가 몇 배가 된다.
결과 코드가 항상 인간의 문체 선호와 일치하지는 않지만 문제가 되지 않는다. 출력이 정확하고 유지관리 가능하며 앞으로의 에이전트 실행에서 읽기 쉽다면 기준을 충족한 것이다. 인간의 취향은 리뷰 코멘트, 리팩터링 pull request, 사용자 측 버그를 통해 문서 업데이트로 기록되거나 툴링에 직접 인코딩되어 시스템에 지속적으로 피드백된다. 문서화가 부족하면 규칙을 코드로 승격한다.
처리량이 바꾼 병합 철학
Codex의 처리량이 증가하면서 기존의 많은 엔지니어링 규범이 오히려 역효과를 내기 시작했다. 리포지터리는 최소한의 차단 병합 게이트로 운영된다. pull request는 수명이 짧다. 테스트 불안정성은 진행을 무기한 막기보다 후속 실행으로 해결하는 경우가 많다. 에이전트 처리량이 사람의 주의력을 훨씬 초과하는 시스템에서는 수정 비용이 저렴하고 대기 비용이 크다. 다만 이는 처리량이 적은 환경에는 적합하지 않으며 적절한 절충이 필요하다.
엔트로피와 가비지 컬렉션
에이전트의 완전한 자율성은 새로운 문제도 야기한다. Codex는 리포지터리에 이미 존재하는 패턴을, 심지어 불균일하거나 최적이 아닌 패턴도 복제한다. 따라서 시간이 지나면 필연적으로 드리프트가 발생한다.
처음에는 사람들이 매주 금요일, 즉 일주일의 20%를 들여 “AI 슬로프”를 수동으로 정리했지만 그 방식은 확장되지 않았다. 대신 “황금 원칙”을 리포지터리에 직접 인코딩하고 정기적인 정리 프로세스를 구축했다. 예를 들어 불변 조건을 중앙에서 관리하기 위해 직접 만든 헬퍼보다 공유 유틸리티 패키지를 선호하고, 경계를 검증하거나 유형 지정된 SDK에 의존해 에이전트가 추측한 형태로 잘못 구축하지 못하게 한다. 정기적으로 편차를 검사하고 품질 등급을 업데이트하며 대상 리팩터링 pull request를 생성하는 Codex 백그라운드 작업을 운영하는데, 대부분 1분 이내에 검토되어 자동 병합된다.
이것은 가비지 컬렉션처럼 작동한다. 기술 부채는 고금리 대출과 같아서 한꺼번에 갚는 것보다 조금씩 꾸준히 갚는 편이 낫다. 사람의 취향은 한 번 포착되면 코드의 모든 라인에 지속적으로 반영되며, 나쁜 패턴이 며칠이나 몇 주 동안 퍼지기 전에 매일 포착해 해결할 수 있다.
자율성 수준의 증가
테스트, 검증, 리뷰, 피드백 처리, 복구 등 더 많은 개발 루프가 시스템에 직접 인코딩되면서, 리포지터리는 Codex가 새로운 기능을 처음부터 끝까지 주도할 수 있는 임계점을 넘어섰다. 이제 에이전트는 한 번의 프롬프트로 다음을 수행할 수 있다.
| 단계 | 동작 |
|---|---|
| 1 | 코드베이스의 현재 상태 검증 |
| 2 | 보고된 버그 재현 |
| 3 | 실패 상황을 시연하는 동영상 녹화 |
| 4 | 수정 사항 구현 |
| 5 | 애플리케이션을 실행하여 수정 검증 |
| 6 | 해결책을 보여 주는 두 번째 동영상 녹화 |
| 7 | pull request 열기 |
| 8 | 에이전트와 사람 피드백에 응답 |
| 9 | 빌드 실패 감지 및 수정 |
| 10 | 판단이 필요할 때만 사람에게 에스컬레이션 |
| 11 | 변경 사항 병합 |
저자는 이러한 동작이 이 리포지터리의 특정 구조와 툴링에 크게 의존하며, 적어도 아직은 유사한 투자 없이 일반화할 수 있다고 가정해서는 안 된다고 강조한다.
에이전트가 생성하는 것은 제품 코드와 테스트뿐 아니라 CI 구성과 릴리스 툴링, 내부 개발자 도구, 문서화와 설계 내역, 평가 하네스, 리뷰 코멘트와 응답, 리포지터리를 관리하는 스크립트, 생산 대시보드 정의 파일까지 포함한다. 사람은 항상 루프에 남지만 예전과 다른 추상화 레이어에서 작업한다. 업무를 우선시하고, 사용자 피드백을 수용 기준으로 바꾸며, 결과를 검증한다. 에이전트가 어려움을 겪으면 이를 도구, 가드레일, 문서가 누락되었다는 신호로 간주하고, 항상 Codex 자체로 수정 사항을 작성해 리포지터리에 다시 제공한다.
의미와 시사점
이 글에서 핵심은 에이전트 관점의 가독성이다. 에이전트의 관점에서 실행 중 컨텍스트로 접근할 수 없는 것은 사실상 존재하지 않는다. Google Docs, 채팅 스레드, 사람들의 머릿속 지식은 시스템에서 접근할 수 없고, 리포지터리 내의 버전 관리되는 아티팩트인 코드, 마크다운, 스키마, 실행 계획에만 접근할 수 있다. 따라서 Slack 토론에서 모은 합의도 에이전트가 검색할 수 없다면, 3개월 후 입사한 신입 사원이 알 수 없는 것과 같은 의미로 판독 불가능하다.
이 구상은 여러 절충을 명확히 했다. 팀은 리포지터리 내에서 완전히 내부화하고 추론할 수 있는 종속성과 추상화를 선호했다. 흔히 지루하다고 평가되는 기술은 결합성, API 안정성, 학습 데이터 내 표현 덕분에 에이전트가 모델링하기 쉬운 경향이 있다. 어떤 경우에는 공개 라이브러리의 불투명한 업스트림 동작에 맞추기보다 에이전트가 기능 일부를 다시 구현하는 편이 더 저렴했다. 예를 들어 범용 p-limit 스타일 패키지를 가져오는 대신, OpenTelemetry 계측과 긴밀히 통합되고 테스트 커버리지가 100%이며 런타임 기대와 정확히 일치하는 자체 map-with-concurrency 헬퍼를 구현했다.
저자는 여전히 배우고 있는 점도 솔직하게 밝힌다. 완전한 에이전트 생성 시스템에서 아키텍처 일관성이 수년에 걸쳐 어떻게 진화하는지, 사람의 판단이 가장 큰 영향력을 발휘하는 부분과 그 판단을 인코딩해 복합적으로 활용하는 방법은 아직 학습 중이다. 분명해진 것은 소프트웨어 구축에 여전히 규율이 필요하지만, 그 규율이 코드보다는 스캐폴딩에서 더 많이 드러난다는 점이다.
결론
지난 5개월의 실험은 사람이 한 줄도 직접 작성하지 않고도 약 백만 라인의 실사용 제품을 구축할 수 있음을 보여주었다. 그러나 그 결과는 Codex의 단독 역량이 아니라, 사람이 설계한 환경, 피드백 루프, 제어 시스템의 산물이다. 엔지니어의 역할은 코드를 쓰는 것에서 에이전트가 안정적으로 작동할 수 있는 하네스를 설계하는 것으로 이동했다. 관측 가능성, 지식 베이스, 아키텍처 불변 조건, 가비지 컬렉션 루프는 모두 사람의 희소한 시간과 주의를 극대화하기 위한 장치다. Codex와 같은 에이전트가 소프트웨어 라이프사이클에서 더 많은 부분을 차지할수록, 어떤 환경과 피드백 루프를 설계할 것인가라는 질문은 더 중요해질 것이다.