'하네스 엔지니어링' 용어가 처음 바이럴된 Open AI Blog 글 읽어보기

 

최근 하네스 엔지니어링이라는 용어가 인기를 얻고 있는 것 같습니다.

그 용어가 처음 어디에서 쓰였을지가 궁금해서 찾아보았습니다.

 

하네스 엔지니어링이라는 용어는 OpenAI 공식 블로그의 글에서 쓰인 이후 크게 관심이 늘어난 것 같습니다.

 

OpenAI는 5개월간 인간 엔지니어가 수동으로 코드를 한 줄도 작성하지 않고

오직 AI 에이전트(Codex)만을 활용하여 실제 서비스 수준의 소프트웨어 제품을 구축하고 출시한 실험을 진행하였습니다.

최종적으로 AI 에이전트는 100만라인 규모의 코드베이스를 구축 했습니다.

 

당연하지만 원글은 하네스 엔지니어링이란 이것이다! 라는 paper 형식의 글은 아닙니다.

글의 내용은 AI만으로 서비스를 만드는 실험을 진행하면서 얻었던 고찰과 시행착오들을 공유해주는 내용입니다.

 

뒤에는 블로그글에 소개된 OpenAI가 직면한 문제와, 해결을 위해 했던 노력을 정리 해보았습니다.

주로 번역된 원문이고 제 생각이 중간중간 달려있습니다.

 

1. 깊이 우선 문제해결

초기 진행은 예상보다 더뎠습니다. 이는 Codex의 역량이 부족해서가 아니라 환경이 제대로 갖춰지지 않았기 때문입니다. 에이전트가 상위 목표를 달성하기 위한 도구, 추상화, 내부 구조가 부족했습니다. 엔지니어링 팀의 주요 업무는 에이전트가 유용한 업무를 수행할 수 있도록 지원하는 것이 되었습니다.

 

실제로는 큰 목표를 더 작은 빌딩 블록(설계, 코드, 검토, 테스트 등)으로 세분화하고 에이전트가 이러한 블록을 구성하도록 유도한 다음 이를 사용하여 더 복잡한 작업을 해결하는 깊이 우선 작업을 의미했습니다. 

 

 

2. 애플리케이션의 가독성 향상 (에이전트 피드백 루프)

코드 처리량이 증가하면서, 인적 QA 역량에 병목 현상이 발생했습니다. 

 

사람의 시간과 주의력이 고정된 제약이었기 때문에 애플리케이션 UI, 로그, 앱 메트릭 등을 Codex가 직접 읽고 이해할 수 있도록 하여 에이전트에 더 많은 기능을 추가하기 위해 노력해 왔습니다.

- git worktree별로 앱을 부팅할 수 있게 하여 Codex가 변경사항마다 하나의 인스턴스를 실행하고 제어할 수 있도록 했습니다.
- Chrome DevTools Protocol을 에이전트 런타임에 연결하고 DOM 스냅샷, 스크린샷, 탐색 작업을 위한 스킬을 만들었습니다.
- 로그, 메트릭, 추적은 각 워크트리에 대해 일시적으로 유지되는 로컬 관측 가능성 스택을 통해 Codex에 노출됩니다.

에이전트는 LogQL로 로그를 쿼리하고 PromQL로 메트릭을 쿼리할 수 있습니다. 이러한 컨텍스트가 주어지면 “서비스 시작이 800ms 이내에 완료”되도록 하거나 “이 네 가지 핵심 사용자 여정에서 어떤 스팬도 2초를 초과하지 않도록” 하는 등의 프롬프트를 다루기 쉬워집니다.

 

3. 문서화 전략

컨텍스트 관리는 에이전트가 크고 복잡한 작업을 효과적으로 수행하는 데 있어 가장 큰 과제 중 하나입니다. 초기에 우리가 배운 교훈 중 하나는 간단했습니다. Codex에 1,000페이지의 설명서가 아닌 맵을 제공해야 한다는 것이었습니다.

 

“하나의 큰 AGENTS.md⁠” 접근 방식을 시도해 보았지만 다음과 같이 예측 가능한 방식으로 실패했습니다.

  - 컨텍스트는 희소 리소스. 거대한 지침 파일로 인해 작업, 코드 및 관련 문서가 복잡해져서 에이전트가 주요 제약 조건을 놓치거나 잘못된 제약 조건에 맞게 최적화를 시작하게 됩니다.
  -  지침이 너무 많으면 지침이 되지 않음. 모든 것이 “중요”하다면 중요한 것은 아무것도 없습니다. 에이전트는 의도적으로 탐색하는 대신 로컬에서 패턴 매칭을 수행하게 됩니다.
  -  순식간에 망가짐. 획일적인 거대 매뉴얼은 낡은 규칙들의 무덤으로 변합니다. 에이전트는 무엇이 여전히 사실인지 알 수 없고, 사람들은 더 이상 이를 유지관리하지 않으며, 파일은 조용히 매력적인 골칫거리로 변합니다.
  -  확인하기 어려움. 단일 블롭은 기계적 점검(커버리지, 신선도, 소유권, 교차 연결)에 적합하지 않으므로 드리프트는 불가피합니다.

따라서 AGENTS.md를 백과사전으로 취급하는 대신 목차로 취급합니다.

 

 

AGENTS.md

• https://agents.md/
• 짧은 AGENTS.md(약 100개 라인)는 컨텍스트에 삽입되어 주로 맵 역할을 하며, 다른 곳에 있는 더 심층적이고 신뢰할 수 있는 정보 소스를 알려줍니다.

 

ARCHITECTURE.md

• https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html
• 도메인과 패키지 레이어링의 최상위 맵을 제공합니다

 

DESIGN.md

• 검증 상태와 에이전트 우선 운영 원칙을 정의하는 몇 가지 핵심 신념을 포함하여 분류되고 색인합니다.

 

QUALITY_SCORE.md

• 각 제품 도메인과 아키텍처 레이어에 등급을 매기며, 시간이 지남에 따라 격차를 추적합니다.

 

PLANS.md

• https://developers.openai.com/cookbook/articles/codex_exec_plans
• 일급 아티팩트로 간주됩니다. 일시적이며 간단한 계획은 작은 변경에 사용되며, 복잡한 작업은 진행 상황과 의사결정 로그와 함께 실행 계획⁠에 포함되어 리포지터리에 저장됩니다.

 

우리는 이를 기계적으로 시행합니다. 전용 린터와 CI 작업은 지식 베이스가 최신 상태이고, 교차 링크되어 있으며, 올바르게 구성되어 있는지 검증합니다. 반복 실행되는 “doc-gardening” 에이전트가 실제 코드 동작을 반영하지 않는 오래되거나 더 이상 유효하지 않은 문서화를 검토하여 수정용 pull request를 엽니다.

 

 

4. 에이전트 가독성 향상

에이전트의 관점에서 보면 실행 중에 컨텍스트 내에서 액세스할 수 없는 것은 사실상 존재하지 않는 것입니다. Google Docs, 채팅 스레드 또는 사람들의 머릿속에 있는 지식은 시스템에서 접근할 수 없습니다. 리포지터리 내의 버전 관리되는 아티팩트(예: 코드, 마크다운, 스키마, 실행 계획)에만 접근할 수 있습니다.

 

결합성과 API 안정성이 높고 모델이 쉽게 추론할 수 있는 "지루하고 안정적인(Boring) 기술"을 선호합니다.

 

어떤 경우에는 공개 라이브러리의 불투명한 업스트림 동작에 맞춰 작업하는 것보다 에이전트가 기능의 일부 하위 집합을 다시 구현하는 것이 더 저렴했습니다.

 

 

5. 구현을 통제하지 말고, 불변 규칙을 강제

문서화만으로는 에이전트가 생성한 코드베이스의 완전히 일관되게 유지할 수 없습니다. 
구현을 세세하게 관리하지 않고 불변 조건을 강제 적용함으로써 기초를 튼튼히 유지하면서 에이전트가 빠르게 출시할 수 있도록 합니다. 

 

예를 들어서 OpenAI 에서는 데이터 파싱 등을 경계에서 수행 하도록 요구하되,

실제 파싱에 어떤 라이브러리를 사용할지에 대한 제약은 두지 않았다고 합니다.

(모델은 Zod를 선택해서 개발했다고 합니다.)

 

에이전트는 엄격한 경계와 예측 가능한 구조⁠를 갖춘 환경에서 가장 효과적이므로, 우리는 엄격한 아키텍처 모델을 중심으로 애플리케이션을 구축했습니다.

 

엄격한 경계와 예측 가능한 구조에 대해서는 한 게시글을 링크 해두었습니다.

https://bits.logic.inc/p/ai-is-forcing-us-to-write-good-code

AI Is Forcing Us To Write Good Code

 

Layered Domain Architecture

• 각 비즈니스 도메인 내에서 코드는 고정된 레이어 집합(Types → Config → Repo → Service → Runtime → UI)을 통해서만 전달할 수 있습니다. 
• 교차되는 문제(인증, 커넥터, 텔레메트, 기능 플래그)는 하나의 명시적인 인터페이스인 Providers를 통해 유입됩니다.

커스텀 린터

• 구조화된 로깅, 스키마 및 유형의 명명 규칙, 파일 크기 제한, 플랫폼별 안정성 요구 사항을 정적으로 적용
• 린트가 맞춤형이므로 오류 메시지를 작성하여 에이전트 컨텍스트에 수정 지침을 주입
• 개발자의 '취향'에 해당하는 것들을 린터로 관리

구조적 테스트

 

인간의 취향은 시스템에 지속적으로 피드백됩니다. 리뷰 코멘트, 리팩터링 pull request, 사용자 측 버그는 문서화 업데이트로 기록되거나 툴링에 직접 인코딩됩니다. 문서화가 부족한 경우 규칙을 코드로 승격합니다.

 

이러한 종류의 아키텍처는 보통 수백 명의 엔지니어가 확보될 때까지 미루는 경우가 많습니다. 코딩 에이전트에는 초기 전제 조건이 있습니다. 제약 조건이 있어야 성능 저하나 아키텍처 드리프트 없이 속도를 낼 수 있습니다.

 

6. 병합(merge) 철학을 변화 시키는 처리량

Codex의 처리량이 증가함에 따라 기존의 많은 엔지니어링 규범이 오히려 역효과를 내기 시작했습니다.

리포지터리는 최소한의 차단 병합 게이트로 운영됩니다. pull request는 수명이 짧습니다. 테스트 불안정성은 진행을 무기한으로 막기보다는 후속 실행으로 해결하는 경우가 많습니다. 에이전트 처리량이 사람의 주의력을 훨씬 초과하는 시스템에서는 수정 비용이 저렴하고 대기 시간은 오래 걸립니다.

이는 처리량이 적은 환경에서는 적합하지 않습니다. 여기에서 종종 적절한 절충안이 필요합니다.

 

AI 에이전트가 코드를 생산하는 속도가 너무 빨라 PR의 수명이 너무 짧아졌습니다.

일반적으로 사람이 개발할 때, PR은 테스트를 거치고 코드의 안정성을 확보 해야 병합하지만

OpenAI는 차라리 후속 개발에 수정을 추가하고 불안정한 코드를 병합하는게 더 빠르다는 걸 확인 했습니다.

 

7. 에이전트 생성의 실제 의미

코드베이스가 Codex 에이전트에 의해 생성된다는 것은 코드베이스에 있는 모든 것을 의미합니다.

에이전트가 생성하는 것:

- 제품 코드 및 테스트
- CI 구성 및 릴리스 툴링
- 내부 개발자 도구
- 문서화 및 설계 내역
- 평가 하네스
- 리뷰 코멘트 및 응답
- 리포지터리 자체를 관리하는 스크립트
- 생산 대시보드 정의 파일


사람은 항상 루프에 남아 있지만, 예전과는 다른 추상화 레이어에서 작업합니다. 업무를 우선시하고, 사용자 피드백을 수용 기준으로 바꾸며, 결과를 검증합니다. 에이전트가 어려움을 겪으면 이를 신호로 간주하여 도구, 가드레일, 문서화 등 무엇이 누락되었는지 파악하고 항상 Codex 자체에서 수정사항을 작성하여 리포지터리에 다시 제공합니다.

에이전트는 우리의 표준 개발 도구를 직접 사용합니다. 에이전트는 리뷰 피드백을 가져오고, 인라인으로 응답하고, 업데이트를 푸시하며, 종종 자체 pull request를 스쿼시하고 병합하기도 합니다.

 

8. 엔트로피 및 가비지 컬렉션

시간이 지나면 필연적으로 드리프트*가 나옵니다.

에이전트가 기존 코드를 보고 패턴을 학습해서 새 코드를 쓰기 때문에, 나쁜 패턴이 있으면 나쁜 패턴을 계속 복제하고 증폭시키는 문제가 생깁니다.

 

OpenAI에서는, 프로젝트 초기 인간 엔지니어들이 매주 금요일마다 이걸 정리하느라 시간을 보냈지만 확장성 없는 방법인건 자명했습니다.

 

대신 "황금 원칙(golden principles)" 을 저장소에 직접 인코딩하고, 반복적인 정리 프로세스를 구축했습니다.

이 원칙들은 미래의 에이전트 실행을 위해 코드베이스를 읽기 쉽고 일관되게 유지하는 주관적이고 기계적인 규칙들이고,

예시로 두 가지 원칙이 소개됩니다:

1. 직접 만든 헬퍼보다 공유 유틸리티 패키지를 선호한다 — 불변 규칙을 한 곳에 집중시키기 위해
2. 데이터를 "YOLO 방식"으로 탐색하지 않는다 — 경계에서 검증하거나 타입이 있는 SDK에 의존함으로써, 에이전트가 추측된 형태 위에 실수로 무언가를 만들지 않도록

* AI 드리프트(AI Drift)는 배포된 인공지능 모델의 성능이 시간이 지남에 따라 점진적으로 저하되거나 엉뚱한 결과를 출력하는 현상을 말합니다  

 

이것은 가비지 컬렉션처럼 작동합니다. 기술 부채는 고금리 대출과 같아서, 이자가 쌓여 고통스럽게 한꺼번에 갚는 것보다 조금씩 꾸준히 갚아나가는 편이 훨씬 낫습니다. 사람의 취향은 한 번 포착되면 코드의 모든 라인에 지속적으로 반영됩니다. 이렇게 하면 나쁜 패턴이 코드베이스에 며칠 또는 몇 주 동안 퍼지지 않도록 매일 포착하고 해결할 수 있습니다.

 

 

고찰

하네스 엔지니어링이라는 용어는 새로운 도구의 이름도, 정형화된 방법론도 아닙니다.

결국 핵심은 단순합니다. AI를 잘 쓰려면 AI가 잘 쓸 수 있는 환경을 사람이 만들어줘야 한다는 것입니다.

 

그리고 또한 이번에는 실험이였지만,장기적으로 AI가 개발자를 어떻게 대체해 나갈건지 보여주는 청사진이라고 생각합니다.