Claude Code 모노레포 설정 — 설정 파일은 위에서 안 내려오고, 폴더를 더해줘도 그쪽 규칙은 안 읽습니다

프로젝트가 커지면 쓰지도 않은 토큰이 먼저 나갑니다. 공식 문서가 이걸 정확히 한 문장으로 적어놨더군요 — 작은 프로젝트에 맞춰진 기본값이 컨텍스트 창을 지금 작업과 무관한 지시와 파일 읽기로 채운다고요. 그래서 큰 저장소·모노레포 전용 설정 가이드가 따로 있습니다. 읽어 보니 설정 목록보다 "분명히 적어놨는데 왜 안 먹지"의 원인 두 개가 더 값졌습니다. 하나는 설정 파일이 위에서 안 내려온다는 것, 다른 하나는 폴더를 더해줘도 그쪽 규칙서는 안 읽는다는 것입니다.

📌 30초 요약

• CLAUDE.md는 부모 폴더까지 거슬러 올라가며 읽는데, 설정 파일은 시작한 폴더 것만 읽습니다. 둘이 반대입니다.
• 그래서 문서가 같은 규칙을 두 곳에 적어두라고 예시를 듭니다. 자족적으로 쓰라는 말이 곧 중복을 감수하라는 뜻입니다.
• 폴더를 설정으로 추가하면 파일은 고치는데 그 폴더의 CLAUDE.md·규칙·스킬은 전부 안 읽습니다. 플래그로 추가하면 스킬만 읽습니다.
• 읽기 금지 규칙에 구멍이 셋 있습니다. 그중 하나는 검색 결과에서는 안 걸러진다는 것입니다.
• 워크트리를 가볍게 만들 때 루트 파일은 딸려오는데 루트 폴더는 안 딸려옵니다. .claude를 안 적으면 통째로 사라집니다.
• 문서가 "모델이 좋아지면 규칙을 지우라"고 직접 말합니다. CLAUDE.md는 쌓기만 하는 파일이 아닙니다.

어디서 켜느냐가 제일 먼저 갈립니다

문서가 이 절을 먼저 읽으라고 못 박습니다. 어디서 실행하느냐가 추가 권한 없이 읽고 고칠 수 있는 파일 범위, 시작할 때 컨텍스트로 들어오는 CLAUDE.md, 그리고 어느 프로젝트 설정이 적용되는지 셋을 동시에 정하기 때문입니다.

시작 위치	파일 접근	시작 시 들어오는 CLAUDE.md	이럴 때
저장소 루트	전체 파일	루트 것만. 하위 것은 그쪽 파일을 읽는 순간 추가로	여러 패키지에 걸친 작업
하위 디렉터리	그 아래만. 더 주려면 따로 허용	그 폴더 것 + 조상 폴더 전부	한 패키지 안에서 끝나는 작업

표에서 눈여겨볼 건 루트에서 시작해도 하위 CLAUDE.md가 결국 들어온다는 점입니다. 시작할 때 안 들어올 뿐이지, Claude가 그 폴더 파일을 하나라도 열면 그 순간 딸려 들어옵니다. 그러니 "루트에서 켜면 가볍다"는 건 처음 몇 분 얘기입니다. 지금 무엇이 올라와 있는지는 컨텍스트 확인 명령의 메모리 파일 목록에서 볼 수 있습니다.

설정 파일은 위에서 안 내려옵니다

⚠️ 두 파일의 규칙이 정반대입니다

문서 문장을 그대로 옮기면 이렇습니다 — 프로젝트 설정은 시작 디렉터리에서만 로드되고, CLAUDE.md처럼 부모 디렉터리로부터 상속되지 않는다. 즉 저장소 루트에 설정을 걸어놨어도 하위 패키지에서 실행하면 그 설정은 적용되지 않습니다. CLAUDE.md는 반대로 조상 폴더까지 전부 훑어 올라가고요. 같은 폴더에 나란히 있는 두 파일이 정반대로 동작합니다. 그래서 문서가 결론을 이렇게 냅니다 — 하위 디렉터리마다의 설정 파일은 루트 파일 위에 얹히는 게 아니라 자족적이어야 한다. 완곡하게 적혀 있지만 실무 번역은 "같은 규칙을 여러 곳에 복사해 두라"입니다. 실제로 문서의 종합 예시가 읽기 금지 규칙을 패키지 설정과 루트 설정 두 곳에 똑같이 적어둡니다. 한쪽만 고치면 "어제는 됐는데 오늘은 안 되는" 상태가 됩니다.

예외가 하나 있습니다. 개인용 로컬 설정 파일은 저장소 안에서 실행하면 시작 위치와 관계없이 로드됩니다. 다만 여기에 버전 조건이 붙습니다 — 문서가 특정 버전 이전에는 이 파일도 시작 디렉터리에서만 로드됐다고 적어뒀습니다. 그러니 팀원끼리 버전이 다르면 같은 파일을 두고 서로 다른 결과를 봅니다. "제 쪽에선 되는데요"가 나오는 자리죠.

CLAUDE.md는 쪼개고, 낡은 건 지웁니다

루트 파일 하나로 버티면 둘 중 하나가 된다고 문서가 진단합니다 — 모든 하위 시스템의 관례를 담느라 비대해지거나, 아니면 너무 뻔해서 쓸모가 없거나. 처방은 두 층으로 쪼개는 것입니다. 루트에는 어디에나 적용되는 것(코딩 표준·커밋 관례·저장소 구조), 하위 폴더에는 그 영역의 기술 스택에 한정된 것을 둡니다.

# 루트 CLAUDE.md — 지도 역할만
packages/api    : Node + Express + PostgreSQL
packages/web    : React + Vite + Tailwind
packages/shared : 양쪽이 쓰는 공용 유틸

# packages/api/CLAUDE.md — 여기서만 쓰는 것
- 테스트 실행: npm test
- 라우트는 src/routes/ 아래, 각 파일이 라우터를 export
- 라우트 핸들러에 생 SQL 문자열 금지

이렇게 두면 API 폴더에서 켰을 때 프런트엔드 관례는 컨텍스트에 안 들어옵니다. 그리고 문서가 관리 방법으로 셋을 제안하는데, PR에서 CLAUDE.md 수정도 문서 변경처럼 리뷰할 것, 세션이 끝날 때 도는 훅으로 갱신안을 제안받을 것, 그리고 아래의 세 번째가 이 글에서 제일 실용적입니다.

🧹 "모델이 좋아졌으면 그 규칙은 지우세요"

문서 요지 — 주요 모델이 새로 나오면 다시 볼 것. 옛 모델의 한계를 우회하려고 넣은 지시는 새 모델이 알아서 처리하게 되면 그냥 오버헤드가 된다. 든 예가 구체적입니다 — "리팩터링은 한 번에 파일 하나씩만" 같은 규칙은 그 한계가 사라지면 지워도 된다고요. 이게 왜 절약 얘기냐면, CLAUDE.md는 매 요청마다 통째로 올라가는 상시 비용이기 때문입니다. 한 번 적어두면 그 뒤로는 쓰든 안 쓰든 계속 값을 치릅니다. 대부분 이 파일을 쌓기만 하는 파일로 다루는데, 문서는 빼는 작업을 정기적으로 하라고 말하고 있습니다. 제가 한 글자도 치기 전에 이미 올라가 있는 토큰을 세어 본 글에서 확인한 것과 같은 계열입니다 — 보이지 않는 상시 부하가 진짜 비용입니다.

안 쓰는 폴더의 CLAUDE.md를 아예 막는 설정도 있습니다. 경로나 글로브 패턴으로 지정하면 그 파일들은 영영 로드되지 않습니다. 다른 팀 패키지·레거시 코드·외부에서 가져다 넣은 하위 트리가 대상이고요. 다만 조건을 둘 짚어둡니다. 첫째, 이건 정적인 목록이지 작업별 스위치가 아닙니다. 문서가 직접 "오늘은 이 패키지, 내일은 저 패키지라면 목록을 고치지 말고 그 패키지 폴더에서 켜라"고 안내합니다. 둘째, 관리 정책으로 내려온 CLAUDE.md는 제외할 수 없습니다. 조직 차원의 지시는 항상 적용됩니다. 이 구분은 제가 서버에서 내려주는 관리 설정을 정리한 글에서 다룬 우선순위와 같은 얼개입니다.

읽는 양 자체를 줄이는 두 가지

지시문은 절반일 뿐이고, 파일 읽기가 나머지 절반입니다. 여기는 손이 두 갈래로 나뉩니다 — 못 읽게 막기와 덜 읽고도 찾게 만들기.

막는 쪽부터. 좋은 소식은 내용 검색이 기본적으로 .gitignore를 존중한다는 것입니다. node_modules/·dist/는 아무 설정 없이도 검색 결과에서 빠집니다. 문제는 저장소에 실제로 커밋돼 있는 것들입니다 — 가져다 넣은 SDK, 커밋된 생성 코드처럼요. 이건 읽기 금지 규칙으로 막습니다.

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/*.generated.*)",
      "Read(./vendor/**)"
    ]
  }
}

적용 범위는 어느 파일에 적느냐로 정해집니다 — 팀 전체면 커밋하는 프로젝트 설정, 나만이면 로컬 설정, 누구도 못 덮게 하려면 관리 설정. 로컬 설정에 쓸 때 함정이 하나 있는데, 상대 경로는 실행한 폴더 기준으로 붙습니다. 하위 폴더에서 켜는 습관이면 경로가 통째로 빗나가니 절대 경로 형식으로 쓰라고 문서가 안내합니다.

🕳️ 막았다고 안 보이는 건 아닙니다 — 구멍 셋

문서가 스스로 경계를 긋습니다. 금지 규칙은 내장 파일 도구와 인식된 셸 파일 명령을 덮습니다. 즉 cat·grep에 금지 경로를 인자로 넘기면 막힙니다. 그런데 덮지 못하는 게 둘이라고 명시합니다 — ①재귀 검색의 출력에서 금지 경로를 걸러내지는 않고, ②스스로 파일을 여는 임의의 하위 프로세스는 커버하지 않습니다. 여기에 앞서 말한 ③상대 경로 기준점 어긋남까지 합치면 셋이죠. 그러니 이 설정은 기밀을 지키는 벽이 아니라 컨텍스트를 아끼는 장치로 이해하는 게 맞습니다. 둘을 헷갈리면 "막아뒀으니 안 보겠지"가 됩니다.

덜 읽게 만드는 쪽은 코드 인텔리전스입니다. 큰 저장소에서 어떤 심볼이 어디 정의됐는지 찾는 건 파일 읽기와 검색 호출을 여러 번 먹는 작업인데, 언어 서버를 붙이면 정의로 바로 점프하고 참조를 바로 찾습니다. 문서가 이 둘의 조합을 이렇게 정리합니다 — 앞의 두 설정이 무관한 내용을 컨텍스트 밖으로 밀어내고, 코드 인텔리전스는 남은 것마저 훑지 않게 한다. 이 접근을 MCP 서버로 먼저 구현한 사례를 제가 Serena MCP 글에서 다룬 적이 있는데, 이제는 공식 플러그인으로 같은 자리를 채웁니다. 다만 언어 서버 바이너리는 각자 깔아야 하고, 이 조건은 플러그인 설치를 정리한 글에서 짚은 그대로입니다.

폴더를 더해줘도 그쪽 규칙은 안 읽습니다

이 글에서 제일 놀란 대목입니다. 하위 폴더에서 켠 뒤 옆 패키지도 건드려야 할 때 접근을 여는 방법이 둘 있습니다 — 설정 파일에 폴더를 적어두는 방식과 실행할 때 플래그로 붙이는 방식. 파일을 읽고 고치는 건 둘 다 됩니다. 그런데 그 폴더의 지시문·규칙·스킬을 읽느냐는 갈립니다.

추가한 방식	파일 읽기·편집	CLAUDE.md·규칙	스킬
설정 파일에 폴더 목록	가능	절대 안 읽음	절대 안 읽음
실행 플래그·중간 추가 명령	가능	환경 변수를 켜야 읽음	읽음

표를 말로 풀면 이렇습니다. 설정 파일에 옆 패키지를 적어두면, 그 패키지 파일을 고칠 수는 있는데 그 패키지의 관례는 하나도 모르는 상태로 고칩니다. "생 SQL 쓰지 마라" 같은 규칙이 그쪽 CLAUDE.md에 적혀 있어도 안 읽습니다. 게다가 환경 변수를 켜도 설정 파일로 추가한 폴더에는 효과가 없습니다. 문서가 그것까지 못 박아뒀습니다. 반대로 플래그로 붙이면 스킬은 그냥 읽히고, 지시문은 환경 변수를 켜야 읽힙니다. 같은 "폴더 추가"인데 세 항목이 서로 다르게 동작하는 셈이죠.

이 함정이 유독 조용한 이유가 있습니다 — 아무 오류도 안 납니다. 파일은 잘 열리고 편집도 되니까, 결과물이 그쪽 관례와 어긋나 있어도 리뷰에 가서야 발견됩니다. 참고로 같은 플래그가 세션을 재개할 때는 복원되지 않는다는 것도 전에 확인한 바 있는데, 두 사실을 합치면 결론이 같습니다 — 중요한 폴더 추가는 플래그가 아니라 설정 파일에, 다만 규칙까지 읽히길 원하면 플래그와 환경 변수로. 목적에 따라 갈라 써야 합니다.

워크트리를 필요한 폴더만 체크아웃하기

워크트리는 기본적으로 저장소 전체를 체크아웃합니다. 큰 저장소면 이게 그대로 시간과 디스크죠. 필요한 폴더만 적어두는 설정을 쓰면 그 목록과 루트 파일들만 디스크에 씁니다. 여기에 무거운 폴더를 심링크로 돌리는 설정을 짝지으면 의존성 폴더를 워크트리마다 복제하지 않습니다.

{
  "worktree": {
    "sparsePaths": [
      ".claude",           // 이 줄이 없으면 루트 설정이 통째로 사라짐
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": ["node_modules"]
  }
}

주석으로 달아둔 게 이 절에서 제일 잘 걸리는 함정입니다. 문서가 규칙을 이렇게 정리합니다 — 루트 레벨 파일은 항상 같이 체크아웃되지만, 루트 레벨 디렉터리는 아니다. 즉 패키지 설정 파일이나 잠금 파일 같은 파일은 알아서 딸려오는데, .claude는 디렉터리라서 명시하지 않으면 안 들어옵니다. 그러면 워크트리 안에서 루트의 설정·규칙·스킬이 전부 없는 상태가 됩니다. "파일은 다 있는데 규칙만 안 먹는" 상황의 정체죠.

연쇄되는 조건이 하나 더 있습니다. 워크트리가 만들어지면 작업 폴더가 워크트리 루트로 바뀝니다. 그러니 하위 패키지에서 켜서 만든 워크트리라도, 그 안에서 로드되는 프로젝트 설정은 워크트리 루트의 것, 곧 저장소 루트 설정의 사본입니다. 앞 절의 읽기 금지 규칙을 패키지 쪽에만 적어뒀다면 워크트리 세션에서는 그 규칙이 사라집니다. 문서의 종합 예시가 같은 규칙을 두 번 적는 이유가 바로 이것입니다. 워크트리 자체를 병렬로 굴리는 방식은 워크트리 병렬 작업 글에 따로 정리해뒀습니다.

부수 효과도 하나 밝혀둡니다 — 이 기능은 git이 저장소 공유 설정에 항목 하나를 켜야 동작합니다. 마지막 워크트리가 지워지면 되돌려놓는데, 직접 켜둔 값이라면 건드리지 않습니다. 그리고 특정 버전 이전에는 그 항목이 남아 있어서 일부 git 호환 도구가 저장소를 못 여는 문제가 있었다고 문서가 적어뒀습니다.

스킬은 수백 개로 불어나고, 설명은 잘립니다

폴더마다 스킬을 두면 그 영역 작업일 때만 로드되니 구조적으로 알뜰합니다. 문제는 고를 목록입니다. 하위 폴더에서 켜면 그 폴더와 조상들, 사용자·조직 수준까지가 후보인데, 루트에서 켜면 세션 중 Claude가 건드린 모든 하위 폴더의 스킬이 쌓여 수백 개까지 갈 수 있다고 문서가 적습니다.

여기서 조용한 손실이 생깁니다. 고르는 방식은 모든 스킬의 이름과 설명을 읽고 판단하는 건데, 이름은 항상 올라가지만 설명은 개수가 많아지면 짧게 잘립니다. 잘리면서 판단에 쓰이던 키워드가 같이 날아갈 수 있습니다. 그래서 처방이 "설명을 짧게 쓰고, 실제 요청에 나올 법한 단어를 앞쪽에 두라"입니다. 뒤에 붙인 부연은 못 살아남는다고 보는 게 맞습니다.

안 쓰이는 스킬을 골라내는 방법도 나옵니다 — 로그 내보내기를 켜고 도구 상세 기록 옵션을 함께 켜면 스킬 이름이 가려지지 않고 그대로 남고, 호출 이벤트에 무엇이 그 스킬을 불렀는지까지 기록됩니다. 이 옵션을 안 켜면 이름이 가려진다는 사실은 제가 비용을 스킬별로 쪼개 본 글에서 짚었던 그 조건입니다. 정리를 시작하기 전에 먼저 무엇이 안 쓰이는지 재는 게 순서입니다.

🙋 정직하게 밝혀둘 것

• 모노레포에 직접 걸어 보고 쓴 글이 아닙니다. 절약되는 토큰이 몇 퍼센트인지 제가 잰 값이 없습니다. 문서도 숫자는 안 줍니다.
• "설정이 상속 안 되니 나쁘다"는 뜻이 아닙니다. 하위 폴더에서 켜는 것 자체가 다른 패키지 지시문을 애초에 안 부르는 가장 싼 방법이고, 문서도 그걸 먼저 권합니다. 문제는 루트에 걸어두면 다 적용되겠거니 하고 넘어갈 때입니다.
• "작은 프로젝트도 이렇게 하라"는 것도 아닙니다. 문서 자체가 큰 코드베이스를 전제로 하고, 설정마다 각각 독립이라 필요한 것만 골라 쓰라고 적혀 있습니다. 전부 켜는 게 목표가 아닙니다.
• 버전에 걸린 항목이 둘 있습니다. 로컬 설정의 로드 범위와 워크트리가 남기는 git 항목인데, 둘 다 특정 버전 이전 이야기라 최신 버전이면 해당하지 않습니다. 팀 안에서 버전이 섞여 있을 때만 신경 쓰면 됩니다.

🗺️ AI 지출 전체 지도

이 글의 설정들은 전부 "안 읽게 만들어서 아끼는" 쪽입니다. 같은 돈을 아끼는 다른 손잡이들 — 구독과 종량제 고르기, 캐시, 모델 조합, 상한 걸기 — 까지 지금까지 확인한 것들을 일곱 단계 지도 한 장으로 묶어뒀습니다.

자주 묻는 것

Q. 그래서 루트에서 켜는 게 나은가요, 패키지에서 켜는 게 나은가요?

문서 기준은 작업이 여러 패키지에 걸치면 루트, 한 패키지 안에서 끝나면 그 폴더입니다. 아끼는 것만 보면 패키지 쪽이 유리한데, 대신 옆 패키지 접근을 따로 열어야 하고 그때 위의 규칙 안 읽힘 문제가 따라옵니다. 하루에도 여러 패키지를 오간다면 제외 목록을 계속 고치기보다 그때그때 해당 폴더에서 켜는 편을 문서가 권합니다.

Q. 폴더별 CLAUDE.md와 경로 규칙 파일 중 뭘 쓰나요?

파일이 어디 놓이고 언제 로드되느냐가 다릅니다. 폴더별 CLAUDE.md는 코드 옆에 있어서 그 폴더 주인이 직접 관리하고 코드와 같이 버전이 매겨집니다. 경로 규칙은 루트 한곳에 모여 있고 글로브에 걸리는 파일을 다룰 때 로드되죠. 관례를 한곳에 모으고 싶거나 같은 규칙이 여기저기 흩어진 경로에 걸린다면 후자가 맞습니다.

Q. 패키지를 넘나드는 변경은 어떻게 시키나요?

문서가 둘을 권합니다 — 공용 타입 수정과 그걸 쓰는 모든 호출부를 한 세션에 통째로 넘길 것(패키지마다 판단을 다시 만들지 않도록), 그리고 계획을 파일로 적어둘 것입니다. 두 번째 이유가 현실적인데, 긴 세션은 도중에 컨텍스트를 압축하기 때문에 대화는 사라져도 저장한 계획은 남습니다.

✨ 정리하면

큰 저장소에서 토큰이 새는 자리는 지시문과 파일 읽기 둘이고, 손잡이는 쪼개기·제외하기·못 읽게 막기·덜 읽고 찾기·워크트리 줄이기 다섯입니다. 그런데 설정을 걸기 전에 알아야 할 게 둘 있습니다 — 설정 파일은 위에서 안 내려오니 시작 위치를 먼저 정해야 하고, 폴더를 더해줘도 그쪽 규칙서는 자동으로 안 읽힙니다. 둘 다 오류 없이 조용히 어긋나는 종류라, 설정을 늘리기 전에 이 두 개를 먼저 확인하는 게 빠릅니다.

※ 출처: Claude Code 공식 문서 code.claude.com/docs/en/large-codebases (2026-08-18 확인). 설정 이름과 동작은 버전에 따라 바뀔 수 있고, 본문에서 특정 버전 이전이라고 적은 항목은 문서가 그렇게 밝혀둔 것입니다. 절약 폭은 저장소 구성에 따라 크게 달라지므로 수치는 제시하지 않았습니다.