swift-best-practices

Swift のベストプラクティススキル

概要

macOS 15.7 以降を対象とする iOS および macOS プロジェクト向けに、Swift 6 以降の機能、並行処理の安全性、API 設計の原則、コード品質のガイドラインに重点を置いた、最新の Swift 開発のベストプラクティスを適用します。

このスキルを使用するタイミング

次のような場合に、このスキルを使用してください：

• iOS または macOS アプリケーション向けに新しい Swift コードを書く場合
• 正確性、安全性、スタイルの観点から Swift コードをレビューする場合
• Swift の並行処理機能（async/await、アクター、MainActor）を実装する場合
• Swift API や公開インターフェースを設計する場合
• コードを Swift 5 から Swift 6 に移行する場合
• Sendable／隔離に関連する並行処理の警告、データ競合の問題、コンパイラーエラーに対処する場合
• Swift 6 および 6.2 で導入された最新の Swift 言語機能を使用する場合

SwiftLens MCP の統合（Claude Code）

このスキルは、意味レベルの Swift コード分析を行う SwiftLens MCP サーバー を補完します。

SwiftLens が提供する機能：

• Apple の SourceKit-LSP を使用した、意味レベルの Swift 分析ツール 15 個
• シンボル検索、ファイル間参照、型情報
• 安全なコードの変更とリファクタリング
• Swift コード構造に関するコンパイラー品質の理解

このスキルが提供する機能：

• Swift 6 以降の設計パターンとベストプラクティス
• 並行処理の戦略（async/await、アクター、MainActor）
• API 設計のガイドラインと命名規則
• 移行のガイダンス（Swift 5 → Swift 6）

Claude Code CLI のセットアップ：

Swift プロジェクト内に .claude/mcps/swiftlens.json を作成します。

{
  "mcpServers": {
    "swiftlens": {
      "description": "SwiftLens MCP provides semantic Swift analysis via SourceKit-LSP",
      "command": "uvx",
      "args": ["swiftlens"]
    }
  }
}

⚠️ 注意：これは Claude Code の設定です（Claude Desktop ではありません）。セットアップ手順、15 個すべてのツール、インデックスの構築、使用例については、references/swiftlens-mcp-claude-code.md を参照してください。

ワークフロー：SwiftLens は 実行時分析（コードが何をしているか）を提供し、このスキルは 設計の専門知識（コードが何をすべきか）を提供します。

基本ガイドライン

基本原則

1. 使用箇所での明確さが最も重要です。宣言だけでなく、ユースケースを検討して設計を評価してください
2. 簡潔さより明確さを優先してください。コンパクトなコードは、最小限の文字数ではなく、型システムによって実現します
3. すべての公開宣言にドキュメントを記述してください。機能を簡潔に説明できない場合、API の設計が不適切である可能性があります
4. 型ではなく役割に基づいて名前を付けてください。var string = "Hello" ではなく var greeting = "Hello" とします
5. シンプルさによって洗練を目指してください。複雑さが本当に必要でない限り、過剰な設計は避けてください

Swift 6 の並行処理モデル

Swift 6 では、領域ベースの隔離（SE-0414）により、デフォルトで完全な並行処理チェックが有効になります。コンパイラーがコードの安全性を証明するようになり、多くの誤検出を排除するとともに、実際の並行処理の問題をコンパイル時に検出します。

重要な理解事項：

• 非同期 ≠ バックグラウンド — 非同期関数は中断できますが、自動的にバックグラウンドスレッドで実行されるわけではありません
• アクターは自動同期によって、変更可能な共有状態を保護します
• @MainActor は UI 関連のコードがメインスレッドで実行されるようにします
• グローバルアクターで隔離された型は、自動的に Sendable になります

必須パターン

Async/Await

// Parallel execution with async let
func fetchData() async -> (String, Int) {
    async let stringData = fetchString()
    async let intData = fetchInt()
    return await (stringData, intData)
}

// Always check cancellation in long-running operations
func process(_ items: [Item]) async throws -> [Result] {
    var results: [Result] = []
    for item in items {
        try Task.checkCancellation()
        results.append(await process(item))
    }
    return results
}

UI コード向けの MainActor

// Apply at type level for consistent isolation
@MainActor
class ContentViewModel: ObservableObject {
    @Published var images: [UIImage] = []

    func fetchData() async throws {
        self.images = try await fetchImages()
    }
}

// Avoid MainActor.run when direct await works
await doMainActorStuff()  // Good
await MainActor.run { doMainActorStuff() }  // Unnecessary

アクター隔離

actor DataCache {
    private var cache: [String: Data] = [:]

    func store(_ data: Data, forKey key: String) {
        cache[key] = data  // No await needed inside actor
    }

    nonisolated func cacheType() -> String {
        return "DataCache"  // No await needed - doesn't access isolated state
    }
}

避けるべきよくある落とし穴

1. 関数に不必要に async を付けないでください — 非同期呼び出し規約にはオーバーヘッドがあります
2. async/await と DispatchSemaphore を決して併用しないでください — デッドロックの危険があります
3. ステートレスなアクターを作成しないでください — 代わりに非隔離の非同期関数を使用してください
4. 隔離の分割を避けてください — 1 つの型の中で複数の隔離領域を混在させないでください
5. タスクのキャンセルを確認してください — 長時間の処理では Task.checkCancellation() を確認する必要があります
6. 非同期処理がバックグラウンド処理を意味すると思い込まないでください — 必要に応じて、処理を明示的にバックグラウンドに移してください
7. 過剰なコンテキスト切り替えを避けてください — 同じ隔離領域内で処理をまとめてください

API 設計クイックリファレンス

命名規則

• 型／プロトコル：UpperCamelCase
• その他すべて：lowerCamelCase
• 機能を表すプロトコル：-able、-ible、-ing の接尾辞（Equatable、ProgressReporting）
• ファクトリーメソッド：make で始めます（x.makeIterator()）
• ミューティングメソッドのペア：命令形と過去分詞形（x.sort() ／ x.sorted()）

副作用に応じたメソッドの命名

• 副作用なし：名詞句（x.distance(to: y)）
• 副作用あり：命令形の動詞（x.append(y)、x.sort()）

引数ラベル

• 引数を区別できない場合は省略します：min(number1, number2)
• 値を保持する変換では、最初のラベルを省略します：Int64(someUInt32)
• 前置詞句では、前置詞の位置にラベルを付けます：x.removeBoxes(havingLength: 12)
• その他すべての引数にはラベルを付けます

Swift 6 の破壊的変更

型に @MainActor を明示的に指定する必要があります（SE-0401）

プロパティラッパーによるアクター分離の自動推論は行われなくなりました。

@MainActor
struct LogInView: View {
    @StateObject private var model = ViewModel()
}

グローバル変数は並行処理に対して安全である必要があります（SE-0412）

static let config = Config()  // Constant - OK
@MainActor static var state = State()  // Actor-isolated - OK
nonisolated(unsafe) var cache = [String: Data]()  // Unsafe - use with caution

その他の変更

• @UIApplicationMain／@NSApplicationMain は非推奨です（@main を使用してください）
• 存在型には any が必要です
• インポートの可視性には明示的なアクセス制御が必要です

API の利用可能性に関するパターン

// Basic availability
@available(macOS 15, iOS 18, *)
func modernAPI() { }

// Deprecation with message
@available(*, deprecated, message: "Use newMethod() instead")
func oldMethod() { }

// Renaming with auto-fix
@available(*, unavailable, renamed: "newMethod")
func oldMethod() { }

// Runtime checking
if #available(iOS 18, *) {
    // iOS 18+ code
}

// Inverted checking (Swift 5.6+)
if #unavailable(iOS 18, *) {
    // iOS 17 and lower
}

主な違い：

• deprecated - 警告が表示されますが、使用できます
• obsoleted - 指定したバージョン以降はエラーになります
• unavailable - エラーになり、使用が完全に禁止されます

このスキルの使い方

コードを書くとき

1. 役割に基づき、明確さを優先した原則に従って命名規則を適用します
2. 適切な分離を使用します（UI には @MainActor、変更可能な状態にはアクター）
3. 適切なキャンセル処理を行い、async/await のパターンを正しく実装します
4. Swift 6 の並行処理モデルに従い、コンパイラのフロー解析を信頼します
5. 公開 API には、明確で簡潔な概要を記述します

コードをレビューするとき

1. 並行処理の安全性に関する違反がないか確認します
2. アクター分離と Sendable への適合が適切か確認します
3. 非同期関数がキャンセルを適切に処理していることを確認します
4. API の命名が Swift のガイドラインに従っているか検証します
5. 利用可能性の注釈が対象プラットフォームに適していることを確認します

コード品質の基準

• コメントは最小限にします。可能な限り、コード自体で内容が分かるようにします
• 過剰な設計や不要な抽象化を避けます
• 型ではなく役割に基づいた、意味のある変数名を使用します
• プロジェクトで確立されているアーキテクチャとパターンに従います
• filter().count より count(where:) を優先します
• サイズが固定され、パフォーマンスが重要なデータには InlineArray を使用します
• コンパイラの並行処理フロー解析を信頼し、不要な Sendable 適合を避けます

リソース

references/

詳細な情報が必要な場合に読み込む、詳細なリファレンス資料です。

• swiftlens-mcp-claude-code.md - Claude Code CLI 向け SwiftLens MCP サーバーのセットアップ、15 種類のセマンティック解析ツール、インデックスの構築、使用例、統合ワークフロー
• api-design.md - API 設計規則、ドキュメントの基準、パラメーターのガイドライン、命名パターンの全容
• concurrency.md - async/await のパターン、アクターのベストプラクティス、よくある落とし穴、パフォーマンス上の考慮事項、スレッドセーフのパターンの詳細
• swift6-features.md - Swift 6／6.2 の新しい言語機能、破壊的変更、移行方法、最新のパターン
• availability-patterns.md - @available 属性の包括的な使い方、非推奨化の方法、プラットフォームバージョンの管理

上記の基本ガイドラインを超える詳細情報が必要な場合は、これらのリファレンスを読み込んでください。

プラットフォーム要件

• Swift 6 の機能には Swift 6.0 以降のコンパイラが必要です
• InlineArray と強化された並行処理機能には Swift 6.2 以降が必要です
• 適切な SDK を備えた macOS 15.7 以降
• 最新のプラットフォーム機能には iOS 18 以降
• 実行時のプラットフォーム検出には #available を使用します
• API の利用可能性の指定には @available を使用します