`Claude Code .claude/rules/`로 팀별 AI 규칙을 모듈화하는 법 — 프론트엔드, 백엔드, 보안 팀 분리 전략

팀이 커지면서 CLAUDE.md가 점점 뚱뚱해지는 걸 경험해본 적 있는가? 저도 처음엔 하나의 파일에 모든 규칙을 때려 넣었다가, 어느 순간 500줄이 넘어가면서 "이걸 대체 누가 관리하지?" 싶었다. 프론트엔드 팀이 React 규칙을 수정하면 백엔드 팀과 머지 충돌이 나고, 보안 팀이 새 정책을 추가하려면 PR 리뷰어를 전부 소집해야 했다.

최근 업데이트된 Claude Code의 .claude/rules/ 디렉터리는 이 문제를 꽤 깔끔하게 풀어준다. 핵심은 팀별로 규칙 파일을 분리하고, YAML 프론트매터의 paths: 필드로 해당 규칙이 필요한 순간에만 선택적으로 로드되게 만드는 것이다. 이 글을 다 읽으면 세 팀의 실전 규칙 파일과 CI 검증 파이프라인까지 손에 쥐어진다. 어떻게 설계하고 운용하는지, 실무에서 마주치는 함정까지 솔직하게 풀어보겠다.

핵심 개념

두 가지 로딩 방식: 전역 vs 조건부

.claude/rules/ 안에 배치된 .md 파일은 크게 두 가지 방식으로 동작한다.

python

.claude/
├── CLAUDE.md              # 전사 공통 규칙
└── rules/
    ├── frontend.md        # 조건부 로드 (paths: 있음)
    ├── backend.md         # 조건부 로드 (paths: 있음)
    ├── security.md        # 항상 로드 (paths: 없음)
    └── testing.md         # 조건부 로드 (paths: 있음)

파일 유형	`paths:` 프론트매터	로드 시점
전역 규칙	없음	세션 시작 시 항상
조건부 규칙	있음	Claude가 해당 글로브 패턴 파일을 Read 도구로 읽을 때

글로브 패턴(Glob Pattern): src/app/**/*.tsx처럼 와일드카드(*, **)를 사용해 파일 경로를 매칭하는 표현식이다. **는 중간 디렉터리를 몇 개든 건너뛸 수 있어 깊은 중첩 경로에서도 유연하게 동작한다.

프론트매터(Frontmatter): Markdown 파일 맨 위에 ---로 감싸인 YAML 메타데이터 블록이다. paths:, title: 같은 구조화된 정보를 파일 내에 함께 담을 수 있다.

여기서 한 가지 짚고 넘어갈 점이 있다. paths: 조건은 Claude가 해당 경로의 파일을 Read 도구로 읽을 때 트리거된다. 파일명을 대화에서 단순히 언급하거나 Edit·Write 도구로 쓰기 작업을 할 때는 트리거되지 않는 알려진 제약이 있다(GitHub Issue #23478, 2025년 5월 기준 미수정). 쓰기 시에도 반드시 적용되어야 하는 규칙은 전역 파일에도 중복 배치하는 것이 안전하다.

조건부 로딩의 진짜 가치는 토큰 효율에 있다. Claude가 src/api/users.ts를 읽을 때 React 컴포넌트 규칙이 컨텍스트를 차지할 필요가 없으니까. Cursor가 .cursor/rules/*.mdc에서 globs: 필드로 이미 구현해 좋은 반응을 얻었던 방식을 Claude Code가 네이티브로 들여온 것이다.

모노레포에서의 계층적 로딩

모노레포 환경이라면 계층 구조까지 활용할 수 있다. Claude Code는 현재 작업 디렉터리에서 루트 방향으로 올라가며 CLAUDE.md를 누적 로드하고, 각 레벨의 .claude/rules/도 함께 탐색한다.

python

my-platform/
├── CLAUDE.md                    # TypeScript strict, pnpm, Git 컨벤션
├── .claude/
│   └── rules/
│       └── security.md          # 전사 보안 규칙 — 항상 로드
├── apps/
│   ├── web/
│   │   ├── CLAUDE.md            # Next.js 앱 공통 규칙
│   │   └── .claude/
│   │       └── rules/
│   │           └── frontend.md  # React/Next.js 세부 규칙
│   └── api/
│       ├── CLAUDE.md            # NestJS 앱 공통 규칙
│       └── .claude/
│           └── rules/
│               └── backend.md   # NestJS/API 세부 규칙
└── packages/
    └── shared/
        └── CLAUDE.md            # 공유 라이브러리 규칙

apps/web/에서 작업하면 루트 CLAUDE.md → 루트 security.md → apps/web/CLAUDE.md → apps/web/.claude/rules/frontend.md 순서로 쌓이고, apps/api/의 백엔드 규칙은 로드되지 않는다. 팀 간 규칙 간섭 없이 각자의 컨텍스트만 가져가는 구조다.

실전 적용

팀별 규칙 파일 작성

실무에서 자주 쓰는 세 가지 팀 규칙 파일의 실제 작성 예시다.

프론트엔드 팀 (frontend.md)

markdown

---
paths:
  - "src/app/**/*.tsx"
  - "src/components/**/*.tsx"
  - "src/app/**/*.ts"
---
 
# 프론트엔드 규칙
 
- React Server Component를 기본으로 사용하고, Client Component는
  상태·이벤트 핸들링 최소 단위에만 적용
- 모든 API 호출은 Server Actions를 통해 처리 (클라이언트 fetch 금지)
- shadcn/ui 컴포넌트 우선 사용, 커스텀은 src/components/ui/에 배치
- Tailwind CSS 클래스는 cn() 유틸리티로 조합
- named export 사용 (default export 금지)

백엔드 팀 (backend.md)

markdown

---
paths:
  - "src/api/**/*.ts"
  - "src/services/**/*.ts"
  - "src/modules/**/*.ts"
---
 
# 백엔드 규칙
 
- 비즈니스 로직은 Service 레이어에만 위치, Controller는 요청/응답 변환만
- 모든 API 응답은 { data, error, meta } 표준 형태 준수
- DB 마이그레이션은 drizzle/migrations/에서만 관리
- 환경변수는 반드시 src/env.ts에서 Zod 스키마로 검증 후 사용
- async/await 사용, .then() 체이닝 금지

보안 팀 (security.md) — paths: 없이 항상 로드

markdown

# 보안 규칙 (전역 적용)
 
- SQL 쿼리는 반드시 파라미터화 (raw string 쿼리 금지)
- 사용자 입력은 서비스 경계에서만 검증 (DTO + Zod)
- XSS 방지: dangerouslySetInnerHTML 사용 시 보안 팀 리뷰 필수
- JWT 토큰은 httpOnly 쿠키에 저장, localStorage 금지
- OWASP Top 10 최신 기준 준수 (특히 공급망 실패, 취약한 의존성 관리)
- 외부 의존성 추가 시 CVE 스캔 결과 PR에 첨부

보안 규칙은 어떤 파일을 건드리든 항상 유효해야 하기 때문에 paths: 프론트매터 없이 전역으로 두는 게 자연스럽다. TikiTribe의 claude-secure-coding-rules처럼 GitHub에서 커뮤니티가 OWASP·NIST AI RMF 기반으로 관리하는 오픈소스 보안 규칙 셋을 드롭인으로 가져다 쓰기에도 딱 좋은 위치다.

CI 검증 파이프라인 연결

규칙 파일도 코드처럼 CI/CD 파이프라인을 태울 수 있다. 이 파이프라인은 .claude/rules/ 파일이 변경된 PR에서만 실행되어 불필요한 CI 비용을 줄이고, YAML 프론트매터 문법 오류를 자동으로 잡아낸다.

yaml

# .github/workflows/validate-rules.yml
name: Validate Claude Rules
 
on:
  pull_request:
    paths:
      - ".claude/rules/**"
      - "**/CLAUDE.md"
 
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: YAML 프론트매터 문법 검사
        run: |
          pip install pyyaml -q
          python3 - << 'PYEOF'
          import sys, re, yaml, glob
 
          errors = []
          for filepath in glob.glob('.claude/rules/**/*.md', recursive=True):
              content = open(filepath).read()
              match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
              if match:
                  try:
                      yaml.safe_load(match.group(1))
                      print(f'OK: {filepath}')
                  except yaml.YAMLError as e:
                      errors.append(f'ERROR: {filepath} — {e}')
 
          if errors:
              for e in errors:
                  print(e, file=sys.stderr)
              sys.exit(1)
          PYEOF
 
      - name: 파일 크기 경고
        run: |
          echo "규칙 파일 라인 수 현황:"
          wc -l .claude/rules/*.md
          for file in .claude/rules/*.md; do
            lines=$(wc -l < "$file")
            if [ "$lines" -gt 200 ]; then
              echo "WARNING: $file — ${lines}줄 (권장 200줄 초과)"
            fi
          done

솔직히 처음엔 "규칙 파일에 CI까지 필요할까?" 싶었는데, 팀이 5명만 넘어가도 누군가는 YAML 따옴표를 빠뜨리거나 중복 규칙을 슬쩍 추가하게 된다. 자동화해두면 코드 리뷰 비용이 확연히 줄어든다.

장단점 분석

장점

항목	내용
관심사 분리	팀별 규칙을 독립 파일로 분리해 머지 충돌 최소화
컨텍스트 효율	글로브 패턴으로 관련 규칙만 로드해 토큰 낭비 방지
독립적 소유권	각 팀이 자신의 파일만 PR로 관리, 타 팀 간섭 없음
점진적 도입	기존 `CLAUDE.md`를 유지하면서 파일 하나씩 추가 가능
Git 이력 추적	규칙 변경 이력이 코드 변경과 함께 PR에 기록됨

단점 및 주의사항

항목	내용	대응 방안
YAML 파싱 오류	`{`, `*`로 시작하는 글로브는 YAML 오류 발생 (Issue #13905, #17204)	패턴을 반드시 큰따옴표로 감싸기
Write 트리거 미지원	`paths:` 규칙이 Read 도구에만 트리거, 쓰기 작업 시 로드 안 됨 (Issue #23478, 2025년 5월 기준 미수정)	중요 쓰기 규칙은 전역 파일에 중복 배치
사용자 수준 규칙 미적용	`~/.claude/rules/`의 `paths:` 무시되는 알려진 버그 (Issue #21858)	글로벌 규칙은 `~/.claude/CLAUDE.md`에 직접 작성

실무에서 가장 흔한 실수

팀에 이 구조를 도입하면서 가장 많이 목격한 실수 세 가지다.

글로브 패턴에 따옴표를 빠뜨리는 것 — paths: - src/app/**/*.tsx처럼 따옴표 없이 작성하면 YAML 파서가 *를 특수 문자로 해석해 조용히 실패한다. 반드시 "src/app/**/*.tsx"처럼 큰따옴표로 감싸는 것을 권장한다. 위 CI 파이프라인을 연결해두면 이 실수를 자동으로 잡아낼 수 있다.
전사 보안 규칙을 조건부로 걸어두는 것 — 보안 정책은 어떤 파일을 작업하든 적용되어야 한다. paths: 없이 항상 로드되는 전역 파일에 두지 않으면, Claude가 새 파일을 생성하거나 쓰기 작업을 할 때 보안 규칙이 누락될 수 있다.
규칙 파일 소유자를 지정하지 않는 것 — 처음엔 "팀 전체가 관리하면 되지"라고 생각하기 쉬운데, 실제론 아무도 안 관리하게 된다. 파일별로 담당팀과 월별 검토 일정을 명시해두면 규칙이 코드베이스 변화를 따라갈 수 있다.

마치며

.claude/rules/는 AI 규칙을 코드처럼 팀별로 소유하고, Git으로 진화시키는 가장 현실적인 방법이다. 처음부터 완벽한 구조를 만들 필요는 없다. 지금 가장 고통스러운 팀부터 파일 하나 떼어내는 것으로 충분하다.

한 가지 덧붙이자면 — 이 구조가 안정화되면 다음 병목은 규칙 파일이 아니라 팀이 규칙을 얼마나 자주 리뷰하느냐에 있다. 완벽한 규칙 파일보다, 매달 30분씩 팀이 모여 규칙을 점검하는 루틴이 장기적으로 더 큰 차이를 만든다.

지금 바로 시작할 수 있는 3단계:

기존 CLAUDE.md에서 팀별 규칙 분리: mkdir -p .claude/rules 후, 프론트엔드 관련 내용만 뽑아 frontend.md로 이동하면 된다. 파일 상단 프론트매터의 글로브 패턴에는 큰따옴표 필수.
보안 규칙을 security.md로 독립: paths: 없이 전역 로드로 배치한다. TikiTribe의 오픈소스 보안 규칙 셋을 기반으로 시작하면 별도 작성 없이 실무 수준의 가이드라인을 바로 적용할 수 있다.
GitHub Actions에 규칙 검증 스텝 추가: 위 예시 파이프라인을 .github/workflows/validate-rules.yml로 붙여 넣으면 된다. YAML 파싱 오류와 200줄 경고만으로도 팀 규모가 커질수록 큰 도움이 된다.

참고 자료

`Claude Code .claude/rules/`로 팀별 AI 규칙을 모듈화하는 법 — 프론트엔드, 백엔드, 보안 팀 분리 전략 | DEV BAK - 기술블로그

Claude

`Claude Code .claude/rules/`로 팀별 AI 규칙을 모듈화하는 법 — 프론트엔드, 백엔드, 보안 팀 분리 전략

핵심 개념

두 가지 로딩 방식: 전역 vs 조건부

.claude/rules/ 안에 배치된 .md 파일은 크게 두 가지 방식으로 동작한다.

python

.claude/
├── CLAUDE.md              # 전사 공통 규칙
└── rules/
    ├── frontend.md        # 조건부 로드 (paths: 있음)
    ├── backend.md         # 조건부 로드 (paths: 있음)
    ├── security.md        # 항상 로드 (paths: 없음)
    └── testing.md         # 조건부 로드 (paths: 있음)

파일 유형	`paths:` 프론트매터	로드 시점
전역 규칙	없음	세션 시작 시 항상
조건부 규칙	있음	Claude가 해당 글로브 패턴 파일을 Read 도구로 읽을 때

글로브 패턴(Glob Pattern): src/app/**/*.tsx처럼 와일드카드(*, **)를 사용해 파일 경로를 매칭하는 표현식이다. **는 중간 디렉터리를 몇 개든 건너뛸 수 있어 깊은 중첩 경로에서도 유연하게 동작한다.

프론트매터(Frontmatter): Markdown 파일 맨 위에 ---로 감싸인 YAML 메타데이터 블록이다. paths:, title: 같은 구조화된 정보를 파일 내에 함께 담을 수 있다.

모노레포에서의 계층적 로딩

python

my-platform/
├── CLAUDE.md                    # TypeScript strict, pnpm, Git 컨벤션
├── .claude/
│   └── rules/
│       └── security.md          # 전사 보안 규칙 — 항상 로드
├── apps/
│   ├── web/
│   │   ├── CLAUDE.md            # Next.js 앱 공통 규칙
│   │   └── .claude/
│   │       └── rules/
│   │           └── frontend.md  # React/Next.js 세부 규칙
│   └── api/
│       ├── CLAUDE.md            # NestJS 앱 공통 규칙
│       └── .claude/
│           └── rules/
│               └── backend.md   # NestJS/API 세부 규칙
└── packages/
    └── shared/
        └── CLAUDE.md            # 공유 라이브러리 규칙

실전 적용

팀별 규칙 파일 작성

실무에서 자주 쓰는 세 가지 팀 규칙 파일의 실제 작성 예시다.

프론트엔드 팀 (frontend.md)

markdown

---
paths:
  - "src/app/**/*.tsx"
  - "src/components/**/*.tsx"
  - "src/app/**/*.ts"
---
 
# 프론트엔드 규칙
 
- React Server Component를 기본으로 사용하고, Client Component는
  상태·이벤트 핸들링 최소 단위에만 적용
- 모든 API 호출은 Server Actions를 통해 처리 (클라이언트 fetch 금지)
- shadcn/ui 컴포넌트 우선 사용, 커스텀은 src/components/ui/에 배치
- Tailwind CSS 클래스는 cn() 유틸리티로 조합
- named export 사용 (default export 금지)

백엔드 팀 (backend.md)

markdown

---
paths:
  - "src/api/**/*.ts"
  - "src/services/**/*.ts"
  - "src/modules/**/*.ts"
---
 
# 백엔드 규칙
 
- 비즈니스 로직은 Service 레이어에만 위치, Controller는 요청/응답 변환만
- 모든 API 응답은 { data, error, meta } 표준 형태 준수
- DB 마이그레이션은 drizzle/migrations/에서만 관리
- 환경변수는 반드시 src/env.ts에서 Zod 스키마로 검증 후 사용
- async/await 사용, .then() 체이닝 금지

보안 팀 (security.md) — paths: 없이 항상 로드

markdown

# 보안 규칙 (전역 적용)
 
- SQL 쿼리는 반드시 파라미터화 (raw string 쿼리 금지)
- 사용자 입력은 서비스 경계에서만 검증 (DTO + Zod)
- XSS 방지: dangerouslySetInnerHTML 사용 시 보안 팀 리뷰 필수
- JWT 토큰은 httpOnly 쿠키에 저장, localStorage 금지
- OWASP Top 10 최신 기준 준수 (특히 공급망 실패, 취약한 의존성 관리)
- 외부 의존성 추가 시 CVE 스캔 결과 PR에 첨부

CI 검증 파이프라인 연결

yaml

# .github/workflows/validate-rules.yml
name: Validate Claude Rules
 
on:
  pull_request:
    paths:
      - ".claude/rules/**"
      - "**/CLAUDE.md"
 
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: YAML 프론트매터 문법 검사
        run: |
          pip install pyyaml -q
          python3 - << 'PYEOF'
          import sys, re, yaml, glob
 
          errors = []
          for filepath in glob.glob('.claude/rules/**/*.md', recursive=True):
              content = open(filepath).read()
              match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
              if match:
                  try:
                      yaml.safe_load(match.group(1))
                      print(f'OK: {filepath}')
                  except yaml.YAMLError as e:
                      errors.append(f'ERROR: {filepath} — {e}')
 
          if errors:
              for e in errors:
                  print(e, file=sys.stderr)
              sys.exit(1)
          PYEOF
 
      - name: 파일 크기 경고
        run: |
          echo "규칙 파일 라인 수 현황:"
          wc -l .claude/rules/*.md
          for file in .claude/rules/*.md; do
            lines=$(wc -l < "$file")
            if [ "$lines" -gt 200 ]; then
              echo "WARNING: $file — ${lines}줄 (권장 200줄 초과)"
            fi
          done

장단점 분석

장점

항목	내용
관심사 분리	팀별 규칙을 독립 파일로 분리해 머지 충돌 최소화
컨텍스트 효율	글로브 패턴으로 관련 규칙만 로드해 토큰 낭비 방지
독립적 소유권	각 팀이 자신의 파일만 PR로 관리, 타 팀 간섭 없음
점진적 도입	기존 `CLAUDE.md`를 유지하면서 파일 하나씩 추가 가능
Git 이력 추적	규칙 변경 이력이 코드 변경과 함께 PR에 기록됨

단점 및 주의사항

항목	내용	대응 방안
YAML 파싱 오류	`{`, `*`로 시작하는 글로브는 YAML 오류 발생 (Issue #13905, #17204)	패턴을 반드시 큰따옴표로 감싸기
Write 트리거 미지원	`paths:` 규칙이 Read 도구에만 트리거, 쓰기 작업 시 로드 안 됨 (Issue #23478, 2025년 5월 기준 미수정)	중요 쓰기 규칙은 전역 파일에 중복 배치
사용자 수준 규칙 미적용	`~/.claude/rules/`의 `paths:` 무시되는 알려진 버그 (Issue #21858)	글로벌 규칙은 `~/.claude/CLAUDE.md`에 직접 작성

실무에서 가장 흔한 실수

팀에 이 구조를 도입하면서 가장 많이 목격한 실수 세 가지다.

글로브 패턴에 따옴표를 빠뜨리는 것 — paths: - src/app/**/*.tsx처럼 따옴표 없이 작성하면 YAML 파서가 *를 특수 문자로 해석해 조용히 실패한다. 반드시 "src/app/**/*.tsx"처럼 큰따옴표로 감싸는 것을 권장한다. 위 CI 파이프라인을 연결해두면 이 실수를 자동으로 잡아낼 수 있다.
전사 보안 규칙을 조건부로 걸어두는 것 — 보안 정책은 어떤 파일을 작업하든 적용되어야 한다. paths: 없이 항상 로드되는 전역 파일에 두지 않으면, Claude가 새 파일을 생성하거나 쓰기 작업을 할 때 보안 규칙이 누락될 수 있다.
규칙 파일 소유자를 지정하지 않는 것 — 처음엔 "팀 전체가 관리하면 되지"라고 생각하기 쉬운데, 실제론 아무도 안 관리하게 된다. 파일별로 담당팀과 월별 검토 일정을 명시해두면 규칙이 코드베이스 변화를 따라갈 수 있다.

마치며

지금 바로 시작할 수 있는 3단계:

기존 CLAUDE.md에서 팀별 규칙 분리: mkdir -p .claude/rules 후, 프론트엔드 관련 내용만 뽑아 frontend.md로 이동하면 된다. 파일 상단 프론트매터의 글로브 패턴에는 큰따옴표 필수.
보안 규칙을 security.md로 독립: paths: 없이 전역 로드로 배치한다. TikiTribe의 오픈소스 보안 규칙 셋을 기반으로 시작하면 별도 작성 없이 실무 수준의 가이드라인을 바로 적용할 수 있다.
GitHub Actions에 규칙 검증 스텝 추가: 위 예시 파이프라인을 .github/workflows/validate-rules.yml로 붙여 넣으면 된다. YAML 파싱 오류와 200줄 경고만으로도 팀 규모가 커질수록 큰 도움이 된다.

핵심 개념

두 가지 로딩 방식: 전역 vs 조건부

모노레포에서의 계층적 로딩

실전 적용

팀별 규칙 파일 작성

CI 검증 파이프라인 연결

장단점 분석

장점

단점 및 주의사항

실무에서 가장 흔한 실수

마치며

참고 자료

핵심 개념

두 가지 로딩 방식: 전역 vs 조건부

모노레포에서의 계층적 로딩

실전 적용

팀별 규칙 파일 작성

CI 검증 파이프라인 연결

장단점 분석

장점

단점 및 주의사항

실무에서 가장 흔한 실수

마치며

참고 자료

추천 포스트

Claude Code MCP와 `.claude/rules/`로 팀별 AI 도구 접근 권한을 선언적으로 분리하는 방법

Claude Code Status Line 커스터마이징 — 세션 정보를 터미널에 항상 띄우는 법

Claude Code MCP 서버 연동과 Hooks로 PostgreSQL·REST API 호출까지 자동화하기

Claude Code Hooks 실전 가이드 — PreToolUse·PostToolUse로 나만의 자동화 파이프라인 구축하기

Claude Code Routines 실전 가이드 — 스케줄·웹훅·API 트리거로 반복 개발 작업 완전 자동화하기

LangGraph · A2A로 멀티 에이전트 오케스트레이션 구현하기 — 공유 메모리 설계부터 실전 코드까지