리포지터리를 작업 환경으로 설계하기
짧은 AGENTS.md, 문서 계층, executable SSOT와 observability
좋은 리포는 모든 정보를 한 번에 주지 않습니다. 짧은 진입점 → 상세 문서 → 실행 명령 → 검증 신호로 이어지는 탐색 경로를 제공합니다. 문서가 실제 행동과 분리되지 않도록 규칙을 스킬·명령·훅·검사로 내리는 것이 핵심입니다.
| 레이어 | 담을 내용 | 대표 산출물 |
|---|---|---|
| Global | 보안·코드 스타일·공통 게이트 | 루트 AGENTS.md, 전역 검사 |
| Domain | 결제·데이터·UI 같은 고유 불변식 | 도메인 규칙, ADR, 전용 스킬 |
| Local | 현재 목표·범위·브랜치 맥락 | 이슈, 실행 계획, 임시 판단 기록 |
| Observability | 결과가 실제로 맞는지 확인할 창 | 테스트, 브라우저, 로그, 메트릭 |
- 짧은 진입점 작성필수 명령과 상세 문서 위치만 선명하게 둡니다.
- 불변식 외부화암묵적 설계와 금지 패턴을 ADR·규칙 문서로 옮깁니다.
- 실행 표면 연결반복 규칙을 스킬·명령·훅·검사로 자동화합니다.
- 확인 창 제공브라우저·로그·테스트가 같은 완료 기준을 증명하게 합니다.