swift-architecture-skill

Swift アーキテクチャスキル

概要

このスキルを使うと、SwiftUI/UIKit のコードベースに最適な Swift アーキテクチャのプレイブックを選び、ユーザーのタスクに適用できます。

クイックスタート

アーキテクチャを選ぶ前に、必ず次の項目を把握してください。

• タスクの種類（新機能、リファクタリング、PR レビュー、デバッグ）
• UI スタック（SwiftUI、UIKit、または混在）
• 最小デプロイターゲット（iOS 17 以降では @Observable を利用でき、iOS 16 では ObservableObject が必要です）
• スコープ（単一画面、複数画面、アプリ全体）
• 状態と副作用の複雑さ
• チームの習熟度と依存関係の許容度
• 維持すべき既存の規約

そのうえで、次のように進めてください。

• ユーザーがアーキテクチャを明示している場合は、それを最初の候補として扱い、まず適合性を確認してください
• アーキテクチャが指定されていない場合は、references/selection-guide.md を読み込み、提示された制約から最適なものを推定してください
• 最適な構成が複数のパターンを組み合わせる場合は、機能境界を担うプライマリープレイブックと、補助的な課題を担うセカンダリープレイブックをそれぞれ指定してください
• 制約が明確な単一機能の指針には、クイック推奨モードを選んでください
• 移行、複数のアーキテクチャの混在、またはモジュール境界の変更には、ディープリファクタリングモードを選んでください

クイック推奨モード

次の条件に当てはまる場合は、このモードを使ってください。

• スコープが単一の機能または画面である
• 1 つのプライマリーパターンを推奨できる程度に制約が明確である
• ユーザーが主に必要としているのが、推奨、ひな形、またはレビューチェックリストである

次の内容を提示してください。

• 適合性の結果（fit または mismatch）
• リクエストに基づく理由を 1～2 点
• 選択したリファレンスファイル
• 機能の範囲に沿った、具体的な構成、状態、依存関係、非同期処理、テストの指針

ディープリファクタリングモード

次の条件に当てはまる場合は、このモードを使ってください。

• リクエストが複数のモジュールまたは画面にまたがる
• コードベースですでに複数のアーキテクチャが混在している
• あるパターンから別のパターンへの移行を行う

次の内容を提示してください。

• 現状の評価
• 適合性または不適合性を含む、目標アーキテクチャの推奨
• 境界の変更点を明示した段階的な移行手順
• 移行に伴うリスク、トレードオフ、検証ポイント

アーキテクチャルーター

ユーザーがアーキテクチャを明示している場合は、それを最初の候補として扱い、採用を確定する前に適合性を確認してください。

• UI スタックとの適合性（SwiftUI/UIKit/混在）、最小デプロイターゲット、状態の複雑さ、副作用のオーケストレーションの必要性、チームの習熟度、既存のコードベースの規約に照らして検証してください
• 適合する場合は、指定されたアーキテクチャで進めてください
• 主要な制約に適合しない場合は、その不適合を明確に説明し、references/selection-guide.md から最も適合する代替案を推奨してください
• ユーザーが不適合なアーキテクチャを引き続き希望する場合は、リスクを軽減する計画で進め、冒頭でリスクを示してください

アーキテクチャのリファレンスマッピング：

• MVVM（軽量なバインディングを備えた画面レベルの状態管理） → references/mvvm.md
• MVI（フレームワークに依存しない、リデューサースタイルの状態機械） → references/mvi.md
• TCA（厳密な副作用オーケストレーションを備えたコンポーザブルな機能） → references/tca.md
• Clean Architecture（厳密なレイヤー構成と交換可能なインフラストラクチャ） → references/clean-architecture.md
• VIPER（役割を明確に分離する大規模な UIKit モジュール） → references/viper.md
• Reactive（Combine/RxSwift を多用するストリームベースの機能） → references/reactive.md
• MVP（プレゼンター主導のレンダリングを行う UIKit のパッシブビュー） → references/mvp.md
• Coordinator（ナビゲーションフローとディープリンク） → references/coordinator.md

共有リファレンス（必要に応じて、選択したプレイブックと併せて読み込みます）：

• references/concurrency.md：キャンセル、古いレスポンスへの対処、プレイブックのコード例で使われる userMessage(for:) エラーマッピング規約。非同期コードを作成またはレビューする際に読み込みます
• references/observation.md：デプロイターゲットに応じた @Observable と ObservableObject の使い分け。SwiftUI の状態を接続する際に読み込みます

最適な構成が複数のパターンを組み合わせる場合は、references/selection-guide.md のアーキテクチャの組み合わせに従い、両方のプレイブックを読んでください。ファイル構成やコードを提示する前に、各境界をどのパターンが担うかを明示してください。

既存のコードベースを分析する（該当する場合）

既存のコードがある場合：

• 現在のアーキテクチャと DI スタイルを把握します
• 並行処理モデル（async/await、Combine、GCD、混在）を確認します
• 推奨事項を既存の規約に合わせます

ガードレール

• 現在のローカルパターンがまだ妥当な場合、小規模な機能のためにアーキテクチャの切り替えを強制しないでください。
• 不一致が変更を正当化するほど深刻でない限り、既存の規約を維持してください。
• ユーザーが明示的にトレードオフを受け入れるか、コードベースですでに使用している場合を除き、TCA などの新しいフレームワーク依存関係を導入しないでください。
• 要求を適切に解決できる、最小限のアーキテクチャ変更を優先してください。
• ガイダンスはアーキテクチャ固有のものとし、パターン間の境界が明確でない限り、プレイブックを混在させないでください。
• 複合パターンでは、責務を統合しないでください。まず主要な境界を特定し、その後、二次プレイブックを該当する懸念事項にのみ適用してください。

具体的な成果物を作成する

選択したアーキテクチャのリファレンスを読み、そのガイダンスをユーザーの要求に合わせた成果物に落とし込みます。

• ファイルとモジュールの構成：機能に固有のファイル名を含むディレクトリ構成
• 状態と依存関係の境界：具体的な型、プロトコル、注入ポイント
• 非同期処理の方針：キャンセル、アクター分離、エラー経路
• テスト方針：テスト対象、依存関係のスタブ方法、テスト構成の例
• 移行手順（リファクタリングの場合）：現在のアーキテクチャから目標のアーキテクチャへ移行する段階的な手順
• UI スタックへの適応：選択したアーキテクチャで、SwiftUI と UIKit のガイダンスをどこで分けるか

出力要件

• 推奨事項は、要求された機能またはレビュータスクの範囲内に収めてください。
• プロトコルベースの依存性注入と、明示的な状態モデリングを優先してください。
• 既存コードでアンチパターンが見つかった場合は指摘し、直接的な修正方法を提示してください。
• すべての非同期処理にキャンセル処理とエラー処理を含めてください。
• アーキテクチャが明示的に指定されている場合は、適合結果（fit または mismatch）と、その理由を1～2点示してください。
• 不適合の場合は、最も近い適合案を1つ示し、それが提示された制約により適している理由と、トレードオフを1つ説明してください。
• コードを書く場合は、タスクに関連するパターンのみを含めてください。プレイブック全体をそのまま出力しないでください。
• リファレンスのコード断片は、特に指定がない限り説明用として扱ってください。実行可能なコードを求められた場合にのみ、完全なコンパイル用の枠組みを追加してください。
• 質問は、回答に不可欠なものだけにしてください。それ以外の場合は、前提を明示して作業を進めてください。
• PR をレビューする場合は、アーキテクチャ固有のチェックリストを使用し、違反箇所を行単位の修正案とともに指摘してください。

検証チェックリスト

最終化する前に：

1. 選択したパターンがユーザーの制約とスタックに適合していることを確認します
2. 依存性注入、状態の所有権、副作用、テスト方針が網羅されていることを確認します
3. アーキテクチャの変更を推奨する場合は、移行リスクを明示的に指摘します
4. 選択したアーキテクチャの PR レビューチェックリストを、ユーザーの機能に合わせて調整したうえで最後に記載します

ドキュメント QA チェックリスト

リファレンスを更新する場合は、次の点を検証します。

1. セクション構成に一貫性があること（デフォルトのパス、高度なバリエーション、移行に関する注記、最低基準を含むテストセクション、PR レビューチェックリスト）
2. コード断片に矛盾がなく、コンパイル可能性が妥当であること
3. 他のプレイブックへのリンクが、正しいリファレンスファイルを指していること
4. 選択ガイドとプレイブック全体で用語が一貫していること