대형 코드베이스에서 Claude Code 제대로 쓰는 법 — 원리부터 실전까지

 

 

안녕하세요! 갓대희 입니다.

수십만? 수백만? 줄 규모의 코드베이스를 처음 받았을 때의 막막함은 누구나 알 것 이다.

(개인 프로젝트, 간단한 서비스를 처음부터 만들땐 비교적 문제가 없지만 복잡한 규모의 프로젝트를 다루기 시작하면 막상 막막한 분들이 많은 것 같다.)

 

어디서부터 손을 대야 할지 몰라 find 명령을 반복하거나, 팀 문서를 뒤지거나, 동료에게 물어보는 시간이 의외로 길다. Claude Code는 이 문제를 "에이전틱 검색(agentic search)"이라는 방식으로 풀어낸다.

이 글에서는 Claude Code가 대형 코드베이스를 탐색하는 원리, 컨텍스트 윈도우를 관리하는 전략, CLAUDE.md 파일 설계 방법, 그리고 실전 시나리오에서 바로 꺼내 쓸 수 있는 명령 패턴까지 정리한다.

먼저 용어부터 가볍게 잡고 가자

• Agentic Search: RAG 인덱스 없이 파일 시스템을 직접 탐색하며 필요한 것을 찾는 방식
• Context Window(컨텍스트 윈도우): 모델이 한 번에 처리할 수 있는 최대 텍스트 크기
• CLAUDE.md: 세션 시작 시 자동 로드되는 프로젝트 지침 파일
• Harness(하네스): Claude Code가 대형 코드베이스를 다루기 위해 연결하는 도구 모음
• Subagent(서브에이전트): 메인 세션과 분리된 별도 컨텍스트로 실행되는 탐색 전담 인스턴스
• LSP: Language Server Protocol — 코드 편집기에 심볼 이동, 정의 찾기 같은 정밀 탐색 기능을 제공하는 표준 프로토콜
• MCP: Model Context Protocol — Claude Code가 외부 서비스 및 도구와 연결하기 위한 프로토콜
• Auto memory(자동 메모리): 세션 간 지식을 자동으로 축적하는 기능 (v2.1.59+)
• /compact: 컨텍스트를 수동으로 압축하는 내장 슬래시 명령
• DRI: 조직에서 Claude Code 설정을 단독으로 책임지도록 지정된 담당자 (Anthropic 공식 블로그가 제시한 최소 운영 단위)
• 에이전트 매니저(Agent Manager): Claude Code 생태계 운영을 전담하는 PM·엔지니어 혼합 직책

목차

1. Claude Code란 무엇인가 — 대형 코드베이스에서의 핵심 문제
2. 탐색 원리 — 에이전틱 검색과 하네스 구조
3. 컨텍스트 윈도우 관리 — 토큰 한계를 넘어서는 전략
4. CLAUDE.md — 프로젝트 지침 설계와 계층 구조
5. 낯선 코드베이스에서 시작하기 — 탐색 전략과 Plan Mode
6. 실전 사용 시나리오 — 버그 수정, 리팩토링, 기능 탐색
7. 제한사항과 흔한 실수 — 기대를 조정하는 법
8. 조직 차원의 도입과 운영 — DRI, 에이전트 매니저, 검수 문화
9. 트러블슈팅 Q&A

 

1. Claude Code란 무엇인가 — 대형 코드베이스에서의 핵심 문제

Claude Code는 터미널, VS Code, JetBrains IDE, 데스크탑 앱, 웹에서 모두 사용할 수 있는 AI 코딩 도구이다. 모든 환경에서 동일한 CLAUDE.md 파일, 설정, MCP 서버가 그대로 작동한다는 점이 특징이다.

 

대형 코드베이스에서 AI 도구가 가장 많이 실패하는 지점은 "컨텍스트 파악"이다. 코드베이스 전체를 한꺼번에 로드할 수 없으니, 어떤 파일을 어느 순서로 읽을지 결정하는 방식 자체가 결과의 질을 가른다.

 

전통적인 RAG 방식은 사전에 구축한 벡터 인덱스를 기반으로 관련 코드 조각을 검색한다.

문제는 타이밍이다. Anthropic 공식 블로그는 "개발자가 인덱스를 조회할 시점에 인덱스는 수 시간, 심지어 수 주 전의 코드베이스를 반영하고 있다"는 점을 지적한다.

빠르게 변하는 코드베이스에서 인덱스는 언제나 한 박자 늦다.

 

Claude Code는 이 문제를 다른 방식으로 접근한다. 인덱스 없이 파일 시스템을 직접 탐색하는 에이전틱 검색 방식을 채택한 것이다.

 

두 방식의 차이를 정리하면 다음과 같다.

구분	인덱스 기반 검색 (RAG)	에이전틱 검색 (Claude Code)
동작 방식	코드베이스 전체를 미리 임베딩해 인덱스로 만들고, 쿼리 시 관련 청크를 검색	인덱스 없이 그때그때 파일 시스템을 직접 탐색하고 grep으로 찾음
코드 최신성	인덱스가 수 시간~수 주 전 상태를 반영 — 조회 시점보다 한 박자 늦음	조회하는 시점의 실제 코드 상태를 그대로 반영
대규모 팀 확장성	수천 명이 커밋하면 임베딩 파이프라인이 따라가지 못해 실패할 수 있음	유지할 파이프라인이나 중앙 인덱스가 없어 이 실패 모드 자체를 피함

 

이 차이가 Anthropic 공식 블로그가 에이전틱 검색을 채택한 이유로 든 핵심이다 — 수천 명의 엔지니어가 새 코드를 커밋하는 환경에서는 유지해야 할 임베딩 파이프라인이 없다는 점 자체가 곧 안정성이 된다.

 

2. 탐색 원리 — 에이전틱 검색과 하네스 구조

에이전틱 검색: 인덱스 없이 파일을 찾는 방법

Claude Code의 탐색 방식은 숙련된 개발자가 낯선 코드베이스를 처음 분석할 때 하는 행동과 비슷하다.

Claude Code는 "파일 시스템을 탐색하고, 파일을 직접 읽고, grep으로 필요한 것을 정확히 찾고, 코드베이스 전반에 걸쳐 참조를 따라간다" — 이 모든 것을 별도의 인덱스 유지 없이 수행한다.

처음 맞닥뜨린 코드베이스에서는 넓게 훑은 다음 구체적인 곳으로 좁혀 들어가는 편이 훨씬 낫다. 에이전틱 검색이 그 흐름을 자연스럽게 따른다.

 

Claude Code 에이전틱 루프의 3단계

작업을 받으면 Claude Code는 세 단계를 반복한다

1. 컨텍스트 수집(Gather Context) — 관련 파일과 참조를 파악한다
2. 행동 실행(Take Action) — 코드를 편집하거나 명령을 실행한다
3. 결과 검증(Verify Results) — 테스트 실행이나 타입 체크로 의도대로 동작하는지 확인한다

이 세 단계는 직선이 아니라 혼합되어 반복된다. 탐색 중에 편집이 일어나고, 편집 후 다시 탐색이 필요해지는 식이다.

 

내장 도구 5가지 카테고리

카테고리	주요 기능
파일 작업(File operations)	파일 읽기, 코드 편집, 신규 파일 생성, 이름 변경 및 재구성
검색(Search)	패턴으로 파일 찾기, regex로 내용 검색, 코드베이스 탐색
실행(Execution)	셸 명령 실행, 서버 시작, 테스트 실행, git 사용
웹(Web)	웹 검색, 문서 가져오기, 에러 메시지 조회
코드 인텔리전스(Code intelligence)	편집 후 타입 에러 확인, 정의로 이동, 참조 찾기

grep과 ripgrep은 "검색" 카테고리의 핵심이다. 실제로 의외로 자주 막히는 부분이 ripgrep 바이너리 호환성 문제인데, 이는 7절 제한사항에서 다룬다.

 

하네스(Harness) 7가지 구성 요소

대형 코드베이스를 다루기 위한 Claude Code Harness는 7가지 구성 요소로 이루어져 있다:

구성 요소	역할
CLAUDE.md Files	세션 시작 시 자동 로드되는 프로젝트 지침
Hooks	특정 이벤트에 연결되는 자동화 액션
Skills	재사용 가능한 전문 지식 저장소
Plugins	기능 확장 모듈
LSP (Language Server Protocol)	심볼 수준의 정밀 탐색
MCP Servers	외부 서비스 및 도구 연결
Subagents	탐색 전담 격리 인스턴스

 

이 7가지를 어떻게 조합하느냐에 따라 동일한 코드베이스에서도 탐색 효율이 크게 달라진다.

LSP와 Subagents는 특히 주목할 만하다. LSP는 텍스트 패턴 매칭에서 발생하는 오탐을 줄여 심볼 수준의 정확한 탐색을 제공한다. Subagents는 탐색 작업을 독립된 컨텍스트에서 실행해 메인 세션의 컨텍스트 윈도우를 깨끗하게 보존한다.

⚠️ 중요한 주의사항: LSP 연동은 자동으로 되지 않는다. 이것이 흔한 실수 중 하나다 — LSP 서버를 별도로 배포해야 한다.

 

Hooks · Skills · Plugins — 자주 오해하는 세 가지

하네스 7요소 중 Hooks, Skills, Plugins는 흔히 한 줄로 요약되지만, 공식 블로그의 설명을 보면 실제 쓰임새는 그보다 넓다.

 

Hooks — 차단 장치가 아니라 개선 장치. 많은 팀이 Hooks를 'Claude가 잘못된 행동을 하지 못하게 막는 스크립트'로만 생각한다. 그러나 더 가치 있는 용도는 '지속적 개선'이다. 예를 들어 세션이 끝나는 시점에 실행되는 stop hook는 그 세션에서 무슨 일이 있었는지 되돌아보고, 컨텍스트가 아직 신선할 때 CLAUDE.md에 반영할 업데이트를 제안할 수 있다.

 

Skills — 필요할 때만 꺼내는 전문 지식. Skills는 progressive disclosure(점진적 공개) 방식으로 동작한다. 전문 워크플로와 도메인 지식을 평소에는 컨텍스트 밖에 두었다가, 그 작업이 실제로 필요해지는 순간에만 로드한다. 한정된 컨텍스트 공간을 불필요하게 차지하며 경쟁하지 않게 하는 것이다. 특정 경로에 스코프를 지정하면 해당 코드 영역에서만 활성화되도록 할 수도 있다.

 

Plugins — 묶어서 배포하는 패키지. 플러그인은 Skills, Hooks, MCP 설정을 하나의 설치 가능한 패키지로 묶는다. 잘 잡아 둔 설정 한 벌을 팀이나 조직 전체가 동일하게 설치해 쓸 수 있다는 뜻이다. 이 '공유' 성격은 8절의 조직 차원 운영으로 이어진다.

 

3. 컨텍스트 윈도우 관리 — 토큰 한계를 넘어서는 전략

왜 컨텍스트 관리가 핵심인가

모범 사례의 대부분이 단 하나의 제약에서 나온다고 명확히 말한다:

"Claude의 컨텍스트 윈도우는 빠르게 채워지고, 가득 찰수록 성능이 저하된다."

단일 디버깅 세션이나 코드베이스 탐색만으로도 수만 개의 토큰이 생성·소비될 수 있다.

컨텍스트 윈도우에는 대화 기록, 파일 내용, 명령 출력, CLAUDE.md, 자동 메모리, 로드된 스킬, 시스템 지침이 모두 쌓인다. 이 공간은 유한하다.

 

자동 압축(Auto-compact)의 동작 방식

컨텍스트가 한계에 가까워지면 Claude Code는 자동으로 대응한다.

1. 먼저 오래된 도구 출력을 제거한다
2. 필요하면 대화를 요약한다
3. 요청과 핵심 코드 스니펫은 보존된다
4. 초기 상세 지침은 손실될 수 있다

실제로 "지속해야 할 규칙은 대화 기록에 의존하지 말고 CLAUDE.md에 넣어라"는 원칙이 여기서 나온다.

Autocompact thrashing 경고

Autocompact is thrashing: the context refilled to the limit... 오류가 보이면, 하나의 파일이나 도구 출력이 너무 커서 압축 직후 컨텍스트가 다시 가득 찬 상태다. Claude Code는 무한 루프를 피하기 위해 재시도를 멈춘다. 이 경우 큰 파일이나 빌드 출력을 .claude/ignore에 추가하거나, 더 작은 범위로 작업을 쪼개야 한다.

 

수동 컨텍스트 관리 명령

자동 압축만으로 부족할 때는 직접 제어한다.

# 관련 없는 작업 사이에 컨텍스트 초기화
/clear

# 컨텍스트 수동 압축
/compact

# 포커스를 지정한 압축 (특정 변경사항에 집중)
/compact Focus on the API changes

 

/compact <지침> 형태가 단순 /compact보다 유용하다. 무엇을 중심으로 요약할지 명시하면 다음 작업에서 방향이 유지된다.

 

Subagents로 탐색 컨텍스트 분리하기

가장 효과적인 컨텍스트 보존 방법 중 하나는 탐색 작업을 Subagent에 위임하는 것이다.

"use subagents to investigate X"라고 지시하면 Subagent가 별도 컨텍스트에서 코드베이스를 탐색하고 파일을 읽은 뒤 결과만 메인 세션에 보고한다.

메인 대화는 구현에만 집중하고, 탐색의 잡음은 Subagent가 흡수한다. 탐색과 편집을 같은 세션에서 섞지 않는 것이 중요하다 — 이는 흔한 실수 목록에도 명시되어 있다.

 

4. CLAUDE.md — 프로젝트 지침 설계와 계층 구조

CLAUDE.md 파일의 위치별 범위

CLAUDE.md 파일은 여러 위치에 배치할 수 있으며, 위치에 따라 적용 범위가 다르다:

 

위치	파일 경로	범위
관리 정책	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)	조직 전체
사용자 지침	~/.claude/CLAUDE.md	모든 프로젝트 개인 설정
프로젝트 지침	./CLAUDE.md 또는 ./.claude/CLAUDE.md	팀 공유 프로젝트 설정
로컬 지침	./CLAUDE.local.md	개인 프로젝트별 설정 (.gitignore 권장)

 

루트 파일은 중요한 정보만 간결하게 유지하고, 디렉토리 계층을 이동할수록 추가 CLAUDE.md가 적재되는 "lean and layered" 구조가 권장된다.

 

CLAUDE.md에 포함할 것과 제외할 것

 

포함할 것:

• Claude가 코드만 봐서는 알 수 없는 Bash 명령
• 기본값과 다른 코드 스타일 규칙
• 테스트 지침 및 선호하는 테스트 러너
• 브랜치 명명, PR 컨벤션 같은 리포지토리 에티켓
• 프로젝트 고유의 아키텍처 결정사항
• 필수 환경 변수 같은 개발 환경 특이사항

제외할 것:

• Claude가 코드를 읽으면 스스로 파악할 수 있는 내용
• 이미 알고 있는 표준 언어 규칙
• 상세한 API 문서 (문서 링크로 대체)
• 자주 바뀌는 정보

 

CLAUDE.md 크기와 @import 문법

파일당 200줄 미만을 목표로 한다. 공식 문서에서는 "파일이 길어질수록 컨텍스트를 더 많이 소모하고 준수율이 떨어진다"고 명시하고 있다. 지침이 많아지면 path-scoped 규칙으로 분리해 해당 경로에서만 로드되도록 구성한다.

 

대규모 프로젝트에서 내용이 늘어날 때는 @import 문법이 유용하다:

# CLAUDE.md 내에서 외부 파일 가져오기
@path/to/shared-conventions.md
@.claude/architecture-notes.md

 

이렇게 가져온 파일들은 세션 시작 시 CLAUDE.md와 함께 컨텍스트에 로드된다.

공통 규칙은 한 파일에서 관리하고, 프로젝트별 CLAUDE.md에서 가져오는 패턴으로 중복을 줄일 수 있다.

 

CLAUDE.md 유지 관리 주기

주요 모델 릴리스 후 3~6개월마다 검토를 권장한다. 이때 두 가지를 확인하자:

1. 구형 모델 한계를 보완하기 위해 추가했던 지침 — 제거한다
2. 최신 기능을 오히려 제한하는 규칙 — 제거한다

모델이 업그레이드될수록 예전에 필요했던 세세한 지침이 오히려 방해가 되는 경우가 많다.

CLAUDE.md도 코드처럼 정기적으로 다이어트가 필요하다.

 

5. 낯선 코드베이스에서 시작하기 — 탐색 전략과 Plan Mode

첫 번째 세션: 넓게 훑고 좁혀가기

권장순서

# 1. 프로젝트 루트로 이동
cd /path/to/project

# 2. Claude Code 실행
claude

# 3. 고수준 개요 요청
give me an overview of this codebase

# 4. 특정 컴포넌트로 심화 탐색
explain the main architecture patterns used here
what are the key data models?
how is authentication handled?

 

이 순서대로 실행하면 전체 구조 파악 → 핵심 패턴 이해 → 특정 관심 영역 심화의 흐름이 자연스럽게 이어진다.

 

Plan Mode로 구현 전에 계획 검토하기

Shift+Tab을 두 번 누르면 Plan Mode에 진입한다.

이 모드에서 Claude는 먼저 코드베이스를 분석하고, 구현 계획을 대화로 설명한다.

계획을 검토하고 피드백을 주고받은 다음 실제 구현으로 넘어가는 2단계 접근 방식이다.

처음이라면 복잡한 기능 추가나 리팩토링 작업 전에 반드시 Plan Mode를 거치는 습관을 들이는 편이 낫다. "바로 코드로 뛰어들기"보다 계획 단계에서 방향을 맞추는 편이 훨씬 효율적이다.

 

코드베이스를 탐색 가능하게 만드는 설정

설정	방법	효과
하위 디렉토리 초기화	저장소 루트 대신 하위 디렉토리에서 claude 실행	불필요한 파일 탐색 범위 제한
테스트/린트 범위 지정	CLAUDE.md에 서브디렉토리별 명령 명시	관련 없는 빌드 출력 차단
생성 코드 제외	.claude/ignore에 자동 생성 파일 경로 추가	노이즈 감소
코드베이스 맵 구축	비전통적 구조에 CLAUDE.md에 맵 기술	구조 이해 지원
LSP 서버 배포	언어별 LSP 서버 설정	심볼 기반 정밀 탐색

 

"비전통적 구조"란 게임 엔진 바이너리 에셋, 일반적이지 않은 버전 관리, 비개발자 기여자 환경 등을 말한다. 이런 경우에는 표준 설정만으로는 부족하고 추가 커스터마이징이 필요하다.

 

6. 실전 사용 시나리오 — 버그 수정, 리팩토링, 기능 탐색

시나리오 1: 버그 수정

1. 오류 메시지를 Claude에 공유
   → "npm test를 실행하면 이 에러가 나온다"

2. 수정 방안 요청
   → "user.ts의 @ts-ignore를 수정하는 방법 몇 가지를 제안해줘"

3. 수정 적용
   → "user.ts에 null 체크를 추가해줘"

4. 이슈 재현 명령과 스택 트레이스 제공으로 검증

 

에러 메시지와 재현 명령을 함께 제공하는 것이 핵심이다.

Claude가 직접 테스트를 실행해서 수정 결과를 확인할 수 있어야 루프가 빠르게 돈다.

 

시나리오 2: 레거시 코드 리팩토링

1. 레거시 코드 식별
   → "우리 코드베이스에서 deprecated API 사용 부분을 찾아줘"

2. 리팩토링 권장사항 요청
   → "utils.js를 모던 JavaScript 기능으로 리팩토링하는 방법을 제안해줘"

3. 안전하게 적용
   → "utils.js를 ES2024 기능으로 리팩토링하되 동작은 그대로 유지해줘"

4. 테스트로 검증
   → "리팩토링된 코드의 테스트를 실행해줘"

 

"동작은 그대로 유지"라는 조건을 명시하는 것이 중요하다. Claude가 임의로 로직을 변경하는 것을 방지한다.

 

시나리오 3: 새로운 코드베이스 파악

처음에는 "이 코드베이스 개요를 설명해줘"처럼 넓은 질문으로 시작하고,

"인증은 어떻게 처리되는가?", "핵심 데이터 모델은 무엇인가?" 순서로 좁혀가는 것이 효과적이다.

한 번에 모든 걸 파악하려 하면 컨텍스트만 낭비된다.

 

시나리오 4: 신규 기능 추가 — Explore → Plan → Implement → Commit

새 기능을 추가할 때 바로 구현으로 뛰어드는 것은 대형 코드베이스에서 잘못된 방향으로 작업하는 가장 빠른 길이다.

1단계: Explore (Plan mode 진입)
   → "read /src/auth and understand how we handle sessions and login.
      also look at how we manage environment variables for secrets."

2단계: Plan (구현 계획 수립)
   → "I want to add Google OAuth.
      What files need to change? What's the session flow? Create a plan."

3단계: Implement (Plan mode 해제 후 구현)
   → "implement the OAuth flow from your plan.
      write tests for the callback handler, run the test suite and fix any failures."

4단계: Commit (커밋 및 PR 생성 요청)
   → "commit with a descriptive message and create a PR."

 

Plan mode(Shift+Tab 두 번 또는 claude --permission-mode plan)에서 Claude는 파일을 읽고 분석만 하며, 승인 전까지 어떤 파일도 수정하지 않는다. Ctrl+G를 누르면 계획을 텍스트 에디터에서 직접 편집한 뒤 Claude가 진행하도록 할 수도 있다.

 

대형 기능이라면 먼저 Claude에게 인터뷰를 진행하게 하는 방법도 있다.

AskUserQuestion 도구를 사용해 기술 구현, UI/UX, 엣지 케이스, 트레이드오프를 물어보게 한 뒤, 완성된 스펙을 SPEC.md로 작성하게 하고 새 세션에서 구현을 시작하는 패턴이다.

 

테스트는 구현과 함께 가는 편이 낫다. Claude는 프로젝트의 기존 테스트 파일을 분석해 동일한 스타일, 프레임워크, 어서션 패턴으로 테스트를 생성한다. "write tests for the callback handler, run the test suite and fix any failures(callback handler 테스트를 추가한 다음, 테스트 suite를 돌려보고 실패하는 부분이 있으면 고쳐줘.)"처럼 테스트 실행까지 한 번에 지시하면 Claude가 실패를 직접 수정하는 루프가 돈다.

 

7. 제한사항과 흔한 실수 — 기대를 조정하는 법

구조적 제한: 컨텍스트 윈도우

가장 근본적인 제약은 컨텍스트 윈도우다.

단일 디버깅 세션이나 코드베이스 탐색만으로도 수만 개의 토큰이 소비될 수 있고, 컨텍스트가 가득 찰수록 성능이 저하된다.

 

Claude Code가 대형 코드베이스에서 잘 못 하는 것:

• 전체 코드베이스를 한 번에 파악하는 작업 — 컨텍스트가 빠르게 차고 성능이 저하된다
• 단일 세션에서 탐색과 편집을 계속 반복하는 작업 — Subagents로 분리해야 한다

 

흔한 설정 실수 5가지

1. CLAUDE.md에 재사용 전문 지식을 넣기 → Skills를 사용해야 할 내용이다
2. 모든 것을 CLAUDE.md에 로드하기 → Skills와 계층적 CLAUDE.md로 분산해야 한다
3. LSP 연동이 자동으로 된다고 가정하기 → LSP 서버는 별도로 배포해야 한다
4. 기초가 작동하기 전에 MCP 연결 구축하기 → 단계적으로 설정한다
5. 탐색과 편집을 같은 세션에서 실행하기 → Subagents로 분리한다

이 중 3번과 5번이 실전에서 가장 자주 실수가 나오는 지점이다.

 

환경별 제한사항: WSL과 ripgrep

1. ripgrep 바이너리 호환성: 번들된 ripgrep이 일부 시스템에서 실행되지 않을 수 있다. Search 도구, @file 멘션, 커스텀 에이전트, 커스텀 스킬이 파일을 찾지 못하면 이 문제를 의심한다.
2. WSL 파일 시스템 간 작업: WSL에서 서로 다른 파일 시스템 간 작업 시 디스크 읽기 성능 저하로 검색 결과가 불완전할 수 있다.

 

적용 범위: 어떤 환경에서 이 패턴이 동작하는가

이 패턴들이 표준 디렉토리 구조의 일반적인 Git 기반 환경에 적용된다고 명시한다. 게임 엔진 바이너리 에셋, 비전통적 버전 관리, 비개발자 기여자가 있는 환경은 추가 커스터마이징이 필요하다.

 

8. 조직 차원의 도입과 운영 — DRI, 에이전트 매니저, 검수 문화

여기까지는 개발자 한 사람이 Claude Code를 잘 쓰는 방법이었다.

그런데 이 글이 토대로 삼은 Anthropic 공식 블로그의 제목은 "best practices and where to start"다.

'where to start' — 팀과 조직이 어디서부터 시작해야 하는가 — 가 글의 큰 축을 차지한다.

도구를 능숙하게 다루는 것과, 그 도구를 조직의 표준으로 정착시키는 것은 별개의 문제다.

유능한 신입 사원 한 명을 뽑아도, 회사에 업무 매뉴얼도 사수도 검수 절차도 없다면 그 역량은 개인 안에 갇힌다. Claude Code도 같다. 도구의 잠재력이 아무리 커도, 그것이 팀의 실제 성과로 이어질지는 조직이 갖춘 교육·관리 체계가 결정한다.

 

왜 조직 차원의 운영이 필요한가

Claude Code 도입은 보통 현장 개발자들이 자발적으로 시작한다(bottoms-up).

공식 블로그는 이런 방식이 열정을 만들어내지만, 무엇이 잘 작동하는지를 중앙에서 모아 줄 사람이 없으면 파편화될 수 있다고 지적한다.

그 정리 작업이 없으면 노하우는 특정 개인·팀 안에만 머무는 'tribal knowledge'로 남고, 도입은 어느 선에서 정체(plateau)된다.

해결책 자체는 단순하다.

한 개인 또는 한 팀이 잘 작동하는 Claude Code 컨벤션을 모으고, 조직 전체에 적극적으로 전파(evangelize)하는 것이다.

같은 팀의 누군가가 찾아낸 좋은 설정이 그 사람 노트북에만 남지 않게 만드는 일이다.

 

DRI와 에이전트 매니저 — 누가 책임지는가

공식 블로그는 이 책임을 맡는 형태를 두 가지로 제시한다.

조직 규모와 성숙도에 따라 골라 쓰면 된다.

구분	DRI	에이전트 매니저 (Agent Manager)
적용 조직	전담 팀을 두기 어려운 조직의 최소 형태	여러 조직에서 떠오르고 있는 본격적 역할
정의	Claude Code 설정에 대한 ownership을 가진 한 사람	Claude Code 생태계 관리를 전담하는 PM·엔지니어 혼합 직책
책임 범위	설정, 권한 정책, 플러그인 마켓플레이스, CLAUDE.md 컨벤션을 소유하고 최신 상태로 유지	같은 범위를 전담 업무로 수행하며, 컨벤션 수립과 조직 내 확산을 주도
성격	"이건 내가 책임진다"가 분명한 담당자 1명	기획(PM)과 기술 이해(엔지니어)를 함께 갖춘 신규 직무

핵심은 직책 이름이 아니라 'ownership이 한 곳에 모여 있는가'다.

설정을 아무도 책임지지 않으면 4절에서 다룬 3~6개월 주기 검토도, 컨벤션 전파도 실제로는 실행되지 않는다. 담당자가 비어 있는 일은 결국 아무 일도 일어나지 않는다.

 

AI가 작성한 코드의 검수 — 인간 코드와 같은 기준

조직 규모가 커지면, 특히 규제 산업에서는 거버넌스 질문이 일찍 등장한다. 공식 블로그가 그대로 인용한 질문은 이렇다.

"AI가 생성한 코드가 인간이 작성한 코드와 동일한 리뷰 프로세스를 거치도록 어떻게 보장할 것인가?"

블로그가 권장하는 답은 한꺼번에 모든 문을 여는 것이 아니라 단계적으로 넓히는 것이다.

1. 승인된 Skills 집합을 먼저 정의한다
2. 코드 리뷰 프로세스를 필수 절차로 건다
3. 초기 접근 범위를 제한해서 시작한다
4. 신뢰가 쌓이는 만큼 범위를 확대한다

요지는 분명하다. AI가 만든 코드라고 검수를 건너뛰지 않는다.

동료 엔지니어의 PR과 똑같은 리뷰 라인을 통과시키는 것 — 블로그가 거버넌스 질문에 내놓은 답의 핵심이 여기에 있다.

 

도입 플레이북

오늘 바로 할 수 있는 것:

1. 하나의 프로젝트 루트에 CLAUDE.md 생성 — 200줄 제한으로 핵심 정보만
2. 낯선 코드베이스라면 give me an overview of this codebase로 시작
3. /clear 명령을 작업 전환 습관으로 만들기

이번 주 안에 설정할 것:

1. .claude/ignore에 빌드 디렉토리와 생성 코드 추가
2. 자주 쓰는 탐색 패턴을 Skills로 분리 (CLAUDE.md에서 덜어내기)
3. Plan Mode 습관화 — 복잡한 작업 전에 Shift+Tab 두 번

팀 환경에 반영할 것:

1. Claude Code 설정을 책임질 DRI를 한 명 지정 — 전담 팀이 가능하면 에이전트 매니저 역할로 키운다
2. 조직 수준 CLAUDE.md와 프로젝트 수준 CLAUDE.md 계층 분리
3. 개인 설정은 CLAUDE.local.md + .gitignore로 분리
4. AI가 생성한 코드도 인간 코드와 동일한 코드 리뷰 라인을 통과하도록 검수 절차 수립
5. 주요 모델 릴리스 후 3~6개월 주기로 CLAUDE.md 검토 일정 등록

 

9. 트러블슈팅 Q&A

Q. 컨텍스트가 계속 금방 가득 찬다

A. 세 가지를 확인한다:

• /compact를 정기적으로 사용한다
• 주요 작업 사이에 Claude Code를 재시작한다
• 큰 빌드 디렉토리를 .gitignore에 추가한다

Q. "Autocompact is thrashing" 오류가 발생한다

A. 하나의 파일이나 도구 출력이 너무 커서 압축 직후 컨텍스트가 다시 가득 찬 상태다. .claude/ignore에 대용량 파일 경로를 추가하거나 작업 범위를 더 작게 쪼개야 한다.

Q. 검색 도구가 파일을 못 찾는다

A. 번들된 ripgrep 바이너리가 해당 시스템에서 실행되지 않을 가능성이 있다. WSL 환경이라면 파일 시스템 간 경계를 넘는 작업인지도 확인한다.

Q. CLAUDE.md 지침을 무시하는 것 같다

A. 파일이 200줄을 넘지 않는지 확인한다. 길어질수록 준수율이 떨어진다. 지침이 많다면 path-scoped 규칙으로 분산하거나 @import 문법으로 외부 파일로 빼낸다.

Q. Auto memory를 사용하려면 어떻게 해야 하나

A. Claude Code v2.1.59 이상이 필요하다. claude --version으로 버전을 확인하고, MEMORY.md의 처음 200줄 또는 25KB 중 먼저 도달하는 범위가 세션 시작 시 자동으로 로드된다.

Q. Claude Code를 팀 전체에 도입하려면 어디서부터 시작해야 하나

A. 먼저 설정을 책임질 DRI를 한 명 지정한다. 전담 팀을 둘 수 있다면 PM과 엔지니어 역량을 함께 갖춘 에이전트 매니저 역할로 키운다. 그다음 승인된 Skills 집합과 필수 코드 리뷰 절차를 정하고, 제한된 접근 범위로 시작해 신뢰가 쌓이는 만큼 확대한다.

 

Claude Code의 대형 코드베이스 지원은 도구 하나를 쓰는 것이 아니라 탐색 방식 자체를 재설계하는 과정에 가깝다. 에이전틱 검색, 계층적 CLAUDE.md, Subagents를 통한 컨텍스트 분리 — 이 세 가지 원리를 이해하면 나머지 모범 사례들이 자연스럽게 맞아 들어간다.

 

그리고 팀 단위로 넘어가면 기술 설정만으로는 부족하다. DRI나 에이전트 매니저처럼 설정을 책임지고 전파하는 역할이 있어야, 개인이 찾아낸 노하우가 조직의 표준으로 자리 잡는다. 좋은 도구를 들이는 데서 멈추지 않고 그 도구가 제 역량을 펼칠 운영 체계까지 함께 설계하는 것 — 원본 블로그가 말한 'where to start'의 진짜 의미는 거기에 있다.

---

작성일: 2026-05-19
분석 대상 버전: Claude Code (2026-05-19 기준 공식 문서)
면책 조항: 이 글은 2026-05-19 기준으로 작성되었다. 이후 변경될 수 있다.

참고 자료

• Anthropic 공식 블로그 — How Claude Code works in large codebases: best practices and where to start
• Claude Code 공식 문서 — Overview
• Claude Code 공식 문서 — How Claude Code Works
• Claude Code 공식 문서 — Best Practices
• Claude Code 공식 문서 — Memory & CLAUDE.md
• Claude Code 공식 문서 — Common Workflows
• Claude Code 공식 문서 — Troubleshooting