---
title: AI 코딩 자동화가 실패하는 진짜 이유: CLAUDE.md 200줄의 저주와 조건부 규칙 해법
date: 2026-09-29
model: admin
category: knowhow
summary: CLAUDE.md가 수백 줄로 불어나면 토큰 비용이 폭증하고 규칙을 무시하기 시작한다. @import와 .claude/rules의 paths 조건부 로딩, 우선순위, 트러블슈팅 순서를 정리한다.
tags: ClaudeCode, CLAUDEmd, 컨텍스트관리, 토큰최적화, 규칙, 에이전트
---

AI 코딩 에이전트는 개발 생산성을 비약적으로 높여준다. 하지만 현장에서 실제로 써 보면 곧바로 거대한 장벽에 부딪힌다. 바로 '토큰 비용 폭탄'과 **규칙 불이행(Instruction Compliance Drop)** 문제다.

프로젝트 설정 파일인 `CLAUDE.md`에 타입스크립트 컨벤션, 리액트 컴포넌트 규칙, API 라우트 지침, 보안 가이드를 모두 집어넣다 보면 파일 길이가 금세 수백 줄을 넘어간다. 공식 문서에 따르면 한 파일당 **200줄**을 넘길 경우 AI의 규칙 준수율이 급격히 떨어진다고 경고한다 `[00:00:34]`.

문서 수정 세션 하나를 시작했을 뿐인데 수백 줄의 코딩 규칙이 컨텍스트에 통째로 실려 들어가고, 정작 중요한 지시사항은 AI가 무시해 버린다. 토큰은 소모되고 결과물의 밀도는 떨어진다 `[00:01:13]`. 이 문제를 풀려면 Claude Code가 제공하는 조건부 규칙과 파일 참조 구조를 정확히 이해하고 적용해야 한다.

원본 영상: [Claude Code 입문 E23](https://www.youtube.com/watch?v=ICDN7_lry98)

## 1. 정적 통합(`@` import)과 동적 로딩(`paths`)의 차이

`CLAUDE.md`가 비대해질 때 해결 접근은 두 가지로 나뉜다. 하나는 토큰을 아끼지 못하는 방식이고, 다른 하나는 실제로 아끼는 방식이다.

### @ 멘션 Import (정적 통합)

`CLAUDE.md` 안에 `@README.md`나 `@package.json`처럼 파일 경로를 적어 지침을 합치는 방식이다 `[00:05:13]`.

- 참조 깊이는 **최대 5단계**까지 지원된다 `[00:05:48]`.
- 세션 시작 시점에 컨텍스트로 무조건 불러온다. 파일 분할과 관리는 쉬워지지만 **토큰 비용 자체는 줄어들지 않는다** `[00:06:57]`.

정리하면 이 방식은 관리 편의성의 해결책이지 비용의 해결책이 아니다. 규칙을 쪼개 놓았다는 사실만으로 컨텍스트 압박이 해소되는 것은 아니다.

### .claude/rules/ 와 paths 프론트매터 (동적 조건부 로딩)

실질적으로 토큰 비용을 아끼는 핵심 메커니즘은 이쪽에 있다 `[00:07:20]`.

- `.claude/rules/` 디렉토리에 토픽별 마크다운 파일(예: `testing.md`, `security.md`)을 분산해 두고, 파일 상단에 YAML 형태로 `paths` 글로브 패턴을 지정한다 `[00:03:08]`.
- 세션 시작 시 항상 로드되는 게 아니라, AI가 `src/api/**/*.ts`처럼 **패턴에 매칭되는 파일을 실제로 읽는(Read) 순간** 해당 규칙이 동적으로 활성화된다 `[00:02:56]`.
- 관련 없는 작업(예: README 문장 수정)을 할 때는 불필요한 규칙이 컨텍스트를 차지하지 않으므로 토큰 비용이 대폭 줄고 지침 준수율은 오른다 `[00:02:56]`.

여기서 결정적인 차이는 '언제 로드되는가'다. 정적 통합은 시작 시점에 전부 쌓고, 조건부 로딩은 필요 시점에 해당 규칙만 주입한다. 프로젝트가 커질수록 이 차이는 선형이 아니라 비례해서 벌어진다.

## 2. 규칙 우선순위와 모노레포·팀 공유 전략

여러 계층의 규칙이 충돌할 때 Claude Code의 로딩 우선순위 구조는 다음과 같다 `[00:08:34]`.

1. **개인 전용 규칙 (`~/.claude/rules/`)**: 머신 전체에 적용되는 개인 선호 사항 `[00:08:02]`.
2. **팀 공통 규칙 (`.claude/rules/`)**: Git 저장소에 커밋되어 팀원 전체가 공유하는 표준 지침 `[00:08:55]`.
3. **우선순위 동작**: 개인 규칙이 먼저 로드되고, 나중에 로드되는 팀 프로젝트 규칙이 컨텍스트상 더 가까운 위치에 놓이므로 팀 표준이 개인 선호를 상쇄(override)한다 `[00:08:34]`.

여러 저장소나 모노레포 환경에서 전사 보안 규칙이나 표준 가이드를 동기화할 때는 심볼릭 링크를 활용하면 한 곳에서 일괄 업데이트가 가능하다 `[00:09:47]`.

## 3. 규칙이 적용되지 않을 때 5단계 점검 순서

조건부 규칙을 적용한 뒤 "왜 작성한 규칙이 안 먹히지?"라는 상황은 흔하다. 다음 순서로 확인하면 원인을 빠르게 좁힐 수 있다 `[00:14:21]`.

1. **/memory 명령어로 실제 로드 상태 확인**: 현재 세션에 어떤 파일이 로드되어 있는지 디렉토리 목록으로 점검한다 `[00:12:05]`.
2. **글로브 패턴 검증**: `paths` 패턴이 대상 파일 경로와 맞는지 확인한다. 매칭은 절대 경로가 아니라 워킹 디렉토리 기준 상대 경로로 이뤄진다 `[00:15:00]`.
3. **Read 트리거 발생 여부**: 단순 `ls`나 bash 명령으로는 부족하다. Claude가 해당 파일을 실제로 읽는 도구(Read)를 실행해야 규칙이 활성화된다 `[00:15:07]`.
4. **instructions_loaded 훅 활용**: `hooks`에 관찰용 훅을 설정해 규칙이 로드되는 시점과 사유를 감사 로그로 남기고 분석한다 `[00:12:56]`.
5. **상충 규칙 점검**: 다른 `rules` 파일에 정반대 지침이 들어 있지 않은지 확인한다 `[00:14:46]`.

## 결론: 정교한 컨텍스트 설계가 진짜 경쟁력이다

에이전트가 쏟아져 나오는 시대에 모든 지침을 프롬프트에 몰아넣는 방식은 비용 폭탄과 품질 저하라는 부작용만 남긴다.

`.claude/rules/`와 `paths` 프론트매터처럼 **필요한 순간에만 최소한의 컨텍스트를 주입하는 설계**가 AI 도구를 진짜 생산성 무기로 바꾼다. 규칙을 적게 쓰는 게 미명이 아니라, 규칙이 필요한 정확한 시점에 정확히 읽히는 것이 설계다.

## 참고

- 원본 영상: [새로운 시작 (neosarchizo) 채널 - Claude Code 입문 E23](https://www.youtube.com/watch?v=ICDN7_lry98)
- 본문 인용 표기 `[00:00:34]` 는 원본 영상 시점
- 규칙 세부 동작은 Claude Code 업데이트에 따라 달라질 수 있으므로, 현재 배포 버전의 공식 문서를 함께 확인할 것