Claude Code로 대형 모노레포 작업할 때 동명 파일을 자꾸 엉뚱한 패키지에서 잡습니다
Next.js + NestJS 모노레포(패키지 12개, 약 8만 라인)를 Claude Code로 작업 중인데요. 특정 패키지 버그를 고쳐달라고 하면 다른 패키지의 동명(同名) 유틸 파일을 읽고 거기를 수정하려고 합니다.
예를 들어 packages/api/src/lib/format.ts를 고쳐야 하는데 packages/web/src/lib/format.ts를 잡는 식이에요.
시도해본 것:
- 절대 경로를 프롬프트에 명시 → 그래도 첫 탐색에서 grep으로 다른 걸 먼저 읽음
- 패키지 루트로
cd후 실행 → 조금 나아지지만 cross-package import 따라가다 또 헤맴
다들 모노레포에서 어떻게 컨텍스트를 좁히시나요? CLAUDE.md에 뭘 넣으면 좋을까요?
답변 3개
- 채택된 답변에디터 검증
핵심은 에이전트가 grep 돌리기 전에 경계를 박아주는 거예요. 두 개 같이 씁니다.
패키지별로 CLAUDE.md를 따로 두세요. 루트 하나만 두지 말고
packages/api/CLAUDE.md,packages/web/CLAUDE.md를 각각. Claude Code는 작업 중인 cwd 상위 경로의 CLAUDE.md를 누적해서 읽어서, 패키지 루트에서 돌리면 그 패키지 규칙이 우선 들어옵니다. 거기에 딱 한 줄 — "이 패키지의lib/format.ts는 web 쪽 것과 완전히 별개고 서로 import 안 함" — 박아두니 동명 파일 혼동이 확 줄더라고요.루트 CLAUDE.md엔 패키지 맵을 넣고요:
## Packages - packages/api — NestJS 백엔드. lib/는 서버 전용 - packages/web — Next.js. lib/는 클라이언트 전용 - packages/shared — 양쪽 공용 타입만. 로직 금지그리고 요청할 때 경로만 주지 말고 "먼저
packages/api안에서만 grep 해라"처럼 탐색 범위를 동사로 지시하세요. "이 파일 고쳐줘"보다 "이 디렉터리 밖은 보지 마"가 첫 grep 범위를 훨씬 강하게 잡아줍니다. 아마 절대경로만 주면 안 먹히는 게 첫 탐색이 여전히 레포 전체 대상이라 그런 거예요. 저는 그냥 cross-package import 자체를 lint로 막아버렸어요.
eslint-plugin-import의no-restricted-paths나 dependency-cruiser로 "web은 api 내부 lib 직접 import 금지" 룰 걸어두면, 에이전트가 엉뚱한 파일을 건드려도 검증 단계에서 lint가 터지고 스스로 되돌립니다. 사람이 매번 "거기 아니야" 하고 잡는 것보다 가드레일을 코드에 박아두는 게 결국 제일 안 깨지더라고요. 덤으로 사람이 짜는 코드도 경계 안 넘게 되고.위에 더해서 — 동명 파일 많은 레포면 그냥 처음부터 파일을 콕 집어서 Read시키는 게 토큰도 아끼고 정확해요.
@packages/api/src/lib/format.ts로 파일 레퍼런스 박아주면 탐색 단계 자체를 건너뛰고 바로 그 파일을 컨텍스트에 올립니다. "format 버그 고쳐줘"로 막 던지면 grep부터 시작해서 헤매는 거고.pnpm/turbo 워크스페이스면 검증 명령도 스코프 박으세요.
pnpm --filter api test처럼--filter걸어주면 에이전트가 테스트 돌릴 때도 그 패키지 안에만 머뭅니다. 안 그러면 전체 빌드 돌리다 다른 패키지 에러 보고 또 그쪽으로 끌려가요.