Monorepo의 지침 경계

내용 검토: 2026. 09. 23.

결론부터

하위 AGENTS.md는 규칙이 실제로 갈라지는 경계에만 두고, 상위를 복사하지 않고 그 범위의 차이만 적는다

여러 앱의 검사 명령이나 의존 규칙이 달라졌을 때 읽는 심화다. 단일 프로젝트는 루트 AGENTS.md 하나로 충분하다. 질문은 폴더가 많을 때 어느 경계에 지침을 추가하는가다.

이 장에서 처음 나오는 말1개

Monorepo: 여러 앱이나 package를 한 저장소에서 관리하는 구성. 지침도 실제 작업 경계에 맞춰 나눌 필요가 생긴다.

경계는 폴더 수가 아니라 규칙의 차이다

my-workspace/
  AGENTS.md              # 공통 규칙. 하위 지침이 있으면 수정 전에 읽으라는 조건 포함
  docs/verification.md   # 공통 검증
  apps/web/
    AGENTS.md            # web에서만 다른 명령·제약
  apps/api/
    AGENTS.md            # api에서만 다른 명령·제약

apps/web/src/components가 web 전체와 같은 규칙이면 거기에는 파일을 두지 않는다. 명령·의존 방향·검증 방식이 달라지는 곳만 경계다.

하위 파일은 차이만 적는다

루트에 “모든 package는 Jest”, web에 “Vitest”라고 쓰면 충돌한다. 루트에는 “package별 명령은 가까운 AGENTS.md를 따른다”고 쓰고 하위에 정확한 명령을 둔다.

# web

- 이 지침은 apps/web/에 적용한다.
- 공유 UI는 packages/ui의 기존 컴포넌트를 먼저 확인한다.
- src/server 모듈을 브라우저 코드에서 import하지 않는다.
- 동작 변경은 pnpm --filter web test로 검증한다.

두 도구 모두 작업 디렉터리 아래의 지침은 시작 때 읽지 않으므로(로딩 범위) 루트에서 시작해 apps/web을 고칠 때는 루트 AGENTS.md의 “하위 지침을 수정 전에 읽는다” 조건이 이 파일을 읽게 한다. Claude Code는 그 폴더의 파일을 읽을 때 하위 AGENTS.md를 로드하지만, 그 폴더에 CLAUDE.md가 있으면 그것만 읽는다. 한 package만 고친다면 그 폴더에서 시작하는 편이 확실하다.

구조가 자란 뒤의 점검

공통 규칙이 루트 한 곳에만 있는가
어느 폴더에도 CLAUDE.md·CLAUDE.local.md가 남아 있지 않은가. 있으면 그 범위의 AGENTS.md가 무시된다
상위와 하위가 충돌하지 않고, 하위의 검사 명령이 실제 package와 맞는가

이해 확인

web과 api의 규칙이 같은데 폴더가 둘이다. 하위 AGENTS.md가 둘 다 필요할까? 필요 없다. 공통 규칙으로 충분한 동안은 루트만 유지하고, 실제 차이가 생긴 경계에 추가한다.

공개 레포의 배치 비교스펙·계획을 두는 세 갈래와 실제 레포의 선택을 비교한다.