Anthropic이 소개하는 대규모 코드베이스에서 Claude Code를 성공적으로 도입하는 방법

9bow · 5월 17, 2026, 3:30오전

Claude Code 대규모 도입 가이드 소개

Anthropic이 Claude Code를 대규모 코드베이스에서 성공적으로 도입하기 위한 실전 패턴을 정리한 글을 공개했습니다. 여기서 말하는 대규모 코드베이스는 단순히 파일 수가 많은 저장소만을 뜻하지 않습니다. 수백만 줄짜리 모노레포, 수십 년 동안 축적된 레거시 시스템, 여러 저장소에 흩어진 마이크로서비스, 그리고 C, C++, C#, Java, PHP처럼 AI 코딩 도구가 상대적으로 다루기 어렵다고 여겨졌던 언어까지 모두 포함합니다.

이 글의 핵심은 "좋은 모델 하나를 붙인다고 대규모 코드베이스 문제가 자동으로 풀리지는 않는다" 는 점입니다. 실제 성공 사례에서는 모델 자체만큼이나 그 모델을 둘러싼 하네스(harness), 즉 컨텍스트 파일, 훅, 스킬, 플러그인, MCP 서버, LSP 통합, 서브에이전트 같은 실행 환경이 중요했습니다. 사람 개발자가 낯선 코드베이스에서 README, 빌드 스크립트, 테스트 명령, 팀 규칙, IDE 탐색 기능을 함께 사용하듯이, Claude Code도 코드베이스를 읽고 수정하려면 주변 환경이 잘 정리되어 있어야 합니다.

특히 대규모 조직에서 AI 코딩 도구를 도입할 때 흔히 생기는 문제는 기술 자체보다 운영 방식에서 나옵니다. 누군가는 잘 동작하는 CLAUDE.md를 만들었지만 다른 팀에는 공유되지 않고, 어떤 팀은 훅으로 자동 검증을 잘 구성했지만 조직 전체 표준은 없으며, 새로 들어온 개발자는 무엇을 설치해야 하는지 모른 채 시행착오를 반복합니다. Anthropic은 이런 상황을 피하려면 개인의 팁을 조직의 인프라로 끌어올려야 한다고 설명합니다.

이 글은 PyTorchKR의 Claude Code의 조직별 활용 전략, Claude Code 플러그인 기능, Everything Claude Code 같은 기존 글에서 보셨던 개념을 더 큰 조직과 더 큰 코드베이스 관점에서 다시 묶어 이해하는 데 도움이 됩니다.

인덱스보다 중요한 것은 살아 있는 코드베이스를 직접 탐색하는 능력입니다

많은 AI 코딩 도구는 코드베이스를 미리 임베딩하고, 사용자의 질문이 들어오면 관련 조각을 검색하는 검색 증강 생성(Retrieval-Augmented Generation, RAG) 방식에 의존합니다. 이 방식은 문서 검색이나 비교적 안정적인 코드베이스에서는 유용하지만, 수천 명의 개발자가 매일 커밋하는 대형 저장소에서는 쉽게 낡은 정보가 됩니다. 어떤 함수가 2주 전에 이름이 바뀌었거나, 모듈이 지난 스프린트에서 삭제되었는데도 검색 인덱스가 아직 예전 상태라면, 모델은 이미 사라진 코드를 근거로 답할 수 있습니다.

Claude Code가 취하는 접근은 조금 다릅니다. Claude Code는 개발자의 로컬 환경에서 실제 파일 시스템을 순회하고, 필요한 파일을 읽고, grep이나 ripgrep 같은 검색 도구를 통해 참조를 따라갑니다. 즉, 중앙 인덱스를 업로드하거나 유지하는 대신, 현재 체크아웃된 코드베이스를 직접 탐색합니다. Anthropic은 이를 에이전틱 검색(agentic search)에 가까운 방식으로 설명합니다.

이 접근의 장점은 최신성입니다. 별도의 임베딩 파이프라인이 밀릴 일이 없고, 개발자의 로컬 브랜치에 있는 변경사항까지 그대로 반영됩니다. 그러나 대가도 있습니다. Claude가 어디부터 찾아야 할지 모르면, 거대한 코드베이스 전체를 무작정 훑다가 컨텍스트를 낭비하게 됩니다. 사람이 낯선 회사의 코드베이스를 볼 때도 "결제 관련 코드는 이 디렉터리부터 보면 됩니다", "이 서비스의 테스트는 루트가 아니라 하위 폴더에서 실행해야 합니다" 같은 힌트가 있으면 훨씬 빨리 움직이듯이, Claude Code도 시작점과 탐색 규칙이 필요합니다.

따라서 대규모 코드베이스에서 Claude Code를 잘 쓰려면, 모델에게 모든 것을 한 번에 보여주려는 전략보다 탐색 가능한 구조(navigable structure) 를 만드는 것이 중요합니다. 루트에는 전체 지도를 두고, 하위 디렉터리에는 지역 규칙을 두며, 생성 파일과 외부 코드처럼 불필요한 소음은 제외하고, 심볼 단위 탐색이 필요한 언어에는 Language Server Protocol 기반 도구를 붙이는 식입니다.

심화 학습: 코드베이스 탐색과 컨텍스트 관리

Claude Code memory, CLAUDE.md 공식 문서

Claude Code code intelligence 플러그인 문서

Language Server Protocol 공식 사양

모델만큼 중요한 하네스: Claude Code를 둘러싼 일곱 가지 구성 요소

Anthropic은 대규모 코드베이스에서 Claude Code의 성능을 좌우하는 요소를 모델 하나로 보지 않습니다. 모델을 둘러싼 실행 계층, 즉 하네스가 실제 사용 경험을 크게 결정한다고 설명합니다. 이 하네스는 크게 CLAUDE.md, 훅, 스킬, 플러그인, LSP 통합, MCP 서버, 서브에이전트로 나눌 수 있습니다.

구성 요소	역할	적합한 사용처	흔한 실수
`CLAUDE.md`	세션 시작 시 자동으로 읽는 코드베이스 컨텍스트	프로젝트 전반 규칙, 중요한 주의사항	모든 지식을 한 파일에 몰아넣기
훅(Hooks)	특정 이벤트에서 자동 실행되는 스크립트	린트, 포맷, 세션 종료 후 회고, 동적 컨텍스트 주입	프롬프트로 처리할 일을 자동화하지 않기
스킬(Skills)	작업 유형별 전문 지식을 필요할 때만 로드	보안 리뷰, 문서 처리, 배포 절차, 도메인 워크플로우	항상 필요한 내용과 필요할 때만 필요한 내용을 구분하지 않기
플러그인(Plugins)	스킬, 훅, MCP 설정을 묶어 배포	조직 표준 도구 배포, 신규 입사자 온보딩	잘 되는 설정을 개인 노하우로만 남겨두기
LSP 통합	IDE 수준의 심볼 탐색 제공	C, C++, Java, TypeScript 등 정적 분석 가치가 큰 언어	문자열 검색만으로 충분하다고 가정하기
MCP 서버	내부 도구, 문서, 티켓, 데이터 소스 연결	사내 검색, 분석 플랫폼, 이슈 트래커, 배포 시스템	기본 설정 전부터 복잡한 MCP부터 만들기
서브에이전트(Subagents)	별도 컨텍스트를 가진 독립 Claude 인스턴스	탐색과 편집 분리, 병렬 조사, 하위 작업 위임	모든 작업을 한 세션에서 계속 처리하기

이 표에서 중요한 순서는 CLAUDE.md가 먼저라는 점입니다. Claude Code의 메모리 문서에 따르면 CLAUDE.md는 Claude가 세션 시작 시 자동으로 읽는 프로젝트 컨텍스트입니다. 루트 CLAUDE.md는 코드베이스의 큰 그림, 반드시 지켜야 할 규칙, 위험한 명령, 주요 디렉터리 지도를 담기에 좋습니다. 반면 하위 디렉터리의 CLAUDE.md는 해당 모듈의 테스트 명령, 로컬 아키텍처, 팀별 관례를 담기에 좋습니다.

훅(Hooks)은 설정을 더 능동적으로 만듭니다. 많은 팀은 훅을 "Claude가 잘못된 행동을 하지 못하게 막는 장치" 로만 생각하지만, Anthropic은 훅의 더 큰 가치를 자기 개선 루프에서 찾습니다. 예를 들어 세션 종료 훅이 이번 작업에서 새로 배운 팀 규칙을 정리해 CLAUDE.md 업데이트 후보로 남기거나, 세션 시작 훅이 현재 디렉터리에 맞는 문맥을 자동으로 주입할 수 있습니다. 린트나 포맷처럼 결과가 결정적인 작업은 모델에게 기억하라고 말하는 것보다 훅으로 실행하는 편이 더 안정적입니다.

스킬(Skills)은 모든 지식을 기본 컨텍스트에 넣지 않기 위한 장치입니다. 대규모 조직에는 보안 점검, 성능 분석, 데이터 마이그레이션, 문서 업데이트, 모바일 릴리스, 인프라 배포처럼 서로 다른 전문 작업이 많습니다. 이 지식을 전부 CLAUDE.md에 넣으면 매 세션마다 컨텍스트가 무거워집니다. 반대로 진보적 공개(Progressive Disclosure) 방식의 스킬로 분리하면, 필요한 작업이 들어왔을 때만 해당 지식이 로드됩니다. PyTorchKR에서도 Anthropic의 skill-creator 개선과 Google Skills처럼 스킬 생태계 관련 흐름을 계속 소개하고 있습니다.

플러그인(Plugins)은 잘 작동하는 설정을 조직 전체에 배포하는 방식입니다. 어떤 팀이 좋은 스킬과 훅, Model Context Protocol(MCP) 설정을 만들었더라도, 그것이 개인의 dotfiles에만 남아 있으면 조직 도입에는 한계가 있습니다. 플러그인은 이런 구성요소를 하나의 설치 가능한 패키지로 묶습니다. 조직에서는 관리형 마켓플레이스를 통해 승인된 플러그인을 배포할 수도 있습니다.

LSP 통합은 대형 코드베이스에서 특히 중요합니다. 흔한 함수명 하나를 grep으로 검색하면 수천 개의 결과가 나올 수 있지만, LSP는 동일한 심볼을 가리키는 참조만 추려냅니다. clangd 같은 C, C++ 언어 서버나 Eclipse JDT LS 같은 Java 언어 서버는 사람이 IDE에서 쓰는 정의로 이동, 참조 찾기 기능을 Claude에게도 제공합니다. 정적 타입 언어와 오래된 엔터프라이즈 코드베이스에서는 문자열 검색보다 심볼 탐색의 효과가 큽니다.

마지막으로 서브에이전트(Subagents)는 탐색과 편집을 분리하는 데 유용합니다. 예를 들어 읽기 전용 서브에이전트가 결제 모듈의 구조를 조사하고, 그 결과만 부모 에이전트에게 전달하면, 부모 에이전트는 불필요한 조사 로그 없이 수정에 집중할 수 있습니다. 대규모 작업에서는 한 세션이 모든 것을 기억하려고 하기보다, 별도 컨텍스트에서 조사한 결과를 요약해 가져오는 편이 더 안정적일 수 있습니다.

첫 번째 도입 패턴: 코드베이스를 Claude가 길을 잃지 않도록 정리합니다

대규모 코드베이스에서 Claude Code의 한계는 모델의 지능만으로 결정되지 않습니다. 더 직접적으로는 "Claude가 적절한 파일과 명령에 얼마나 빨리 도달할 수 있는가" 로 결정됩니다. Anthropic이 관찰한 성공적인 팀들은 코드베이스를 Claude가 읽기 쉬운 형태로 만들기 위해 몇 가지 공통 패턴을 사용했습니다.

CLAUDE.md를 가볍고 계층적으로 유지하기: 루트 CLAUDE.md는 저장소의 목적, 큰 디렉터리 구조, 절대 하면 안 되는 작업, 공통 개발 규칙처럼 모든 세션에 유효한 내용만 담는 것이 좋습니다. 특정 서비스의 테스트 명령이나 팀별 관례는 해당 하위 디렉터리의 CLAUDE.md에 두어야 합니다. 이렇게 하면 Claude가 루트에서 전체 지도를 보고, 실제 작업 디렉터리로 내려가면서 지역 규칙을 추가로 읽게 됩니다.

항상 루트에서 시작하지 않기: 모노레포에서는 습관적으로 저장소 루트에서 도구를 실행하기 쉽지만, Claude Code 작업은 실제 변경 대상 디렉터리에서 시작하는 편이 더 좋을 때가 많습니다. Claude는 디렉터리 트리를 거슬러 올라가며 CLAUDE.md를 읽기 때문에 루트 컨텍스트를 잃지 않습니다. 대신 처음부터 관련 없는 수십 개 서비스의 파일을 열어보는 일을 줄일 수 있습니다.

테스트와 린트 명령을 하위 디렉터리 단위로 명시하기: 하나의 서비스만 수정했는데 전체 모노레포 테스트를 실행하면 시간이 오래 걸리고, 실패 로그도 너무 커져 Claude의 컨텍스트를 압박합니다. 각 하위 디렉터리의 CLAUDE.md에는 그 영역에 맞는 테스트, 빌드, 린트 명령을 적어두는 것이 좋습니다. 예를 들어 프런트엔드 패키지는 npm 기반 명령을, Python 서비스는 pytest 기반 명령을, Java 서비스는 Gradle이나 Maven 명령을 별도로 적어둘 수 있습니다.

생성 파일, 빌드 산출물, 서드파티 코드를 제외하기: Claude가 읽을 필요가 없는 파일이 많을수록 검색 결과가 지저분해집니다. Git의 .gitignore처럼, Claude Code 설정에서도 빌드 산출물, vendored dependency, generated code를 제외하는 규칙을 두는 것이 좋습니다. 다만 코드 생성기를 개발하는 팀처럼 generated code 자체가 작업 대상인 경우에는 프로젝트 공통 제외 규칙과 개인 로컬 설정을 분리해야 합니다.

디렉터리 구조가 설명력이 없으면 코드베이스 지도를 만들기: 오래된 시스템이나 조직 개편을 여러 번 거친 코드베이스에서는 폴더 이름만 보고 의미를 알기 어렵습니다. 이럴 때는 루트에 가벼운 마크다운 파일을 두고, 상위 폴더별로 "여기에는 결제 정산 로직이 있습니다", "이 폴더는 레거시 배치 작업이며 신규 기능은 추가하지 않습니다" 같은 한 줄 설명을 적어두는 것이 효과적입니다. 수백 개의 상위 폴더가 있다면 루트에는 1단계 지도만 두고, 하위 폴더에 더 자세한 지도를 계층적으로 두는 편이 좋습니다.

LSP로 문자열 검색을 심볼 검색으로 바꾸기: 대형 코드베이스에서 handleRequest 같은 흔한 이름을 검색하면, 실제로 찾는 함수와 무관한 결과가 대량으로 나옵니다. LSP를 붙이면 Claude가 동일한 심볼에 대한 정의와 참조를 구분할 수 있습니다. 특히 C, C++, Java, TypeScript처럼 타입과 심볼 구조가 강한 언어에서는 이 투자가 빠르게 효과를 냅니다.

이 패턴들은 모두 같은 방향을 가리킵니다. Claude Code에게 더 많은 컨텍스트를 주는 것이 아니라, 덜 읽어도 더 정확히 찾을 수 있는 구조 를 만들어 주는 것입니다.

두 번째 도입 패턴: 설정은 한 번 만들고 끝나는 문서가 아니라 계속 관리해야 합니다

Anthropic은 CLAUDE.md, 스킬, 훅 같은 설정을 3~6개월마다 의미 있게 재검토하라고 권합니다. 이유는 단순합니다. 모델과 도구가 발전하면, 예전 모델의 약점을 보완하기 위해 쓴 지시가 새 모델에게는 제약이 될 수 있습니다.

예를 들어 이전 모델이 큰 리팩터링에서 자주 길을 잃었다면, CLAUDE.md에 "모든 리팩터링은 반드시 한 파일씩 나누어 수행하라" 는 규칙을 넣었을 수 있습니다. 하지만 더 강한 모델이 여러 파일의 계약을 함께 추적할 수 있게 되면, 이 규칙은 오히려 자연스러운 변경을 방해합니다. 비슷하게 어떤 팀이 Perforce Helix Core 코드베이스에서 파일 수정 전 p4 edit를 강제하는 훅을 만들었다면, Claude Code가 해당 워크플로우를 기본 지원하게 된 뒤에는 그 훅이 중복 오버헤드가 될 수 있습니다.

이 관점은 AI 코딩 도구 운영에서 중요합니다. 많은 팀이 첫 성공 경험을 만든 뒤 그 설정을 굳혀버립니다. 그러나 AI 도구의 성능은 정적인 플랫폼보다 더 빠르게 변합니다. 새로운 모델 릴리스, 새로운 플러그인, 새로운 권한 모델, 새로운 IDE 통합이 나오면, 기존 설정은 "도움이 되는 지식" 에서 "낡은 우회로" 로 바뀔 수 있습니다. PyTorchKR에서 소개한 Claude Code Auto Mode처럼 권한 모델 하나만 바뀌어도 팀의 훅과 승인 정책은 다시 점검할 필요가 생깁니다.

따라서 CLAUDE.md 관리의 좋은 기준은 양보다 최신성입니다. 루트 파일이 길어지고 있다면, 그중 일부는 스킬로 분리할 수 있는지, 일부는 훅이나 스크립트로 자동화할 수 있는지, 일부는 더 이상 필요 없는 낡은 조언인지 검토해야 합니다. 특히 "Claude가 자주 실수해서 추가한 지시" 는 모델 업그레이드 이후 가장 먼저 재평가할 후보입니다.

심화 학습: 스킬과 설정 유지보수

Claude Code Skills 공식 문서

Agent Skills best practices

Claude Code Hooks 공식 가이드

세 번째 도입 패턴: 개인 생산성 도구가 아니라 조직 인프라로 운영합니다

대규모 조직에서 Claude Code 도입이 빨리 퍼진 사례에는 공통점이 있습니다. 광범위한 접근 권한을 열기 전에, 먼저 소수의 담당자가 도구가 조직의 개발 흐름에 맞도록 배선했습니다. 어떤 회사에서는 몇 명의 엔지니어가 공통 플러그인과 MCP 서버를 준비했고, 어떤 회사에서는 AI 코딩 도구를 관리하는 별도 팀이 초기 인프라를 구축했습니다. 그 결과 개발자들이 Claude Code를 처음 실행했을 때부터 자신의 서비스, 테스트 명령, 내부 문서, 코드 리뷰 흐름과 자연스럽게 연결된 경험을 할 수 있었습니다.

반대로 바텀업 도입만으로 시작하면 초반 열기는 빠르게 생기지만, 성공 패턴이 흩어질 수 있습니다. A팀은 좋은 CLAUDE.md 구조를 만들고, B팀은 훌륭한 보안 리뷰 스킬을 만들고, C팀은 내부 문서 MCP 서버를 만들었는데, 서로 알지 못하면 조직 전체의 품질은 평균화되지 않습니다. Anthropic은 이런 단절을 막기 위해 Claude Code 설정과 정책을 책임지는 개인 또는 팀이 필요하다고 말합니다.

이 역할은 개발자 경험(Developer Experience) 또는 개발자 생산성(Developer Productivity) 조직과 잘 맞습니다. 이미 이 팀들은 신규 개발자 온보딩, 빌드 시스템, 공통 CLI, 내부 문서, 개발 환경 표준을 담당하는 경우가 많기 때문입니다. Anthropic은 일부 조직에서 에이전트 매니저(agent manager) 라는 역할도 등장하고 있다고 설명합니다. 이는 제품 관리자와 엔지니어의 중간 지점에 있는 역할로, 어떤 스킬과 플러그인을 승인할지, 어떤 권한 정책을 적용할지, 어떤 CLAUDE.md 관례를 표준화할지를 관리합니다.

거버넌스도 초기에 다뤄야 합니다. 수천 명의 개발자가 각자 다른 스킬과 플러그인을 만들면 중복이 생기고, 보안 검토가 어려워지며, AI가 만든 코드가 사람 코드와 같은 리뷰 절차를 거치는지도 불명확해집니다. 따라서 초기에는 승인된 스킬 목록, 필수 코드 리뷰 절차, 제한된 접근 범위를 정하고, 신뢰가 쌓이면 점진적으로 확장하는 편이 좋습니다. 특히 금융, 의료, 공공, 보안 민감 산업에서는 엔지니어링, 정보보안, 거버넌스 담당자가 함께 참여하는 워킹 그룹이 필요합니다.

팀 규모별로 적용할 수 있는 실천 체크리스트

Anthropic의 글은 엔터프라이즈 도입을 다루지만, 그 원칙은 개인 프로젝트나 작은 팀에도 적용할 수 있습니다. 차이는 필요한 구성요소의 규모입니다:

상황	먼저 할 일	다음 단계
개인 프로젝트	루트 `CLAUDE.md`에 프로젝트 목적, 실행 명령, 금지 명령 정리	반복 작업이 생기면 스킬이나 훅으로 분리
작은 팀	하위 디렉터리별 테스트 명령과 코드 규칙 정리	팀 공통 스킬, 리뷰 체크리스트, 린트 훅 만들기
모노레포 조직	루트 지도와 하위 `CLAUDE.md` 계층 설계	LSP, 플러그인, MCP 서버, 승인된 스킬 목록 운영
규제 산업 조직	권한, 감사, 코드 리뷰, 데이터 접근 정책 먼저 정의	보안팀과 함께 플러그인 마켓플레이스 및 MCP 거버넌스 운영

실무적으로는 다음 순서가 가장 보수적입니다.

루트 CLAUDE.md에 저장소의 큰 그림과 절대 지켜야 할 규칙만 적습니다.
변경이 잦은 서비스나 패키지부터 하위 CLAUDE.md를 추가합니다.
각 하위 영역에 맞는 테스트, 린트, 빌드 명령을 명확히 적습니다.
생성 파일, 빌드 산출물, 서드파티 코드 등 Claude가 읽지 않아도 되는 대상을 제외합니다.
반복되는 전문 작업을 스킬로 분리합니다.
자동화 가능한 검증은 훅으로 옮깁니다.
팀에서 검증된 구성을 플러그인으로 묶어 배포합니다.
정적 타입 언어와 대형 모듈에는 LSP 통합을 우선 검토합니다.
내부 문서, 티켓, 분석 시스템은 MCP 서버로 연결합니다.
탐색이 무거운 작업은 서브에이전트로 분리합니다.

이 순서의 장점은 복잡도를 천천히 높인다는 것입니다. MCP 서버나 플러그인부터 만들고 싶어질 수 있지만, CLAUDE.md와 하위 디렉터리 테스트 명령이 부실하면 고급 통합도 충분히 효과를 내기 어렵습니다. 반대로 작고 정확한 컨텍스트 파일만 잘 정리해도 Claude Code의 체감 품질은 빠르게 좋아질 수 있습니다.

무엇을 CLAUDE.md에 남기고 무엇을 분리할지 판단하는 기준

대규모 코드베이스에서 가장 흔한 실수는 CLAUDE.md를 만능 문서로 사용하는 것입니다. 처음에는 편해 보입니다. Claude가 자주 실수하는 내용을 발견할 때마다 루트 CLAUDE.md에 한 줄씩 추가하면 되기 때문입니다. 하지만 몇 달이 지나면 이 파일은 프로젝트 규칙, 배포 절차, 보안 체크리스트, 도메인 지식, 금지 명령, 과거 모델을 위한 우회 지시가 뒤섞인 긴 문서가 됩니다. 그러면 모든 세션이 무거워지고, Claude는 실제 작업과 무관한 지시까지 매번 읽어야 합니다.

좋은 기준은 "이 정보가 거의 모든 세션에 필요한가?" 입니다. 답이 예라면 CLAUDE.md에 남길 수 있습니다. 답이 아니라면, 스킬, 훅, MCP 서버, 별도 문서 중 하나로 보내는 편이 낫습니다.

정보 유형	추천 위치	이유
저장소의 목적, 핵심 디렉터리 지도, 공통 금지 사항	루트 `CLAUDE.md`	모든 작업에서 알아야 하는 배경입니다
특정 서비스의 테스트 명령, 로컬 실행 방식, 팀별 관례	하위 디렉터리 `CLAUDE.md`	해당 경로에서만 필요한 지식입니다
보안 리뷰, 릴리스 절차, 문서 업데이트처럼 반복되는 전문 작업	스킬	필요할 때만 로드하면 컨텍스트를 아낄 수 있습니다
린트, 포맷, 테스트, 세션 종료 회고처럼 자동 실행 가능한 작업	훅	모델의 기억에 의존하지 않고 결정적으로 실행할 수 있습니다
내부 문서, 티켓, 실험 추적, 분석 플랫폼처럼 외부 시스템 조회가 필요한 작업	MCP 서버	Claude가 구조화된 도구 호출로 필요한 데이터를 가져올 수 있습니다
긴 배경 설명, 아키텍처 결정 기록, 설계 문서	별도 문서와 링크	항상 읽을 필요는 없지만 필요할 때 참조할 수 있어야 합니다

이 기준을 적용하면 CLAUDE.md는 점점 작아지고, 나머지 지식은 더 정확한 위치로 이동합니다. 예를 들어 "결제 서비스 배포 전에는 반드시 스테이징 정산 검증을 실행하라" 는 규칙은 결제 디렉터리의 CLAUDE.md에 둘 수 있습니다. 반면 "결제 서비스 릴리스 절차 전체" 는 별도 스킬이 더 적합합니다. 배포 체크가 명령으로 자동화되어 있다면 훅이나 CI에 두는 편이 더 좋습니다.

또 하나의 기준은 실패했을 때의 비용입니다. 단순한 스타일 위반은 린트 훅으로 충분하지만, 개인정보가 포함된 데이터를 잘못 읽거나 외부 API에 잘못 쓰는 문제는 권한 정책과 MCP 설계까지 포함해 다뤄야 합니다. 대규모 코드베이스에서는 Claude가 똑똑하게 판단하기를 기대하기보다, 위험한 경계는 도구와 정책으로 좁혀 두는 것이 더 안전합니다.

Claude에게 좋은 작업 단위를 주는 방법

대규모 코드베이스에서 Claude Code가 어려워하는 요청은 대체로 범위가 흐릿합니다. "이 코드베이스에서 성능 문제를 찾아줘", "인증 흐름을 정리해줘", "전체 테스트를 고쳐줘" 같은 요청은 사람에게도 시작점이 넓습니다. Claude는 파일을 열어보며 길을 찾을 수 있지만, 코드베이스가 클수록 탐색 비용이 급격히 늘어납니다.

더 나은 요청은 시작점, 기대 결과, 검증 방법을 함께 줍니다. 예를 들어 "payments/api 디렉터리의 환불 생성 흐름에서 중복 요청 방지 로직을 확인하고, 관련 테스트를 실행해줘" 라고 하면 Claude는 파일 탐색 범위를 줄이고, 어떤 성공 기준을 확인해야 하는지도 알 수 있습니다. 이 방식은 Anthropic이 강조한 하위 디렉터리에서 시작하기 와도 잘 맞습니다.

흐릿한 요청	더 좋은 요청
인증 버그를 고쳐줘	`services/auth`에서 세션 만료 후 재로그인 실패를 재현하는 테스트를 먼저 찾고, 실패 원인을 고쳐줘
테스트가 깨졌어	`packages/web`에서 실패하는 `npm test` 결과를 기준으로 최소 변경으로 수정해줘
코드베이스 구조를 알려줘	`ml/training` 디렉터리의 데이터 로딩, 모델 정의, 학습 루프, 평가 스크립트 연결 관계를 요약해줘
리팩터링해줘	`src/payment/refund`의 중복 검증 로직을 하나의 내부 함수로 모으고 기존 공개 API는 바꾸지 말아줘
보안 문제를 찾아줘	`api/uploads`에서 파일 업로드 경로 검증과 MIME 타입 검증만 검토하고, 위험도와 수정안을 정리해줘

요청을 이렇게 바꾸면 Claude가 스스로 세부 계획을 세우더라도 출발점이 훨씬 선명해집니다. 특히 대규모 조직에서는 이런 요청 양식을 팀 문서나 스킬에 넣어두는 것도 좋습니다. 예를 들어 보안 리뷰 스킬은 대상 경로, 검토할 위협 모델, 수정 가능 여부, 검증 명령 을 먼저 확인하도록 만들 수 있습니다. 데이터 파이프라인 스킬은 입력 데이터, 중간 산출물, 저장 위치, 재실행 비용 을 먼저 점검하도록 만들 수 있습니다.

또한 탐색과 편집을 분리하는 습관도 중요합니다. 처음부터 "전부 조사하고 바로 고쳐줘" 라고 하면 한 세션의 컨텍스트에 조사 로그와 수정 계획, 실제 코드 변경이 모두 섞입니다. 큰 작업에서는 먼저 읽기 전용 조사로 구조를 파악하고, 그 결과를 짧은 메모로 남긴 뒤, 다음 단계에서 수정에 들어가는 편이 안정적입니다. Claude Code의 서브에이전트는 이런 패턴을 도구 차원에서 지원합니다.

도입 성숙도를 확인하는 질문들

Claude Code 도입이 잘 되고 있는지 확인하려면 사용량만 보면 부족합니다. 많은 사람이 실행하고 있어도 각자 다른 방식으로 쓰고 있고, 실패 사례가 조직 지식으로 환류되지 않는다면 성숙한 도입이라고 보기 어렵습니다. 다음 질문들은 현재 상태를 점검하는 데 도움이 됩니다.

새 개발자가 첫날 Claude Code를 실행했을 때 필요한 컨텍스트가 자동으로 제공되나요?
루트 CLAUDE.md, 하위 디렉터리 규칙, 설치해야 할 플러그인, 필요한 권한이 명확하지 않다면 첫 경험은 개인의 운에 좌우됩니다.

팀별로 성공한 설정이 조직 전체로 공유되나요?
한 팀이 좋은 스킬이나 훅을 만들었는데 다른 팀이 모른다면 지식은 여전히 부족별로 흩어져 있습니다. 플러그인이나 내부 마켓플레이스가 필요한 지점입니다.

Claude가 만든 코드도 사람 코드와 같은 리뷰 및 테스트 경로를 지나나요?
AI가 만든 변경이라고 해서 리뷰를 생략하면 위험합니다. 반대로 AI 변경만 과도하게 별도 절차로 묶으면 도입이 느려집니다. 핵심은 작성자가 사람이든 AI든 동일한 품질 기준을 적용하는 것입니다.

설정 파일을 마지막으로 점검한 날짜를 알고 있나요?
모델과 도구가 빠르게 바뀌는 환경에서는 오래된 지시가 성능을 제한할 수 있습니다. 주요 모델 릴리스 이후에는 CLAUDE.md, 스킬, 훅, 권한 정책을 다시 보는 것이 좋습니다.

보안팀과 개발 생산성팀이 같은 지도를 보고 있나요?
Claude Code는 로컬 파일 시스템과 명령 실행에 가까운 도구이므로 생산성과 보안이 분리될 수 없습니다. MCP 서버, 플러그인, 승인 정책을 설계할 때 두 관점이 함께 들어가야 합니다.

PyTorchKR 독자를 위한 실무 적용 메모

AI 코딩 도구를 잘 쓰는 팀과 그렇지 않은 팀의 차이는 "얼마나 좋은 프롬프트를 아는가" 보다는 "코드베이스가 에이전트에게 읽히도록 준비되어 있는가" 에서 갈릴 가능성이 큽니다. 특히 머신러닝과 데이터 인프라 코드베이스는 Python 패키지, 실험 스크립트, 모델 체크포인트, 데이터 파이프라인, CUDA 확장, 노트북, 배포 코드가 한 저장소에 섞여 있는 경우가 많습니다. 이런 환경에서는 Claude Code에게 모든 파일을 열어보게 하는 대신, 어느 디렉터리가 학습 코드이고, 어느 디렉터리가 실험 산출물이며, 어느 명령으로 빠른 단위 테스트를 돌릴 수 있는지를 알려주는 것이 중요합니다.

예를 들어, PyTorch 프로젝트라면 torch 모델 정의, 데이터 로더, 학습 루프, 평가 스크립트, 배포 래퍼가 각각 어디에 있는지 루트 지도에 적어둘 수 있습니다. pytest 기반 빠른 테스트와 장시간 GPU 테스트를 구분하고, pre-commit 훅으로 포맷과 정적 검사를 자동화할 수도 있습니다. CUDA나 C++ 확장이 있다면 clangd 같은 LSP 설정을 붙이는 것이 코드 탐색 정확도를 높이는 데 도움이 됩니다.

또한 연구 코드와 제품 코드가 섞인 조직에서는 권한 정책이 중요합니다. Claude가 대용량 데이터셋, 비공개 모델 가중치, 실험 결과, 고객 데이터에 접근할 수 있는지 여부를 명확히 해야 합니다. MCP로 내부 문서나 실험 추적 시스템을 연결할 때도, 편의성보다 데이터 경계와 감사 가능성을 먼저 설계하는 것이 좋습니다.

결국 Anthropic의 이번 글은 Claude Code를 "똑똑한 터미널 도구" 로만 보지 말고, 개발 조직의 지식과 규칙을 실행 가능한 형태로 담는 인프라로 보라는 메시지에 가깝습니다. 잘 정리된 CLAUDE.md, 필요한 순간에만 열리는 스킬, 자동으로 실행되는 훅, 조직 차원에서 배포되는 플러그인, 심볼 단위 탐색을 돕는 LSP, 내부 시스템을 연결하는 MCP 서버가 함께 작동할 때, Claude Code는 대규모 코드베이스에서도 훨씬 덜 헤매고 더 일관된 결과를 낼 수 있습니다.

How Claude Code works in large codebases 소개 블로그

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~