OpenAI의 Ryan Lopopolo 팀은 5개월간 수동으로 작성한 코드 0줄로 내부 베타 소프트웨어 제품을 출시했다. 애플리케이션 로직·테스트·CI 설정·문서·옵저버빌리티·내부 툴링까지 모든 코드를 Codex가 작성했으며, 수동으로 작성했을 때 대비 약 10분의 1의 시간에 100만 줄 규모의 제품을 구현했다. 이 팀의 경험에서 뽑아낸 에이전트 중심 엔지니어링 원칙을 정리한다.
핵심 원칙: 사람이 조종하고, 에이전트가 실행한다
에이전트 중심 개발에서 엔지니어의 역할은 코드를 작성하는 것이 아니라 환경을 설계하고, 의도를 명세하며, 피드백 루프를 구축하는 것으로 바뀐다. 희소한 자원은 인간의 시간과 주의력이다.
레포지터리 지식을 시스템 오브 레코드로
Codex 에이전트는 컨텍스트 창에서 접근할 수 없는 것은 존재하지 않는 것과 같다. Google Docs·슬랙 스레드·사람의 머릿속에 있는 지식은 에이전트에게 접근 불가능하다. 레포 안에 버전 관리되는 텍스트 파일로 아키텍처와 설계 결정을 남겨야 한다.
권장 레포 구조
AGENTS.md ← 에이전트에게 전달하는 핵심 컨텍스트 파일
ARCHITECTURE.md ← 전체 아키텍처 개요
docs/
├── design-docs/ ← 아키텍처 패턴·core-beliefs
│ ├── index.md
│ ├── core-beliefs.md
│ └── ...
├── exec-plans/ ← 진행 중·완료된 실행 계획
│ ├── active/
│ ├── completed/
│ └── tech-debt-tracker.md
├── generated/ ← 자동 생성 문서 (DB 스키마 등)
│ └── db-schema.md
├── product-specs/ ← 제품 명세
├── references/ ← LLM용 참고 텍스트
│ ├── design-system-reference-llms.txt
│ └── ...
├── DESIGN.md
├── FRONTEND.md
└── PLANS.md슬랙에서 팀이 정렬한 아키텍처 패턴이라도 레포에 없으면 에이전트에게는 없는 정보다. 새 팀원 온보딩처럼, 에이전트에게도 제품 원칙·엔지니어링 규범·팀 문화를 문서로 전달해야 한다.
에이전트 가독성(Legibility) 최우선
코드베이스는 에이전트의 가독성을 최우선으로 설계한다. “에이전트가 레포 자체만으로 비즈니스 도메인 전체를 추론할 수 있는가”가 핵심 질문이다.
실용 원칙:
- 복잡한 외부 의존성보다 인하우스 구현 선호:
p-limit같은 범용 패키지 대신 OpenTelemetry와 타이트하게 연동된 자체map-with-concurrency유틸리티 구현 → 에이전트가 전체 동작을 레포 안에서 추론 가능 - “지루한” 기술 선택 선호: API가 안정적이고 학습 데이터에 잘 표현된 기술이 에이전트에게 더 잘 모델링됨
- 레포 밖으로 나가는 지식은 에이전트에게 불투명한 블랙박스
아키텍처 불변식을 코드로 강제
문서만으로는 에이전트 생성 코드베이스의 일관성을 유지하기 어렵다. 불변식(invariant)을 린터·구조적 테스트로 기계적으로 강제하면 에이전트 속도를 해치지 않고 아키텍처 품질을 유지할 수 있다.
OpenAI 팀의 사례:
- 레이어 의존성 방향 강제: 각 비즈니스 도메인을 고정된 레이어 세트로 분리하고 의존 방향을 단방향으로만 허용 (Types → Config → Repo → Service → Runtime → UI)
- 커스텀 린터: Codex가 생성한 린터로 구조화 로깅·네이밍 컨벤션·파일 크기 제한·플랫폼 신뢰성 요건 강제
- 린트 에러 메시지에 교정 지침을 직접 포함 → 에이전트 컨텍스트에 자동 주입
핵심 철학: 경계를 중앙에서 강제하되, 경계 안에서는 에이전트에게 자율성 부여. 인간 취향과 다른 코드도 올바르고 유지보수 가능하면 충분하다.
처리량이 바뀌면 병합 철학도 바뀐다
에이전트 처리량이 인간의 주의력을 크게 초과하면 전통적인 엔지니어링 규범이 역효과가 된다:
- PR은 단명(short-lived): 빠르게 열고 빠르게 병합
- 최소한의 블로킹 게이트: 테스트 플레이크는 블로킹보다 후속 재실행으로 처리
- “수정은 저렴하고, 기다림은 비싸다”: 고처리량 환경에서는 적극적 수정이 올바른 트레이드오프
에이전트 자율성의 단계적 확장
최종 목표는 에이전트가 단일 프롬프트로 전체 기능 개발을 end-to-end 실행하는 것이다. OpenAI 팀은 이를 달성했다:
- 코드베이스 현재 상태 검증
- 보고된 버그 재현
- 실패 시연 영상 녹화
- 수정 구현
- 수정 사항 검증 및 영상 녹화
- PR 오픈
- 에이전트·인간 피드백 대응
- 빌드 실패 감지 및 해결
테스트·검증·리뷰·피드백 처리·복구가 모두 시스템에 인코딩되어야 이 수준의 자율성이 가능하다.
관련 문서
- codex — OpenAI Codex 개요
- codex-tutorial-getting-started — Codex 처음 시작하기
- codex-tips-maxxing — Durable Threads·Browser Use로 Codex 최대 활용하기
참고 자료
- Harness engineering: leveraging Codex in an agent-first world — OpenAI (2026)