대규모 코드베이스를 위한 Claude Code 구축 패턴

How Claude Code works in large codebases: Best practices and where to start을 읽고, 정리해보자.

 

하네스 구성 요소

요소	설명	자료
CLAUDE.md 파일	클로드가 실행될 때 자동으로 읽는 컨텍스트를 말한다. 전체 맥락을 다루는 루트 경로의 파일과, 하위 파일들로 구성된다. 세션이 실행될 때마다 로드되어서, 너무 길지 않게 작성해야 한다.	memory
훅(hooks)	hook을 사용하면 지속적으로 클로드를 사용하는 방법을 개선할 수 있다. 보통 훅은 클로드코드가 잘못된 방향으로 가는걸 막는데 사용한다고 생각할 수 있다. stop hook은 컨텍스트가 살아있는 상황에서 세션 내에 있었던 어려움을 분석하고, CLAUDE.md 개선을 제안하는데 활용할 수 있다. start hook은 팀별 컨텍스트를 자동으로 읽어서, 개발자들이 수동 설정 없이 개발 환경을 자동으로 셋팅하는데 활용할 수 있다. 그리고 훅에 린트나 포맷팅 같은 것들을 적용하면 일관되고 정확한 결과를 얻을 수 있다. 클로드가 지시사항을 기억하고 구현하는 것보다 더 일관된 결과물을 얻을 수 있다.	hooks-guide
스킬(skills)	스킬은 필요할 때 전문 지식을 로드할 수 있게 하는 역할을 담당한다.  많은 작업 유형이 포함된 규모 코드베이스에서는 모든 세션에 모든 전문 지식이 포함될 필요가 없다.  스킬은 점진적 공개 방식을 통해 이 문제를 해결할 수 있다.  예를 들어, 클로드가 코드의 취약점을 평가할 때는 보안 검토 스킬이 로드되는 방식으로 사용된다.	skills
플러그인(plugins)	플러그인은 skills, hooks, MCP 구성을 하나의 패키지로 묶어준다. 검증된 기능을 한번에 배포할 때 사용할 수 있다. 예를 들어, 신규입사자가 팀에 들어왔을 때, 플러그인 하나로 동일한 하네스 엔지니어링 구성을 할 수 있다.	plugins
Language Server Protocol (LSP)	프로젝트 소스 코드를 단순한 '텍스트 뭉치'가 아니라, 정밀한 구조적 맥락(Semantic Context)으로 이해할 수 있도록 컴파일러 수준의 도구들과 연결하는 기능을 말한다.  LSP은 AI 에이전트가 대규모 프로젝트의 복잡한 의존성을 완벽하게 파악한 상태에서 정확한 리팩토링, 정밀한 버그 수정, 신속한 코드 탐색을 수행하도록 만든다.
MCP 서버	LLM이 외부 도구와 연결할 수 있게 해준다.  예를 들어, 자연어로 데이터베이스를 질의하거나 API를 호출할 수 있게 하는 역할을 담당한다.
서브 에이전트	서브에이전트는 독립적인 컨텍스트를 가진 인스턴스다. 서브 에이전트는 작업을 받아서 처리한 후, 부모 에이전트에게 결과를 전달한다.	sub-agents

 

성공적인 배포를 이끈 세 가지 구성 패턴

1. 대규모 환경에서 코드베이스를 탐색 가능하게 만들기

CLAUDE.md 파일은 짧고, 계층적으로 유지하기	Claude는 코드베이스를 이동하면서 이 파일들을 누적하여 로드한다. 즉, 루트 파일은 큰 그림을 보여주고, 하위 디렉터리 파일은 로컬 컨벤션을 보여줘야 한다. 루트 파일에는 전체적인 포인터와 주요한 주의 사항만 남겨두어야 한다.
하위 디렉터리별로 테스트 및 린트 명령어 제한하기	Claude가 단 하나의 서비스를 수정했을 뿐인데 전체 테스트를 실행하게 만들면, 타임아웃이 발생하고 무관한 출력으로 인해 컨텍스트 공간을 낭비하게 된다. 하위 디렉터리 수준의 CLAUDE.md 파일에 해당 코드베이스 영역에만 적용되는 구체적인 명령어를 명시해야 한다. 이는 각 디렉터리가 자체 빌드 및 테스트 명령어를 갖는 서비스 지향(Service-oriented) 코드베이스에서 특히 잘 작동한다.
.claude/settings.json 파일을 버전관리 시스템으로 관리하기	.claude/settings.json에 permissions.deny 규칙을 커밋해 두면 이러한 제외 규칙이 버전 관리 시스템(Git 등)을 통해 공유된다. 그러면  팀 내 모든 개발자가 별도의 설정 없이도 동일한 환경에서 노이즈 없이 AI를 사용할 수 있다.
디렉터리 구조가 역할을 못 할 때는 '코드베이스 맵' 만들기	코드가 전통적인 디렉터리 구조로 통합되어 있지 않은 조직의 경우, 레포 루트에 각 최상위 폴더와 그 안에 무엇이 들어있는지 한 줄로 설명한 가벼운 마크다운 파일을 작성해 두는 것이 좋다.
LSP 서버를 구동하여 문자열이 아닌 '심볼'로 검색하게 하기	대규모 코드베이스에서 흔히 쓰이는 함수 이름을 grep으로 검색하면 수천 개의 일치 항목이 반환되며, Claude는 어떤 것이 진짜 중요한지 파악하기 위해 파일을 열어보느라 컨텍스트를 소진하게 된다.  반면 LSP는 동일한 심볼을 가리키는 참조만 반환하므로, Claude가 내용을 읽기 전에 이미 필터링이 완료된다.

2. CLAUDE.md 파일 관리

클로드코드 모델이 새로 출시되면, 과거 모델을 기준으로 작성했던 CLAUDE.MD가 신규 모델의 성능에 제약을 줄 수도 있다. 더이상 CLAUDE.MD에 작성된 지침이 유효하지 않을 수도 있다. 그래서 팀들은 3~6개월마다 한 번씩 Configuration review를 하는 것이 좋다. 

3. Claude Code 관리 및 도입을 위한 전담 책임 부여

AI를 전사적으로 도입하려면 기술 뿐만 아니라 조직 레이어에서 투자해야 한다. AI 도입이 가장 빠르게 확산된 곳들은 AI 접근 권한을 열어주기 전에 인프라 투자를 선행했던 조직들이었다. 몇 명의 개발자들이 미리 플러그인과 MCP 등을 미리 구축해두어서, AI를 오픈했을 때 다들 빠르게 사용할 수 있었다. 

이런 작업을 선행하는 조직은 보통 개발자 경험(Developer Experience, DX) 또는 개발자 생산성(Developer Productivity) 부서에 속해있다. 이런 부서는 일반적으로 신규 엔지니어 온보딩과 개발자 툴링 구축을 담당하는 조직이다. 

전담 팀을 꾸릴 여력이 없는 조직이라면, 최소한의 실현 조직이라면, DRI(Direct Responsible Individual, 직접 책임자)를 지정하는 것이 좋다. 이 책임자는 Claude Code 구성, 설정 및 권한 정책에 대한 의사결정 권한, 플러그인 마켓플레이스 및 CLAUDE.md 컨벤션 관리 권한을 가지며, 이를 항상 최신 상태로 유지할 책임을 진다.

바텀업(Bottoms-up) 방식의 도입은 개발자들의 열정을 불러일으키지만, 효과적인 모범 사례를 중앙에서 취합해 주지 않으면 파편화되기 쉽다. 따라서 표준화된 CLAUDE.md 계층 구조나 엄선된 스킬 및 플러그인 세트와 같은 올바른 Claude Code 컨벤션을 조합하고 전파할 개인이나 팀이 반드시 필요하다. 이러한 작업이 없다면 지식은 특정 개인이나 팀 내에만 머무르게 되어 AX 도입이 정체되게 된다. 

 

참고

• https://github.com/walkinglabs/awesome-harness-engineering
• https://walkinglabs.github.io/learn-harness-engineering/ko/lectures/lecture-01-why-capable-agents-still-fail/
• https://walkinglabs.github.io/learn-harness-engineering/ko/projects/