▲

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

 (openai.com)
33P by GN⁺ 18시간전 | ★ favorite | 댓글 1개
  • OpenAI 내부 팀이 5개월간 수동 코드 작성 없이 소프트웨어 제품의 내부 베타를 구축·출시한 실험 사례로, 모든 코드를 Codex 에이전트가 생성
  • 3명의 엔지니어로 시작해 약 100만 라인의 코드와 1,500개의 pull request를 처리했으며, 엔지니어 1인당 하루 평균 3.5개의 PR 병합
  • 엔지니어의 역할이 직접 코딩에서 환경 설계, 의도 명시, 피드백 루프 구축으로 전환되었으며, 에이전트가 안정적으로 작업할 수 있는 스캐폴딩 구축이 핵심
  • AGENTS.md를 백과사전이 아닌 목차로 활용하고, 구조화된 문서·린터·구조적 테스트를 통해 아키텍처 일관성을 기계적으로 강제 적용
  • 에이전트 자율성이 높아질수록 엔트로피 관리와 가비지 컬렉션 방식의 지속적 정리가 필수적이며, 소프트웨어 구축의 규율이 코드에서 스캐폴딩으로 이동 중

빈 git 리포지터리에서 시작한 실험

  • 2025년 8월 말 빈 리포지터리에 첫 커밋을 진행, 초기 스캐폴드(리포지터리 구조, CI 구성, 서식 규칙, 패키지 관리자 설정, 애플리케이션 프레임워크)는 기존 템플릿을 기반으로 GPT-5를 사용하여 Codex CLI에서 생성
  • 에이전트에게 리포지터리 작업 방법을 알려주는 초기 AGENTS.md 파일도 Codex가 직접 작성
  • 처음부터 사람이 작성한 기존 코드 없이, 리포지터리가 에이전트에 의해 형성
  • 5개월 후 애플리케이션 로직, 인프라, 툴링, 문서화, 내부 개발자 유틸리티 전반에 걸쳐 약 100만 라인의 코드 포함
  • 3명의 소규모 팀이 약 1,500개의 pull request를 열고 병합했으며, 이는 엔지니어 1인당 하루 평균 3.5개의 PR 처리량에 해당
  • 7명으로 팀이 성장하면서 처리량이 오히려 증가
  • 수백 명의 사용자가 매일 내부적으로 사용해 왔으며, 내부 파워 유저도 포함
  • 개발 과정 전반에 걸쳐 사람은 코드에 직접 기여한 적이 없음
  • "수동으로 작성한 코드가 없다" 는 팀의 핵심 철학이 됨

엔지니어의 역할 재정의

  • 사람이 직접 코딩하지 않으므로 시스템, 스캐폴딩, 레버리지 중심의 다른 종류의 엔지니어링 작업 필요
  • 초기 진행이 예상보다 더뎠던 이유는 Codex의 역량 부족이 아니라 환경 미비 때문
    • 에이전트가 상위 목표를 달성하기 위한 도구, 추상화, 내부 구조가 부족
  • 엔지니어링 팀의 주요 업무는 에이전트가 유용한 업무를 수행할 수 있도록 지원하는 것으로 전환
  • 큰 목표를 더 작은 빌딩 블록(설계, 코드, 검토, 테스트 등)으로 세분화하고, 에이전트가 이 블록들을 구성한 뒤 더 복잡한 작업을 해결하는 깊이 우선 작업 방식
  • 실패 시 "더욱 분발"이 아닌, "어떤 기능이 누락되어 있으며, 에이전트가 읽기 쉽고 실행 가능하게 만들려면 어떻게 해야 하는가" 라는 질문이 핵심
  • 사람은 거의 전적으로 프롬프트를 통해 시스템과 상호작용
    • 작업 설명, 에이전트 실행, pull request 오픈 등을 지시
  • PR 완료를 위해 Codex에게 로컬에서 자체 변경사항 검토, 로컬 및 클라우드에서 에이전트 검토 추가 요청, 피드백 응답, 모든 에이전트 검토자 만족 시까지 반복하도록 지시
    • 사실상 Ralph Wiggum Loop 방식
  • Codex는 gh, 로컬 스크립트, 리포지터리 내장 스킬 등 표준 개발 도구를 직접 사용하여 컨텍스트 수집
  • 사람의 pull request 검토는 가능하지만 필수 아님, 시간이 지나며 거의 모든 검토 작업을 에이전트 간 처리로 전환

애플리케이션의 가독성 향상

  • 코드 처리량 증가에 따라 인적 QA 역량에 병목 발생
  • 사람의 시간과 주의력이 고정 제약이므로 애플리케이션 UI, 로그, 앱 메트릭 등을 Codex가 직접 읽고 이해할 수 있도록 하여 에이전트에 기능 추가
  • git worktree별 앱 부팅 기능을 통해 Codex가 변경사항마다 별도의 인스턴스를 실행·제어 가능
  • Chrome DevTools Protocol을 에이전트 런타임에 연결하고, DOM 스냅샷, 스크린샷, 탐색 작업을 위한 스킬 생성
    • Codex가 버그 재현, 수정사항 검증, UI 동작에 대해 직접 추론 가능
  • 관측 가능성 툴링도 동일 방식 적용
    • 로그, 메트릭, 추적은 각 워크트리에 대해 일시적으로 유지되는 로컬 관측 가능성 스택을 통해 Codex에 노출
    • 작업 완료 후 로그와 메트릭 삭제
    • 에이전트가 LogQL로 로그를, PromQL로 메트릭을 쿼리 가능
  • 이러한 컨텍스트가 주어지면 "서비스 시작이 800ms 이내에 완료"되도록 하거나 "네 가지 핵심 사용자 여정에서 어떤 스팬도 2초를 초과하지 않도록" 하는 프롬프트 처리가 용이
  • 한 번의 Codex 실행으로 6시간 이상(종종 사람이 잠자는 동안) 한 가지 작업 수행

리포지터리 지식을 기록 시스템으로 활용

  • 컨텍스트 관리는 에이전트가 크고 복잡한 작업을 효과적으로 수행하는 데 가장 큰 과제 중 하나
  • 초기 교훈: Codex에 1,000페이지의 설명서가 아닌 맵을 제공해야 함
  • "하나의 큰 AGENTS.md" 접근 방식 시도 후 예측 가능한 실패
    • 컨텍스트는 희소 리소스: 거대한 지침 파일이 작업·코드·관련 문서를 복잡하게 만들어 에이전트가 주요 제약 조건을 놓치거나 잘못된 제약 조건에 최적화
    • 지침이 너무 많으면 지침이 되지 않음: 모든 것이 "중요"하면 중요한 것은 없음, 에이전트가 의도적 탐색 대신 로컬 패턴 매칭 수행
    • 순식간에 망가짐: 획일적 거대 매뉴얼이 낡은 규칙들의 무덤으로 변화, 에이전트는 무엇이 여전히 유효한지 판단 불가
    • 확인하기 어려움: 단일 블롭은 기계적 점검(커버리지, 신선도, 소유권, 교차 연결)에 부적합하여 드리프트 불가피
  • 해결책: AGENTS.md를 백과사전이 아닌 목차로 취급
  • 리포지터리의 지식 베이스는 구조화된 docs/ 디렉터리에 기록 시스템으로 관리
  • 짧은 AGENTS.md(약 100개 라인)는 컨텍스트에 삽입되어 주로 맵 역할, 더 심층적이고 신뢰할 수 있는 정보 소스를 안내
  • 설계 문서화는 검증 상태와 에이전트 우선 운영 원칙을 정의하는 핵심 신념 포함, 분류·색인화
  • 아키텍처 문서화는 도메인과 패키지 레이어링의 최상위 맵 제공
  • 품질 문서는 각 제품 도메인과 아키텍처 레이어에 등급을 매기며 시간에 따라 격차 추적
  • 계획은 일급 아티팩트로 취급
    • 일시적이며 간단한 계획은 작은 변경에 사용
    • 복잡한 작업은 진행 상황과 의사결정 로그와 함께 실행 계획에 포함되어 리포지터리에 저장
    • 진행 중인 계획, 완료된 계획, 알려진 기술 부채 모두 버전화되어 동일 위치에 배치
  • 이를 통해 점진적 공개 가능: 에이전트가 처음부터 부담 없이 작고 안정적인 진입 지점에서 시작하여 다음 단계로 진행
  • 기계적 시행: 전용 린터와 CI 작업이 지식 베이스가 최신 상태이고, 교차 링크되어 있으며, 올바르게 구성되어 있는지 검증
  • 반복 실행되는 "doc-gardening" 에이전트가 오래되거나 유효하지 않은 문서를 검토하여 수정용 pull request 오픈

에이전트의 가독성이 목표

  • 리포지터리가 전적으로 에이전트에 의해 생성되었으므로, 우선적으로 Codex의 가독성에 최적화
  • 인간 엔지니어의 목표: 에이전트가 리포지터리 자체에서 직접 전체 비즈니스 도메인에 대해 추론 가능하도록 하는 것
  • 에이전트 관점에서 실행 중 컨텍스트 내에서 액세스할 수 없는 것은 사실상 존재하지 않음
    • Google Docs, 채팅 스레드, 사람들의 머릿속에 있는 지식은 시스템에서 접근 불가
    • 리포지터리 내의 버전 관리되는 아티팩트(코드, 마크다운, 스키마, 실행 계획)에만 접근 가능
  • Slack 토론에서 합의된 아키텍처 패턴도 에이전트가 검색할 수 없다면 판독 불가능
  • Codex에 더 많은 컨텍스트 제공 = 임시 지침으로 부담을 주는 것이 아니라 올바른 정보를 정리·노출하여 에이전트가 추론할 수 있도록 하는 것
  • 제품 원칙, 엔지니어링 규범, 팀 문화(이모지 선호도 포함)에 대해 새로운 팀원을 합류시키듯이 에이전트에게 정보 제공 시 더 나은 결과물 획득
  • 리포지터리 내에서 완전히 내부화하고 추론할 수 있는 종속성과 추상화 선호
  • "지루한" 기술이 결합성, API 안정성, 학습 설정 내 표현 덕분에 에이전트가 모델링하기 더 쉬운 경향
  • 일부 경우 공개 라이브러리의 불투명한 업스트림 동작 대신 에이전트가 기능의 하위 집합을 직접 재구현하는 것이 더 저렴
    • 예: 범용 p-limit 스타일 패키지 대신 자체 map-with-concurrency 헬퍼 구현, OpenTelemetry 계측과 긴밀 통합, 테스트 커버리지 100%, 런타임 기대대로 정확히 동작
  • 시스템을 에이전트가 검사·검증·직접 수정할 수 있는 형태로 더 많이 끌어올수록 Codex뿐 아니라 다른 에이전트(예: Aardvark)에서도 레버리지 증가

아키텍처 및 취향 강제 적용

  • 문서화만으로는 에이전트가 생성한 코드베이스를 완전히 일관되게 유지 불가
  • 구현을 세세하게 관리하지 않고 불변 조건을 강제 적용함으로써 기초를 튼튼히 유지하면서 에이전트가 빠르게 출시 가능
    • 예: Codex가 경계에서 데이터 형태를 파싱하기를 원했지만, 그 방법(특정 라이브러리)에 대해서는 구체적으로 명시하지 않음(모델은 Zod를 선호하는 경향)
  • 에이전트는 엄격한 경계와 예측 가능한 구조를 갖춘 환경에서 가장 효과적
  • 엄격한 아키텍처 모델 중심으로 애플리케이션 구축
    • 각 비즈니스 도메인은 엄격하게 검증된 종속성 방향과 제한된 허용 에지 집합을 사용하여 고정된 계층 집합으로 분리
    • Types → Config → Repo → Service → Runtime → UI 순서로 코드 전달
    • 교차 문제(인증, 커넥터, 텔레메트리, 기능 플래그)는 Providers라는 하나의 명시적 인터페이스를 통해 유입
    • 그 외 모든 것은 허용되지 않으며 기계적으로 강제 적용
  • 이러한 제약은 Codex가 생성한 맞춤형 린터와 구조적 테스트를 통해 적용
  • 이 수준의 아키텍처는 보통 수백 명의 엔지니어 규모까지 미루는 경우가 많지만, 코딩 에이전트에는 초기 전제 조건
  • 맞춤형 린트로 구조화된 로깅, 스키마 및 유형의 명명 규칙, 파일 크기 제한, 플랫폼별 안정성 요구 사항을 정적으로 적용
    • 린트가 맞춤형이므로 오류 메시지를 작성하여 에이전트 컨텍스트에 수정 지침 주입 가능
  • 사람 중심 워크플로에서는 이러한 규칙이 지나치게 세세하거나 제한적으로 느껴질 수 있지만, 에이전트 활용 시 효과를 몇 배로 증폭
  • 제약 조건이 중요한 부분과 그렇지 않은 부분을 명확히 구분
    • 대규모 엔지니어링 플랫폼 조직 운영과 유사: 중앙에서 경계 설정, 로컬에서 자율성 허용
  • 결과 코드가 인간의 문체 선호도와 항상 일치하지 않을 수 있지만, 출력이 정확하고 유지관리 가능하며 에이전트 실행 시 읽기 쉬우면 기준 충족
  • 인간의 취향은 시스템에 지속적으로 피드백
    • 리뷰 코멘트, 리팩터링 PR, 사용자 측 버그는 문서화 업데이트로 기록되거나 툴링에 직접 인코딩
    • 문서화가 부족한 경우 규칙을 코드로 승격

병합 철학의 변화

  • Codex의 처리량 증가에 따라 기존 엔지니어링 규범이 오히려 역효과
  • 리포지터리는 최소한의 차단 병합 게이트로 운영
  • pull request는 수명이 짧고, 테스트 불안정성은 진행을 무기한 막기보다 후속 실행으로 해결
  • 에이전트 처리량이 사람의 주의력을 훨씬 초과하는 시스템에서는 수정 비용이 저렴하고 대기 시간이 비쌈
  • 처리량이 적은 환경에서는 적합하지 않을 수 있으며, 적절한 절충안 필요

"에이전트 생성"의 실제 범위

  • 코드베이스가 Codex 에이전트에 의해 생성된다는 것은 코드베이스에 있는 모든 것을 의미
    • 제품 코드 및 테스트
    • CI 구성 및 릴리스 툴링
    • 내부 개발자 도구
    • 문서화 및 설계 내역
    • 평가 하네스
    • 리뷰 코멘트 및 응답
    • 리포지터리 자체를 관리하는 스크립트
    • 생산 대시보드 정의 파일
  • 사람은 항상 루프에 남아 있지만, 예전과는 다른 추상화 레이어에서 작업
    • 업무 우선순위 지정, 사용자 피드백을 수용 기준으로 변환, 결과 검증
  • 에이전트가 어려움을 겪으면 이를 신호로 간주하여 도구, 가드레일, 문서화 등 누락 사항 파악, 항상 Codex 자체에서 수정사항을 작성하여 리포지터리에 다시 제공
  • 에이전트는 리뷰 피드백 가져오기, 인라인 응답, 업데이트 푸시, 자체 pull request 스쿼시·병합까지 수행

자율성 수준의 증가

  • 테스트, 검증, 리뷰, 피드백 처리, 복구 등 더 많은 개발 루프가 시스템에 직접 인코딩되면서 중요한 임계점 도달
  • 에이전트가 한 번의 프롬프트를 통해 수행 가능한 작업:
    • 코드베이스의 현재 상태 검증
    • 보고된 버그 재현
    • 실패 상황을 시연하는 동영상 녹화
    • 수정사항 구현
    • 애플리케이션 실행하여 수정사항 검증
    • 해결책을 보여주는 두 번째 동영상 녹화
    • pull request 열기
    • 에이전트 및 사람 피드백에 응답
    • 빌드 실패 감지 및 수정
    • 판단이 필요한 경우에만 사람에게 에스컬레이션
    • 변경사항 병합
  • 이러한 동작은 이 리포지터리의 특정 구조와 툴링에 따라 크게 좌우되며, 유사한 투자 없이 일반화할 수 있다고 가정해서는 안 됨

엔트로피 및 가비지 컬렉션

  • 에이전트의 완전한 자율성은 새로운 문제 야기: Codex가 리포지터리에 이미 존재하는 패턴(불균일하거나 최적 상태가 아닌 패턴 포함)을 복제하여 시간이 지나면 필연적으로 드리프트 발생
  • 초기에는 사람이 수동으로 처리, 매주 금요일(일주일의 20%) "AI 슬로프" 정리에 시간 소비
    • 예상대로 확장되지 않음
  • 대안으로 "황금 원칙" 을 리포지터리에 직접 인코딩하고 정기적 정리 프로세스 구축
    • (1) 불변 조건을 중앙에서 관리하기 위해 직접 만든 헬퍼보다 공유 유틸리티 패키지 선호
    • (2) "YOLO-style"로 데이터 탐색하지 않고, 경계를 검증하거나 유형 지정된 SDK에 의존하여 에이전트가 추측한 형태를 바탕으로 실수로 구축하지 못하도록 방지
  • 정기적으로 편차를 검사하고, 품질 등급을 업데이트하며, 대상 리팩터링 PR을 생성하는 Codex 백그라운드 작업 운영
    • 대부분 1분 이내에 검토 가능, 자동 병합
  • 이 방식은 가비지 컬렉션처럼 작동: 기술 부채는 고금리 대출과 같아서 이자가 쌓이기 전에 조금씩 꾸준히 갚는 것이 효과적
  • 사람의 취향이 한 번 포착되면 코드의 모든 라인에 지속적으로 반영, 나쁜 패턴이 며칠~몇 주간 퍼지지 않도록 매일 포착·해결

현재 진행 중인 학습과 향후 과제

  • 이 전략은 OpenAI에서 내부 출시와 도입 단계까지 잘 적용
  • 실제 사용자를 위한 실제 제품 구축으로 투자를 현실에 안착시키고 장기적인 유지관리 가능성 확보
  • 아직 알지 못하는 부분: 완전한 에이전트 생성 시스템에서 아키텍처 일관성이 수년에 걸쳐 어떻게 진화하는지
  • 사람의 판단이 가장 큰 영향력을 발휘하는 부분과 그 판단을 인코딩하여 복합적으로 활용하는 방법을 여전히 학습 중
  • 모델의 기능이 계속 향상됨에 따라 이 시스템의 발전 방향도 미지수
  • 소프트웨어 구축에는 여전히 규율이 필요하지만, 규율은 코드보다는 스캐폴딩에서 더 많이 발현
  • 코드베이스의 일관성을 유지하는 툴링, 추상화, 피드백 루프가 점점 더 중요
  • 현재 가장 어려운 과제: 에이전트가 복잡하고 안정적인 소프트웨어를 대규모로 구축·유지관리하는 데 도움이 되는 환경, 피드백 루프, 제어 시스템 설계
▲
ragingwind 8시간전  [-]

40일, 100만 줄, 130억 토큰 — Lablup 신정규 대표가 발견한 에이전틱 워크플로의 실체 - 박재홍의 실리콘밸리 - https://wikidocs.net/blog/@jaehong/8206/

답변달기