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

• 내부 베타 소프트웨어 제품은 수동 작성 코드 0줄을 고정 제약으로 삼아 Codex가 애플리케이션 로직, 테스트, CI 설정, 문서, 관측성, 내부 도구까지 작성한 실험 사례
• 빈 git 저장소에서 시작한 코드베이스는 약 5개월 뒤 약 100만 줄 규모가 되었고, 세 명의 엔지니어가 Codex를 구동해 약 1,500개 PR을 열고 병합한 PR 처리량
• 엔지니어의 주된 일은 코드 작성이 아니라 환경 설계, 의도 명세, 에이전트가 신뢰할 수 있게 일하도록 만드는 피드백 루프 구축으로 이동
• 저장소 지식은 짧은 AGENTS.md, 구조화된 docs/, 실행 계획, 린터와 CI로 관리되고, UI·로그·메트릭·추적은 Codex가 직접 읽고 검증할 수 있는 애플리케이션 가독성으로 전환
• 처리량 증가로 병합 게이트 최소화와 후속 실행 기반 수정이 실용적 선택이 되었지만, 장기적 아키텍처 일관성과 인간 판단의 인코딩은 아직 학습 과제

수동 작성 코드 0줄로 만든 내부 베타

• 지난 5개월 동안 내부 베타 소프트웨어 제품을 수동 작성 코드 0줄로 구축하고 출시하는 실험 진행
• 제품은 내부 일일 사용자와 외부 알파 테스터를 보유하고 있으며, 출시·배포·장애·수정 흐름을 실제로 겪는 상태
• 애플리케이션 로직, 테스트, CI 설정, 문서, 관측성, 내부 도구까지 모든 코드 라인을 Codex가 작성했고, 손으로 코드를 쓸 때보다 약 1/10의 시간에 구축했다는 추정
• 인간은 조종하고, 에이전트는 실행
• 몇 주 안에 최종적으로 100만 줄 규모가 된 결과물을 출시해야 했고, 이를 위해 엔지니어링 팀의 주 업무가 코드 작성에서 환경 설계, 의도 명세, 피드백 루프 구축으로 이동

빈 git 저장소에서 시작

• 빈 저장소의 첫 커밋은 2025년 8월 말에 발생
• 초기 스캐폴드인 저장소 구조, CI 설정, 포매팅 규칙, 패키지 매니저 설정, 애플리케이션 프레임워크는 GPT-5를 사용하는 Codex CLI가 기존 템플릿 일부의 안내를 받아 생성
• 에이전트가 저장소에서 일하는 방식을 안내하는 초기 AGENTS.md 파일도 Codex가 작성
• 시스템을 지탱하는 기존 인간 작성 코드는 없었고, 저장소는 처음부터 에이전트에 의해 형성
• 5개월 뒤 저장소는 애플리케이션 로직, 인프라, 도구, 문서, 내부 개발자 유틸리티 전반에서 약 100만 줄 규모
• 세 명의 엔지니어가 Codex를 구동해 약 1,500개 PR을 열고 병합했으며, 이는 엔지니어 1인당 하루 평균 3.5개 PR 처리량
• 팀이 현재 일곱 명의 엔지니어로 커진 뒤에도 처리량은 증가
• 결과물은 출력 자체를 위한 출력이 아니며, 제품은 내부 파워 유저를 포함한 수백 명의 내부 사용자가 사용
• 개발 과정 전반에서 인간은 코드를 직접 기여하지 않았고, 수동 작성 코드 없음이 팀의 핵심 철학

엔지니어 역할 재정의

• 인간이 직접 코딩하지 않는 제약은 시스템, 스캐폴딩, 레버리지에 집중하는 다른 종류의 엔지니어링 작업을 도입
• 초기 진척은 예상보다 느렸지만 Codex의 역량 부족 때문이 아니라 환경이 충분히 명세되지 않았기 때문
• 에이전트는 높은 수준의 목표를 향해 진척하는 데 필요한 도구, 추상화, 내부 구조가 부족한 상태
• 엔지니어링 팀의 주 업무는 에이전트가 유용한 일을 할 수 있도록 만드는 것
• 실제 작업은 큰 목표를 설계, 코드, 리뷰, 테스트 같은 더 작은 빌딩 블록으로 나누고, 에이전트가 그 블록을 만들도록 프롬프트를 주며, 이를 더 복잡한 작업의 발판으로 삼는 깊이 우선 방식
• 실패 시 해결책은 “더 열심히 시도”가 아니라, Codex가 일을 하도록 만드는 데 빠진 역량이 무엇인지 찾고 이를 에이전트가 읽고 따를 수 있게 만드는 방식
• 인간은 대부분 프롬프트로 시스템과 상호작용하며, 엔지니어가 작업을 설명하고 에이전트를 실행한 뒤 PR을 열게 하는 흐름
• PR 완료 과정에서 Codex는 로컬에서 자체 변경을 리뷰하고, 로컬과 클라우드에서 추가 에이전트 리뷰를 요청하며, 인간 또는 에이전트 피드백에 응답하고, 모든 에이전트 리뷰어가 만족할 때까지 반복하는 Ralph Wiggum Loop에 가까운 방식
• Codex는 gh, 로컬 스크립트, 저장소 내장 스킬 같은 표준 개발 도구를 직접 사용해 인간의 복사·붙여넣기 없이 맥락을 수집
• 인간은 PR을 리뷰할 수 있지만 필수는 아니며, 시간이 지나면서 거의 모든 리뷰 작업은 에이전트 간 처리로 이동

애플리케이션 가독성 높이기

• 코드 처리량이 증가하면서 병목은 인간 QA 역량으로 이동
• 고정 제약이 인간의 시간과 주의였기 때문에, 애플리케이션 UI, 로그, 앱 메트릭 자체를 Codex가 직접 읽을 수 있게 만들어 에이전트 역량을 확장
• 애플리케이션은 git worktree별로 부팅 가능하게 구성해 Codex가 변경마다 인스턴스 하나를 실행하고 조작할 수 있는 구조
• Chrome DevTools Protocol을 에이전트 런타임에 연결하고 DOM 스냅샷, 스크린샷, 내비게이션 작업용 스킬을 생성
• Codex는 이를 통해 버그를 재현하고, 수정 사항을 검증하며, UI 동작을 직접 추론 가능
• 로그, 메트릭, 추적은 특정 worktree에 대해 일시적으로 존재하는 로컬 관측성 스택을 통해 Codex에 노출
• Codex는 로그와 메트릭까지 포함한 완전히 격리된 앱 버전에서 작업하며, 해당 작업이 끝나면 관련 로그와 메트릭도 제거
• 에이전트는 LogQL로 로그를 질의하고 PromQL로 메트릭을 질의
• “서비스 시작이 800ms 미만에 완료되도록 보장” 또는 “네 가지 핵심 사용자 여정의 어떤 span도 2초를 넘지 않도록 보장” 같은 프롬프트가 실행 가능한 작업으로 전환
• 단일 Codex 실행이 하나의 작업을 6시간 이상 수행하는 경우가 자주 있으며, 그 시간은 종종 인간이 자는 동안

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

• 대규모·복잡 작업에서 에이전트를 효과적으로 만드는 핵심 난제 중 하나는 맥락 관리
• Codex에는 1,000쪽짜리 지침서가 아니라 지도가 필요
  • 맥락은 희소 자원이며, 거대한 지침 파일은 작업, 코드, 관련 문서를 밀어내 에이전트가 핵심 제약을 놓치거나 잘못된 제약을 최적화하게 만드는 구조
  • 과도한 안내는 안내가 아니게 됨이며, 모든 것이 중요해지면 아무것도 중요하지 않아 에이전트가 의도적으로 탐색하기보다 지역적 패턴 매칭에 머무는 결과
  • 단일 거대 매뉴얼은 즉시 낡으며, 오래된 규칙의 무덤이 되고 인간이 유지보수하지 않는 매력적인 방해물로 변하는 위험
  • 단일 덩어리 파일은 커버리지, 최신성, 소유권, 교차 링크 같은 기계적 검증이 어렵기 때문에 드리프트가 불가피한 구조
• AGENTS.md는 백과사전이 아니라 목차로 취급
• 저장소 지식 기반은 시스템 기록으로 취급되는 구조화된 docs/ 디렉터리에 위치
• 약 100줄짜리 짧은 AGENTS.md가 맥락에 주입되며, 더 깊은 진실의 원천을 가리키는 지도 역할
• 설계 문서는 검증 상태와 에이전트 우선 운영 원칙을 정의하는 핵심 믿음 집합과 함께 카탈로그화·색인화
• 아키텍처 문서는 도메인과 패키지 계층의 최상위 지도를 제공
• 품질 문서는 각 제품 도메인과 아키텍처 계층을 등급화하고 시간에 따른 격차를 추적
• 계획은 1급 산출물로 취급되며, 작은 변경에는 일시적 경량 계획을 사용하고 복잡한 작업은 진행 상황과 의사결정 로그를 포함한 실행 계획으로 저장소에 커밋
• 활성 계획, 완료 계획, 알려진 기술 부채가 모두 버전 관리되고 함께 배치되며, 에이전트는 외부 맥락에 의존하지 않고 작업 가능
• 이 구조는 점진적 공개를 가능하게 하며, 에이전트는 처음부터 압도되는 대신 작고 안정적인 진입점에서 시작해 다음에 볼 곳을 학습
• 전용 린터와 CI 작업은 지식 기반의 최신성, 교차 링크, 구조 정확성을 검증
• 반복 실행되는 문서 정원 관리 에이전트는 실제 코드 동작을 반영하지 않는 낡거나 obsolete 문서를 찾아 수정 PR을 생성

에이전트 가독성이 목표

• 코드베이스 전체가 에이전트 생성물이기 때문에 최우선 최적화 대상은 Codex의 가독성
• 새 엔지니어가 코드를 탐색하기 쉽게 만드는 것처럼, 인간 엔지니어의 목표는 에이전트가 전체 비즈니스 도메인을 저장소 자체에서 직접 추론하게 만드는 것
• 에이전트 관점에서 실행 중 맥락 안에서 접근할 수 없는 것은 사실상 존재하지 않는 것
• Google Docs, 채팅 스레드, 사람의 머릿속에 있는 지식은 시스템 접근 대상이 아니며, 저장소 로컬의 버전 관리 산출물인 코드, 마크다운, 스키마, 실행 계획만 에이전트가 볼 수 있는 대상
• Slack 논의로 팀이 아키텍처 패턴에 합의했더라도 에이전트가 발견할 수 없다면, 3개월 뒤 합류한 신입에게 알려지지 않은 지식과 같은 상태
• Codex에 더 많은 맥락을 준다는 것은 임의 지침을 쏟아붓는 일이 아니라, 에이전트가 추론할 수 있도록 올바른 정보를 조직하고 노출하는 일
• 새 팀원에게 제품 원칙, 엔지니어링 규범, 팀 문화, 이모지 선호까지 온보딩하듯 에이전트에도 이 정보를 제공하면 더 정렬된 출력으로 연결
• 의존성과 추상화는 저장소 안에서 완전히 내재화되고 추론 가능한 쪽을 선호
• 흔히 “지루한” 기술은 조합성, API 안정성, 학습 데이터 내 표현 때문에 에이전트가 모델링하기 쉬운 경향
• 일부 경우에는 공개 라이브러리의 불투명한 상위 동작을 우회하는 것보다 에이전트가 기능 일부를 다시 구현하는 편이 더 저렴
• 범용 p-limit 스타일 패키지를 가져오는 대신 자체 map-with-concurrency 헬퍼를 구현했으며, 이는 OpenTelemetry 계측과 긴밀히 통합되고 100% 테스트 커버리지를 가지며 런타임 기대와 정확히 일치하는 동작
• 에이전트가 직접 검사, 검증, 수정할 수 있는 형태로 시스템을 더 많이 끌어들이면 Codex뿐 아니라 같은 코드베이스에서 작업하는 Aardvark 같은 다른 에이전트의 레버리지도 증가

아키텍처와 취향 강제

• 문서만으로는 완전한 에이전트 생성 코드베이스의 일관성을 유지하기에 부족
• 구현을 세세하게 관리하지 않고 불변 조건을 강제함으로써 에이전트가 기반을 약화시키지 않고 빠르게 출시할 수 있는 구조
• Codex에는 경계에서 데이터 형태를 파싱하도록 요구하지만, 그 방법까지 규정하지는 않는 방식
• 에이전트는 엄격한 경계와 예측 가능한 구조를 가진 환경에서 가장 효과적이므로, 애플리케이션은 견고한 아키텍처 모델 중심으로 구성
• 각 비즈니스 도메인은 고정된 계층 집합으로 나뉘며, 의존 방향과 허용 가능한 연결은 엄격하게 검증
• 이 제약은 Codex가 생성한 커스텀 린터와 구조 테스트로 기계적으로 강제
• 각 비즈니스 도메인에서는 코드가 Types → Config → Repo → Service → Runtime → UI의 고정 계층을 따라 앞으로만 의존 가능
• 인증, 커넥터, 텔레메트리, 기능 플래그 같은 횡단 관심사는 Providers라는 단일 명시 인터페이스를 통해서만 진입 가능
• 그 외 의존은 허용되지 않으며 기계적으로 차단
• 이런 아키텍처는 보통 수백 명의 엔지니어가 생길 때까지 미루는 종류지만, 코딩 에이전트 환경에서는 속도를 유지하면서 부패와 아키텍처 드리프트를 막기 위한 초기 전제조건
• 실제 운영에서는 커스텀 린터, 구조 테스트, 작은 “취향 불변 조건” 집합으로 규칙을 강제
• 구조화 로깅, 스키마와 타입 이름 규칙, 파일 크기 제한, 플랫폼별 신뢰성 요구사항을 커스텀 린트로 정적 강제
• 커스텀 린트의 오류 메시지는 에이전트 맥락에 수정 지침을 주입하도록 작성
• 인간 우선 워크플로에서는 이런 규칙이 지나치게 꼼꼼하거나 제약적으로 느껴질 수 있지만, 에이전트 환경에서는 한 번 인코딩한 규칙이 전체에 동시에 적용되는 승수
• 중앙에서는 경계, 정확성, 재현성을 강하게 관리하고, 그 안에서는 팀 또는 에이전트가 해결 표현 방식에서 큰 자유를 갖는 구조
• 결과 코드가 인간의 스타일 선호와 항상 맞지는 않지만, 정확하고 유지보수 가능하며 향후 에이전트 실행이 읽을 수 있다면 기준 충족
• 인간의 취향은 리뷰 코멘트, 리팩터링 PR, 사용자 대면 버그를 통해 문서 업데이트나 도구로 계속 환류
• 문서가 부족하면 규칙은 코드로 승격

처리량이 바꾼 병합 철학

• Codex 처리량이 증가하면서 기존 엔지니어링 규범 중 상당수가 역효과를 내는 상태
• 저장소는 최소한의 블로킹 병합 게이트로 운영
• PR은 짧게 유지
• 테스트 플래이크는 진행을 무기한 막기보다 후속 실행으로 처리하는 경우가 많음
• 에이전트 처리량이 인간 주의를 크게 초과하는 시스템에서는 수정 비용이 낮고 대기 비용이 높은 구조
• 낮은 처리량 환경에서는 무책임할 수 있는 방식이지만, 이 환경에서는 자주 올바른 트레이드오프

“에이전트 생성”의 실제 범위

• 코드베이스가 Codex 에이전트로 생성된다는 말은 코드베이스 안의 모든 것을 뜻함
• 에이전트가 만드는 대상
  • 제품 코드와 테스트
  • CI 설정과 릴리스 도구
  • 내부 개발자 도구
  • 문서와 설계 이력
  • 평가 하네스
  • 리뷰 코멘트와 응답
  • 저장소 자체를 관리하는 스크립트
  • 프로덕션 대시보드 정의 파일
• 인간은 항상 루프 안에 있지만, 이전보다 더 높은 추상화 계층에서 작업
• 인간은 작업 우선순위를 정하고, 사용자 피드백을 인수 기준으로 번역하며, 결과를 검증
• 에이전트가 어려움을 겪으면 도구, 가드레일, 문서 중 무엇이 빠졌는지 찾는 신호로 취급하고, 그 수정 역시 Codex가 작성하도록 저장소에 환류
• 에이전트는 표준 개발 도구를 직접 사용하며, 리뷰 피드백을 가져오고, 인라인으로 응답하고, 업데이트를 푸시하며, 자체 PR을 squash 후 병합하는 경우도 많음

자율성 수준 높이기

• 테스트, 검증, 리뷰, 피드백 처리, 복구가 시스템 안에 더 많이 인코딩되면서 Codex가 새 기능을 처음부터 끝까지 추진할 수 있는 임계점을 최근 통과
• 단일 프롬프트만으로 에이전트가 수행할 수 있는 작업
  • 현재 코드베이스 상태 검증
  • 보고된 버그 재현
  • 실패를 보여주는 동영상 기록
  • 수정 구현
  • 애플리케이션을 직접 조작해 수정 검증
  • 해결을 보여주는 두 번째 동영상 기록
  • PR 열기
  • 에이전트와 인간 피드백에 응답
  • 빌드 실패 감지와 수정
  • 판단이 필요할 때만 인간에게 에스컬레이션
  • 변경 병합
• 이 동작은 해당 저장소의 구체적인 구조와 도구에 크게 의존하며, 비슷한 투자가 없으면 일반화된다고 가정해서는 안 되는 상태

엔트로피와 가비지 컬렉션

• 완전한 에이전트 자율성은 새로운 문제도 도입
• Codex는 저장소에 이미 존재하는 패턴을 복제하며, 그 패턴이 고르지 않거나 최적이 아니어도 반복
• 시간이 지나면 이런 반복은 드리프트로 이어짐
• 초기에는 인간이 이를 수동으로 처리했고, 팀은 매주 금요일, 즉 주당 20%를 “AI slop” 정리에 사용
• 이 방식은 확장되지 않았기 때문에 “골든 원칙”을 저장소에 직접 인코딩하고 반복 정리 프로세스를 구축
• 골든 원칙은 향후 에이전트 실행을 위해 코드베이스를 읽기 쉽고 일관되게 유지하는 의견 강한 기계적 규칙
• 예시 원칙은 불변 조건을 중앙화하기 위해 손으로 만든 헬퍼보다 공유 유틸리티 패키지를 선호하는 것
• 또 다른 예시는 데이터를 “YOLO식”으로 탐색하지 않고, 에이전트가 추측한 형태 위에 우연히 구축하지 못하도록 경계를 검증하거나 타입 SDK에 의존하는 것
• 정기적으로 백그라운드 Codex 작업이 편차를 스캔하고, 품질 등급을 업데이트하며, 대상 리팩터링 PR을 생성
• 대부분의 리팩터링 PR은 1분 이내에 리뷰 가능하고 자동 병합 가능
• 이 과정은 가비지 컬렉션처럼 동작
• 기술 부채는 고금리 대출과 같으며, 쌓이게 두었다가 고통스럽게 한꺼번에 처리하는 것보다 작은 단위로 계속 갚는 편이 거의 항상 더 나은 방식
• 인간 취향은 한 번 포착된 뒤 모든 코드 라인에 지속적으로 강제
• 나쁜 패턴은 코드베이스에서 며칠 또는 몇 주 퍼지기 전에 매일 포착하고 해결 가능

아직 배우는 중

• 이 전략은 지금까지 OpenAI 내부 출시와 도입 단계까지 잘 작동
• 실제 사용자를 위한 실제 제품 구축은 투자를 현실에 고정하고 장기 유지보수성 쪽으로 이끄는 역할
• 완전한 에이전트 생성 시스템에서 아키텍처 일관성이 수년에 걸쳐 어떻게 변하는지는 아직 미지수
• 인간 판단이 어디에서 가장 큰 레버리지를 더하는지, 그 판단을 어떻게 인코딩해 누적 효과를 만들 수 있는지도 계속 학습 중
• 모델이 시간이 지나며 더 유능해질 때 이 시스템이 어떻게 진화할지도 아직 알 수 없는 영역
• 분명해진 점은 소프트웨어 구축이 여전히 규율을 요구하지만, 그 규율이 코드보다 스캐폴딩에서 더 크게 드러난다는 것
• 코드베이스 일관성을 유지하는 도구, 추상화, 피드백 루프의 중요성은 계속 증가
• 현재 가장 어려운 과제는 에이전트가 복잡하고 신뢰할 수 있는 소프트웨어를 대규모로 만들고 유지하도록 돕는 환경, 피드백 루프, 제어 시스템 설계
• Codex 같은 에이전트가 소프트웨어 생애주기의 더 큰 부분을 맡을수록 이런 질문의 중요성은 더 커지는 흐름
• 초기 학습은 어디에 노력을 투자해야 무언가를 그냥 만들 수 있는지 판단하는 데 도움을 주는 자료