사례: OpenAI

OpenAI 사례의 핵심은 간단합니다. 에이전트가 일하는 장소는 프롬프트 창이 아니라 리포지터리 전체라는 점입니다.

이 관점이 중요한 이유는, 긴 작업의 품질이 모델 파라미터보다 리포가 얼마나 agent-readable한지에 크게 좌우되기 때문입니다.

해결하려는 문제

• 큰 리포에서 에이전트가 어디서부터 읽어야 할지 모름
• 필요한 아키텍처 규칙이 여러 문서에 흩어져 있음
• 코드는 맞아 보여도 실제 UI나 런타임은 다르게 동작함
• 오래된 문서가 쌓이며 잘못된 컨텍스트를 계속 주입함

기술적 메커니즘

이 구조에서 하네스가 하는 일은 세 가지입니다.

1. 탐색 순서 강제: 먼저 읽을 파일과 문서를 지정합니다.
2. 실행 관찰 연결: 브라우저, 로그, 메트릭을 바로 열 수 있게 합니다.
3. 엔트로피 관리: stale 문서를 정리해 다음 작업의 입력 품질을 유지합니다.

왜 이게 엔지니어링인가

OpenAI 방식은 에이전트의 "탐색 비용"을 리포 구조 문제로 다룹니다.

즉, 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 review

docs/
├── architecture.md
├── invariants.md
├── runbooks.md
└── glossary.md

이 구조가 중요한 이유는 문서가 많아서가 아닙니다. 어디서 시작하고 무엇을 믿어야 하는지를 고정하기 때문입니다.

observability를 하네스에 넣는 이유

OpenAI 관점에서 브라우저, 로그, 메트릭은 "개발 이후 운영"이 아니라 에이전트 작업 자체의 일부입니다.

예를 들어 UI 변경을 생각해보면:

1. builder가 코드를 수정합니다.
2. 브라우저로 상태 전환을 확인합니다.
3. 로그에서 에러를 봅니다.
4. 필요하면 메트릭으로 실제 영향 범위를 봅니다.

이 과정을 하네스에 넣지 않으면, 검증은 항상 사람의 암묵지나 사후 발견에 의존하게 됩니다.

실제로 훔칠 것

그대로 복제하면 안 되는 점

• 문서를 많이 쓰는 것이 agent-readable을 보장하지 않습니다.
• 문서가 길면 오히려 시작 비용만 커집니다.
• observability 접근이 있어도 읽는 절차가 없으면 무용지물입니다.

우리 팀으로 번역하면

OpenAI 사례를 실무에 옮길 때의 질문은 이렇습니다.

1. 에이전트가 첫 3분 안에 읽어야 할 문서는 무엇인가
2. 브라우저/로그/테스트 중 어떤 것을 기본 검증으로 강제할 것인가
3. stale 문서를 누가 언제 지울 것인가

이 세 질문에 답하면, 하네스가 추상론에서 리포 구조 설계로 내려옵니다.

참고

• OpenAI, Harness Engineering, 2026-02-11