monorepo에서 에이전트 루트 고르기
monorepo 에이전트 작업에서 가장 흔한 실패는 모델이 아니라 루트(cwd)·워크스페이스 범위를 잘못 잡은 경우입니다. 에이전트는 “지금 어느 디렉터리가 작업 루트인가”를 기준으로 상대 경로·락파일·테스트·중첩 AGENTS.md를 읽습니다. 팁(레포 최상단)에서만 열면 형제 패키지를 건드리고, 패키지 안에서만 열면 워크스페이스 스크립트를 못 찾습니다.
인접 글과 축을 나눕니다. repo-map-inject는 지형 요약 파일을 무엇을·어떻게 주입할지이고, 이 글은 세션의 cwd / 에이전트 루트를 어디를 고를지입니다. 맵이 “어디를 읽을지”를 알려 줘도, 루트가 틀리면 명령·상대 경로가 깨집니다. 요금·플랜·제휴 링크는 없습니다. 근거는 pnpm Workspaces, npm workspaces, Cursor Rules / AGENTS.md입니다.
cwd는?
한 줄 답: 변경을 소유하는 패키지(또는 앱)를 기본 cwd로 두고, 크로스 패키지·루트 스크립트·워크스페이스 설치가 필요할 때만 레포 팁으로 올립니다. “항상 팁”도 “항상 패키지”도 아닙니다.
선택 표:
| 작업 | 권장 cwd | 이유 |
|---|---|---|
| 단일 패키지 버그·UI·유닛 테스트 | apps/web 또는 packages/api | 상대 import·로컬 package.json 스크립트가 맞음 |
pnpm --filter / turbo run / Nx target | 보통 레포 팁 | 워크스페이스 정의·파이프라인이 팁에 있음 |
| 락파일·루트 CI·공유 tsconfig | 레포 팁 | 루트 파일만 손댐 |
| firmware vs host처럼 완전 분리 트리 | 해당 트리 루트 | 호스트 lockfile로 firmware를 설치하지 않음 |
| 서브에이전트에 위임 | 브리프에 명시 cwd | 부모가 팁이어도 자식은 패키지일 수 있음 |
에이전트에게 고정할 문장 예:
Default cwd for this task: <path-from-repo-tip>
Repo tip is only for workspace installs, turbo/nx, and root CI.
Do not cd to sibling packages unless the ticket lists them.
Before running a command, state: cwd=<abs-or-repo-relative> · command=…에디터·CLI 팁:
- Cursor/VS Code에서 폴더를 패키지로 열기 vs 모노레포 팁으로 열기가 곧 에이전트 기본 루트입니다. 멀티루트 워크스페이스면 어느 폴더가 활성인지를 브리프에 적습니다.
- 셸 에이전트는
pwd를 세션 초반에 한 번 보고하게 합니다. 가정하지 않습니다. - 중첩
AGENTS.md/ Project Rules는 열린 루트 아래만 잘 보입니다. 팁에서 열면 패키지 로컬 규칙이 약해질 수 있고, 패키지만 열면 팁 규칙이 안 보입니다—필요 시@로 경로를 명시합니다(prompt-layers·repo-map-inject와 맞물림).
Session start checklist (agent):
1. pwd / workspace folders
2. Nearest package.json / Cargo.toml / pyproject.toml
3. Is there a workspace root above? (pnpm-workspace.yaml, etc.)
4. Which AGENTS.md applies? (nested vs tip)
5. Confirm allowlist packages before edits패키지 범위는?
한 줄 답: 만져도 되는 패키지 allowlist와 실행할 워크스페이스 명령(필터 포함) 을 브리프에 고정합니다. cwd와 범위는 다릅니다—팁에 있어도 packages/legacy는 금지일 수 있습니다.
범위 칸(복붙):
| 칸 | 예 | 금지 |
|---|---|---|
| Touch | packages/api/**, apps/web/src/api/** | “관련 있어 보이는 곳 전부” |
| Do not touch | packages/legacy/**, firmware/** | 침묵 |
| Commands | pnpm --filter api test (cwd=팁) | 필터 없이 루트 test만 |
| Install | 팁에서 pnpm install 한 번 | 패키지 안에서 새 lockfile 생성 |
| Shared types | packages/types가 allowlist에 있을 때만 | 몰래 공유 패키지 API 변경 |
워크스페이스 명령과 cwd 조합:
# cwd = repo tip (typical)
pnpm --filter @acme/api test
pnpm --filter web build
npx turbo run test --filter=api
# cwd = packages/api (local scripts only)
pnpm test # uses this package.json
# Avoid: npm install here if the repo is pnpm-workspace at tip지시 문장 예:
Package scope for this task:
- Touch: packages/api/**
- Do not touch: apps/**, packages/legacy/**, firmware/**
- Run tests: from repo tip → pnpm --filter @acme/api test
- If you need another package, stop and ask (or open a follow-up)
- Never invent a package name that is not on disk / not in the workspace listrepo-map-inject와의 한 줄: 맵의 Layout·Boundaries는 지형 합의이고, 이 절의 allowlist는 이번 세션의 실행 범위입니다. 맵을 읽었다고 cwd·필터가 자동으로 맞지는 않습니다.
잘못된 루트 증상은?
한 줄 답: 증상이 보이면 모델을 바꾸기 전에 cwd·워크스페이스·필터를 먼저 검증합니다. 잘못된 루트는 “똑똑한 환각”처럼 보이지만 대부분 경로·락파일·스크립트 컨텍스트 문제입니다.
증상 → 원인 → 조치:
| 증상 | 흔한 원인 | 조치 |
|---|---|---|
command not found / 스크립트 없음 | 패키지 cwd에서 팁 전용 스크립트 실행 | 팁으로 cd 후 --filter |
새 package-lock.json이 패키지 안에 생김 | npm을 패키지 cwd에서 실행 | 삭제·gitignore 확인, 팁에서 pnpm/yarn 사용 |
| 테스트는 초록인데 버그 그대로 | 다른 패키지 테스트만 실행 | allowlist 패키지 필터로 재실행 |
| import/경로 환각 | 팁 트리 전체를 한 앱으로 착각 | cwd를 소유 패키지로, 맵·트리 재확인 |
잘못된 AGENTS.md 규칙 | 연 루트와 중첩 문서 불일치 | 적용 규칙 경로를 브리프에 명시 |
| 형제 패키지 대규모 diff | 범위 미고정 + 팁 cwd | Do not touch + path allowlist |
| CI만 실패 | 로컬 cwd ≠ CI working-directory | CI와 동일한 cwd/필터를 Test plan에 기입 |
복구 루프(에이전트·사람 공통):
1. Print pwd and workspace root candidates
2. Show nearest package manifest vs workspace definition at tip
3. Re-state Touch / Do not touch
4. Re-run the one command CI uses (same cwd + filter)
5. If still wrong: stop editing; fix root before more patches운영 팁:
- PR Test plan에 cwd + 명령을 같이 적습니다(agent-pr-body와 맞물림).
- 서브에이전트 브리프에 루트를 안 쓰면 부모가 팁이어도 자식이 임의로
cd합니다(subagent-brief). - “레포 맵은 맞는데 빌드만 실패”면 맵이 아니라 루트/필터를 의심합니다—그게 이 글의 축입니다.
한 줄 정리: 소유 패키지를 기본 cwd로, 워크스페이스 명령은 팁+필터, allowlist로 범위 고정, 이상 증상이면 모델보다 루트부터 고칩니다. repo-map-inject는 맵 주입 축입니다.
FAQ
항상 모노레포 팁에서 에이전트를 열면 안 되나요?
됩니다—팀이 팁 전용 규칙·필터 습관이 강하면요. 다만 단일 패키지 작업이 많으면 팁 cwd는 형제 패키지 탐색·잘못된 스크립트 호출 비용을 키웁니다. 기본은 소유 패키지, 예외가 팁입니다.
repo-map-inject 글과 무엇이 다른가요?
그 글은 REPO_MAP 같은 지형 파일의 내용·주입·갱신입니다. 이 글은 세션 cwd·워크스페이스 루트·패키지 allowlist·잘못된 루트 증상입니다. 맵을 주입해도 cwd가 틀리면 명령이 깨집니다.
pnpm·turbo·Nx 중 무엇을 기준으로 하나요?
도구 이름은 팀 표준을 따릅니다. 공통 규칙은 같습니다: 워크스페이스 정의가 있는 곳(대개 팁)에서 필터 실행, 패키지 로컬 스크립트는 그 패키지 cwd, 락파일 도구를 섞지 않기.
멀티루트 워크스페이스면?
브리프에 workspace folders: …와 이번 태스크의 primary folder를 적습니다. 에이전트에게 “첫 번째 폴더가 루트”라고 가정시키지 않습니다.
출처 (Sources)
- pnpm Workspaces — 워크스페이스·filter·팁 설치
- npm workspaces — workspaces 정의·실행 위치
- Cursor Docs — Rules / AGENTS.md — 중첩 프로젝트 지침
- 인접: repo-map-inject(지형 맵 주입), prompt-layers(규칙 계층), subagent-brief(위임 시 cwd 명시), agent-pr-body(Test plan에 cwd·명령)