하네스 엔지니어링

핵심 요약

이 글은 사람이 코드 대신 "환경·규칙·피드백 루프"를 설계하고, 실제 코드는 전부 에이전트(Codex)가 작성하는 개발 방식의 원리와 운영법을 설명한다.

핵심은 코드 품질이 아니라 "레일과 가드레일"을 얼마나 잘 깔아주느냐, 그리고 모든 지식과 판단 기준을 리포지토리 안에 구조적으로 녹여 넣느냐에 달려 있다.

사람은 조종, 에이전트는 실행

이 팀은 "사람이 한 줄도 직접 코드를 쓰지 않는다"는 강력한 제약을 걸고 제품을 만들었다.

개발자의 역할은 더 이상 함수나 클래스를 짜는 것이 아니라, 문제를 정의하고, 목표와 제약을 명확히 서술하고, 에이전트가 움직일 수 있는 작업 환경을 설계하는 쪽으로 바뀐다.

실제 작업 흐름은, 사람이 "어떤 기능을 만들어라", "이 버그를 고쳐라"와 같은 일을 자연어로 설명하면 Codex가 설계, 구현, 테스트, PR 작성, 리뷰 반영까지 수행하는 구조에 가깝다.

이때 사람은 에이전트가 막힐 때 직접 대신 구현하지 않고, "왜 막히는지", "어떤 도구·추상화·규칙이 없어서 막히는지"를 찾아내어 시스템 자체를 개선하는 쪽에 시간을 쓴다.

빈 리포지토리에서 0줄 코드 스타트

처음에는 텅 빈 Git 리포지토리만 있었다.

리포지토리 구조, 패키지 매니저 설정, 포맷팅 규칙, CI 설정, 심지어 에이전트 작업 가이드를 담은 AGENTS.md까지도 Codex가 생성했다.

사람이 작성한 "시드 코드"가 없으니, 리포지토리의 스타일과 구조는 자연스럽게 에이전트가 선호하는 패턴과 추론 방식에 맞게 형성된다.

5개월 동안 약 1500개의 PR이 병합되었고, 결과적으로 애플리케이션 코드, 인프라, 문서, 테스트 등을 합쳐 약 백만 줄 규모의 코드베이스가 만들어졌다.

이 과정에서도 사람은 직접 코드에 손대지 않고, 에이전트가 더 잘 일하게 만들 "환경 튜닝"에 집중했다.

개발자의 역할 재정의: 코드가 아닌 시스템을 만든다

에이전트가 코드를 쓰는 환경에서는 "개발자 = 문제를 해결하는 손"이 아니라 "에이전트가 문제를 해결하게 만드는 시스템 디자이너"에 가깝다.

초기에는 Codex의 능력 부족이 아니라, 에이전트가 제대로 일할 수 있도록 준비된 도구·추상화·내부 구조가 부족해서 속도가 잘 나오지 않았다.

그래서 팀은 큰 목표를 쪼개어, 먼저 필요한 도구나 공통 모듈, 작업 플로우를 에이전트에게 만들게 하고, 그다음 그 도구들을 사용해 더 복잡한 일을 시키는 "깊이 우선" 전략을 썼다.

무언가 실패하면, "에이전트가 더 잘하도록 프롬프트를 세게 치자"가 아니라, "에이전트가 이해하고 따를 수 있는 명확한 규칙이나 구조가 없는 건 아닌가?"를 점검한다.

이 관점이 자리잡으면, 사람의 주요 산출물은 코드가 아니라 규약, 문서, 도구, 검증 체계, 자동화된 리뷰 룰 같은 "메타 수준의 자산"이 된다.

사람 대신 읽게 하라: UI·로그·메트릭까지 에이전트가 직접 본다

개발이 빨라질수록 병목은 "사람이 결과를 확인하는 시간"으로 옮겨간다.

이를 줄이기 위해 팀은 애플리케이션 UI, 로그, 메트릭, 트레이스를 Codex가 직접 다룰 수 있게 만들었다.

예를 들어, 커밋 단위로 독립 실행 가능한 앱 인스턴스를 띄우고, Codex가 각 작업용 브랜치에서 앱을 실제로 구동해 보면서 버그를 재현하고 수정 여부를 검증하도록 했다.

또한 Chrome DevTools Protocol을 붙여 DOM 스냅샷과 스크린샷을 보고 UI 동작을 추론하게 했고, 로그/메트릭도 로컬 관측 스택에 연결해 LogQL, PromQL 쿼리까지 날릴 수 있게 했다.

이렇게 하니 "이 사용자 흐름 네 개에서 어떤 스팬도 2초를 넘기지 마라" 같은 목표를 에이전트가 스스로 측정하고 확인하는 것이 가능해졌고, 긴 작업을 몇 시간 동안 사람 개입 없이 수행하는 것도 자연스러워졌다.

리포지토리를 지식의 단일 출처로 만든다

에이전트가 긴 작업을 잘 수행하게 하려면 "무엇을 어떻게 해야 하는지"를 알려주는 지식 관리가 핵심이다.

처음에는 거대한 AGENTS.md 하나로 모든 규칙과 지식을 때려 넣었지만, 곧 여러 문제가 드러났다.

컨텍스트는 제한적인데 한 파일에 온갖 내용을 담으면, 진짜 중요한 정보가 묻히고, 오래되거나 틀린 내용도 함께 들어가 에이전트를 혼란스럽게 한다.

그래서 이 팀은 AGENTS.md를 "백과사전"이 아니라 "목차"라는 역할로 축소하고, 실제 지식은 docs/ 디렉터리 아래 구조화된 문서들에 분산하여 저장했다.

설계 문서, 아키텍처 개요, 품질 평가표, 실행 계획, 기술 부채 목록, 레퍼런스 자료 등이 모두 리포지토리 안에서 버전 관리되며, 에이전트는 AGENTS.md를 통해 어디에 무엇이 있는지부터 배우게 된다.

추가로, 문서의 최신성·연결 관계·형식을 검사하는 린터와 CI를 두고, "문서 정원 가꾸기"용 에이전트가 주기적으로 문서와 실제 코드의 불일치를 찾아 수정 PR을 올리도록 했다.

결국 "리포지토리에 들어오지 않은 지식은 없는 것과 같다"는 철학이 자리잡는다.

에이전트가 이해할 수 있는 구조: 레거시가 아니라 레일을 깐다

이 코드베이스는 "사람이 보기 예쁜 코드"가 아니라 "에이전트가 논리적으로 추론하기 쉬운 구조"를 목표로 설계된다.

에이전트 입장에서, 코드·문서·스키마·테스트처럼 리포지토리 안에서 직접 읽고 수정할 수 있는 것만이 진짜 세계다. 구글 문서, 슬랙 대화, 사람 머릿속 노하우는 존재하지 않는 것과 같다.

그래서 팀은 의존성·추상화를 선택할 때도, 에이전트가 리포 안에서 끝까지 추적하고 이해할 수 있는 것들을 선호했다.

예를 들어, 불투명한 서드파티 라이브러리에 의존하기보다, 필요한 기능 정도라면 에이전트에게 재구현하기도 한다. 그렇게 만든 유틸은 테스트가 충분하고, 관측 도구와도 잘 통합되어 있어, 이후 작업에서도 에이전트가 재사용과 이해를 쉽게 할 수 있다.

이렇게 "에이전트가 읽고, 검증하고, 바꿀 수 있는 형태"로 시스템을 끌어들이면, 이후 다른 에이전트(예: 코드 리뷰, 평가, 리팩토링 전용 에이전트)도 같은 기반 위에서 더 잘 일할 수 있게 된다.

강한 아키텍처 규칙: 구현이 아니라 경계를 통제한다

에이전트가 코드 대부분을 쓰는 환경에서는 "규칙 없는 자유"가 곧 혼돈으로 이어진다.

이 팀은 각 비즈니스 도메인을 고정된 계층 구조(예: 타입 → 설정 → 저장소 → 서비스 → 런타임 → UI)로 나누고, 어떤 계층에서 어느 계층으로만 의존할 수 있는지 엄격하게 규정했다.

인증, 텔레메트리, 기능 플래그처럼 횡단 관심사는 별도의 Provider 인터페이스를 통해서만 들어올 수 있고, 그 외의 의존성은 린터와 구조 테스트로 자동 차단된다.

이건 마치 "철도 노선도"를 미리 못박아 두고, 열차(에이전트)는 아무리 빨리 달려도 정해진 선로만 이용할 수 있게 만드는 것과 비슷하다.

이 규칙들은 튜닝된 린터와 커스텀 에러 메시지로 구현되어, 에이전트가 규칙을 어기는 코드를 만들면, 오류 메시지 속에 바로 "이렇게 수정하라"는 지침까지 같이 들어간다.

사람 입장에서는 다소 까다로운 규칙처럼 느껴질 수 있지만, 에이전트에게는 "한 번 배우면 계속 재사용 가능한 가이드라인"이 되어 전체 속도를 크게 끌어올린다.

에이전트가 코드를 전부 만든다는 것의 실제 의미

"에이전트가 코드를 쓴다"는 말이 단순히 비즈니스 로직만 생성한다는 뜻은 아니다.

이 시스템에서는 제품 코드, 테스트, CI 설정, 배포 스크립트, 내부 개발 도구, 문서와 설계 역사, 평가용 스크립트, 리뷰 코멘트, 대시보드 정의 등 리포지토리 안의 거의 모든 파일이 Codex에 의해 작성·수정된다.

사람은 여전히 책임을 진다. 다만 손으로 코드를 고치지 않고, "무엇을 기준으로 잘했는지·못했는지를 판단할 것인가"와 "그 판단 기준을 어떻게 시스템에 encode할 것인가"에 집중한다.

에이전트가 실수하거나 막히면, 개발자는 직접 수정하지 않고 "무엇이 부족했는지"를 찾는다. 그리고 그 부족한 도구·문서·린터를 또 다른 에이전트에게 만들게 하여, 같은 문제가 다음에는 자동으로 방지되도록 만든다.

이렇게 하면 사람의 판단과 취향은 한 번 정의되면, 그 이후에는 에이전트와 도구들이 모든 코드에 지속적으로 적용해 주는 형태가 된다.

끝까지 자동화된 개발 루프: 하나의 프롬프트로 기능이 완성된다

점점 더 많은 검증·리뷰·복구 절차가 시스템 안으로 들어오자, 결국 Codex가 "기획된 하나의 작업"을 처음부터 끝까지 거의 혼자 수행할 수 있는 수준에 이르렀다.

예를 들어, 버그 리포트나 기능 요청을 하나의 프롬프트로 주면, Codex는 현재 코드 상태를 파악하고, 문제를 재현하고, 실패 장면을 영상으로 남기고, 수정 코드를 작성하고, 고쳐졌는지 다시 앱을 구동해 확인하며, 그 과정을 담은 두 번째 영상을 만들 수 있다.

그다음 자동으로 PR을 열고, 다른 에이전트나 사람이 남긴 리뷰를 반영하고, 빌드 실패를 고치고, 정말 애매한 판단이 필요한 경우에만 사람에게 도움을 요청한다. 최종적으로는 스스로 머지까지 할 수 있다.

물론 이 수준의 자율성은 리포지토리 구조, 도구, 규칙, 문서, 린터 등 상당한 초반 투자 위에서만 가능하다. 아무 리포지토리에나 같은 에이전트를 붙인다고 바로 이런 결과가 나오지는 않는다.

엔트로피 관리: "AI 슬롭"을 줄이는 금요일 대신 자동 청소

에이전트가 생산성을 폭발적으로 올리면, 자연스럽게 "정리되지 않은 코드와 패턴"도 폭발적으로 늘어난다.

초기에는 팀이 매주 금요일을 거의 통째로 투자해 이런 "AI가 대충 만든 자잘한 코드들"을 정리했지만, 이는 곧 한계에 부딪혔다.

대신 이들은 "골든 프린시플"이라는 형식으로 코드베이스의 미학과 철학을 명문화하고, 이를 자동으로 감시하고 교정하는 프로세스를 구축했다.

예를 들어 "비슷한 기능은 공통 유틸로 빼서 중앙에서 관리한다", "경계에서는 반드시 스키마 검증을 거치며, 추측으로 필드를 쓰지 않는다" 같은 규칙을 정의해놓고, Codex가 주기적으로 리포지토리를 스캔해 위배 사례를 찾아 리팩토링 PR을 연다.

이 PR들은 사람이 1분 이내에 훑어보고 자동 머지할 수 있도록 작고 명확하게 만들어, 기술 부채를 "한 번에 대청소"가 아니라 "매일 조금씩 자동 상환"하는 구조로 바꿨다.

인사이트

에이전트 퍼스트 방식의 핵심은 "코드를 대신 써 줘서 편하다"가 아니라, "사람이 해야 할 일을 한 단계 위로 올린다"는 데 있다.

코드를 직접 치는 대신, 에이전트가 안전하게 달릴 수 있는 선로, 신호등, 규칙, 정기 검진 체계를 설계하는 사람일수록 더 큰 레버리지를 얻게 된다.

실무에서 조금씩 시도해 보고 싶다면, 처음부터 전부 맡기려 하기보다 다음과 같은 단계적 접근이 유용하다.

먼저, 프로젝트 리포지토리 안에 "에이전트 전용" 문서와 규칙을 두고, 사람이 나누어 쓰던 지식을 한곳에 모으며 "리포지토리 = 단일 진실의 원천"이라는 습관을 들여보는 것이 좋다.

다음으로, 자주 반복되는 패턴(예: API 호출, 에러 처리, 로깅)을 에이전트에게 구현시키고, 이를 강제하는 린터와 템플릿을 도입해본다.

마지막으로, 리뷰·테스트·리팩토링 같은 품질 작업 일부를 점진적으로 에이전트에게 넘기며, 실패 사례를 "사람이 손으로 해결"하는 대신 "도구와 규칙을 고쳐서 해결"하는 습관을 들이면, 어느 순간 "에이전트가 도는 공장"에 가까운 개발 환경을 갖추게 된다.

출처 및 참고 : Harness engineering: leveraging Codex in an agent-first world | OpenAI