# 하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기 > Clean Markdown view of GeekNews topic #27457. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=27457](https://news.hada.io/topic?id=27457) - GeekNews Markdown: [https://news.hada.io/topic/27457.md](https://news.hada.io/topic/27457.md) - Type: GN+ - Author: [neo](https://news.hada.io/@neo) - Published: 2026-03-13T11:11:02+09:00 - Updated: 2026-03-13T11:11:02+09:00 - Original source: [openai.com](https://openai.com/ko-KR/index/harness-engineering/) - Points: 89 - Comments: 1 ## Summary 에이전트가 코드를 쓰는 시대에는, 결국 중요한 것은 코딩 실력보다 **에이전트가 잘 일할 수 있는 하네스(harness)를 설계하는 능력**인지도 모르겠습니다. OpenAI 팀의 사례도 모델이 알아서 다 해냈다기보다, 문서·린터·테스트·리뷰 루프 같은 **스캐폴딩을 얼마나 잘 짰는가**가 성패를 갈랐다는 점이 인상적입니다. 코드 생성이 빨라질수록 오히려 더 중요해지는 것은 **일관성, 피드백 루프, 엔트로피 관리**입니다. 소프트웨어 엔지니어링의 규율이 코드 자체에서 점점 **환경 설계 쪽으로 이동하고 있다**는 느낌을 주는 글입니다. ## Topic Body - 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에서 내부 출시와 도입 단계까지 잘 적용 - 실제 사용자를 위한 실제 제품 구축으로 투자를 현실에 안착시키고 장기적인 유지관리 가능성 확보 - 아직 알지 못하는 부분: 완전한 에이전트 생성 시스템에서 **아키텍처 일관성이 수년에 걸쳐 어떻게 진화**하는지 - 사람의 판단이 가장 큰 영향력을 발휘하는 부분과 그 판단을 인코딩하여 복합적으로 활용하는 방법을 여전히 학습 중 - 모델의 기능이 계속 향상됨에 따라 이 시스템의 발전 방향도 미지수 - 소프트웨어 구축에는 여전히 **규율이 필요**하지만, 규율은 코드보다는 **스캐폴딩**에서 더 많이 발현 - 코드베이스의 일관성을 유지하는 **툴링, 추상화, 피드백 루프**가 점점 더 중요 - 현재 가장 어려운 과제: 에이전트가 **복잡하고 안정적인 소프트웨어를 대규모로 구축·유지관리**하는 데 도움이 되는 환경, 피드백 루프, 제어 시스템 설계 ## Comments ### Comment 52974 - Author: ragingwind - Created: 2026-03-13T21:23:02+09:00 - Points: 2 40일, 100만 줄, 130억 토큰 — Lablup 신정규 대표가 발견한 에이전틱 워크플로의 실체 - 박재홍의 실리콘밸리 - https://wikidocs.net/blog/@jaehong/8206/