iOS minne claude code

CLAUDE.md × Skills × Rules のハイブリッド構成によるiOSアプリ開発の効率化

iOS minne claude code

こんにちは、SUZURI・minne 事業部で minne iOS アプリを開発している umatoshi です。

minne iOS アプリでは主に Claude Code を利用してアプリ開発を行なっています。 期待通りのコーディングをしてもらうために、さまざまな情報を CLAUDE.md に集約させていきました。 その結果、レート制限に到達したり、期待通りのコーディングをしてくれないなど、CLAUDE.mdの肥大化に悩まされました。

本記事では、Claude Code のドキュメント管理機能である CLAUDE.md と、2025年10月にリリースされた Skills、さらに 2025年12月に追加された Rules を組み合わせたハイブリッド構成について紹介します。CLAUDE.md の肥大化を防ぎ、期待通りに Claude Code を利用するためのノウハウを共有します。

1. 導入：肥大化した CLAUDE.md と Skills、Rules のハイブリッド構成に至った経緯

minne の iOS アプリでは、Claude Code の導入当初からプロジェクト固有の情報を CLAUDE.md に集約してきました。リポジトリのコードを読み込ませて分析し、アーキテクチャ方針やコーディング規約を整理してもらいながら、以下のような情報を書き溜めていきました。

  • minne iOS アプリのプロジェクト概要
  • アーキテクチャ方針（MVVM、SPM モジュラー構成）
  • テストのコーディング規約（Swift Testing、TDD）
  • MCP を活用したビルド・配信コマンド
  • SwiftLint、SwiftFormat の利用ガイド
  • SwiftUI 規約（Font、Color）
  • etc

その結果、CLAUDE.md は 2,500 行を超える巨大なドキュメントになり、次のような問題が出てきました。

  • コンテキストウィンドウの圧迫: Claude Code は会話開始時に CLAUDE.md を読み込むため、ファイルが大きくなるほどコードや会話に使える容量が減ってしまう
  • 情報の埋没: Color.mi.* や Swift Testing といった重要な規約が大量の情報に埋もれ、Claude Code が見落としやすくなる
  • トークンコストの増加: 毎回全文を読み込むため、API 利用料が高くなる
  • max_tokens 制限への到達: コンテキストが圧迫されて出力トークンの上限に達しやすくなり、回答が途中で切れることが増えた

そこで、2025年10月に登場した Skills(.claude/skills/*/SKILL.md) を活用することにしました。Skills を使えば、専門知識を Skills として分離し、必要なときだけ呼び出せます。さらに 2025年12月に追加された Rules（.claude/rules/） も組み合わせて、CLAUDE.md をリファクタリングしました。

現在の minne iOS アプリでは、下記のような「CLAUDE.md × Skills × Rules」のハイブリッド構成で運用しています。

現在の構成

.claude/
├── rules/                          # 自動適用される簡潔なルール（最優先で守るべき必須ルール）
│   ├── swift.md                    # Swift全般の規約
│   ├── swiftui-view.md             # SwiftUI View実装規約
│   ├── viewmodel.md                # ViewModel実装規約
│   ├── swift-test.md               # テスト実装規約
│   ├── graphql.md                  # GraphQL全般の規約
├── skills/                         # 必要時に呼び出す詳細ガイド（Rulesの内容を含み、それを拡張する）
│   ├── ios-coding-standards/       # Swiftコーディング規約（swift.mdを拡張）
│   ├── swift-solid-principles/     # SOLID原則ガイド
│   ├── testing-swift-patterns/     # テストパターン（swift-test.mdを拡張）
│   ├── build-dev-commands/         # ビルド・開発コマンド
│   ├── color-font-guidelines/      # Color・Font指定規約（swiftui-view.mdを拡張）
│   ├── apple-docs-integration/     # Apple公式ドキュメント活用ガイド
│   ├── pr-review-guidelines/       # PRレビューガイドライン
│   ├── mcp-tools-guide/            # MCPツールガイド
│   └── graphql-client-guide/       # GraphQLクライアント実装（graphql.mdを拡張）
└── CLAUDE.md                       # プロジェクト全体の概要

従来の単一 CLAUDE.md 構成では 2,500 行を常に全ロードしていたため、コンテキストを圧迫して重要な情報が埋もれがちでした。ハイブリッド構成では、CLAUDE.md 170 行 + 編集中のファイルに応じた Rules + 必要な Skills のみをロードすることで、タスクに最適化されたコンテキストを実現できています。

2. CLAUDE.md を Skills へ分離

CLAUDE.md を「地図」として位置づけ、詳細な知識は Skills として専門領域ごとに切り出しました。

CLAUDE.md を「地図」に

CLAUDE.md はセッション開始時に必ず読み込まれるため、詳細な手順は書かずに「どの Skills をいつ使うべきか」を示す地図の役割に徹しています。これによってトークンを節約しつつ、Claude の自律的な Skills 選択を促せます。

Skills はユーザーが明示的に呼び出さなくても、Claude Code がユーザーの指示内容を分析して適切な Skills を Skills の description から自動推論してくれます。それでも、さらに重要なものや使用頻度が高い Skills は呼び出される確率を上げるために、CLAUDE.md に使用シーンと共に一覧にしています。

CLAUDE.md に記載している Skills 一覧

Skills 名 説明 使用シーン
ios-coding-standards Swift コーディング規約とフォーマット コード作成・修正時
swift-solid-principles SOLID 原則に基づく設計ガイド 設計・リファクタリング時
testing-swift-patterns Swift Testing パターンとテスト戦略 テスト作成時
build-dev-commands ビルド・テスト・コード生成コマンド 開発環境セットアップ時
color-font-guidelines Color・Font 指定規約 UI スタイリング時
apple-docs-integration Apple 公式ドキュメント活用ガイド API 調査・実装前
pr-review-guidelines PR 運用とレビューガイドライン PR 作成・レビュー時
mcp-tools-guide MCP ツール総合ガイド MCP ツール使用時
graphql-client-guide GraphQL Client 実装ガイド GraphQL クエリ・ミューテーション追加時

3. Skills の一部を Rules へ移行

Rules には重要な特性があります。paths 指定をしておけば、その paths のファイルを編集するときだけ読み込まれるため、コンテキストを圧迫しません。この特性を活かして、Skills の中から「必ず Claude Code に守らせたい規約」を抜き出して Rules として整理しました。

Skills → Rules 移行判断基準

ただし、Rules の記述が長くなるとコンテキストを圧迫してしまうため、Skills から Rules に移行するものは最小限のルールに絞りました。判断基準は以下の通りです。

判断軸 Rules に移行 Skills に残す
規約の内容 短いルール・制約（数値リテラル） 複雑なルール・制約(アーキテクチャ説明等)
適用頻度 忘れずに適用したい規約 状況に応じて呼び出す知識
判別のしやすさ ファイル種別で判別可能 ファイル種別で判別不可能

Rules の内容は、既存の Skills から「最低限守るべきルール」を抽出して簡略化したものです。Skills 自体は削除せず残してあるので、詳細な情報が必要なときは Skills を参照できます。

4. 実践例：Claude Code による一気通貫の開発フロー

ここまで CLAUDE.md、Skills、Rules の構成について説明してきましたが、実際に私がどのように Claude Code を活用しているかを紹介します。

minne iOS アプリでは MVVM アーキテクチャを採用しており、新機能の実装時には以下のフローで Claude Code を活用しています。

開発フロー

  1. MVVM ひな形の生成

    • ViewModel のプロトコル定義（Inputs/Outputs パターン）と View の基本構造を生成
    • viewmodel.md Rules が自動適用され、規約に沿ったひな形ができあがる

  2. Figma からデザインを読み込み、SwiftUI で View 実装

    • Figma Context MCP を使って、Figma のデザインファイルを直接読み込み SwiftUI コードに変換
    • swiftui-view.md Rules により Color.mi.*、システムフォント優先（無い場合は scaledFont()）が自動適用

  3. ViewModel のロジック実装

    • View と連携する状態管理とビジネスロジックを実装
    • 必要に応じて swift-solid-principles Skills を呼び出して、設計の妥当性を確認

  4. Swift Testing でテスト作成

    • swift-test.md Rules が自動適用され、subject パターンでテストが生成される
    • 詳細なテスト戦略が必要な場合は testing-swift-patterns Skills を参照

  5. コード品質の担保

    • SwiftFormat、SwiftLint の実行と自動修正
    • XcodeBuildMCP を使ってビルドを実行
    • ビルドエラーの検出と修正まで一貫して対応

このフローの利点

このハイブリッド構成によって、以下のようなメリットが得られています。

  • コンテキストの最適化: 必要な情報だけを読み込むため、コンテキストを圧迫せず、Claude Code がより正確に応答できる
  • 人間は「何を作るか」に集中できる: ひな形生成やコーディングなどの定型作業を Claude Code にサポートしてもらうことで、仕様検討や設計判断、コードレビューに時間を使える
  • 規約の自動適用: Rules により、指示しなくてもプロジェクトの規約に沿ったコードが生成される
  • Figma → コードの直接変換: デザインの再現性も向上

CLAUDE.md、Skills、Rules のハイブリッド構成は、こうした一気通貫の開発フローを支える基盤になっています。

5. まとめ

CLAUDE.md は地図、Skills は専門家、Rules は守るべき規約――この役割分担により、CLAUDE.md の肥大化を防ぎつつ、必要な情報だけを適切なタイミングで読み込む仕組みを実現できました。

プロジェクトが大規模化して Claude Code の回答精度に限界を感じている方は、ぜひこの構成を試してみてください。

関連記事

書いた人