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 月 5 日。挙動は 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 の三層構成 を使っているなら、ターミナル側の層分けは IDE の .cursor/rules と似た発想ですが、パスとロードタイミングは異なる——そのままコピペはできません。

典型的な失敗例：五人の 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 命名規約の要約、DB マイグレーションのロールバック必須、Agent による git push --force 禁止。私たちは Black Hat USA 2026 AI Agent 安全確認チェックリスト でも強調しましたが、ターミナル Agent の権限境界は口頭約束ではなく監査可能な Rule として書くべきです。

Skills：再利用可能な手続きフロー

Skills は ~/.claude/skills/（ユーザー級）または .claude/skills/（プロジェクト級）に置き、各 Skill はディレクトリでコアは SKILL.md です。公式 Skills ドキュメント によると段階的開示を採用しています：

• セッション起動：各 Skill の name と description のみ
• 呼び出し時：本文と同梱スクリプトを読み込み
• 複数 Skill はトークン予算を共有し、先に呼んだものが押し出されることがある

Skill 化に向く作業：TestFlight 公開チェックリスト、PR Review 手順、Flutter 国際化の一括置換、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 が緑であることを確認
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 です。

クラウド 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 時間の層分け投資は通常第三週までに繰り返し説明と失敗リトライの削減で回収できます。「全部 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 で人がトリガーしセッションを短く保つ。

一人開発でもこの仕組みは価値がある？

ありますが極小で十分：50 行の CLAUDE.md、Rules 二つ（安全＋言語）、最も繰り返す作業用 Skill 一つ（例：/ship）。一人チームの強みは反復速度——毎週 15 分の整理は、毎回 build コマンドを打ち直すより得です。

まとめ：ワークフローを描いてから設定ファイルを書く

Claude Code の Rules・Skills・Workflow の組み合わせは、要するに「人の経験を機械がロードできるモジュールに分解する」ことです。CLAUDE.md は「このプロジェクトは何か」、Rules は「絶対にしてはいけないこと」、Skills は「難しい作業の手順」、Workflow は「いつ自動でやるか」に答えます。四層を整理してから手を動かせば、最初から五百行のプロンプトを書くよりずっと楽です。

導入順のおすすめ：今週 CLAUDE.md の骨格 → 来週安全 Rules 二つ → 次に最高頻度 Skill 一つ → 最後にクラウド Mac か CI で Hook。層を足すたびに実タスクで試し、トークンと漏れ率が改善するか見てください。