AI 코딩 자동화가 실패하는 진짜 이유: CLAUDE.md 200줄의 저주와 조건부 규칙 해법

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

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

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

원본 영상: Claude Code 입문 E23

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
• 본문 인용 표기 [00:00:34] 는 원본 영상 시점
• 규칙 세부 동작은 Claude Code 업데이트에 따라 달라질 수 있으므로, 현재 배포 버전의 공식 문서를 함께 확인할 것