레포 맵을 에이전트에 주입하려면

에이전트가 첫 몇 턴을 디렉터리 탐색·잘못된 패키지 추정에 쓰는 경우가 많습니다. repo map은 채팅 백업이 아니라, 패키지·엔트리포인트·소유 경계·건드리지 말 곳을 짧게 고정해 두고 세션 시작 시 주입하는 지형도입니다. Cursor의 Instant Grep이나 Explore 서브에이전트는 심볼·문자열을 찾는 도구이고, 맵은 어디부터 읽을지를 사람이(또는 생성 스크립트가) 합의한 요약입니다.

이 글은 **어떤 파일을? · 자동 생성은? · 낡은 맵은?**만 다룹니다. 시스템·유저·프로젝트 규칙 계층·충돌 우선순위는 prompt-layers 축입니다. 맵을 Always Rule에 소설처럼 넣지 말고, 짧은 맵 파일 + 주입 경로로 둡니다. 요금·플랜·토큰 숫자는 없습니다.

어떤 파일을?

한 줄 답: 루트에 짧은 맵 파일 하나(예: docs/REPO_MAP.md, .agent/repo-map.md)를 두고, AGENTS.md나 Project Rule에는 “작업 전 이 경로를 읽어라” 한 줄만 둡니다. 전체 tree 덤프·시크릿·생성물 목록은 넣지 않습니다.

넣을 것 / 빼 둘 것:

넣을 것빼 둘 것
패키지·앱 경계 (apps/, packages/, firmware vs host)node_modules/, build/, .git/ 전체 나열
엔트리포인트·빌드/테스트 한 줄 명령README·설계 문서 전문 복붙
“여기서 고쳐라 / 여기 손대지 마라” 경계.env 값, 토큰, 내부 URL 시크릿
소유·온콜·관련 티켓 접두어(짧게)매 파일 해시·라인 수
생성일·커밋/브랜치 스탬프이미 삭제한 경로를 “현재”로 표기

최소 스키마(복붙용):

# Repo map — <repo-slug>
Updated: <ISO date> · tip: <short sha or branch>

## Layout
- `apps/web` — Next UI; entry `apps/web/src/app`
- `packages/api` — HTTP; entry `packages/api/src/main.ts`
- `firmware/` — device; do not edit from host PRs

## Commands (cwd = repo root)
- web test: `pnpm --filter web test`
- api test: `pnpm --filter api test`

## Boundaries
- Touch: `packages/api/src/**` for API changes
- Do not touch: `firmware/**` unless ticket says so
- Secrets: never paste; names/paths only

## Inject
- Agent: read this file first (or `@docs/REPO_MAP.md`)
- Not a substitute for Instant Grep / Explore on symbols

주입 방법(팀에서 하나를 고릅니다):

  1. 채팅 @docs/REPO_MAP.md — 이번 작업만, 맵이 길거나 자주 바뀔 때
  2. AGENTS.md에 “먼저 읽어라” 한 줄 — 레포 기본; prompt-layers의 Project 행과 맞물림
  3. Intelligent/globs Rule — apps/** 작업 시에만 맵을 붙일 때(Always에 전문을 넣지 않음)
  4. 서브에이전트 브리프에 경로만 — 부모는 맵 전문을 붙이지 않고 경로를 넘김(subagent-brief)

prompt-layers와의 한 줄 경계: 그 글은 규칙이 어디에 사느냐(Team/Project/User/턴) 이고, 이 절은 코드베이스 지형 요약 파일을 무엇으로·어떻게 주입하느냐입니다. 맵은 규칙이 아니라 컨텍스트 아티팩트입니다.

자동 생성은?

한 줄 답: 스크립트로 초안 → 사람이 경계·명령을 검수 → CI/훅에서 구조 변경 시에만 재생성합니다. find/tree 출력을 Always Rule에 그대로 넣는 것은 금지에 가깝습니다.

실무 파이프:

  1. 초안 생성 — 깊이 제한 tree, 또는 package.json workspaces / CMake targets / Yocto layers 목록만 추출
  2. 사람이 쓰는 절 — Boundaries · Commands · Do not touch(자동이 못 함)
  3. 스탬프 — Updated + tip SHA; PR 설명에 “맵 갱신” 한 줄
  4. 검색 도구와 역할 분리 — Instant Grep은 심볼·정규식 검색, Explore 서브에이전트는 광역 탐색 요약을 메인 컨텍스트 밖에 둡니다. 맵은 그 전에 어디를 볼지를 줄입니다. 맵이 Instant Grep 인덱스를 대체하지 않습니다.

생성 스크립트 스케치(개념):

# draft only — review before commit
{
  echo "# Repo map (DRAFT)"
  echo "Updated: $(date -Iseconds) · tip: $(git rev-parse --short HEAD)"
  echo
  echo "## Layout (depth 3, generated)"
  # prefer: workspace package names, not every file
  find apps packages -maxdepth 2 -type d 2>/dev/null | sort
} > docs/REPO_MAP.draft.md
# copy Boundaries/Commands from previous map by hand

자동만으로 끝내면 삭제된 패키지·옮긴 엔트리·금지 경로가 남습니다. 초안은 draft, 머지 전 Boundaries 검수가 필수입니다.

낡은 맵은?

한 줄 답: 낡은 맵은 없는 것보다 해롭습니다. 구조 변경 PR에 맵을 같이 고치고, 에이전트에게 맵과 트리가 어긋나면 트리를 이기고 맵을 고치라고 적습니다.

낡은 신호:

  • tip SHA가 수 주 전이고 apps/가 쪼개졌는데 맵은 모노리스
  • “진입점 src/index.ts”인데 실제는 src/main.ts
  • 삭제한 packages/legacy가 여전히 Touch 목록
  • Always Rule에 맵 전문이 박혀 있어 길이와 충돌(prompt-layers의 “너무 길면”)

갱신·폐기 규칙:

이벤트할 일
패키지 추가·이동·삭제Layout + Boundaries 동시 수정
빌드/테스트 명령 변경Commands만 패치
대규모 리네임맵 재생성 + 사람 검수
맵이 200줄을 넘김루트 요약 + 패키지별 짧은 맵으로 분할
확실하지 않음주입 중단, Explore/Grep으로 확인 후 맵 수정

에이전트용 한 줄(맵 파일 또는 AGENTS.md):

If REPO_MAP.md disagrees with the tree, trust the tree.
Update the map (or open a follow-up) before large edits.
Do not invent packages that are not on disk.

검증 체크리스트(세션 시작·구조 PR):

[ ] Updated / tip이 최근 구조 변경 이후인가?
[ ] Layout 경로가 디스크에 존재하는가?
[ ] Commands가 루트 cwd에서 동작하는가?
[ ] Do not touch가 아직 유효한가?
[ ] 시크릿·.env 본문이 없는가?
[ ] Always Rule에 맵 전문을 복붙하지 않았는가? (경로는 OK)

FAQ

prompt-layers 글과 무엇이 다른가요?

그 글은 Team / Project / User / 턴 규칙 계층과 충돌 시 우선순위입니다. 이 글은 레포 지형 요약(repo map) 파일과 주입·생성·폐기입니다. AGENTS.md에 “맵을 읽어라”는 prompt-layers의 Project 배치이고, 맵 본문 설계는 이 축입니다.

Instant Grep·Explore만으로 충분하지 않나요?

검색·광역 탐색은 강력합니다. 다만 금지 경계·엔트리·팀 합의 명령은 grep이 모릅니다. 맵은 출발점, Grep/Explore는 심볼·근거 확보입니다. 둘을 같이 씁니다.

맵을 git에 커밋해야 하나요?

레이아웃·명령·경계가 팀 공유면 docs/REPO_MAP.md로 커밋합니다. 개인 실험용 초안만이면 .agent/ + gitignore도 가능합니다. 시크릿이 들어가지 않았는지 커밋 전에 확인합니다.

맵이 길어서 컨텍스트를 잡아먹으면?

루트는 Layout·Boundaries·Commands만, 세부 도메인은 패키지 옆 짧은 맵 또는 @로만 붙입니다. Always에 전문을 넣지 않습니다.

출처 (Sources)