사례: OpenAI
OpenAI의 하네스 관점을 repo-readable 시스템, observability, cleanup 중심으로 해부합니다.
핵심 요약
- OpenAI 사례의 핵심은 에이전트가 일하는 장소가 프롬프트 창이 아니라 리포지터리 전체이며, 긴 작업 품질은 리포가 얼마나 agent-readable한지에 좌우된다는 점입니다.
- 하네스는
AGENTS.md + docs + browser + logs + metrics + cleanup의 결합으로, 탐색 순서 강제·실행 관찰 연결·엔트로피 관리 세 가지를 합니다. AGENTS.md는 백과사전이 아니라 시작용 TOC로 축약하고, 아키텍처 금지 규칙은docs/invariants.md로 분리합니다.- 2026년 Agents SDK·Codex 업데이트로 MCP·skills·sandbox·hooks·approvals·Secure MCP Tunnel·plugin이 하네스 runtime surface의 공통 primitive로 표준화되었습니다.
- observability(브라우저·로그·메트릭)는 운영이 아니라 에이전트 작업 자체의 일부라, 읽는 절차가 없으면 접근만 열어 둬도 소용없습니다.
OpenAI 사례의 핵심은 간단합니다. 에이전트가 일하는 장소는 프롬프트 창이 아니라 리포지터리 전체라는 점입니다.
긴 작업의 품질은 모델 파라미터보다
리포가 얼마나 agent-readable한지에 크게 갈립니다.
이 사례에서 볼 것
OpenAI는 하네스를 "명령문 템플릿"보다
AGENTS.md + docs + browser + logs + metrics + cleanup의 결합으로 봅니다.
2026년 4~5월 업데이트로 추가된 관점
2월 글의 핵심은 "repo 자체를 agent-readable하게 만들라"였습니다. 이후 OpenAI Agents SDK와 Codex 업데이트는 그 관점을 제품/플랫폼 primitive로 더 구체화했습니다.
| 업데이트 | 하네스 관점의 의미 |
|---|---|
| Agents SDK model-native harness | agent loop, tool use, memory, sandbox orchestration을 SDK 기본 구조로 취급 |
| Native sandbox execution | 파일, 명령, 의존성, output directory를 통제된 workspace로 제공 |
MCP / skills / AGENTS.md / shell / apply_patch | frontier agent 시스템에서 반복되는 primitive를 공통 surface로 정리 |
| TypeScript sandbox agents + open-source harness | Python 전용 실험이 아니라 웹/TS 스택에서도 적용 가능한 선택지로 확장 |
| Codex remote connections / hooks | 장시간 작업의 승인, 방향 전환, validation, logging을 장치와 환경을 넘어 유지 |
| Secure MCP Tunnel | private/on-prem MCP 도구를 공개 인터넷에 직접 노출하지 않고 연결 |
| OpenAI Developers plugin for Codex | OpenAI Platform 접속, API key setup, API troubleshooting을 plugin surface로 배포 |
그래서 OpenAI 사례는 이제 두 층으로 읽는 편이 낫습니다. 첫째, 리포와 문서를 agent-readable하게 만든다. 둘째, 그 리포를 읽고 실행하는 하네스 runtime surface를 MCP, skills, sandbox, hooks, approvals, plugins로 표준화한다.
해결하려는 문제
- 큰 리포에서 에이전트가 어디서부터 읽어야 할지 모름
- 필요한 아키텍처 규칙이 여러 문서에 흩어져 있음
- 코드는 맞아 보여도 실제 UI나 런타임은 다르게 동작함
- 오래된 문서가 쌓이며 잘못된 컨텍스트를 계속 주입함
- 사내 도구와 민감 데이터를 열어야 하지만 실행 환경과 credential 경계를 분리해야 함
기술적 메커니즘
이 구조에서 하네스가 하는 일은 세 가지입니다.
- 탐색 순서 강제: 먼저 읽을 파일과 문서를 지정합니다.
- 실행 관찰 연결: 브라우저, 로그, 메트릭을 바로 열 수 있게 합니다.
- 엔트로피 관리: stale 문서를 정리해 다음 작업의 입력 품질을 유지합니다.
왜 이게 엔지니어링인가
OpenAI 방식은 에이전트의 "탐색 비용"을 리포 구조 문제로 다룹니다.
| 설계 요소 | 바꾸는 실패 모드 |
|---|---|
짧은 AGENTS.md | 시작점이 매번 흔들리는 문제 |
구조화된 docs/ | 중요한 설계 정보가 검색 운에 좌우되는 문제 |
| MCP / skills | 필요한 도구와 지식을 거대한 프롬프트 대신 적절한 surface로 여는 문제 |
| sandbox / Manifest | 실행 환경, 입력 데이터, 출력 위치, 권한 경계를 예측 가능하게 만드는 문제 |
| 브라우저 / 로그 접근 | 코드만 보고 완료로 착각하는 문제 |
| hooks / approvals | lifecycle validation, logging, 사람 개입 지점을 자동화하는 문제 |
| plugin | 반복되는 provider setup과 troubleshooting을 설치 가능한 실행 경로로 만드는 문제 |
| cleanup 루틴 | 오래된 문서가 다음 세션을 오염시키는 문제 |
OpenAI의 하네스는 "더 잘 말해라"가 아니라 더 잘 찾고, 더 잘 확인하고, 더 적게 오염되게 하라는 시스템 설계입니다.
최소 구현 예시
# AGENTS.md
## Start Here
- Read `docs/architecture.md`
- Read `docs/invariants.md`
- Then inspect the relevant app directory
## Non-negotiables
- Do not bypass browser QA for UI changes
- Run lint/typecheck before finishing
- If schema or auth changes appear, escalate to human reviewdocs/
├── architecture.md
├── invariants.md
├── runbooks.md
└── glossary.md이 구조가 효과적인 건 문서가 많아서가 아니라
어디서 시작하고 무엇을 믿어야 하는지를 고정해 주기 때문입니다.
observability를 하네스에 넣는 이유
OpenAI 관점에서 브라우저, 로그, 메트릭은 "개발 이후 운영"이 아니라 에이전트 작업 자체의 일부입니다.
예를 들어 UI 변경을 생각해보면:
- builder가 코드를 수정합니다.
- 브라우저로 상태 전환을 확인합니다.
- 로그에서 에러를 봅니다.
- 필요하면 메트릭으로 실제 영향 범위를 봅니다.
이 과정을 하네스에 넣지 않으면 검증은 늘 사람의 암묵지나 사후 발견에 매달립니다.
실제로 훔칠 것
| 바로 옮길 것 | 이유 |
|---|---|
AGENTS.md를 시작용 TOC로 축약 | 긴 배경설명보다 초기 경로 고정이 더 중요 |
docs/invariants.md 분리 | 아키텍처 금지 규칙을 빠르게 찾게 함 |
| MCP / skills / hooks를 governance 대상으로 관리 | 도구 접근과 lifecycle 자동화도 문서처럼 drift됨 |
| provider setup plugin을 표준 경로로 관리 | API key 생성, 플랫폼 연결, troubleshooting이 개인 감각에 묶이지 않게 함 |
| sandbox boundary를 작업 유형별로 설계 | 민감 데이터, 의존성, 실행 side effect를 통제 |
| 브라우저 QA를 필수 검증으로 승격 | "코드가 맞다"와 "동작이 맞다"를 분리 |
| stale docs 정리 루틴 추가 | 다음 작업의 입력 품질 유지 |
그대로 복제하면 안 되는 점
- 문서를 많이 쓰는 것이 agent-readable을 보장하지 않습니다.
- 문서가 길면 오히려 시작 비용만 커집니다.
- observability 접근이 열려 있어도 읽는 절차가 없으면 소용없습니다.
우리 팀으로 번역하면
OpenAI 사례를 실무에 옮길 때의 질문은 이렇습니다.
- 에이전트가 첫 3분 안에 읽어야 할 문서는 무엇인가
- 어떤 MCP, skills, shell, filesystem 권한을 sandbox 안에 열 것인가
- 브라우저/로그/테스트 중 어떤 것을 기본 검증으로 강제할 것인가
- hooks와 remote approval로 어떤 lifecycle 이벤트를 붙잡을 것인가
- provider setup과 API troubleshooting을 어떤 plugin/skill로 표준화할 것인가
- stale 문서를 누가 언제 지울 것인가
이 질문들에 답하면 하네스가 추상론에서 리포 구조와 runtime surface 설계로 내려옵니다.
참고
- OpenAI,
Harness Engineering, 2026-02-11 - OpenAI,
The next evolution of the Agents SDK, 2026-04-15 - OpenAI API Changelog, 2026-05-06 / 2026-05-19
- OpenAI,
Work with Codex from anywhere, 2026-05-14 - OpenAI,
OpenAI Developers plugin for Codex, 2026-05-07 - OpenAI Codex Hooks / Remote Connections docs, 2026-05-23 열람 기준