# 리포지터리를 작업 환경으로 설계하기

> 짧은 AGENTS.md, 문서 계층, executable SSOT와 observability

- Canonical: https://learning.reopt.ai/en/courses/harness-engineering/lessons/he-m2-concept
- Language: en
- HTML: https://learning.reopt.ai/en/courses/harness-engineering/lessons/he-m2-concept

---

[Harness engineering](/en/courses/harness-engineering) 2. Repo-readable 시스템 3 / 9

# 리포지터리를 작업 환경으로 설계하기

짧은 AGENTS.md, 문서 계층, executable SSOT와 observability
Concept 45 XP 9 min

좋은 리포는 모든 정보를 한 번에 주지 않습니다. 짧은 진입점 → 상세 문서 → 실행 명령 → 검증 신호 로 이어지는 탐색 경로를 제공합니다. 문서가 실제 행동과 분리되지 않도록 규칙을 스킬·명령·훅·검사로 내리는 것이 핵심입니다.
AGENTS.md는 백과사전이 아니라 TOC 루트 진입 문서는 우선순위와 경로를 안내하고, 상세 규칙은 docs와 도메인 문서에 둡니다. 반드시 지켜야 할 규칙은 실행 가능한 검사로 연결합니다.

| 레이어 | 담을 내용 | 대표 산출물 |
| Global | 보안·코드 스타일·공통 게이트 | 루트 AGENTS.md, 전역 검사 |
| Domain | 결제·데이터·UI 같은 고유 불변식 | 도메인 규칙, ADR, 전용 스킬 |
| Local | 현재 목표·범위·브랜치 맥락 | 이슈, 실행 계획, 임시 판단 기록 |
| Observability | 결과가 실제로 맞는지 확인할 창 | 테스트, 브라우저, 로그, 메트릭 |

- 1 짧은 진입점 작성 필수 명령과 상세 문서 위치만 선명하게 둡니다.

- 2 불변식 외부화 암묵적 설계와 금지 패턴을 ADR·규칙 문서로 옮깁니다.

- 3 실행 표면 연결 반복 규칙을 스킬·명령·훅·검사로 자동화합니다.

- 4 확인 창 제공 브라우저·로그·테스트가 같은 완료 기준을 증명하게 합니다.

실무에 남길 기준

- 정보량보다 필요한 정보를 찾는 비용이 낮아야 한다
- 문서에만 있는 규칙은 드리프트하므로 실행 가능한 SSOT로 내려야 한다
- 관측성은 운영 부가기능이 아니라 에이전트의 작업 환경이다

[Previous](/en/courses/harness-engineering/lessons/he-m1-quiz) Got it · Continue

---

Site guide for agents: https://learning.reopt.ai/llms.txt · Sitemap: https://learning.reopt.ai/sitemap.xml · Contact: https://learning.reopt.ai/contact