Repo-readable 시스템
OpenAI와 Toss 관점에서 AGENTS.md, docs, observability, executable SSOT를 작업 환경으로 묶는 방법을 설명합니다.
하네스의 첫 번째 재료는 모델이 아니라 작업 환경입니다. 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는 "정말 됐는가"를 알려줍니다.
바로 가져갈 수 있는 원칙
- 짧은
AGENTS.md를 루트 진입점으로 둘 것 - 자세한 내용은
docs/로 분리할 것 - 브라우저/로그/메트릭 접근을 하네스 일부로 볼 것
- stale 문서 정리를 정기 업무로 둘 것
- Global / Domain / Local 레이어를 분리할 것
- 문서만이 아니라 command / skill / workflow에 규칙을 내릴 것
- frictionless harness를 목표로 할 것
- 개인 요령을 executable SSOT로 전환할 것
결론
좋은 하네스는 결국 "모델에게 똑똑하게 말하는 법"보다, 리포와 도구를 똑똑하게 배치하는 법에 더 가깝습니다.