5장. 저장소를 작업 환경으로 만든다
다음은 여러 현장에서 반복된 패턴을 합친 합성 사례로, 등장하는 숫자는 설명을 위한 예시 수치다.
새 팀원이 저장소에 합류하면 동료에게 묻는다. 어디서 시작하는지, 어떤 명령이 믿을 만한지, 이 디렉터리를 왜 건드리면 안 되는지, 실패한 테스트가 원래 불안정한지. 에이전트도 같은 정보가 필요하다. 차이는 옆자리 동료에게 물을 수 없고, 실행할 때마다 같은 암묵지를 다시 잃는다는 점이다.
에이전트가 코드를 잘 읽는다는 사실은 저장소를 잘 이해한다는 뜻이 아니다. 파일이 많고 문서가 오래됐으며 규칙이 CI와 사람의 기억에 흩어져 있으면, 더 넓게 읽을수록 서로 충돌하는 문맥을 만난다.
이번 장의 약속
- 저장소의 ‘가독성’을 사람과 에이전트가 함께 쓰는 운영 속성으로 다룬다.
- 루트 안내서와 지역 안내서를 계층적으로 배치한다.
- 신뢰할 명령, 변경 경계, 아키텍처 지도를 실행 가능하게 만든다.
- 오래된 문서를 발견하고 폐기하는 검사를 추가한다.
저장소는 데이터가 아니라 환경이다
전통적인 저장소는 소스 코드와 변경 이력을 보관한다. 에이전트 작업 환경으로 쓰려면 최소한 다섯 질문에 답해야 한다.
- 방향: 이 제품은 무엇이고 현재 중요한 목표는 무엇인가?
- 지도: 기능과 책임은 어느 디렉터리·모듈에 있는가?
- 행동 규칙: 무엇을 읽고, 무엇을 수정하며, 어떤 명령을 실행하는가?
- 판정 기준: 변경이 맞다는 증거는 무엇인가?
- 기억: 왜 이렇게 설계했고 최근 어떤 결정이 바뀌었는가?
README 하나에 모든 것을 넣으면 길어서 읽히지 않고 변경 주기가 다른 정보가 섞인다. 반대로 문서를 너무 잘게 쪼개면 탐색 비용이 늘고 어떤 것이 공식인지 모호해진다. 해결책은 짧은 입구와 연결된 깊이다.
AGENTS.md 1~2분 안에 읽는 작업 입구
docs/repository-map.md 책임과 경계 지도
docs/architecture/ 오래가는 구조와 결정
specs/ 작업별 제품 의도
scripts/ 복잡한 명령의 실행 가능한 이름
policy/ 기계가 강제하는 변경·보안 규칙
그림 5-1. 루트 안내서에 모든 내용을 복제하지 않는다. 짧은 공식 입구에서 필요한 깊이로 이동한다.
파일 이름은 도구마다 다를 수 있다. 중요한 것은 공식 입구가 하나이고, 세부 정보가 링크로 연결되며, 규칙이 가능한 한 실행되는 검사로 뒷받침되는 것이다.
루트 안내서에는 행동만 둔다
좋은 루트 AGENTS.md는 백과사전이 아닙니다. 첫 작업을 안전하게 시작하고 더 깊은 문서를 찾게 하는 표지판입니다. 다음은 현장 저장소에 적용할 설계 예시이며 03-labs의 실제 파일 목록을 가장한 화면이 아닙니다.
# Repository work guide
## Purpose
주문 생성·조회·취소를 제공하는 학습용 서비스다.
## Start here
- 제품 용어: `docs/domain-glossary.md`
- 구조 지도: `docs/repository-map.md`
- 활성 명세: `specs/README.md`
## Trusted commands
- 전체 확인: `npm test`
- 구조 검사: `npm run test:architecture`
- 출간 골든 경로: `npm run verify`
## Change boundaries
- `src/orders/` 변경 시 `test/orders/`를 함께 검토한다.
- `factory/policy.json`과 `.github/`는 승인 없이 수정하지 않는다.
- 생성물 `.factory/`를 제품 커밋에 포함하지 않는다.
## Definition of done
관련 명세의 수용 기준과 모든 필수 게이트를 통과하고,
변경 이유·남은 위험·실행 증거를 인계 문서에 남긴다.
모델에게 “항상 최선을 다하라”는 추상 지시보다 npm test처럼 관찰 가능한 행동을 준다. 규칙의 이유를 한 문장 덧붙이면 예외 상황에서 잘못 일반화하는 위험도 줄어든다.
지역 안내서는 가까운 규칙을 덮어쓴다
모노레포나 여러 도메인이 있는 저장소에서는 하위 디렉터리에 지역 안내서를 둔다.
AGENTS.md
packages/
├── payments/
│ └── AGENTS.md
└── analytics/
└── AGENTS.md
루트 규칙은 전체 기본값이고 지역 규칙은 해당 경로의 추가 제약이다. 충돌 시 더 구체적인 규칙이 우선하되, 보안·승인 같은 전역 금지는 하위 파일이 완화하지 못하게 한다.
지역 안내서에 적합한 정보는 다음과 같다.
- 해당 모듈의 책임과 외부 계약
- 로컬 테스트·생성 명령
- 데이터 마이그레이션 절차
- 수정하면 함께 갱신할 파일
- 모듈 고유의 금지 의존성
회사 역사와 공통 코딩 스타일처럼 전역 정보는 중복하지 않는다. 중복 문서는 한쪽만 갱신되는 순간 상충하는 지시가 된다.
저장소 지도를 코드 구조와 맞춘다
파일 트리를 그대로 나열하는 것은 지도가 아니다. 책임, 데이터 흐름, 변경 이유를 연결한다.
| 경로 | 책임 | 공개 경계 | 대표 검사 |
|---|---|---|---|
| `src/orders/domain/` | 주문 규칙·상태 전이 | 순수 함수 | 단위 검사 |
| `src/orders/api/` | HTTP 입력·출력 | OpenAPI 계약 | 계약 테스트 |
| `src/orders/store/` | 영속화 어댑터 | repository interface | 통합 테스트 |
| `factory/` | 작업 실행·게이트 | task schema | harness tests |
그리고 핵심 의존 방향을 적는다.
api ──> application ──> domain
store ────────────────> domain ports
domain ─X─> api/store/factory
─X─>는 금지 의존성이다. 이 규칙이 중요하다면 문서에서 끝내지 않고 11장에서 구조 테스트로 옮긴다.
신뢰할 명령은 하나의 이름을 가진다
문서에 긴 셸 명령을 복사하면 운영체제와 옵션 차이로 금방 낡는다. 복잡성은 package.json 스크립트나 scripts/ 아래의 버전 관리되는 실행기로 감싼다.
설계 예(실행용 아님) — 원본: 이 장의 신뢰 명령 설명; 명령: 없음.
{
"scripts": {
"test:architecture": "node scripts/test-architecture.mjs",
"test": "node scripts/test.mjs",
"verify": "node scripts/verify.mjs"
}
}
문서에는 npm test만 적고 실제 검사 구성이 바뀌면 스크립트 내부를 갱신한다. 에이전트, 개발자, CI가 같은 진입점을 사용해야 “로컬에서는 됐다”는 차이를 줄일 수 있다.
명령은 다음 속성을 가져야 한다.
- 저장소 루트에서 실행 가능하다.
- 성공은 종료 코드 0, 실패는 0이 아닌 값으로 표현한다.
- 실패 메시지에 원인, 대상, 다음 확인 위치가 있다.
- 대화형 입력을 요구하지 않는다.
- 가능한 한 같은 입력에 같은 결과를 낸다.
- 생성 파일과 네트워크 사용을 문서화한다.
코드가 설명하는 것과 문서가 설명하는 것
코드에서 바로 확인할 수 있는 상세 구현을 문서에 복제하지 않는다. 문서는 코드만 읽어서는 알기 어려운 의도와 경계를 담당한다.
| 코드에 둘 것 | 문서에 둘 것 |
|---|---|
| 함수 입력·출력 | 왜 이 경계를 선택했는가 |
| 현재 제어 흐름 | 금지된 대안과 그 이유 |
| 타입과 스키마 | 도메인 용어의 제품 의미 |
| 실행되는 규칙 | 예외 승인과 운영 절차 |
| 테스트의 구체 예 | 어떤 위험을 이 테스트가 대표하는가 |
좋은 문서는 코드를 요약하지 않고 다음 결정을 줄인다.
실습: 저장소 입구를 10분 테스트한다
예제 저장소를 처음 보는 동료나 새 세션의 에이전트에게 다음 과제를 준다.
“주문 총액 계산 규칙을 바꾸려면 어디를 읽고,
어떤 파일을 수정하며, 어떤 검사를 실행해야 하는지 찾아라.
코드는 바꾸지 말고 근거 경로를 적어라.”
10분 안에 다음 답을 찾는지 본다.
- 공식 제품 명세
- 도메인 코드와 테스트 경로
- 금지된 변경 경계
- 빠른 검사와 전체 검사 명령
- 관련 아키텍처 결정
찾지 못한 항목을 프롬프트에 추가하지 말고 저장소 입구를 고친다. 한 세션만 아는 정보보다 다음 사람과 다음 에이전트도 읽을 수 있는 정보가 더 큰 자산이다.
문서 신선도를 검사한다
문서는 존재하는 것보다 맞는 것이 중요하다. 다음 검사를 자동화한다.
링크와 경로
AGENTS.md와 저장소 지도에 적힌 로컬 경로가 실제로 존재하는지 검사한다. 이름이 바뀌면 CI에서 즉시 실패해야 한다.
명령
문서의 ‘신뢰할 명령’을 깨끗한 환경에서 실행한다. 최소한 --help나 빠른 검사 경로가 동작하는지 확인한다.
소유자와 검토일
가격이나 제품 기능처럼 빨리 낡는 문서에는 소유자와 다음 검토일을 둔다. 오래가는 아키텍처 원리는 변경 이벤트 기반으로 검토한다. 모든 문서에 임의의 만료일을 붙여 알람 소음을 만들지는 않는다.
설계 예(실행용 아님) — 원본: 이 장의 문서 신선도 설명; 명령: 없음.
owner: platform-devex
last_verified: 2026-07-17
verify_on:
- package-script-change
- directory-move
모순 탐지
같은 명령이나 금지 규칙이 여러 파일에 반복되면 검색 검사로 경고한다. 해결은 문구를 맞추는 것이 아니라 공식 정의 하나를 두고 링크하는 것이다.
저장소를 위한 최소 지식 예산
에이전트에게 저장소 전체를 매번 읽히는 것은 느리고 불필요한 정보가 많다. 입구 문서는 세 층으로 공개한다.
L0 작업 계약: 지금 해야 할 목표·명세·경계
L1 작업 안내: 공통 명령·지도·완료 정의
L2 필요시 참조: 상세 결정·운영 절차·과거 기록
기본 문맥은 L0와 짧은 L1이다. 에이전트가 특정 모듈을 건드릴 때 해당 지역 안내서와 관련 L2를 검색한다. ‘모든 것을 먼저 주기’와 ‘아무것도 주지 않고 알아서 찾게 하기’ 사이의 균형이다.
왜 실패하는가
지시 파일이 너무 길다
스타일, 역사, 모든 도메인 규칙을 한 파일에 넣으면 중요한 금지가 묻힌다. 작업 시작에 필요한 행동만 두고 세부 문서로 연결한다.
프롬프트와 CI 규칙이 다르다
에이전트 지시는 npm test를 말하지만 CI는 다른 숨은 명령을 실행하면 피드백이 늦어집니다. 사람·에이전트·CI의 공식 진입점을 통합합니다.
낡은 문서를 더 신뢰한다
자신 있게 쓰인 오래된 문서는 문서가 없는 것보다 위험하다. 경로·명령 검사를 자동화하고, 확인되지 않은 설명에는 상태를 표시한다.
모든 예외를 문서로 해결한다
반복되는 금지 의존성과 경로 제약은 사람이 읽는 문서가 아니라 검사로 승격한다. 문서는 이유와 해결 방향을 설명한다.
운영 판단: 문서가 준비되었다는 기준
- 처음 온 개발자가 도움 없이 빌드와 전체 검사를 실행한다.
- 작업 계약에서 관련 명세와 지역 안내서까지 경로가 이어진다.
- 아키텍처 지도에 책임·공개 경계·대표 검사가 있다.
- 금지 규칙 중 반복 가능한 항목은 자동 검사로 연결된다.
- 문서의 경로와 신뢰 명령이 CI에서 검증된다.
- 가장 중요한 규칙을 찾는 데 긴 문서 검색이 필요하지 않다.
연습문제
- 현재 저장소의 루트 README에서 작업 입구에 필요한 내용과 제품 소개 내용을 분리하라.
- 한 모듈의 책임·공개 경계·금지 의존성·대표 테스트를 네 줄로 적어라.
- 여러 문서에 중복된 명령 하나를 공식 스크립트로 통합하라.
- 새 팀원에게 10분 탐색 테스트를 실행하고 막힌 지점을 저장소 개선 이슈로 바꿔라.
체크포인트
- 2분 안에 읽을 수 있는 루트 작업 안내서가 있다.
- 저장소 지도에서 책임과 의존 방향을 찾을 수 있다.
- 사람·에이전트·CI가 같은 검사 명령을 사용한다.
- 문서의 경로·명령·중요 규칙이 자동으로 검증된다.
다음 장에서는 ‘무엇을 만들 것인가’를 실행 가능한 명세로 바꾼다. 좋은 저장소 지도가 있어도 도착 상태가 모호하면 에이전트는 정확한 방향으로 움직일 수 없다.