Repo-readable 시스템
OpenAI와 Toss 관점에서 AGENTS.md, docs, observability, executable SSOT를 작업 환경으로 묶는 방법을 설명합니다.
핵심 요약
- 하네스의 첫 재료는 모델이 아니라 작업 환경이며, 핵심은 정보를 많이 넣기가 아니라 필요한 정보를 빠르게 찾고 실행·검증까지 잇는 것입니다.
- OpenAI 관점에서
AGENTS.md는 백과사전이 아니라 어디서 무엇을 읽고 어떤 검증 루프를 돌릴지 안내하는 짧은 TOC여야 합니다. - Toss 관점에서 문서만으로는 부족하고 command·skill·hook·workflow로 살아 있는 executable SSOT가 필요하며, Global·Domain·Local 세 레이어로 나눕니다.
- observability(브라우저·로그·메트릭·테스트 러너)는 "정말 됐는가"를 알려주는 작업 환경의 일부입니다.
- 2026년 SDK·Codex 업데이트로 repo-readable 시스템은 MCP·Skills·sandbox·hooks·Secure MCP Tunnel·plugins 같은 표준 runtime surface로 이동해, 문서 위치뿐 아니라 tool surface 설계까지 함께 해야 합니다.
하네스의 첫 번째 재료는 모델이 아니라 작업 환경입니다. OpenAI와 Toss가 입을 모아 강조하는 지점도 여기입니다.
리포가 하네스의 중심이 되는 이유
에이전트는 리포 안의 정보, 그리고 리포에서 이어진 도구 안에서 가장 안정적으로 일합니다. 그래서 작업 환경 설계의 핵심은 "모든 정보를 많이 넣기"가 아니라, 필요한 정보를 빠르게 찾아 실행과 검증까지 잇는 것입니다.
OpenAI식 관점: AGENTS는 백과사전이 아니라 TOC여야 한다
OpenAI 글에는 반복해서 나오는 메시지가 있습니다.
AGENTS.md는 거대한 지식 저장소가 아니라 짧은 진입점이어야 함- 자세한 내용은
docs/와 설계 문서로 내려보내야 함 - 문서 구조는 에이전트가 "탐색 가능한 정보 구조"로 느끼도록 설계해야 함
- 브라우저, 로그, 메트릭 접근까지 함께 연결되어야 실제 수정 속도가 빨라짐
좋은 AGENTS.md는 모든 답을 담는 파일이 아니라,
어디서 무엇을 읽고 어떤 검증 루프를 돌릴지 안내하는 문서입니다.
Toss식 관점: 문서만으로는 부족하고 실행 가능한 SSOT가 필요하다
Toss 글은 문서가 시간이 지나면 죽기 쉽다는 현실을 더 세게 짚습니다. 그래서 "좋은 위키"보다 좋은 workflow / plugin / command / template를 더 중요하게 봅니다.
핵심 포인트:
- 규칙이 문서에만 있으면 실제 실행과 분리되기 쉽다
- 팀의 기본 루틴이 command, skill, hook, workflow로 살아 있어야 한다
- 사람이 기억해야 하는 규칙을 줄이고 시스템이 강제해야 한다
- 개인의 프롬프트 감각보다 팀의 공통 실행 루틴이 생산성 저점을 끌어올린다
Global / Domain / Local 레이어
Toss 관점에서 하네스는 대체로 세 레이어로 나뉩니다.
| 레이어 | 포함할 것 | 예시 |
|---|---|---|
| Global | 전사 공통 기준 | 승인 정책, 보안 규칙, 코드 스타일, 필수 검증 명령 |
| Domain | 제품/서비스 고유 규칙 | 결제 정합성, 권한 정책, 모바일 QA, 고객데이터 처리 |
| Local | 현재 태스크 맥락 | 이슈 링크, 실험 목표, 브랜치 전략, 이번 변경 범위 |
하네스가 팀에 잘 안 먹는 이유 중 하나는 이 세 레이어가 한 파일에 섞이거나, 반대로 서로 전혀 연결되지 않아서입니다.
리포 안에 남아야 하는 최소 구조
아래는 하네스 친화적인 문서 구조의 한 예시입니다.
어떤 문서가 load-bearing인가
| 문서/산출물 | 역할 | 없을 때 생기는 문제 |
|---|---|---|
AGENTS.md | 진입점, 우선순위, 경로 안내 | 어디서부터 읽어야 할지 몰라 탐색 비용 증가 |
| 아키텍처 문서 | 구조와 책임 경계 설명 | 에이전트가 암묵적 구조를 추측함 |
| 불변식 문서 | 절대 깨면 안 되는 규칙 | "그럴듯하지만 위험한 변경"이 늘어남 |
| 릴리즈 게이트 | 완료 기준과 승인 조건 | self-evaluation이 과도하게 낙관적이 됨 |
| 런북 / updates | 운영과 변화 이력 | stale 규칙과 드리프트가 누적됨 |
boring tech와 invariants
OpenAI 글에서 특히 중요한 포인트는, 하네스가 화려한 프롬프트보다 boring tech와 architecture invariants를 더 사랑해야 한다는 것입니다.
이 말을 풀어 쓰면 보통 이렇습니다.
- 예외적인 cleverness보다 읽기 쉬운 폴더 구조
- 비법 프롬프트보다 명시적 release gate
- 암묵적 감각보다 ADR과 invariant 문서
- "알아서 해"보다 브라우저, 로그, 테스트에 대한 연결
observability도 작업 환경이다
문서만 정리해서는 부족합니다. 하네스는 에이전트가 결과를 확인하는 창까지 품어야 합니다.
| 도구 | 하네스 안에서의 의미 |
|---|---|
| 브라우저 | 실제 동작 확인 |
| 로그 | 실패 원인 추적 |
| 메트릭/트레이스 | 성능과 품질의 지속 관찰 |
| 테스트 러너 | 기계 판정 가능한 완료 기준 |
문서가 "무엇을 해야 하는가"를 알려준다면, observability는 "정말 됐는가"를 알려줍니다.
하네스 primitive가 표준 인프라로 내려오는 흐름
2026년 4~5월 OpenAI Agents SDK와 Codex 업데이트를 함께 보면, repo-readable 시스템은 단순한 문서 구조가 아니라 표준화된 agent runtime surface로 옮겨 가고 있습니다.
| primitive | 하네스 안에서의 역할 |
|---|---|
| MCP | 사내 시스템, SaaS, 데이터 소스, 브라우저/도구를 일관된 tool surface로 연결 |
| Skills | 큰 지침 묶음을 필요할 때만 발견하고 로드하는 progressive disclosure |
AGENTS.md | 프로젝트의 짧은 진입점과 작업 우선순위 |
shell / apply_patch | 실행과 파일 수정을 모델이 검증 가능한 방식으로 수행 |
| Sandbox / Manifest | 입력 파일, 출력 위치, 의존성, 실행 환경을 명시적으로 구성 |
| Hooks | prompt 검사, validation, logging, memory 생성 같은 lifecycle 작업 자동화 |
| Secure MCP Tunnel | private/on-prem MCP를 public internet에 노출하지 않고 연결 |
| Plugins | provider setup, API key 연결, troubleshooting, domain workflow를 설치 가능한 단위로 배포 |
실무에서 이 변화의 의미는 분명합니다. 팀 하네스를 만들 때 이제 "문서를 어디에 둘까"만 정해서는 부족합니다. 어떤 tool surface를 MCP로 열지, 어떤 skill을 lazy load할지, 어떤 작업을 sandbox 안에 가둘지, 어떤 hook으로 검증과 로깅을 자동화할지, 어떤 plugin을 팀 표준 setup으로 둘지까지 함께 설계해야 합니다.
바로 가져갈 수 있는 원칙
결론
좋은 하네스는 결국 "모델에게 똑똑하게 말하는 법"보다 리포와 도구를 똑똑하게 배치하는 법에 더 가깝습니다.