설정 드리프트 (Configuration Drift)의 비용: 15명의 엔지니어가 공유된 설정 없이 Claude Code를 실행하면, 각 세션은 서로 다른 코드 스타일, 명명 규칙 (naming conventions), 그리고 아키텍처 패턴을 생성합니다. 이로 인한 실질적인 결과는 대규모 환경에서의 출력 변동성 (output variance)입니다. 동일한 리팩토링 (refactoring) 작업이 일관되지 않은 결과를 초래하여, 리뷰 사이클을 배가시키고 전달 속도를 늦춥니다.

CLAUDE.md 파일은 저장소 루트 (repository root)에 위치하며, Claude Code가 해당 프로젝트에서 어떻게 동작해야 하는지 지시하는 설정 문서입니다. 이 파일은 어떤 규칙을 따를지, 어떤 디렉토리를 피해야 할지, 어떤 명령에 인간의 검토가 필요한지, 그리고 변경 사항이 완료되었다고 간주되기 전에 어떤 테스트 요구 사항이 적용되는지를 정의합니다. 이 파일이 없으면 Claude Code는 기본값 (defaults)에 따라 작동하며, 그 기본값들은 여러분의 기술 스택 (stack), 표준, 또는 고객과의 약속에 대해 전혀 알지 못합니다.

CLAUDE.md가 없을 때 발생하는 실질적인 결과는 대규모 환경에서의 출력 변동성입니다. 공유된 설정 없이 Claude Code를 실행하는 15인 규모 팀의 각 엔지니어는 사실상 임시 프롬프트 (ad hoc prompts)와 개인적인 습관을 통해 자신만의 규칙을 설정하고 있는 것입니다. 동일한 리팩토링 작업이 서로 다른 스타일로 다른 결과를 만들어냅니다. 프로젝트 수준의 CLAUDE.md는 프로젝트 내의 모든 세션, 모든 기기, 그리고 모든 엔지니어에 걸쳐 일관된 동작의 하한선을 설정함으로써 그러한 변동성을 제거합니다.

CLAUDE.md 파일이 위치하는 곳

Claude Code는 서로 다른 범위를 가진 세 가지 위치에서 지침 파일을 읽습니다.

**저장소 루트 (repository root)**는 주요 CLAUDE.md가 위치해야 하는 곳입니다. 이는 팀원 모두가 저장소 내부에서 Claude Code를 실행할 때 자동으로 가져가게 되는 프로젝트 수준의 파일입니다. 이 파일은 다른 설정 파일과 마찬가지로 버전 관리 (version control) 시스템에 커밋되므로, 변경 사항이 검토되고 버전이 관리되며 가시성을 갖게 됩니다.

하위 디렉터리(Subdirectory) CLAUDE.md 파일은 코드베이스의 특정 부분에 대해 루트(root) 파일을 재정의(override)하거나 확장할 수 있습니다. 만약 모노레포(monorepo) 내의 백엔드 서비스가 프론트엔드와 다른 컨벤션(convention)을 사용한다면, 각 하위 디렉터리에 고유한 지침을 담을 수 있습니다. Claude Code는 현재 작업 중인 파일에 따라 이러한 문맥(context)을 병합합니다.

사용자 홈 디렉터리(~/.claude/CLAUDE.md)는 개발자 머신의 모든 레포지토리(repo)에 적용되는 개인적 선호도를 저장합니다. 이곳은 개인적인 스타일 선호도, 도구 설정(tool configuration), 또는 개인적인 컨벤션을 위한 적절한 장소입니다. 이는 버전 관리(version control)에 포함되어서는 안 되며, 프로젝트 수준의 규칙을 재정의해서도 안 됩니다.

10명에서 20명 규모의 엔지니어링 팀에게는 레포지토리 루트에 있는 프로젝트 수준의 파일이 가장 중요합니다. 거기서부터 시작하세요.

CLAUDE.md에 포함되어야 할 내용

목표는 Claude Code가 매번 프롬프트(prompt)를 요구하지 않고도 좋은 로컬 결정을 내릴 수 있도록 충분한 문맥(context)을 제공하는 것입니다. 여기에는 네 가지 핵심 카테고리가 있습니다.

**프로젝트 문맥 (Project context)**은 코드베이스가 무엇인지, 어떤 역할을 하는지, 그리고 어떻게 구조화되어 있는지를 다룹니다. Claude Code는 자신이 Django 모놀리스(monolith)에서 작업 중인지, 별도의 API 레이어가 있는 Next.js 프론트엔드에서 작업 중인지, 아니면 마이크로서비스 아키텍처(microservices architecture)에서 작업 중인지를 알아야 합니다. 주요 디렉터리, 주요 언어 및 프레임워크 버전, 그리고 코드가 작성되는 방식에 영향을 미치는 모든 아키텍처 결정 사항을 포함하세요.

**코딩 컨벤션 (Coding conventions)**은 팀이 이미 리뷰를 통해 강제하고 있는 규칙들입니다. 명명 규칙(naming conventions), 파일 구조에 대한 기대치, 비동기 처리(async handling)를 위한 선호 패턴, 주석 관련 규칙, 그리고 포맷팅 표준이 모두 여기에 해당합니다. 특정 설정으로 ESLint를 실행한다면 이를 명시하세요. 의존성 주입(dependency injection)에 특정 방식을 사용한다면 이를 문서화하세요. Claude Code는 주변 코드를 통해 추론하는 것보다 명시적인 컨벤션을 따를 때 훨씬 더 신뢰할 수 있습니다.

**테스트 접근 방식 (Testing approach)**는 팀이 테스트를 작성하고 실행하는 방법을 Claude에게 알려줍니다. 어떤 프레임워크를 사용하나요? 구현과 함께 테스트를 작성하나요, 아니면 구현 후에 작성하나요? 재사용해야 할 테스트 유틸리티(test utilities)나 팩토리(factories)가 있나요? 테스트 파일에 대한 명명 규칙(naming convention)이 있나요? 이것이 없다면, Claude는 모델에게 자연스럽게 느껴지는 스타일로 테스트를 생성할 것이며, 이는 귀하의 CI 파이프라인(CI pipeline)이 기대하는 방식과 일치하지 않을 수 있습니다.

**금지된 작업 (Prohibited actions)**은 명시적인 제약 사항입니다. 여기에는 다음과 같은 내용이 포함될 수 있습니다: 데이터베이스 마이그레이션(database migration) 파일을 직접 수정하지 말 것, 알리지 않고 새로운 제3자 종속성(third-party dependencies)을 추가하지 말 것, 에러 로깅(error logging)을 제거하지 말 것, 현재 작업 범위를 벗어난 코드를 리팩터링(refactor)하지 말 것. 금지된 작업은 리뷰 과정에서 찾아내기 가장 어려운, 의도는 좋지만 실수하기 쉬운 Claude의 오류 유형을 방지하는 지점입니다.

10~20명 규모의 팀을 위한 파일 구조화

길이가 중요합니다. 500줄에 달하는 CLAUDE.md 파일은 컨텍스트 압박(context pressure)이 증가할 때 모델에 의해 무시되거나, 부분적으로 읽히거나, 조용히 우선순위에서 밀려납니다. 완결성보다는 명확성을 목표로 하세요.

중규모 엔지니어링 팀을 위한 실용적인 구조는 다음과 같습니다: 프로젝트와 기술 스택(stack)에 대한 2~3문장의 설명으로 시작합니다. 이어서 영역별(명명, 구조, 비동기(async), 에러 처리)로 그룹화된 코딩 컨벤션(coding conventions)의 글머리 기호 목록을 작성합니다. 짧은 테스트 섹션을 추가합니다. 마지막으로 "금지된 작업(Prohibited Actions)" 또는 "엄격한 규칙(Hard Rules)" 헤더 아래에 강력한 제약 사항 목록을 배치하며 마무리합니다.

규칙 역할을 하는 모든 항목에는 산문(prose)보다는 글머리 기호(bullet points)를 사용하세요. Claude Code는 특정 코드 변경 사항에 규칙을 적용할 때 단락 형태의 지침보다 구조화된 목록을 더 안정적으로 파싱(parse)합니다.

파일을 300줄 이내로 유지하세요. 만약 그 이상으로 늘어난다면, 일부 내용이 특정 모듈을 위한 하위 디렉터리 파일에 속해야 하는 것은 아닌지, 아니면 AI 설정을 통해 문서화 문제를 해결하려고 하는 것은 아닌지 검토해 보세요.

효과를 떨어뜨리는 흔한 실수들

너무 모호함 (Too vague): "모범 사례(best practices)를 따르세요" 또는 "클린 코드(clean code)를 작성하세요"라고 쓰는 것은 Claude에게 실행 가능한 정보를 전혀 주지 못합니다. 당신의 맥락에서 모범 사례가 무엇을 의미하는지 구체적으로 명시하세요. "기본 내보내기(default exports) 대신 이름 있는 내보내기(named exports)를 사용하세요"는 Claude가 적용할 수 있는 규칙입니다. "클린 코드를 작성하세요"는 그렇지 않습니다.

아키텍처 변경 후 업데이트하지 않음: CLAUDE.md가 6개월 전에 이미 사용 중단한 스택을 설명하고 있다면, 이는 오히려 부담(liability)이 됩니다. 소유권을 할당하세요. 팀 리드가 아키텍처 변경 사항을 머지(merge)할 때, CLAUDE.md를 업데이트하는 것은 별도의 후속 작업이 아니라 동일한 풀 리퀘스트(pull request)의 일부여야 합니다.

전역(global) 설정과 프로젝트(project) 설정의 혼동: 개인적인 선호도(선호하는 터미널 도구, 개인적인 스타일 선택 등)는 프로젝트 레벨 파일이 아닌 홈 디렉토리 파일에 있어야 합니다. 이를 섞어 놓으면 모델에게 노이즈를 추가하고, 해당 선호도를 공유하지 않는 팀원들에게 마찰을 일으킵니다.

자율적 행동의 범위 누락: 팀이 긴 작업에 대해 에이전트 모드(agentic mode)로 Claude Code를 사용한다면, CLAUDE.md에는 Claude가 인간의 확인 없이 수행할 수 있는 일과 수행해서는 안 되는 일을 명시적으로 기술해야 합니다. 프롬프트 없이 테스트를 실행하는 것은 괜찮습니다. 파일을 삭제하는 것은 안 됩니다. 이를 명시적으로 기술하세요.

실무에서의 전역(Global) vs 프로젝트(Project) 구분

대부분의 엔지니어링 팀에게 가장 명확한 멘탈 모델(mental model)은 다음과 같습니다: ~/.claude/CLAUDE.md에 있는 전역 파일은 개발자로서의 당신 자신에 대해 Claude에게 알려주는 내용입니다. 리포지토리 루트(repo root)에 있는 프로젝트 파일은 Claude가 작업 중인 코드베이스(codebase)에 대해 Claude에게 알려주는 내용입니다.

두 파일은 모두 읽히고 병합됩니다. 충돌이 발생할 경우 프로젝트 레벨의 규칙이 우선순위를 갖습니다. 이는 공유 프로젝트 설정을 오염시키지 않으면서도 개인적인 워크플로우 선호도를 전역적으로 설정할 수 있으며, 가장 중요한 순간에는 프로젝트 규칙이 항상 승리한다는 것을 의미합니다.

잘 구조화된 CLAUDE.md를 위해 2시간을 투자하는 15명 규모의 엔지니어링 팀은, 리뷰 수정 사항 감소와 Claude가 팀 컨벤션(conventions)에서 벗어나는 세션 감소를 통해 일주일 이내에 그 시간을 회수할 수 있습니다. 이것은 문서화(documentation)가 아니라 운영 설정(operational configuration)입니다.

FAQ

CLAUDE.md가 적용되려면 팀의 모든 개발자가 무언가를 해야 하나요?

아니요. 파일이 리포지토리(repository) 루트에 커밋(commit)되면, Claude Code는 해당 리포지토리 내에서 실행되는 모든 세션에 대해 자동으로 파일을 읽습니다. 개발자가 개별적으로 설정할 필요는 없습니다. 이 파일은 모든 머신의 모든 세션에 적용됩니다.

브랜치(branch)마다 다른 CLAUDE.md 규칙을 가질 수 있나요?

네, CLAUDE.md는 다른 파일과 마찬가지로 커밋되는 파일이기 때문입니다. 수정된 CLAUDE.md가 포함된 기능 브랜치(feature branch)를 체크아웃(check out)하면, Claude Code는 해당 버전을 사용합니다. 이는 메인 설정(main config)에 병합(merge)하기 전에 브랜치에서 새로운 컨벤션(convention)을 실험해 볼 수 있음을 의미합니다.

CLAUDE.md에서 비밀 정보(secrets)나 민감한 컨텍스트(context)는 어떻게 처리하나요?

CLAUDE.md에 비밀 정보(secrets)를 넣지 마세요. 이 파일은 버전 관리(version control) 시스템에 커밋되며 로그(logs)에 나타나게 됩니다. 만약 Claude Code가 외부 서비스에 대해 알아야 한다면, 자격 증명(credential)이 아닌 이름과 패턴으로 참조하세요. 비밀 정보 관리(secrets management)는 기존의 비밀 정보 인프라(secrets infrastructure)를 그대로 유지합니다.

작성자: Dr Hernani Costa | 제공: Core Ventures

원문 게시처: First AI Movers.

기술은 쉽습니다. 하지만 기술을 손익(P&L)과 연결하는 것은 어렵습니다. First AI Movers에서 우리는 단순히 AI 도구를 설정하는 것에 그치지 않고, AI 거버넌스(governance), 워크플로우 자동화 설계(workflow automation design), 그리고 운영적 AI 구현(operational AI implementation)을 탐색하는 EU 중소기업(SMEs)을 위한 '경영 신경계(Executive Nervous System)'를 구축합니다.

귀하의 AI 도구 활용이 기술 부채(technical debt)를 만들고 있습니까, 아니면 비즈니스 자산(business equity)을 만들고 있습니까?

👉 AI 준비도 점수 확인하기 (무료 기업 진단)

거버넌스, 자동화, 실행 측면에서 팀의 AI 준비도를 평가해 보세요. 영업 목적이 아닌, 진단적 명확성을 제공합니다.