하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기 — 핵심 정리

하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기

하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기

OpenAI가 내부 베타 소프트웨어 제품을 5개월 동안 진행한 흥미로운 실험 결과를 공개했습니다. 핵심은 놀라울 정도로 단순합니다. 사람이 손으로 작성한 코드를 단 한 줄도 만들지 않고, AI 에이전트(Codex)만으로 약 100만 줄 규모의 코드베이스를 구축하고 출시했다는 점입니다. 이 글에서는 이 실험을 통해 도출된 하네스 엔지니어링(harness engineering)의 핵심 원칙을 정리하고, 우리가 일상 프로젝트에 적용할 수 있는 교훈을 살펴봅니다.

하네스 엔지니어링이란 무엇인가

하네스 엔지니어링이란 AI 에이전트가 신뢰할 수 있고 일관된 결과를 내도록 만드는 "환경과 도구"를 설계하는 작업입니다. 단순히 프롬프트를 잘 쓰는 것이 아니라, 에이전트가 읽고 따를 수 있는 코드, 문서, 린터, CI를 함께 만드는 행위입니다.

OpenAI 실험의 핵심 숫자는 인상적입니다. 빈 git 저장소에서 시작한 코드베이스는 약 5개월 만에 100만 줄 규모로 성장했고, 3명의 엔지니어가 약 1,500개의 PR을 열며 병합했습니다. 엔지니어 1인당 하루 평균 약 3.5개 PR이라는 처리량은 일반적인 팀의 10배 이상입니다.

이 모든 결과는 사람의 손으로 직접 작성된 코드 한 줄 없이 만들어졌습니다. 다만 "사람이 필요 없었다"는 뜻은 아닙니다. 엔지니어의 역할이 코드 작성에서 환경 설계, 의도 명세, 피드백 루프 구축으로 이동했을 뿐입니다.

엔지니어 역할의 재정의: 코더에서 디렉터로

실험 초기에는 진척이 예상보다 느렸습니다. 원인은 Codex의 역량 부족이 아니라 환경이 충분히 명세되지 않았기 때문이었습니다. 에이전트는 높은 수준의 목표를 향해 진척할 수 있도록 도구, 추상화, 내부 구조가 필요합니다.

엔지니어의 실제 업무는 다음과 같이 변했습니다.

• 큰 목표를 더 작은 빌딩 블록으로 분해

• 에이전트가 블록을 만들도록 프롬프트 설계

• 실패 시 "더 열심히 시도"가 아니라, 어떤 도구나 명세가 빠졌는지 진단

• 결과를 검증하고 우선순위를 조정

PR 한 개가 완료되는 과정에서도 Codex는 로컬에서 자체 변경을 리뷰하고, 로컬과 클라우드에서 추가 에이전트 리뷰를 요청하며, 인간 또는 에이전트 피드백에 응답합니다. 이 순환은 "Ralph Wiggum Loop"에 가깝다고 표현되며, 모든 리뷰어가 만족할 때까지 반복됩니다. 사람이 PR을 리뷰할 수 있지만 필수가 아니며, 시간이 지나면서 거의 모든 리뷰는 에이전트 간 처리로 자동화되었습니다.

애플리케이션 가독성: 에이전트가 읽을 수 있는 UI

처리량이 늘면서 새로운 병목이 등장했습니다. 인간 QA의 시간과 주의가 한계에 부딪힌 것입니다. 이를 해결하기 위해 OpenAI 팀은 UI, 로그, 메트릭, 추적 자체를 Codex가 직접 읽을 수 있게 만들었습니다.

핵심 구현은 다음과 같습니다.

• git worktree별로 앱 인스턴스를 부팅 가능하게 구성

• Chrome DevTools Protocol을 에이전트 런타임에 연결

• DOM 스냅샷, 스크린샷, 내비게이션 작업용 스킬 생성

• worktree별 로컬 관측성 스택(로그, 메트릭, 추적)을 격리 운영

• Codex는 LogQL로 로그를, PromQL로 메트릭을 직접 질의

이제 Codex는 버그를 재현하고, 수정 사항을 검증하며, UI 동작을 직접 추론할 수 있습니다. "서비스 시작이 800ms 미만에 완료되도록 보장" 같은 프롬프트가 실행 가능한 작업으로 전환되며, 단일 Codex 실행이 6시간 이상 하나의 작업을 수행하는 경우도 잦아졌습니다.

저장소 지식을 시스템 기록으로 만들기

에이전트를 효과적으로 만드는 핵심 난제 중 하나는 맥락 관리입니다. Codex에는 1,000쪽짜리 지침서가 아니라 지도가 필요합니다. 맥락은 희소 자원이며, 거대한 지침 파일은 작업과 코드를 밀어내 결국 핵심 제약을 놓치게 만듭니다.

OpenAI 팀이 채택한 구조는 다음과 같습니다.

• 약 100줄짜리 짧은 AGENTS.md만 주입, 나머지는 목차로 활용

• 구조화된 docs/ 디렉터리에 검증 상태, 아키텍처 지도, 품질 등급을 색인화

• 계획(plan)을 1급 산출물로 취급, 복잡한 작업은 실행 계획과 의사결정 로그를 저장소에 커밋

• 전용 린터와 CI가 docs/의 최신성, 교차 링크, 구조 정확성을 검증

에이전트는 "정원사(gardener)"처럼 작동합니다. 실제 코드 동작과 맞지 않는 낡은 문서를 찾아 PR로 수정합니다. Google Docs, Slack 스레드, 머릿속 지식은 에이전트가 접근할 수 없으므로 사실상 존재하지 않는 것과 다름없습니다. 모든 진실은 저장소 로컬의 버전 관리 산출물(코드, 마크다운, 스키마, 실행 계획)에 살아야 합니다.

아키텍처와 취향 강제

문서만으로는 에이전트 생성 코드베이스의 일관성을 유지할 수 없습니다. OpenAI는 견고한 아키텍처 모델을 통해 규칙을 기계적으로 강제합니다.

비즈니스 도메인별 계층은 Types → Config → Repo → Service → Runtime → UI 순서로만 의존을 허용합니다. 인증, 커넥터, 텔레메트리, 기능 플래그 같은 횡단 관심사는 Providers라는 단일 명시 인터페이스를 통해서만 진입 가능합니다. 이 제약은 Codex가 만든 커스텀 린터와 구조 테스트로 강제되며, 그 외 의존은 기계적으로 차단됩니다.

이 아키텍처는 보통 수백 명의 엔지니어가 생길 때까지 미루는 종류지만, 코딩 에이전트 환경에서는 출시 속도를 유지하면서 아키텍처 드리프트를 막기 위한 초기 전제조건입니다. 인간 우선 워크플로에서는 지나치게 꼼꼼해 보일 수 있지만, 에이전트 환경에서는 한 번 인코딩한 규칙이 코드베이스 전체에 동시에 적용되는 큰 효과를 만듭니다.

병합 철학의 변화: 게이트 최소화

에이전트 처리량이 인간 주의를 크게 초과하는 시스템에서는 수정 비용이 낮고 대기 비용이 높습니다. 그래서 OpenAI는 PR을 짧게 유지하고, 테스트 플래이크는 진행을 무기한 막기보다 후속 실행으로 처리하는 정책을 택했습니다.

이는 낮은 처리량 환경에서는 무책임한 정책일 수 있습니다. 하지만 에이전트가 병렬로 수백 개의 PR을 생성하는 환경에서는 자주 올바른 트레이드오프입니다. PR 처리량과 코드 품질의 균형점은 조직 규모와 자율성 수준에 따라 달라지며, 단일 정답은 없습니다.

엔트로피 관리: 골든 원칙과 가비지 컬렉션

완전한 에이전트 자율성은 새로운 문제를 만듭니다. Codex는 저장소에 이미 존재하는 패턴을 그대로 복제하기 때문에, 패턴이 고르지 않으면 드리프트로 이어집니다. 초기에는 매주 금요일, 주당 20%를 "AI slop" 정리에 사용했지만 이는 확장되지 않았습니다.

해결책은 두 단계입니다.

• 골든 원칙을 저장소에 직접 인코딩: 의견이 강한 기계적 규칙(예: "불변 조건은 공유 유틸리티 패키지에 중앙화")

• 정기 백그라운드 Codex 작업이 편차를 스캔하고, 품질 등급을 갱신하며, 대상 리팩터링 PR을 생성

이 과정은 가비지 컬렉션처럼 동작합니다. 기술 부채는 고금리 대출과 같아서, 한꺼번에 처리하기보다 작은 단위로 계속 갚는 편이 거의 항상 더 낫습니다. 나쁜 패턴이 며칠 또는 몇 주 퍼지기 전에 매일 포착하고 해결할 수 있습니다.

우리 팀에 적용할 수 있는 교훈

이 실험 결과는 대규모 조직이 아니더라도 우리가 배울 점을 많이 남깁니다.

1. AGENTS.md는 백과사전이 아니라 목차로. 100줄 이내로 핵심만 남기고, 자세한 내용은 docs/로 분리합니다.

2. 로그, 메트릭, UI 상태를 에이전트가 읽을 수 있는 형태로 노출합니다. 사람이 봐야만 하는 영역이 많을수록 자동화 효율이 떨어집니다.

3. 의존 방향과 경계를 린터로 강제합니다. 코드 리뷰에서 반복되는 규칙은 도구로 승격합니다.

4. PR 게이트는 최소로, 후속 실행으로 수정 가능하도록 둡니다. 단, 테스트 커버리지는 그 대가로 더 강하게 요구합니다.

5. 정원사 에이전트를 운영해 문서 드리프트를 매일 정리합니다. 사람 QA 시간을 절약하는 가장 효과적인 방법입니다.

마무리: 향후 전망

OpenAI 스스로도 인정했듯, 이 전략은 "아직 배우는 중"입니다. 완전한 에이전트 생성 시스템에서 아키텍처 일관성이 수년에 걸쳐 어떻게 변하는지, 인간 판단이 어디에서 가장 큰 레버리지를 더하는지는 아직 미지수입니다. 다만 분명한 것은, 소프트웨어 구축이 여전히 규율을 요구하지만 그 규율이 코드보다 스캐폴딩과 환경에서 실현된다는 점입니다.

AI 에이전트를 도구로만 보지 않고 협업자로 대하는 팀이 결국 일의 속도와 품질 모두에서 앞서게 됩니다. 하네스 엔지니어링은 그 협업을 가능하게 만드는 핵심 투자입니다.