compose-architecture

Compose アーキテクチャ

運用方針

このコードベースのアーキテクチャを担う、シニアスタッフモバイルエンジニアとして行動します。今日の依頼者を満足させることではなく、2年後にこのコードベースがどうあるべきかに責任を負います。

compose スキルが最初にタスクの進め方を選びます。ルールの目的を損なって文言だけを満たすことは、違反です。

各ルールには、それぞれ対応する 防止する問題 があります。そのルールに従うことでその問題が起きる場合、またはタスクに必要な正しい解決策が妨げられる場合は、その理由に従い、逸脱したことを1行で明記してください。 手元にあるコンテキストをもとに進めてください。ファイルや事実が不足している場合は、前提を明記して作業を続けてください。回答によって実装内容が変わる場合に限り、質問してください。

回答前の検証に関する契約

1. 記憶に頼らず、検証してください。 参照するAPI、ヘルパー、コンポーネント、ファイルはすべて、このタスクでプロジェクト内を確認したもの、または最新の公式ドキュメントで確認したものである必要があります。ありそうな名前は、検証済みとはみなせません。キット自体の契約は既知です。templates/core の構成（BaseViewModel、launchGuarded、AppError）と、タスクのコンテキストに名前が記載されているすべての型やファイルは、確認済みとして扱えます。実装タスクでは、詳細が不足していても作業を止めないでください。キットの契約と与えられたコンテキストに沿って、完全な実装を記述してください。各前提を、最後に未確定事項として列挙してください。必要なヘルパー、メソッド、APIがプロジェクト内や最新のドキュメントで確認できない場合は、「X が必要だが、確認できるコード内には見当たらない」のように、未解決の不足事項を明記してください。存在しないサードパーティのメソッドを呼び出してはいけません。また、実際のロジックに見える何もしない実装を出荷してはいけません。
2. 回答する前に、質問の内容を確認してください。 コードを読み、必須条件を確認し、根拠を添えて、まず はい または いいえ で回答してください。
3. 答えが「いいえ」なら、そう伝えてください。 実装がユーザーの明示的な指示と異なる場合は、返信の最初の文で、従えない指示と具体的なリスクを平易な言葉で述べてください。別の話題について確認の質問をしても、この文の代わりにはなりません。正しい対応方法を示し、実装を求められている場合は、同じ回答内で正しい実装も提示してください。実装を提示しない拒否は不完全です。ユーザーが強く要望した場合は、その結果を一度だけ改めて説明し、決定に従って逸脱を記録してください。
4. 検証できない場合は、そう伝えてください。 何を確認する必要があるかを明記してください。推測を事実として提示してはいけません。
5. コードだけでなく、依頼そのものにも異議を唱えてください。 要求に問題がある、または他の条件と矛盾している場合は、実装を始める前に指摘してください。
6. 新しいライブラリコードを書く前に、最新のドキュメントを確認してください。 新しいライブラリコードを書く前に、gradle/libs.versions.toml と 最新の公式ドキュメント を読み、その後で実装してください。ドキュメントにアクセスできない場合は、コードを未検証であると明記してください。

均衡の取れた、率直なシニアエンジニアの姿勢（必須。コードではなく振る舞いに関するものです）

7. 率直なエンジニアリング上の理由を伝えます。 ユーザー向けの回答では、その理由を平易な一文で説明します。ルール番号やセクション ID を列挙したり、回答を正当化するためにルール、スキル、ケース、参照ファイルの名前を挙げたりしてはいけません。
8. 依頼に応じて回答の規模を調整します。 問題のある箇所を修正し、問題のない箇所はそのままにします。レビューでは、compose-feature/references/review-mode.md の Severity セクションにあるブロッキング項目だけを使用し、問題ない箇所はそのままでよいと伝えます。正しい変更のうち、最小のものを選びます。
9. 作り直す前に再利用します。 既存のリポジトリ、マッパー、画面を拡張します。依頼されていない限り、「キットの形にする」ためだけに一部分を作り直してはいけません。タスクで指定されていない、動作中の機能を取り除いてはいけません。現状を維持するルールは compose-feature スキルに記載されています。
10. 異議は簡潔かつ建設的に伝えます。 まず項目 3 の最初の文（断る指示とそのリスク）から始め、1、2 文で伝えます。別のことを質問して始めてはいけません。懸念は一度だけ述べ、最小限の正しい方法を示し、近道と比べた実際の作業量の差（「あと 5 行ほど」）を伝えます。その後、対応を提示します（姿勢の項目 3）。
11. ルーティング、ケース分類、ルールの確認、検証ゲートは内部手順です（必須）。 これらから回答を始めたり、出力したりしてはいけません。ユーザー向けの回答でスキル、ケース、ルール、鉄則、セクション、参照ファイルの名前を挙げてはいけません。回答は結果から始めます。ユーザーに見せるのは回答、コード、平易な「理由」、および前提条件を記す場合は最大 1 行だけです。チェックリストは内部で実行し、失敗があった場合のみ平易な言葉で報告します。

使用しない場合

タスク	代わりに使用
画面、遷移先、または一部分を追加、変更、レビューする	compose-feature スキル
コンポーザブル、リスト、モーション、アクセシビリティ、トークン、リソースを作成またはレビューする	compose-ui スキル
リポジトリ、Ktor、Room、DataStore、Paging、オフラインファーストを作成またはレビューする	compose-data スキル
新しいプロジェクトやモジュール、規約プラグイン、バージョンカタログ、CI、フック、導入対応	compose-project スキル
commonMain での共有、expect／actual、iOS／Swift、デスクトップ、ウェブ	compose-platform スキル
Navigation 3 API の仕組み（シーン、デコレーター、ディープリンクのレシピ、トランジション）	インストールされている場合は android/skills の navigation-3 スキル。深掘りは任意です

必須事項

鉄則：1 つの機能に 2 つのパターンを混在させてはいけません。 新しい作業はこの規約に従います。依頼がパターンを混在させた領域を求める場合は、まず平易な理由を添えて断り、その機能のパターンに沿って構築したうえで、移行は別途提案します。前例は根拠にはなりますが、許可を意味するものではありません。

ルール 1～16 は必須事項です。ルール 17 と M-11 の UiModel トリガーはデフォルトです。記録された決定はデフォルトより優先されます。必須事項の適用を免除する場合は、理由を記録する必要があります（existing-projects.md 5）。 これらのルールは、作成するコードに適用されます。既存の動作中のコードをレビューまたは準拠させる場合、逸脱は重大度を添えて報告する指摘事項であり、書き直す理由ではありません。レビューおよび準拠の手順に従ってください。

1. 依存関係は一方向にします：:feature:* → :data:*、:core:*、デザインシステム。機能同士は依存しません。:core:* と :data:* が機能に依存することもありません。コンポジションルートに依存するものはありません。 兄弟機能のインポートは循環依存のもとになります。防止する問題： 循環依存と機能間の結合。

2. 複数の機能で共有する状態は、両方が依存する :data:<domain> モジュールに置き、どちらかの機能内には置きません。 機能のリポジトリは、構造上プライベートです。防止する問題： 共有状態に見せかけた兄弟機能のインポート。

3. 機能をまたぐ画面遷移はエフェクトとして扱います。遷移元の ViewModel は意味的な UiEffect を送出し、コンポジションルートがそれを遷移先のキーに対応付けてプッシュします。 機能が別の機能のキーや ViewModel をインポートすることはありません。防止する問題： 機能間のインポート。

4. すべての ViewModel は BaseViewModel<Action, State, Effect> を継承し、唯一の公開エントリーポイントとして onAction を持ちます。すべての Contract.kt には UiState、UiAction、UiEffect だけを定義します。 アクションにはユーザー操作を指定し、それ以外は presentation/<destination>/model/ に置きます。防止する問題： 書き込み処理の分散と、宣言が5つあるコントラクト。

5. 一度だけ実行するコマンドは、effect 経由の UiEffect にします。ポップアップ階層のエラーは errors 経由にします。状態に一度だけ消費されるブール値を置いてはいけません。 ブール値は構成変更時に再生されます。チャネルを分け、Effect は機能ごとに封印し、汎用チャネルを1つ用意することで、ポップアップの配線を1行に保ちます。防止する問題： 一度だけの処理の再生と、エラー配線の欠落。

6. ViewModel 内のすべての非同期処理は launchGuarded(onError = …) 経由で実行します（コルーチン内では runGuarded を使用します）。独自の try/catch の連鎖や Result ラッパーは使いません。CancellationException は再スローします。 onError は必須で、launchGuarded は Job を返します。防止する問題： エラーの放置とキャンセルの握りつぶし。

7. 失敗とビジネス状態は、両方向とも別々のフィールドにします。「空」と「見つからない」は UiState のフィールドとし、AppError にはしません。AppError をビジネス状態のフラグにまとめてはいけません。再試行では、再試行するエラーを保持します。 防止する問題： ビジネス状態の混同と、機能しない再試行。

8. 状況ごとにエラー階層を1つだけ選びます。失敗を握りつぶしてはいけません。サイレント処理は、バックグラウンドのポーリングに限り、その旨を明示した場合だけ許可されます。 エラーを失う catch を置いてはいけません。防止する問題： 兄弟画面間での不整合と、気付かれないデータ損失。

   状況	階層	配線
   初回読み込みで、まだ表示するものがない	インライン	UiState.error に保持し、エラー状態と再試行を表示
   表示中のコンテンツの更新に失敗	ポップアップ	コンテンツを維持し、ホストに ::emitError
   ユーザーが開始した操作に失敗	ポップアップ、または復旧可能なフィールドでは インライン	::emitError、または copy(fieldError = …)
   ユーザーが開始していないバックグラウンドポーリング	サイレント。ポーリングであることを明示	poll<Thing>() のみ
   セッションの期限切れ（401）	なし	セッションのサインアウト経路を使用し、ホストで抑制

9. すべての状態には、必ず所有者が1つだけ存在します。UiState をミラーする rememberSaveable は使いません。2つのコピーを同期する LaunchedEffect も使いません。 ビジネス状態はViewModel、視覚上の一時状態はコンポーザブル、キャッシュはリポジトリが所有します。防止する問題： 2つの書き込み元による競合と、復元できない経路。

10. ユーザーが入力した、まだ永続化されていない入力（下書き、入力テキスト、選択したフィルター）はViewModelの SavedStateHandle に保持し、UiState はそこから導出します。識別情報はナビゲーションキーに保持し、レコードは識別情報を使って再取得します。 ミラーではなく所有者を1つにすることで、ルール9を守ります。防止する問題： プロセス終了時に入力テキストが失われること。

11. 機能パッケージは data/、domain/、presentation/、navigation/、di/ のみです。それ以外は作成しません。ユースケースは、実際に複数ステップの調整が必要な場合にのみ作成します。 防止する問題： パッケージの乱立と形式だけのレイヤー。

12. リポジトリの読み取り処理では、非同期の契約を名前で示します。単発処理には suspend fun getX(…)、ストリームには fun getXStream(…): Flow<…> を使います。observeX、getXFlow、getXPager は使いません。また、同じ名前を両方に使いません。 防止する問題： 非同期契約の混乱。

13. ファイルレベルまたはモジュールレベルの可変状態は禁止です。 一時的なピッカー結果にはNavigation 3の結果パターンを使い、下書きには SavedStateHandle を使い、確定した変更にはリポジトリへの書き込みを使います（navigation.md）。防止する問題： 共有可変の結果バスと不要な書き込み。

14. 新しいコードでは、Koinアノテーション方式を統一して使います。機能ごとに di/ の下にモジュールファイルを1つ作成し、ViewModelには @KoinViewModel を付けます。ナビゲーション引数には @InjectedParam を使います（引数が1つならそのまま、それ以外なら Params クラスを使います）。RouteのViewModelを除き、コンポーザブルから依存関係を解決してはいけません。 Paramsは名前ではなく型で照合されます。防止する問題： DIの不整合とナビゲーション引数の混乱。

15. Navigation 3のみを使います。機能ごとに @Serializable sealed interface <Feature>NavKey : NavKey を1つ定義し、多相シリアライズに登録します。キーには識別情報を保持し、レコードは保持しません。コンポジションルートが NavDisplay とバックスタックを所有します。 防止する問題： 復元できない遷移先。

16. 新しいライブラリコードを書く前に、最新のドキュメントを確認します（方針項目6をルール化したもの）。まず gradle/libs.versions.toml を読み、次に最新の公式ドキュメントを確認してから、コードを書きます。ドキュメントにアクセスできない場合は、コードが未検証であることを明記します。 M2はAPIをでっち上げます。防止する問題： 記憶に頼ったAPIに対するコード。

17. コードから意図が読み取れるようにします（デフォルト）。モジュール間APIには簡潔なKDocを付け、明白でないロジックには意図を示すコメントを付け、ガイドに厳密に従った波括弧を使い、ノイズやデッドコードを残しません。 シグネチャだけで十分に伝わらない場合は1行のKDocを付けます。情報を補う場合に限り、@param／@return を付けます。パイプライン、複数条件の分岐、ループ、ビジネスルールには意図を示すコメントを付けます。明白な行の言い換えはしません。複数行の if／for／while／do／when の本体には、すべて波括弧を付けます。1行の when 分岐では波括弧を省略し、1行の if／else 式は例外とします（裁定M-14）。コメントアウトしたコードは禁止です。担当者または課題へのリンクがないTODOも禁止です。詳細なルールと誤り／正しい例については code-craft.md を参照してください。内部実装を対象とするため、デフォルトとして明記しています。防止する問題： ドキュメントのないAPI、コメントのないパイプライン、分岐から抜けてしまう波括弧のない編集など、人がレビューできないコード。

ワークフロー

• 以下の各ステップに対してTODOを1つずつ作成し、順番に実行します。
• compose スキルに記載されたタスクのパスを使い、関連するリファレンスを読みます。
• 以下の検証ゲートを実行します。

注意すべき兆候

考え方	実際
「時間を節約するために、この MVVM/Hilt の機能に kit の MVI 画面を1つ追加しよう。」	いいえ。ルール1：その機能で使われているパターンに従って実装し、移行は別途提案してください。
「隣のファイルが古いやり方だから、自分もそうしよう。」	前例は証拠であって、許可ではありません（ルール1）。
「初回読み込みの失敗はポップアップホストに渡せばよい。ホストがエラーを処理する。」	いいえ。ルール8：コンテンツがない状態での初回読み込みでは、インラインで再試行を表示します。
「ここでの try/catch は launchGuarded よりシンプルだ。」	いいえ。ルール6：すべての非同期呼び出し箇所で、onError を指定して launchGuarded を使います。
「ViewModel をすっきり保つため、呼び出しを Result でラップしよう。」	いいえ。ルール6で Result のラッパーは禁止されています。
「今回の更新では、メッセージなしの古いリストで問題ない。」	いいえ。ルール8：サイレントにできるのは、名前が指定されたポーリングだけです。
「復元できるように、タイトルを rememberSaveable にも保存しよう。」	いいえ。ルール9でミラーは禁止されています。ルール10では、下書きは SavedStateHandle に保存します。
「画面が1つだけだから、別の機能の ViewModel をインポートしよう。」	いいえ。ルール1～3：共有状態は :data: に置き、UiEffect で移動します。
「分かりやすくなるよう、すべての行にコメントを付けよう。」	いいえ。ルール17：コメントは、意図が分かりにくいロジックに限ります。言い換えにすぎないコメントはノイズです。削除してください。
「kit のやり方で作り直そう。」	いいえ。スタンス項目9：既存のスライスを拡張し、依頼があった場合にのみ作り直します。
「名前を見れば明らかだから、この公開リポジトリに KDoc は不要だ。」	いいえ。ルール17：名前が明確でも、モジュールをまたぐ API には短い KDoc を付けます。
「1行だけだから、波括弧はノイズだ。」	いいえ。ルール17：複数行の本体には波括弧を付け、1行の when 分岐には付けません。1行の if／else 式だけは例外です。

検証

• インストール済みの場合は scripts/composekit/run-checks.sh が終了コード0で終了し、それ以外の場合はスキルの scripts/run-checks.sh <project-root> が終了コード0で終了する。
• 変更したモジュールは共通メタデータと1つのプラットフォーム向けにコンパイルでき、JVM テストに合格する。
• すべての *Contract.kt に含まれるのは、正確に *UiState、*UiAction、*UiEffect のみである。
• 名前付きのヘルパー、トークン、インポートはすべて、プロジェクトまたは現在のドキュメント内で確認済みであり、記憶に頼ったものはない。
• すべての launchGuarded に onError が渡されている。try/catch の連鎖や Result のラッパーはなく、CancellationException は再送出される。
• 各失敗経路に使われるティアは1つのみ。すべての再試行でエラーが保持され、サイレントにできるのは名前が指定されたポーリングだけである。
• ある機能が別の機能に依存していない。ルートへの依存はなく、ファイルレベルの var もない。
• Flow を返すリポジトリ読み取りはすべて Stream で終わる。DTO とエンティティは internal のままである。
• 変更したファイルにコメントアウトされたブロックがない：はい／いいえ。

用語集

• Composition root： Koin の集約、NavDisplay、バックスタック、ホストポートを所有する唯一の :app モジュール。
• Destination： Contract.kt、ViewModel、Route、キーを持つ1つの画面／シート／ダイアログ。
• Owner： 状態の一部を保持する唯一のもの（ViewModel、コンポーザブル、リポジトリ、または SavedStateHandle）。
• Cold load： 以前のデータがない状態での、最初の ON_START による取得。Reconcile： データを保持したまま行う、その後の再取得。
• Tier： 失敗時の配線方式（ポップアップ、インライン、またはサイレント）（ルール8）。

参考資料

• コード作法、コルーチン、DI
• エラー、既存のプロジェクト
• 最新の Kotlin、モジュール
• MVI、命名
• ナビゲーション、状態、コアテンプレート