나는 일주일 동안 모델을 탓하며 시간을 보냈다.

나의 Codex 실행 환경은 계속해서 예산을 초과했고, 나의 에이전트(agents)들은 계속해서 잘못된 파일을 수정했으며, 매일 아침 나는 "거의" 성공할 뻔했던 또 다른 PR(Pull Request)을 마주하며 잠에서 깨어났다. 나는 유행을 따라 Sonnet을 GPT-5로 교체했다가 다시 되돌리기도 하고, 더 큰 컨텍스트 윈도우(context window)를 시도했다가 더 작은 것을 시도하기도 했다. 아무것도 변하지 않았다.

버그는 내 AGENTS.md 파일의 단 한 단락 속에 숨어 있었다.

OpenAI는 2026년 2월에 "Harness engineering: leveraging Codex in an agent-first world"를 발표했으며, Codex 팀의 공개 수치는 내가 그 주에 겪었던 것과 동일한 이야기를 들려준다. 2025년 8월부터 2026년 1월 사이에 세 명의 엔지니어가 약 1,500개의 병합된 PR을 주도했으며, 수작업으로 작성된 코드는 단 한 줄도 없이 약 100만 줄의 프로덕션 코드(production code)를 배포했다. 중간에 모델이 바뀌지는 않았다. AGENTS.md가 두 번 바뀌었을 뿐이다.

다음은 이 실험이 증명한 세 가지 사항이다.

교훈 1: "하나의 거대한 AGENTS.md"는 그 무게를 견디지 못하고 무너진다

Codex 팀의 첫 번째 시도는 전체 저장소(repo)를 아우르는 하나의 커다란 AGENTS.md를 만드는 것이었다. 코딩 컨벤션(Coding conventions), 모듈 경계(module boundaries), 리뷰 체크리스트(review checklist), 배포 런북(deployment runbook)이 모두 하나의 파일에 담겨 있었다. 이는 마치 옳은 방법처럼 보인다.

하지만 그것은 가장 예측 가능한 방식으로 실패했다. 컨텍스트(Context)는 희소한 자원이며, 거대한 지침 파일은 에이전트가 실제로 살펴보아야 할 작업, 코드, 그리고 문서를 밀어낸다. 팀은 이에 대해 직접적으로 기술했다. 백과사전식 접근 방식은 실패했는데, 그 백과사전 자체가 에이전트가 코드를 읽는 것을 중단하게 만든 원인이었기 때문이다.

해결책은 AGENTS.md를 목차(약 100줄 정도)로 축소하고, 실제 지식은 기록 시스템(system of record)으로 취급되는 docs/ 디렉토리로 옮기는 것이었다. 이제 AGENTS.md는 질문에 답하지 않는다. 대신 어디를 찾아봐야 하는지를 가리킨다.

그 글을 읽은 당일에 나는 동일한 형태를 나의 자체적인 하네스 (harness)에 이식했다. 나의 이전 AGENTS.md는 940줄이었다. 새로운 것은 118줄이며 다음과 같은 모습이다:

# AGENTS.md

## Overview
...

이전 파일의 AGENTS.md에 자리 잡고 있던 모든 제약 조건들은 이제 그것이 실제로 필요한 스킬 (skill) 파일 내에 존재한다. 에이전트 (agent)는 해당 작업에 진입할 때만 그것을 로드한다.

내가 싸워오던 회귀 (regressions) 현상은 그날 오후에 멈췄다. 모델이 더 똑똑해졌기 때문이 아니다. 모델로부터 코드를 숨기는 것을 그만두었기 때문이다.

교훈 2: 하네스 (harness)가 버그일 때 모델을 교체하는 것은 아무것도 해결하지 못한다

이것은 불편한 진실이다.

일주일 동안 나는 모델들을 A/B 테스트했다. GPT-5를 시도해 보았고, Claude Sonnet 4.6을 시도해 보았으며, 저렴한 실행을 위해 Haiku를, 어려운 작업에는 Opus를 시도해 보았다. 동일한 15개 작업에 대한 나의 완료율 (completion rate)은 네 가지 모델 모두에서 4퍼센트 포인트 미만으로 움직였다.

나는 더 작은 모델로 교체하되 더 깔끔한 하네스 (harness)를 도입했다: 118줄의 AGENTS.md, 모든 커밋 전에 린터 (linters)를 실행하는 훅 (hooks), 그리고 app/ 외부의 쓰기를 거부하는 샌드박스 (sandbox)를 구축했다. 동일한 15개 작업에 대한 완료율이 31포인트 급증했다.

그 후 Codex 팀의 표현이 다르게 다가왔다: "에이전트 (agents)가 어려운 것이 아니라, 하네스 (harness)가 어려운 것이다." 나는 그것을 믿기 한 달 전에 읽었는데, 이는 대략 업계 평균 지연 시간과 비슷하다.

Louis Bouchard는 그의 2026년 글에서 더 직설적으로 표현했다: "모델이 멍청하다"라고 말하는 것을 멈추고, "내 시스템이 이 실패를 용인했다"라고 말하기 시작하라. 이러한 재프레임 (reframe) 덕분에 Codex 팀은 몇 주 동안 동일한 모델 체크포인트 (model checkpoint)를 유지하며, 모든 회귀 (regression)를 모델 교체가 아닌 docs/ 업데이트로 취급한다. 하네스 (harness)가 변하는 대상이 될 때, 모델은 안정적인 변수가 되며, 무엇이 고장 났는지 실제로 추론할 수 있게 된다.

교훈 3: AGENTS.md, Anthropic Skills, 그리고 .cursorrules는 서로 다른 역할을 수행한다

용어들이 의도적으로 혼란스럽다. 모든 벤더 (vendor)가 유사한 형태에 대해 서로 다른 명사를 선택했기 때문이다.

내가 각 도구와 함께 배포하는 내용을 바탕으로 실제로 차이점이 무엇인지 정리하면 다음과 같다:

이들은 서로 보완합니다. 나만의 하네스 (harness)에서는 최상위 인덱스로 슬림한 AGENTS.md를 유지하고, 작업별로 특화된 모든 내용은 docs/skills/ 아래에 Anthropic 스타일의 스킬 (skill) 파일로 관리하며, 모든 작업에 걸쳐 유지되는 두세 가지 에디터 범위 컨벤션(예: any를 절대 사용하지 말 것, 허가 없이 main.py를 수정하지 말 것)을 위해 짧은 .cursorrules를 사용합니다. AGENTS.md는 스킬들과 경쟁하는 것이 아니라, 스킬들이 어디에 있는지 알려주는 역할을 합니다.

다른 사람들의 저장소에서 여전히 가장 자주 보이는 실패 사례는

Codex 실험의 불편한 진실은 "어떤 모델인가"가 내내 잘못된 질문이었다는 점입니다. 올바른 질문은 이 모델이 어떤 하네스 (Harness)를 착용하고 있는가입니다. 만약 체크포인트 (Checkpoint)를 교체하며 벤더 (Vendor)를 탓해왔다면, 먼저 AGENTS.md를 축소해 보십시오. 그것이 더 저렴하며, 대개 그것이 실제 버그입니다.

이에 대한 더 긴 버전 — 하네스의 6가지 구성 요소, 왜 AGENTS.md가 그중 하나일 뿐인지, 그리고 동일한 형태가 CLAUDE.md와 훅 (Hooks)에 어떻게 적용되는지에 대해 알고 싶다면, 그것이 바로 제 책의 주제입니다.

Harness Engineering: Building the Environment That Makes AI Agents Reliable

출처: OpenAI — Harness engineering, Anthropic — Harness design for long-running app development, InfoQ — Anthropic three-agent harness.