[Claude Code] 단일 CLAUDE.md의 한계를 넘어서: .claude/rules/와 Nested 구조를 활용한 에이전트 통제

1. 도입부 (Introduction)

소프트웨어 개발 아키텍처가 발전하고 인공지능 에이전트가 개발 프로세스의 주류로 편입되면서, 단순히 대화창에 코드를 복사하고 붙여넣던 ad-hoc 방식의 AI 활용은 종말을 고했다. 이제는 터미널과 로컬 환경을 직접 제어하고, 자율적으로 코드를 수정하며 컴파일과 테스트까지 수행하는 '에이전틱 코딩(Agentic Coding) 환경'이 대세로 자리 잡았다. 그리고 그 최전선에 서 있는 도구가 바로 앤트로픽(Anthropic)의 터미널 기반 AI 개발 어시스턴트, Claude Code다.

하지만 많은 개발자가 Claude Code를 실무 프로젝트에 도입할 때 치명적인 실수를 범하곤 한다. 바로 프로젝트 루트에 단 하나의 CLAUDE.md 파일만 생성해 두고, 빌드 명령어부터 테스트 수칙, 코딩 컨벤션, 백엔드 아키텍처 패턴, 프론트엔드 스타일 규칙까지 프로젝트와 관련된 모든 가이드라인을 그 안에 전부 욱여넣는 것이다.

이처럼 무작정 규칙을 쌓아 두는 ad-hoc 설정 방식은 프로젝트 규모가 조금만 커져도 심각한 부작용을 낳는다. 에이전트가 지침을 무시하는 현상인 프롬프트 희석(Prompt Dilution)이 발생하고, 작업 하나를 처리할 때마다 무거운 컨텍스트가 반복 적재되어 극심한 토큰 낭비와 비용 누적이 일어난다.

 

2. 주요 특징 및 핵심 로직 (Main Features & Logic)

Claude Code의 설정 제어 아키텍처는 에이전트가 실행되는 물리적 컨텍스트 크기를 스스로 조절하고 정밀하게 관리할 수 있도록 유도하는 데 초점이 맞춰져 있다. 단일 CLAUDE.md 구조가 가져오는 병목을 해결하고, 동적인 타겟 에이전트 통제 시스템으로 전환하기 위해 반드시 이해해야 할 3대 병목 현상과 핵심 시스템 아키텍처는 다음과 같다.

 

2.1 단일 CLAUDE.md 구조의 3대 아키텍처적 병목

A) 컨텍스트 윈도우의 선형 팽창 (O(N) Token Growth)

단일 파일에 프로젝트 내의 모든 명령어와 규칙을 채워 넣으면, Claude Code는 매 실행 턴마다 이 방대한 공통 지침을 시스템 프롬프트(System Prompt) 영역에 강제로 적재한다. 규칙서의 줄 수(N)가 늘어날수록 매 대화 턴마다 소모되는 기본 고정 비용은 선형적으로 증가한다.

매 턴 소모되는 기본 토큰 계산 공식 (T_base) T_base = T_system + (alpha * N) + T_history

• N: 규칙서의 줄 수 (Line Count)
• alpha: 한 줄당 환산되는 가중 토큰 상수
• T_history: 대화가 거듭되며 쌓이는 누적 이력 토큰

결국 간단한 변수명 수정이나 오타 하나를 고치는 10토큰짜리 가벼운 작업 요청에도, 시스템에 매번 2만~3만 토큰에 이르는 전역 규칙서가 같이 전송되어 엄청난 고정 비용을 발생시킨다.

 

B) 프롬프트 희석 효과 (Prompt Dilution)

거대 언어 모델(LLM)은 입력된 컨텍스트가 길어질수록 본문 중간에 삽입된 상세한 제약 조건을 놓치거나 무시하는 경향이 있다. 학계에서 일명 'Lost in the Middle(중간 실종)' 현상으로 부르는 이 문제 때문에, 500줄이 넘어가는 단일 CLAUDE.md를 가동하면 에이전트가 "CamelCase를 준수하라"거나 "Controller에서 Repository를 직접 주입하지 말라"는 명확한 아키텍처 규칙을 교묘히 무시하며 코드를 작성하는 참사가 빈번하게 일어난다.

 

C) 폴리글랏 및 풀스택 모노레포에서의 지침 충돌

현대의 모노레포 환경은 백엔드(Spring Boot)와 프론트엔드(React/TypeScript)가 한 저장소에 공존하는 경우가 많다. 이 상황에서 단일 CLAUDE.md를 사용하면 Java 코드를 고칠 때도 Tailwind CSS의 컨벤션 규칙이 시스템 프롬프트를 오염시키며, 반대로 React 컴포넌트를 조작할 때 백엔드의 데이터 트랜잭션 규칙이 주입되어 상충 지침으로 인한 추론성 오작동을 유발한다.

💡 그림 1 기술 해설 및 아키텍처 원리 에이전트의 지능을 통제할 때 핵심은 '컨텍스트의 최소성과 정밀성'이다. 왼쪽의 단일 병목 구조는 LLM의 주의 집중력(Attention)을 분산시켜 실무 코딩 컨벤션을 준수할 수 없게 만든다. 반면 오른쪽의 하이브리드 디스패치(Hybrid Dispatch) 시스템은 사용자가 수정하는 타겟 파일의 경로와 확장자를 Claude Code가 자동으로 감지하고, 해당 파일에 매핑된 규칙만 선별적으로 주입한다. 이를 통해 매 턴 메모리에 불필요하게 낭비되는 토큰 소모를 원천 차단하고 정밀도를 최고치로 유지할 수 있다.

💡 그림 2 기술 해설 및 아키텍처 원리 Claude Code는 시스템 시작 및 명령 수행 시점에 설정 상속 체인을 탐색한다. 우선순위는 [하부 디렉토리 CLAUDE.md] > [.claude/rules/ 매칭 규칙] > [최상위 루트 CLAUDE.md] > [사용자 개인 전역 설정] 순으로 결정된다. 따라서 최상위 루트 가이드는 '전역 Fallback(기본값)' 역할을 수행하고, 도메인 특화 세부 로직이나 보안 토큰 정책 같은 마이크로서비스 수준의 규칙은 하위 Nested 파일이 직접 상위 지침을 오버라이딩하여 제어의 주도권을 갖게 된다.

 

 

3. 상세 가이드 및 심층 분석 (Detailed Guide)

단일 규칙서의 한계를 넘어 에이전트가 가볍고 정밀하게 움직이도록 하기 위한 구체적인 구현 전략 2가지를 상세 예제와 함께 정리한다.

3.1 전략 1: .claude/rules/ 상황별 동적 규칙 분기 기술

동적 규칙 분기를 활성화하기 위해서는 최상위 디렉토리에 .claude/rules/ 폴더를 생성하고, 각 도메인 영역에 맞는 수칙을 마크다운 파일로 분할하여 관리해야 한다. 이때 가장 핵심은 마크다운 문서 최상단에 작성되는 YAML Frontmatter 구조다.

Frontmatter 안에는 해당 규칙이 트리거되는 파일 탐색 패턴인 globs와, 에이전트에게 해당 문서의 용도를 알려주는 description이 반드시 정의되어야 한다.

예제 1: 백엔드용 동적 규약 (.claude/rules/backend-rules.md)

---
globs: "**/src/main/java/**/*.java"
description: "스프링 부트 기반의 레이어드 아키텍처 설계 수칙 및 예외 처리 가이드라인"
---

# Spring Boot Backend Architecture Rules

당신은 스프링 부트 및 엔터프라이즈 자바 설계 표준을 엄격하게 통제하는 백엔드 개발 전용 에이전트입니다.

## 1. 레이어드 아키텍처 종속성 및 호출 제약
- **Controller**는 오직 **Service**만 호출할 수 있다. 컨트롤러가 Repository를 직접 주입받거나 호출하여 DB 계층에 접근하는 구조는 엄격히 금지한다.
- 컨트롤러와 서비스 계층 간의 데이터 교환에는 도메인 엔티티(Entity)를 노출해서는 안 되며, 반드시 전용 **DTO(Data Transfer Object)**를 설계하여 전달해야 한다.
- 트랜잭션의 제어 경계는 오직 서비스 계층의 메서드 단위에 `@Transactional` 어노테이션을 사용하여 선언한다.
- 데이터 조회 기능만 수행하는 전용 조회 서비스의 메서드에는 반드시 `@Transactional(readOnly = true)` 설정을 강제하여 시스템 가용성과 리소스를 보존해야 한다.

## 2. 전역 예외 처리 및 비즈니스 예외 설계
- 예외 발생 시 개발자 임의로 Java의 표준 `RuntimeException`을 직접 던지지 않는다.
- 비즈니스 상에서 예외적인 상황이 감지되면 반드시 정의된 전역 공통 `BusinessException`을 상속받은 구체적인 커스텀 예외(예: `UserNotFoundException`, `TokenExpiredException`)를 정의하여 처리해야 한다.

 

예제 2: 프론트엔드용 동적 규약 (.claude/rules/frontend-rules.md)

---
globs: "**/src/components/**/*.{ts,tsx}"
description: "리액트 및 테일윈드 컴포넌트 스타일링, 상태 설계 수칙 가이드라인"
---

# React Frontend Component & Styling Rules

당신은 UI/UX 정밀도와 렌더링 성능 최적화를 관리하는 리액트 및 웹 퍼블리싱 전문 에이전트입니다.

## 1. 컴포넌트 선언 및 상태 관리 규칙
- 모든 리액트 컴포넌트는 화살표 함수 형태의 함수형 컴포넌트(`const Component = () => {}`) 형식으로 정형화하여 선언한다.
- 하위 자식 컴포넌트들이 부모 상태 전파로 인해 무분별하게 재렌더링되는 현상을 사전에 방지하기 위해, 가능한 한 로컬 상태(`useState`)를 지향하고 파생 상태는 `useMemo`를 통해 연산을 최적화해야 한다.
- 비동기 데이터 처리나 사이드 이펙트를 제어하는 `useEffect` 작성 시, 의존성 배열(Dependency Array)에 입력되는 참조 변수들을 엄밀히 추적하여 누락 없이 반영해야 한다.

## 2. 테일윈드 CSS 스타일링 및 마크업 원칙
- 마크업 구조 설계 시 별도의 인라인 인젝션 스타일을 적용하는 것은 원천 금지하며, 오직 테일윈드(Tailwind) CSS 유틸리티 클래스만 사용해야 한다.
- 동적인 UI 변경이나 클래스 조건부 결합이 요구되는 경우에는 가독성 확보를 위해 `clsx` 또는 `tailwind-merge` 라이브러리를 통하여 가공하도록 설계한다.

 

3.2 전략 2: 하위 디렉토리 계층형 하이브리드 메모리 설계 (Nested CLAUDE.md)

대규모 모노레포 구조 혹은 MSA(Microservice Architecture) 구조에서는 공통 규칙도 중요하지만, 각 마이크로서비스 모듈이 독립적으로 운용하는 비즈니스 규칙과 기술 스택에 관한 세부 규격서가 필요하다.

이를 위해 최상위 루트 CLAUDE.md와 하위 서브 폴더 내부에 위치하는 Nested CLAUDE.md를 분리하여 다음과 같이 위계형 구조를 구축해야 한다.

분류 기준 속성	최상위 전역 CLAUDE.md (Root)	하부 모듈 CLAUDE.md (Nested)
핵심 설계 목적	프로젝트 전체 구조 조망, 빌드/테스트 전역 명령어 매핑	특정 하부 도메인 모듈의 전용 기술 규격 및 데이터 표준화 정책 제어
시스템 적재 시점	Claude Code 세션 초기화(/init) 시 전역 디바이스 메모리에 우선 상주	에이전트의 작업 및 탐색 포커스가 해당 하위 디렉토리 내부로 진입할 때 로드
권장 가이드라인 길이	50줄 이내 (전역 아키텍처 요약 및 명령어 키 바인딩 위주)	100줄 내외 (구체적인 라이브러리 스펙, 데이터 명세 위주)
역할 제어 우선순위	전역 백업 및 기본 규칙(Fallback) 제공	해당 하부 도메인에서만큼은 절대 우선순위 보장 (Override)

 

실제 구현 예시: apps/auth-service/CLAUDE.md

백엔드 마이크로서비스 중에서도 인증 및 보안 인프라를 총괄하는 auth-service 폴더 내에 배치하여 에이전트를 영리하게 가이드하는 하위 규약집 예시다.

# Auth Service Microservice Guidelines

인증 및 보안 처리 마이크로서비스 전용 세부 아키텍처 규칙서입니다. 에이전트는 이 폴더 내부 소스 코드를 편집할 때 최상위 공통 수칙보다 아래의 규격을 최우선 적용해야 합니다.

## 1. 보안 인프라 구현 표준
- 모든 사용자 인증 정보 및 토큰 발행은 단방향 혹은 대칭키 방식을 철저히 배제하고, 비대칭키 암호화(RS256) 알고리즘 방식을 준수하여 발급한다.
- Access Token의 세션 만료 수명은 15분으로 고정하며, Refresh Token은 7일로 기한을 타이트하게 조율해야 한다.
- 사용자 패스워드 해싱은 스프링 시큐리티 내장 `BCryptPasswordEncoder`의 강도(Strength) 설정을 12 이상으로 고정하여 DB에 영속화한다.

## 2. API 상태 코드 및 예외 아웃풋 표준화
- 인증 필터 체인에서 인증 실패가 감지되었을 경우, 임의의 HTML 에러 페이지를 렌더링하지 말고 반드시 `401 Unauthorized` 상태 코드와 함께 아래의 고정된 JSON 규격만 바디에 실어 클라이언트에게 반환해야 한다:
  ```json
  {
    "status": "UNAUTHORIZED",
    "errorCode": "AUTH_001",
    "message": "제시된 인증 토큰이 정상적이지 않거나 만료되었습니다."
  }

 

 

6. 실무 팁 및 주의사항 (Tips & Notes)

6.1 컨텍스트 포화 극복과 세션 최적화 기술

에이전트와 장시간 긴 대화를 나누다 보면, 그동안 생성하고 수정한 다량의 파일 이력과 터미널 컴파일 로그들이 에이전트의 워킹 메모리를 점유해 속도가 느려지거나 이전 규칙들을 조금씩 망각하는 부작용이 나타난다. 

이때는 터미널에 **/compact** 명령을 입력하여 세션 최적화를 실행해야 한다. 이 명령을 수행하면 에이전트가 그동안 나눴던 방대한 대화 로그 중 핵심 아키텍처 합의안과 변경 사항만 골라내 요약 정리하고, 가득 차 있던 메모리 공간을 효과적으로 비워내 준다.

 

6.2 협업 자산으로서의 Git 커밋 전략

`.claude/` 디렉토리와 그 하위에서 동작하는 상황별 동적 규칙서 파일들은 로컬 개발 전용 환경 설정이 아니다. 이것은 인공지능 에이전트와 인간 개발자 팀이 협업하기 위한 프로젝트 고유의 **'공동 아키텍처 자산'**이다. 

따라서 `.claude/rules/` 내의 설정 파일들과 Nested `CLAUDE.md` 파일들은 Git 저장소에 커밋하여 전사 팀원들과 안전하게 동기화해야 한다. 반면 개인용 로컬 경로 지정이나 특정 빌드 터미널 테마 설정 등은 개별화 파일인 `.claude/settings.local.json`에 분리해서 선언하고, 이 파일은 반드시 `.gitignore`에 등록하여 설정 충돌을 미연에 방지하도록 조치해야 한다.

 

6.3 상속 충돌에 대처하는 규칙 상충 제어법

하부 폴더의 Nested `CLAUDE.md`와 상위 `.claude/rules/`가 동일한 도메인(예: 백엔드 Java 설계)을 처리하는 과정에서 서로 규칙이 상충되는 일이 발생할 수 있다. 이때 에이전트의 판단 혼선을 막기 위해, 전역 규칙서의 상단 Frontmatter 필드 아래 혹은 description 영역에 다음과 같이 위임 처리를 명확하게 서술해 두는 패턴을 적극 권장한다.

> "프로젝트의 글로벌 공통 코딩 규격은 본 가이드라인을 따르되, 하위 도메인 폴더 내에 별도의 CLAUDE.md 파일이 존재하여 보안 혹은 상세 정책에 차이가 발생할 경우, 에이전트는 하부 디렉토리의 지침에 우선권을 양도(Delegate)한다."

 

7. 마무리 (Conclusion)

인공지능 코딩 에이전트의 생산성을 지탱하는 진정한 기술은 단순히 AI에게 "성능을 좋게 내달라"거나 "클린 코드를 짜라"는 모호하고 친절한 프롬프트를 작성하는 것에 있지 않다. 진정한 기술적 가치는, 도구가 스스로 당면한 비즈니스 스택에 맞추어 최소한의 핵심 정보만 똑똑하게 캐싱하고 최적의 메모리 공간을 조립해 내도록 유도하는 **'프롬프트 아키텍처 설계'**에 있다.

본 실무 정리 노트에서 다룬 `.claude/rules/` 기반의 상황별 동적 규칙 설계와 'Nested CLAUDE.md'를 조합한 계층형 하이브리드 컨텍스트 통제 아키텍처는 매 턴 소모되는 대량의 토큰 비용을 획기적으로 감축시켜 준다. 이와 동시에, 에이전트가 단 하나의 상세 규약도 빠뜨리지 않고 완벽히 암기한 채 시스템 코드를 자율 수정할 수 있도록 유도하는 최고의 열쇠다. 이 계층적 컨텍스트 최적화 기법을 여러분의 프로덕션 모노레포 아키텍처에 즉각 적용하여, 한 명의 시니어 개발자 몫을 거뜬히 해내는 강력한 전용 에이전트 군단을 구축해 보기를 권장한다.