현또의 코딩세상

[Claude Code] CLAUDE.md가 수백 줄이 되면 생기는 일, 그리고 ".claude/rules/"

또코딩 — Sat, 30 May 2026 18:29:11 +0900

실무에서 CLAUDE.md 하나에 모든 규칙을 쌓다 보면 어느 순간 파일이 수백 줄이 됩니다. 그리고 그때쯤 Claude는 규칙을 잘 따르지 않기 시작합니다.

이유는 단순합니다!

CLAUDE.md는 세션 시작 시 전체가 컨텍스트 윈도우에 올라갑니다. 파일이 길수록 토큰을 낭비하고 준수율이 떨어집니다. 공식 문서도 파일당 200줄 이하를 권장하며, 그 이상이 되면 path-scoped rules로 분리하라고 명시합니다.

공식 문서에서 이 문제의 해법으로 제시하는 게 .claude/rules/입니다.

두 가지 메모리 시스템

CLAUDE.md와 .claude/rules/는 로드 방식 자체가 다릅니다.

CLAUDE.md는 세션이 시작될 때 항상 전체가 로드됩니다. 그래서 여기에는 어떤 파일을 작업하든 항상 알아야 하는 것만 넣어야 합니다. (ex. 빌드 명령, 폴더 구조, "항상 X를 수행한다" 같은 규칙)

.claude/rules/는 다릅니다.

paths frontmatter로 범위를 지정하면, Claude가 해당 패턴과 일치하는 파일을 Read할 때만 로드됩니다.

예를 들어, C 파일 작업할 때 Python 규칙이 올라올 필요가 없고, DB 건드릴 때만 DB 규칙이 올라오면 됩니다.

rules 로드 흐름

주의할 점은, 경로별 규칙은 도구를 사용할 때마다 트리거되는 게 아니라 파일을 Read하는 시점에 트리거됩니다.
client/foo.cs를 열면 그때 c-style.md와 client.md가 로드되는 식입니다.

실무 폴더 구조

C/Python 혼합, Git 기반 프로젝트 기준으로 구성하면 이렇습니다.

project/
├── CLAUDE.md
└── .claude/
    └── rules/
        ├── git-workflow.md          ← paths 없음, 항상 로드
        ├── languages/
        │   ├── c-style.md           ← paths: "**/*.{c,h,cs}"
        │   └── python-style.md      ← paths: "tool/**/*.py"
        └── modules/
            ├── client.md            ← paths: "client/**/*"
            ├── db.md                ← paths: "db/**/*"
            └── bin.md               ← paths: "bin/**/*"

git-workflow.md처럼 paths를 지정하지 않으면 CLAUDE.md와 동일하게 세션 시작 시 항상 로드됩니다.

Git 워크플로우처럼 어떤 파일을 작업하든 항상 지켜야 하는 규칙이 여기 해당합니다.

CLAUDE.md 작성

여기에는 최소한만 넣습니다.

# 프로젝트 개요
C/Python 기반 임베디드 프로젝트

## 폴더 역할
- client/    : 클라이언트 모듈 (C, C#)
- src/       : 핵심 소스 (C)
- bin/       : 빌드 산출물 (수정 금지)
- tool/      : 내부 유틸리티 (Python)
- resources/ : 정적 리소스
- db/        : DB 테이블 정의 (수정 금지)

## 빌드 명령
- 전체 빌드 : make all
- 테스트     : make test
- 클린       : make clean

## 공통 규칙
- main 브랜치 직접 push 금지, PR을 통해 머지
- 커밋 전 make lint 실행

## 민감한 영역
- db/ 수정이 필요할 시, 담당자 확인 후 진행 (.claude/rules/modules/db.md 참고)
- bin/ 직접 수정 금지, 빌드로만 생성

db 관련 경고를 CLAUDE.md에도 넣는 이유가 있습니다.

db.md는 db/ 파일을 열 때 로드되지만, CLAUDE.md의 경고는 세션 시작부터 인지합니다. 작업 계획 단계에서부터 건드리지 않도록 하는 이중 안전장치입니다.

paths 패턴 매칭

패턴이 틀리면 rules 자체가 의미 없습니다.
자주 실수하는 부분이니 주의해야할거 같습니다.

# 안 되는 패턴
paths:
  - "client/"          # 슬래시만으로는 매칭 안 됨
  - "*.c"              # 루트의 .c 파일만 매칭, 하위 폴더 안 됨
  - "client/*.c"       # client/ 바로 아래만, 하위 폴더 안 됨

# 올바른 패턴
paths:
  - "client/**/*.c"    # client/ 하위 모든 .c 파일
  - "client/**/*"      # client/ 하위 모든 파일

확장자가 여러 개면 중괄호로 묶습니다.

paths:
  - "src/**/*.{c,h}"
  - "client/**/*.{c,h,cs}"
  - "**/*.{json,xml}"

패턴 설계 전에 실제 확장자 분포를 먼저 확인하는 게 좋습니다.

find . -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn

db.md 작성 예시

---
paths:
  - "db/**/*"
  - "**/*.sql"
---

# DB 규칙

## 절대 금지
- 테이블 정의 파일 직접 수정 금지
- 컬럼 삭제, 타입 변경 금지 (레거시 의존성)
- DROP, TRUNCATE 구문 사용 금지

## 수정이 필요한 경우
- 반드시 담당자에게 먼저 확인
- Claude는 수정안 제안만 하고, 실제 적용은 하지 않음
- 새 컬럼은 반드시 nullable로 추가

정리

결국 CLAUDE.md는 "무엇을 조심해야 하는지", .claude/rules/는 "어떻게 다뤄야 하는지"로 역할을 나누는 구조입니다.

이렇게 나누면 얻는 것들이 있습니다.

관계없는 규칙은 컨텍스트에 올라오지 않으니 속도가 붙고,
GitHub 저장소에 커밋해두면 팀 전체가 동일한 규칙을 clone 받습니다. (중앙 관리하기 좋겠죠?)

신규 팀원이 .claude/rules/만 읽어도 프로젝트 규칙 대부분을 파악할 수 있고, Claude가 실수할 때마다 해당 rules 파일에 한 줄 추가하면 팀의 노하우가 코드베이스에 쌓입니다.

결론적으로, AI가 무엇을 알고, 무엇을 모르고, 무엇을 건드리면 안 되는지를 코드베이스 수준에서 버전관리하는 구조입니다.

실전 프로젝트 적용기

Unity 데스크톱 게임 사이드 프로젝트에 Claude Code를 쓰면서, 기존에 CLAUDE.md 하나에 모든 규칙을 넣던 방식을 .claude/rules/로 분리하는 실험을 했습니다.

1. 적용 전 — 한 파일에 모든 규칙이 쌓여있던 상태

CLAUDE.md는 세션 시작 시 항상 전체가 컨텍스트 윈도우에 로드됩니다. 그런데 어느 순간 213줄까지 늘어 있었습니다. 공식 문서 권장치인 200줄을 이미 넘긴 상태였습니다.

안에는 이런 것들이 섞여 있었습니다.

§1~§3: 프로젝트 개요·폴더 구조·진입점 — 어떤 작업이든 알아야 하는 것
§4~§5: CLAUDE.md 운영 규칙 — 메타 문서
§6.1: 파일/폴더 명명 — 문서 작업할 때만 필요
§6.2 Git 워크플로우, §7 AI 공통 규칙 — 합의 필요로 비어있는 placeholder
§8.1~§8.4 Behavioral Guidelines — LLM 코딩 공통 가드레일

문제는 .cs 파일을 만질 때도, 문서를 쓸 때도, 씬을 건드릴 때도 위 §1~§8 전체가 매번 컨텍스트에 들어간다는 점입니다.

작업 맥락과 무관한 규칙이 항상 함께 떠 있고, 새 영역(셰이더·사운드 등)을 추가할수록 모든 작업의 비용이 같이 늘어날거 같았습니다.

2. 실제로 쪼갠 구조

.claude/rules/의 핵심은 paths frontmatter로 매칭되는 파일을 Read할 때만 해당 규칙 파일이 시스템 프롬프트에 끼어든다는 점입니다.

이걸 활용해 다음과 같이 나눴습니다.

.claude/rules/
├── git-workflow.md          ← paths 없음, 항상 로드
├── behavioral-guidelines.md ← paths 없음, 항상 로드
├── unity/
│   ├── csharp.md            ← C# 작업 시에만 로드
│   ├── scenes.md            ← 씬 파일 작업 시에만 로드
│   ├── project-settings.md  ← ProjectSettings 건드릴 때만 로드
│   └── characters.md        ← 캐릭터 에셋 작업 시에만 로드
└── docs-conventions.md      ← 문서 작업 시에만 로드

써보면서 이 구조가 두 가지 다른 목적으로 작동한다는 걸 알게 됐습니다.

장점 1. CLAUDE.md 슬림화 — 정리 목적

git-workflow.md, behavioral-guidelines.md처럼 paths가 없는 파일들입니다.
로드 시점은 CLAUDE.md와 완전히 동일해서 컨텍스트 절약 효과는 없습니다.

대신 규칙 종류별로 파일이 분리되어 있어서 수정할 때 CLAUDE.md 전체를 뒤지지 않고 파일명으로 바로 찾을 수 있다는 게 장점입니다.

(팀이 합의할 때마다 해당 파일만 열어서 한 줄 추가하면 끝입니다.)

빈 §6.2 / §7 placeholder를 CLAUDE.md 본문 한가운데서 들어내고 git-workflow.md placeholder 파일로 옮긴 것도 같은 목적입니다. (본문이 깔끔해집니다)

장점 2. 컨텍스트 절약 — paths 지정 파일만 해당

csharp.md, scenes.md처럼 paths를 지정한 파일들입니다.

해당 경로의 파일을 Read하는 순간 시스템 프롬프트에 삽입됩니다.

.md 문서 작업 중에는 C# 규칙이 올라오지 않고, .cs 작업 중에는 씬 규칙이 올라오지 않습니다. 매 요청마다 입력 토큰에 포함되는 내용이 작업 맥락에 맞게 줄어드는 구조입니다.

3. 토큰을 재봤습니다

추정은 다음 방식으로 했습니다. Claude 공식 tokenizer는 비공개라 chars / 2.5 추정을 썼습니다(한글+영문+코드 혼합 텍스트 기준, 오차 ±15%).

(정확한 값은 anthropic SDK의 count_tokens API가 필요합니다)

# 원본 CLAUDE.md (슬림화 전 git HEAD)
git show HEAD:CLAUDE.md > /tmp/original.md
python3 -c "print(round(len(open('/tmp/original.md').read())/2.5))"
# → 2513

비교 기준 — 무엇과 무엇을 비교해야 공정한가

원본 CLAUDE.md(213줄, ~2,513 tokens)에는 아직 Unity-specific 규칙이 없었습니다. 어차피 Unity 규칙은 어딘가에 적어야 했고, 두 가지 선택지가 있었습니다.

선택 A: CLAUDE.md에 Unity 규칙들을 그대로 이어 적기 (monolithic)
선택 B: .claude/rules/로 분리 (지금 한 것)

공정한 비교는 "같은 규칙들을 monolithic으로 가져갔다면 어땠을지" 대 "rules로 나눈 결과"입니다.

만약 .claude/rules/를 안 쓰고 모든 규칙을 CLAUDE.md 본문에 통합했다면:

원본 213줄 (~2,513 tokens)
+ Git 워크플로우 (~440 tokens)
+ 문서 컨벤션 추가분 (~230 tokens)
+ Unity C# 규칙 (~422 tokens)
+ 씬 규칙 (~249 tokens)
+ ProjectSettings 규칙 (~352 tokens)
+ Characters 규칙 (~481 tokens)
= 약 4,676 tokens (어떤 작업이든 매 턴 통째 로드)

반면 .claude/rules/ 시나리오는,

항상 로드: 슬림 CLAUDE.md + behavioral-guidelines.md + git-workflow.md = 약 2,497 tokens
+ 매칭되는 1개 룰 (작업에 따라 ~250–481 tokens)

시나리오별 비교

작업 종류	monolithic	.claude/rules/	절약
`.cs` 파일 작업	4,676	2,919	−1,757 (−38%)
`.unity` 씬 작업	4,676	2,746	−1,930 (−41%)
`ProjectSettings/` 작업	4,676	2,849	−1,827 (−39%)
`Characters/` 자산 작업	4,676	2,978	−1,698 (−36%)
문서(`.md`) 작업	4,676	2,888	−1,788 (−38%)

작업당 평균 약 1,800 tokens, 38.5% 절약입니다.

게다가 룰이 늘어날수록 격차는 더 벌어집니다. UI / Sound / Shader 등 영역이 추가되면 monolithic은 항상 그만큼 더 부풀고, .claude/rules/는 그 작업을 할 때만 한 줄 더해집니다.

다만 지금 프로젝트 규모에서는 절대 토큰 수가 그리 크진 않습니다.
rules 파일이 수십 개, 각 파일이 수백 줄씩 쌓일 때 차이가 더 체감될 것입니다.
(지금은 "구조적으로 절약되는 형태로 시작했다"는 정도의 의미로...)

4. 주의할 점

paths 패턴은 "필터"가 아니라 "트리거"

paths 패턴 매칭은 파일 내용을 필터링하는 게 아닙니다!
특정 경로의 파일을 Read하는 순간 해당 rules 파일 전체가 컨텍스트에 올라오는 트리거이고, frontmatter 포함 전체가 다 로드됩니다.

---
paths:
  - "**/*.cs"
  - "Project_Cozy/Assets/Scripts/Platform/**/*.cs"
---

자주 틀리는 패턴을 정리해두면,

"src/"처럼 슬래시만 쓰거나 "*.cs"처럼 단순 글로브는 하위 폴더를 잡지 못합니다.
재귀 매칭은 "src/**/*.cs"처럼 **을 써야 합니다.

Claude가 파일을 알아서 읽으러 가지 않습니다

.claude/rules/와 CLAUDE.md 외에 일반 파일은 Claude가 명시적으로 열지 않으면 내용을 모릅니다.
git-workflow.md에 "자세한 내용은 Docs/Development/GitWorkflow.md 참고"라고 써도 Claude가 자동으로 읽으러 가지 않습니다.

CLAUDE.md 파일 안에서는 @경로 문법으로 외부 파일을 임포트할 수 있습니다. 예를 들어 @docs/git-instructions.md처럼 쓰면 세션 시작 시 해당 파일이 자동으로 로드됩니다.

이 기능을 활용하면 rules 파일 개수를 늘리지 않고도 관련 문서를 CLAUDE.md에서 참조할 수 있습니다.

rules 파일 자체에 필요한 규칙은 직접 적거나 @import를 활용하는걸로...!

`.claude/`는 보호 영역일 수 있습니다

Cowork에서 .claude/ 디렉토리에 직접 쓰기가 막힙니다. 저는 일반 폴더(_claude_rules_stage/)에 만들고 PowerShell Copy-Item으로 옮겼습니다.

로드된 파일 확인은 `/memory` 커맨드로

/memory를 실행하면 현재 세션에 로드된 모든 CLAUDE.md, rules 파일 목록을 확인할 수 있습니다. path-scoped rules가 기대대로 트리거되는지 디버깅할 때 유용합니다.

마무리

.claude/rules/는 토큰을 자동으로 줄여주는 마법이 아닙니다.
나누는 결정은 사람이 해야 하고, 잘못 나누면 보강하다가 오히려 토큰이 늘 수도 있습니다.

특히 지금처럼 프로젝트 규모가 작을 땐 보강 한 줄의 비중이 커서 위험이 더 큽니다. (저도 처음 나눴을 땐 오히려 늘 뻔했었던...)

결국 .claude/rules/의 진짜 가치는 paths를 가진 파일들에 있고, paths 없는 파일들은 CLAUDE.md가 길어지는 걸 막기 위한 분리 그 이상도 이하도 아닙니다.

참고 문서

[Claude Desktop] Claude MCP로 Windows 입력 제어하기 - 칠전팔기와 실험 후기

또코딩 — Sat, 30 May 2026 18:22:35 +0900

칠전팔기 기록부터 그림판 하트까지 — 설정 이슈와 실험 후기

Claude Desktop에 windows-driver-input-mcp를 연동해 마우스 제어부터 그림판 하트까지 직접 테스트해봤다.

AnyDriver 설정 이슈 해결법과 LLM 에이전트가 빠른 게임에 느릴 수밖에 없는 이유도 함께 정리했습니다.

사용 MCP와 설정

windows-driver-input-mcp 라이브러리를 Claude Desktop에 연동해봤다. 과정은 간단해 보였지만, 예상치 못한 곳에서 막혔다.

해당 GitHub 레포를 로컬에 clone
Claude Desktop 설정에서 해당 MCP 프로젝트를 바인딩
실행 — 그런데 안 된다.....?
가이드대로 env를 설정했는데, AnyDriver가 문제였음...!
드라이버를 SendInput으로 변경 후 해결!

❌ 문제 — 초기 설정 (AnyDriver)

{
  "WINDOWS_MCP_INPUT_BACKEND": "ibsim-dll",
  "WINDOWS_MCP_INPUT_DRIVER": "AnyDriver",
  "WINDOWS_MCP_RATE_MOVE_HZ": "120",
  "WINDOWS_MCP_RATE_MAX_DELTA": "60",
  "WINDOWS_MCP_RATE_SMOOTH": "0.0",
  "WINDOWS_MCP_RATE_CPS": "8.0",
  "WINDOWS_MCP_RATE_KPS": "12.0",
  "WINDOWS_INPUT_LOG_LEVEL": "INFO"
}

✅ 해결 — 드라이버를 SendInput으로 변경

{
  "WINDOWS_MCP_INPUT_BACKEND": "ibsim-dll",
  "WINDOWS_MCP_INPUT_DRIVER": "SendInput",
  "WINDOWS_MCP_RATE_MOVE_HZ": "120",
  "WINDOWS_MCP_RATE_MAX_DELTA": "60",
  "WINDOWS_MCP_RATE_SMOOTH": "0.0",
  "WINDOWS_MCP_RATE_CPS": "8.0",
  "WINDOWS_MCP_RATE_KPS": "12.0",
  "WINDOWS_INPUT_LOG_LEVEL": "INFO"
}

참고 — 백엔드를 ibsim-ahk로 바꿔봤을 때는 마우스 커서가 아예 이동하지 않았다. 원인은 아직 불명확.

Input 제어 사용기

실제로 어떤 것들을 시킬 수 있는지 테스트해봤다.

마우스 중앙으로 이동

!youtube[r4auRymosb8?si=uj-CU_3p9ymKRn64]

마우스를 화면 중앙으로 이동시키는 기본 동작.

마우스 우측 끝으로 이동 후 우클릭

!youtube[bkyI49cjsiI?si=ykE4hPFQcQjVKkX5]

화면 우측 가장자리로 이동 후 우클릭 수행.

메모장에 글 쓰기

!youtube[PwFItUbD2EI?si=x8yvhNTEdV349cL4]

영어 입력은 정상 동작. 메모장이 꺼져 있으면 명령어로 직접 실행해주기도 함...!!!!!!

한계: 한글 입력은 현재 지원 안 됨.

그림판에 하트 그리게 하기

그림판에 직접 그린 하트 (중간에 네트워크 끊겨서 미완성 )

실행 시간이 약 6분으로 굉장히 오래 걸린다. 중간에 네트워크가 끊기면 도중에 멈춰버리는 문제도 있음...하...

간단 미니게임 플레이

생각 → 이동 과정을 캡처한 스크린샷

응답 속도가 매우 느리다... 한 번 판단하고 행동하는 데 상당한 시간이 걸림...

결론

windows-driver-input-mcp를 통해 Claude가 실제로 Windows UI를 자율적으로 조작할 수 있다는 걸 확인했다.

마우스 이동/클릭, 앱 실행, 텍스트 입력, 그림 그리기까지 — 생각보다 꽤 많은 걸 할 수 있었다.

다만 실용적으로 쓰기엔 아직 몇 가지 한계가 있다.

항목	상태
영어 입력	✅ 정상 동작
한글 입력	❌ 미지원
앱 자동 실행	✅ 정상 동작
응답 속도	⚠️ 느림 (행동 간 딜레이 큼)
장시간 작업 안정성	⚠️ 네트워크 끊기면 중단됨

설정 시 AnyDriver 대신 SendInput 드라이버를 잡으면 일단 돌아가긴 한다.
속도와 한글 입력 문제가 해결되면 활용도가 훨씬 높아질 것 같다.

왜 "사람처럼 라이브 게임 플레이"는 어려울까?

미니게임 플레이가 굉장히 느렸던 이유는 단순히 모델 성능의 문제가 아니다.
(하이쿠 쓴다해서 빨라지는건 아님)

"사람처럼 라이브로 플레이하는 AI"를 만들려면 사실 세 가지 조건을 동시에 충족해야 한다.

조건	설명	LLM 에이전트	RL 정책 신경망
인터페이스	화면을 보고 키보드로 입력 (내부 변수 X)	✅	✅
인지	미리 짠 if문이 아닌 스스로 판단	✅	✅
속도	60FPS 액션 기준 16ms급 판단-입력	❌	✅

현재 MCP로 쓰는 방식은 LLM 기반 에이전트다.

화면 캡처 → 추론 → 입력의 왕복 구조라 한 번 판단에 수백 ms~수 초가 걸린다.

턴제나 느린 게임이라면 충분하지만, 60FPS 액션에서는 판단이 끝나기도 전에 이미 맞고 있었다...(그래서 많이 죽었었음)

모델을 어떤 걸로 바꿔도 이 왕복 구조 자체는 극복이 안 된다.

세 조건을 동시에 만족하는 현실적인 방법은 비전 기반 강화학습(RL) 뿐인 것 같다.

화면 픽셀을 입력받아 학습된 정책으로 행동을 출력하고, 추론 자체는 1ms 미만이라 60FPS도 거뜬히 따라간다고 한다.
다만 수만~수백만 판의 자가 플레이 훈련이 필요하다는 대가가 있다.

결국 LLM 에이전트의 판단은 "적이 셋이니 후퇴하자"처럼 말로 설명되는 느린 추론이고, RL의 판단은 격투게임 고수의 반사신경처럼 빠르지만 설명이 안 되는 반응이다.

빠른 액션 게임에서 사람처럼 노는 건 후자에 가깝다.
(사람도 격투게임 할 때 매번 논리적으로 따지고 누르는 게 아니니까...@!)

하지만, 나는 AI가 사용자 컴퓨터에 빠르게 반응할 수 있는 방법을 찾아낼 것이다... To be continued...

나의 링크

또코딩 — Sat, 30 May 2026 18:19:34 +0900

Velog: https://velog.io/@kohyeonseo1006/posts

kohyeonseo1006 (고현서) / 작성글 - velog

New 현또의 코딩세상 / 개발자

velog.io

Github: https://github.com/KoHyeonSeo