Claude Code 설정 가이드: Rules·Skills·Workflow를 어떻게 조합할까?

결론부터: Claude Code 설정은 「한 파일에 프롬프트를 쌓는 일」이 아니라 네 층의 역할 분담입니다——CLAUDE.md에는 항상 알아야 할 프로젝트 사실, Rules에는 경로 스코프 제약과 관례, Skills에는 재사용 가능한 다단계 절차, Workflow로 Skills·Hooks·정시 작업·CI를 팀이 복제할 수 있는 자동화로 엮습니다. 층을 섞는 것이 가장 흔한 실패입니다. 40줄 배포 체크리스트를 CLAUDE.md에 넣으면 세션 시작마다 수천 토큰을 쓰고, 「force push 금지」 같은 레드라인을 Skill 안에 흩뿌리면 컨텍스트 압축 후 Claude가 잊어버립니다.

이 글은 Claude Code를 쓰거나 도입을 검토하는 iOS·Flutter·AI 앱 개발자, 특히 주력 개발 환경을 클라우드 Mac·리모트 Mac 렌탈로 옮기려는 팀을 위한 것입니다. 2026년 8월 공식 문서와 실측을 바탕으로 디렉터리 구조, YAML frontmatter 예시, 조합 결정표, Apple Silicon 클라우드 Mac 장기 운용 시 유의점을 정리합니다.

데이터 확인일: 2026년 8월 6일. 동작은 Claude Code Skills 공식 문서와 Anthropic 블로그를 따릅니다. 버전에 따라 frontmatter 필드는 약간 달라질 수 있습니다.

왜 하나의 거대 CLAUDE.md가 아니라 층을 나누나

많은 팀의 첫 반응은 같습니다. Claude Code가 저장소를 읽을 수 있으니 루트 CLAUDE.md에 모든 약속을 쓰면 끝이라고 생각합니다. 문제는 컨텍스트 예산이 공유된다는 점입니다——매 세션 상시 로드되는 내용이 많을수록 코드 diff와 도구 출력에 쓸 공간이 줄어듭니다. 더 나쁜 경우는 절차적 내용(「테스트 → 버전 bump → tag → push」)과 사실적 내용(「메인 scheme은 MyApp-Prod, 인증서는 Profile XYZ」)이 섞여 한 줄을 고칠 때 전체가 흔들립니다.

Anthropic Steering 공식 블로그는 커스터마이즈 수단을 일곱 가지로 나눕니다: CLAUDE.md, Rules, Skills, Subagents, Hooks, Output Styles, 시스템 프롬프트 추가. 대부분의 엔지니어링 팀에는 앞 네 가지와 Workflow 오케스트레이션으로 90%를 커버할 수 있습니다. 이미 Cursor + Claude Code + OpenRouter 3단 구성을 쓰는 경우, 터미널 층 분리는 IDE의 .cursor/rules와 비슷한 발상이지만 경로와 로드 시점이 다릅니다——그대로 복사해 붙이지 마세요.

흔한 실패 사례: 5인 Flutter 팀이 Code Review 체크리스트, Archive 단계, Git 브랜치 전략을 모두 CLAUDE.md에 넣어 400줄을 넘겼습니다. widget 하나를 고칠 때도 runbook 전체를 짊어져 응답이 느려지고, 압축 후 후반 테스트 요구를 「잊는」 경우가 늘었습니다. path-scoped Rules와 Skill 세 개로 나눈 뒤 같은 작업에서 입력 토큰이 평균 약 30% 줄고 Review 누락은 줄었습니다.

핵심 개념: 네 층이 각각 풀 문제

CLAUDE.md: 프로젝트 「상시 메모리」

CLAUDE.md(또는 .claude/CLAUDE.md)는 세션 시작 시 로드되며 짧고·안정적·전원 합의 정보에 적합합니다:

• 원클릭 빌드·테스트(xcodebuild -scheme MyApp test 등)
• Monorepo 디렉터리 지도(apps/ios, packages/core 역할)
• 활성 Skills / Rules 색인(한 줄 설명 + 경로)
• 팀 금기 사항의 요약(상세는 Rules)

공식 권장은 읽기 쉬운 분량입니다. 200줄을 넘기면 절차를 잘못 넣었는지 의심하세요. CLAUDE.md는 wiki가 아니라 Claude의 「부팅 자가 점검표」입니다.

Rules: 제약과 경로 스코프 관례

Rules는 .claude/rules/ 아래 Markdown으로 Claude에 특정 제약을 줍니다. CLAUDE.md와의 핵심 차이:

• path-scoped 가능: 매칭 파일 편집 시에만 로드(예: paths: ["**/*.swift"])
• 컨텍스트 압축(compaction) 후 재주입——보안 레드라인에 적합
• 톤은 「해야 함 / 금지」이지 「다음 12단계로」가 아님

Rules에 넣을 내용: 비밀 커밋 금지, Swift naming 요약, DB 마이그레이션 롤백 필수, Agent의 git push --force 금지. Black Hat USA 2026 AI Agent 보안 원격 Mac 점검표에서도 강조했듯, 터미널 Agent 권한 경계는 구두 약속이 아니라 감사 가능한 Rule로 써야 합니다.

Skills: 재사용 가능한 절차적 플로우

Skills는 ~/.claude/skills/(사용자) 또는 .claude/skills/(프로젝트)에 두고, 각 Skill은 디렉터리이며 핵심은 SKILL.md입니다. 공식 Skills 문서에 따르면 점진적 공개를 씁니다:

• 세션 시작: 각 Skill의 name과 description만
• 호출 시: 본문과 번들 스크립트 읽기
• 여러 Skill이 토큰 예산을 공유, 먼저 호출된 것이 밀려날 수 있음

Skill화에 좋은 작업: TestFlight 릴리스 체크리스트, PR Review 단계, Flutter i18n 일괄 치환, OpenAPI 클라이언트 재생성. YAML frontmatter로 allowed-tools(사전 승인), disable-model-invocation: true(수동 /skill-name만), context: fork(서브 Agent 실행) 등을 설정할 수 있습니다.

Workflow: 구성 요소를 팀 리듬으로 엮기

Workflow는 다섯 번째 폴더가 아니라 오케스트레이션입니다. Hooks가 git commit 전 formatter를 돌리고, 정시 작업이 밤에 /refactor-module Skill을 호출하고, CI가 비대화형 Claude Code로 마이그레이션 스크립트를 생성하고, 클라우드 Mac의 launchd가 세션 환경을 일정하게 유지합니다. Workflow가 답하는 질문은 「누가·언제·어떤 층을 트리거하는가」입니다.

조합 대조: 무엇을 어디에 둘까

실습: iOS 팀 설정을 처음부터

아래 디렉터리 구조는 2~6인 iOS / Flutter 혼합 저장소에서 검증했습니다. 팀에 맞게 줄이세요:

your-repo/
├── CLAUDE.md                    # 빌드 명령, scheme 목록, Skill 색인
├── .claude/
│   ├── settings.json            # 팀 공유 설정(비밀 넣지 않기)
│   ├── settings.local.json      # 로컬 덮어쓰기, gitignore
│   ├── rules/
│   │   ├── global-security.md   # .env 읽기·force push 금지
│   │   ├── ios-swift.md         # paths: ["**/*.swift"]
│   │   └── flutter-dart.md      # paths: ["lib/**/*.dart"]
│   └── skills/
│       ├── release-testflight/
│       │   └── SKILL.md
│       └── pr-review/
│           └── SKILL.md

1단계: CLAUDE.md 작성(80~120줄). 앞에 scheme·최소 OS·테스트 진입을 표로; 중간에 디렉터리 설명; 끝에 사용 가능 Skill bullet(이름+한 줄). 여기에 단계별 조작은 쓰지 않습니다.

2단계: Rules 분리. 전역 보안은 단일 파일; 언어 규약은 경로로 분리. path-scoped frontmatter 예:

---
paths:
  - "**/*.swift"
  - "**/*.xcodeproj/**"
---

# iOS / Swift 제약
- 새 UI에는 Preview 또는 생략 사유
- Signing & Capabilities의 Team ID 변경 금지
- 네트워크 계층 변경 시 단위 테스트 업데이트

3단계: 첫 Skill. 가장 잦고 실수하기 쉬운 절차부터——많은 iOS 팀은 TestFlight 릴리스나 PR Review입니다:

---
name: release-testflight
description: "메인 scheme Archive 후 TestFlight 업로드. 릴리스일 또는 「배포」 시 사용"
disable-model-invocation: true
allowed-tools: Bash(xcodebuild *) Bash(fastlane *)
---

## 배포 전 점검
1. `main` 머지·CI green 확인
2. `CHANGELOG` 최신 항목과 버전 일치 확인
3. `xcodebuild -scheme MyApp -destination 'generic/platform=iOS' archive` 실행
4. fastlane `upload_testflight` lane 호출
5. PR에 build 번호·처리 그룹 코멘트

disable-model-invocation: true는 개발자가 수동으로 /release-testflight를 입력할 때만 로드한다는 뜻입니다. UI 수정 중 오배포를 막습니다. 민감 작업에는 필수입니다.

4단계: Workflow 연결. .claude/settings.json에 Hooks(PreToolUse로 위험 명령 차단 등)를 설정하고, 클라우드 Mac·로컬 모두 같은 .claude를 쓰면 Remote Mac SSH 동작이 로컬과 같습니다. 팀 공유는 Git, 개인 API Key와 settings.local.json은 gitignore입니다. CI 파이프라인 설계는 VPS 클라우드 Mac 프로덕션 개발 환경 2026: 제로에서 CI/CD 완전 자동화도 참고하세요.

클라우드 Mac / Apple Silicon 연계 시나리오

Claude Code는 본질적으로 터미널 Agent입니다. 실행 환경 품질이 곧 맡길 수 있는 범위를 정합니다. VPSSpark 같은 클라우드 Mac·리모트 Mac 렌탈에서 설정 층 분리는 세 가지 실익이 있습니다:

• 환경 고정: .claude/, Homebrew 의존, Ruby fastlane 버전을 이미지에 굽히면 노드 교체 시 Skill 재설정 불필요.
• 장세션 안정: Apple Silicon M4 통합 메모리는 Xcode·시뮬레이터·Claude Code 동시 실행에 적합. 대기 약 4W로 야간 /refactor Skill에 유리.
• 권한 분리: 클라우드 Mac 전용 macOS 사용자로 Agent 실행, Rules로 키체인 경로 제한——개인 본기에서 맨몸으로 돌리는 것보다 안전.

대표 Workflow: 로컬 Cursor에서 코드 수정 → Git push → 클라우드 Mac CI가 pull 후 비대화형 마이그레이션 Skill → fastlane 업로드. Rules가 CI에서 force push를 막고, Skills가 수동 배포와 같은 단계를 보장합니다. Flutter 팀은 flutter build ipa와 iOS 서명도 Skill화하고 같은 보안 Rules를 공유할 수 있습니다.

OpenRouter 등으로 API 비용을 줄이는 경우 Skills의 allowed-tools와 모델 선택은 무관하지만, Workflow에서는 서브 Agent(context: fork) 병렬 시 메모리 피크를 봐야 합니다. M4 16GB 노드에서 fork Skill 두 개와 Xcode Archive를 동시에 돌리면 한계에 닿을 수 있습니다. Rules나 Skill에 「Archive 중 두 번째 fork Skill 병렬 금지」를 명시하는 것이 현실적입니다.

비용·성능·리스크 비교

토큰 비용: 비대한 CLAUDE.md는 매 세션 「배경세」를 냅니다. Skills 점진적 공개는 절약하지만 한 세션에 Skill을 연속 호출하면 예산을 나눠 씁니다. /context나 공식 토큰 통계로 어떤 층이 큰지 주기적으로 확인하세요.

유지 비용: Rules·Skills는 code review·버전 관리 가능——구두보다 저렴합니다. Skill이 15개 넘으면 색인·폐기 담당이 필요합니다.

리스크: allowed-tools 사전 승인은 Skill 활성 턴에서 확인 문턱을 낮춥니다——신뢰 Skill만. 공유 클라우드 Mac은 settings.local.json으로 개인 키 격리. Hooks 오설정은 commit 불가를 만들 수 있으니 브랜치에서 먼저 시험하세요.

「아무 설정 없이 매번 구두」와 비교하면 초기 2~4시간 투자는 보통 3주차에 반복 설명·재시도 감소로 회수됩니다. 「전부 CLAUDE.md」와 비교하면 층 분리의 장기 토큰·누락률이 더 관리 가능합니다. 분기마다 .claude 트리를 돌며 미사용 Skill을 폐기하고 path 스코프를 줄이는 팀이 설정 비대 없이 효과를 유지합니다.

FAQ

Claude Code Rules와 Cursor Rules를 같이 쓸 수 있나요?

개념은 비슷하지만 경로·형식이 다릅니다. Cursor는 .cursor/rules, Claude Code는 .claude/rules/. 같은 Markdown 소스를 스크립트로 양쪽에 동기화할 수는 있지만 자동 상호 연동은 기대하지 마세요.

Skill이 외부 스크립트를 호출할 수 있나요?

가능합니다. Skill 디렉터리에 scripts/를 두고 본문에서 실행을 지시하세요. allowed-tools: Bash(./scripts/*)로 반복 확인을 줄입니다. 스크립트는 사람이 review하고, 감사 안 된 shell을 Agent에 맡기지 마세요.

팀은 새 Rule·Skill을 어떻게 리뷰하나요?

코드와 같은 PR로: .claude/rules/foo.md나 skills/bar/SKILL.md 추가 시 사람 reviewer가 보안 Rules 충돌·CLAUDE.md 중복을 확인합니다. Claude Code Settings 문서의 skillOverrides로 파일 삭제 없이 임시 비활성화할 수 있습니다.

컨텍스트 압축 후 Skill 단계를 잊으면?

긴 세션에서 먼저 호출한 Skill이 공유 예산에서 밀릴 수 있습니다. 대응: 핵심 단계를 Hook으로(확정적); Skill 끝에 체크리스트를 파일로 출력; 배포 Skill은 disable-model-invocation: true로 사람이 트리거해 세션을 짧게.

1인 개발도 이 구조가 가치 있나요?

있습니다. 극소로: 50줄 CLAUDE.md, Rules 2개(보안+언어), 가장 자주 하는 Skill 하나(예: /ship). 1인의 강점은 반복 속도——매주 15분 정리는 매번 build 명령을 다시 치는 것보다 낫습니다.

정리: 워크플로를 그린 뒤 설정 파일을 쓰세요

Claude Code Rules·Skills·Workflow 조합은 사람의 경험을 기계가 로드할 모듈로 쪼개는 일입니다. CLAUDE.md는 「이 프로젝트가 무엇인지」, Rules는 「절대 하지 말 것」, Skills는 「복잡한 일의 순서」, Workflow는 「언제 자동으로 하는지」에 답합니다. 네 층을 정리한 뒤 시작하면 처음부터 500줄 프롬프트보다 훨씬 수월합니다.

도입 순서: 이번 주 CLAUDE.md 골격 → 다음 주 보안 Rules 2개 → 최빈 Skill 1개 → 마지막에 클라우드 Mac·CI Hook. 층을 추가할 때마다 실제 작업으로 토큰·누락률을 확인하세요.