compose-project

Compose Project

運用方針

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

ビルドファイルは、急いで通り過ぎるための足場ではなく、重要な契約です。モジュールのビルドファイルに加えた近道は、その後のすべてのモジュールに波及します。ルールの文言を満たしながら、その目的を損なうことは違反です。

回答前に検証する契約（要約版。全文は compose-architecture スキルにあります）

1. 記憶に頼らず、検証してください。 記述するすべてのプラグイン ID、座標、Gradle DSL ブロックは、gradle/libs.versions.toml に記載されたバージョンの公式ドキュメントで確認したものにしてください。キット自体の契約は既知です。このスキルの templates/ の形式と、タスクのコンテキストで指定されたすべてのファイルは、確認済みのものとして扱います。存在しないプラグインやタスクを呼び出してはいけません。
2. 答える前に質問を確認してください。 ビルドファイルを読み、譲れない条件を確認し、証拠（ファイルパスまたはドキュメント URL）を示して、まずはい／いいえで答えてください。
3. 答えが「いいえ」なら、そう伝えてください。 正しいアプローチを示し、実装を求められている場合は、同じ回答内で正しい実装も提示してください。実装を伴わない拒否は不完全です。異議は簡潔で率直に、状況に応じた程度にしてください（compose-architecture スキルの「運用方針」項目 7〜11 を参照）。そこでのルーティング、ケース分類、検証ゲートについては明示しないでください。
4. 検証できない場合は、その旨を伝えてください。 何を確認する必要があるかを示してください。推測を事実として提示してはいけません。
5. 新しいビルドコードを追加する前に、最新のドキュメントを確認してください。 新しい Gradle プラグイン、AGP のアップグレード、KMP ターゲット、または相互運用ライブラリを適用する前に、gradle/libs.versions.toml のバージョンを確認し、そのバージョンに対応する最新の公式ドキュメントを読んでから記述してください。ドキュメントにアクセスできない場合は、変更が未検証であることを明記してください。

使用しない場合

タスク	代わりに使用
まずタスクの経路と読むべきファイルを判断する	以下の作業に入る前に、compose スキルを使用
画面、デスティネーション、またはスライスを追加、変更、レビューする	compose-feature スキル
リポジトリ、Ktor、Room、DataStore、Paging、オフラインファースト	compose-data スキル
commonMain の共有、expect／actual、iOS／Swift、デスクトップ、ウェブ	compose-platform スキル
Composable、安定性、リソース	compose-ui スキル

絶対に守るべき事項

ルール1～8は必ず守るべき事項です。ルール9～10はデフォルトです。## Project decisions に記録されたプロジェクトの決定があれば、異議なくそれに従います。必ず守るべき事項の例外を認めるには、理由を記録する必要があります（compose-architecture スキルの existing-projects.md の項目5を参照）。

1. ライブラリ、データ、機能モジュールのビルドファイルには、ターゲット、SDK、ツールチェーンの設定を記述せず、規約プラグインに任せます。 :feature:tags のビルドファイルでは、機能プラグインを適用し、名前空間と依存関係のみを宣言します。（例外：コンポジションルートのシェルである CMP の :androidApp、または Android 専用プロジェクトの :app では、公式テンプレートの android {} ブロックをそのまま使用します。）ターゲットブロックを1つのライブラリモジュールにコピーすると、50個のモジュール間で確実に差異が生じます。防止する問題： モジュールごとの SDK の不整合（brief §12.1）。
2. 依存関係の型がこのモジュールの公開シグネチャに登場する場合に限り api() を使い、どの型かを示すコメントを添えます。 漏れ出した型は、すべての利用側のクラスパスとビルドグラフを拡大します。防止する問題： コアモジュールを介したクラスパスの漏出（brief §12.6）。
3. どのモジュールもコンポジションルートに依存してはいけません。 ルートだけが機能モジュールとデータモジュールに依存します。ルートの NavKey やコンポーネントをインポートする機能モジュールは、循環依存を作っています。防止する問題： 機能モジュールからルートへの循環依存（brief §1.2）。
4. 新しいモジュールはすべて .composekit.conf に登録し、run-checks.sh に合格する必要があります。 未登録のモジュールはガードから見えません。対象をスキップしたまま成功する実行は、見せかけにすぎません。防止する問題： ガードの対象外となるモジュール。
5. 既存プロジェクトへの導入は段階的に行います。ガードは既存プロジェクトでは WARN モードで開始し、ベースラインがクリーンになってからブロックモードに切り替えます。 別のタスクのついでに、動作中の機能を書き換えてはいけません。1つの機能内に2つのパターンを混在させてはいけません（compose-architecture スキルを参照）。防止する問題： 途中で停滞する一括書き換え（STANDARDS §6）。
6. 新しいビジネスロジックをコンポジションルートに置いてはいけません。 ルートのスライスは一時的な足場であり、対象モジュールが完成したら削除します。「今のところ :app に置いておく」タグフィルタリングは、ガードでは検出できない安易な回避策として放置されます。防止する問題： ルートが何でも放り込む場所になること（brief §12.3）。
7. バージョンはすべて gradle/libs.versions.toml で一度だけ宣言し、モジュールのビルドファイルには記述しません。 同じバージョンを2か所に記述すると、どちらか一方を更新した日に食い違います。防止する問題： モジュール間のバージョン不整合。
8. Compose の安定性設定ファイルは、モジュールごとに手動で設定せず、build-logic で配線します。 共有設定では、ドメインモデルのパッケージと kotlin.collections.* を宣言します。有効性は不変モデルを前提とします。このルールは設定を管理する compose-ui スキル（ルール4）に定められています。防止する問題： 安定性の修正が気付かないうちに適用されなくなること。
9. ［デフォルト］プロジェクトに別の決定が記録されていない限り、UiModel のスキャフォールド切り替え設定は when-needed のままにします。 .composekit.conf の UI_MODEL=always を設定すると、スキャフォールドはデフォルトで UiModel のペアを生成します。「すべての機能で UiModel を使う」という ## Project decisions の記録がある場合も、この設定にします。チャット上の希望は現在のタスクにのみ適用され、エージェントはその希望を記録することを提案します。
10. ［デフォルト］ガードは、迂回するのではなく run-checks.sh レジストリを通じて、変更のたびに CI で実行します。 CI ジョブはレジストリを呼び出し、エージェントのフックは Compose の変更を終える前にレジストリを呼び出します。ジョブの具体的な構成はプロジェクトの forge に従いますが、レジストリを最初に実行する順序は変わりません。

バージョンの条件：作成を始める前に gradle/libs.versions.toml を確認します。AGP が 9 未満の場合は、AGP 9 の形式を適用せず、停止して報告します。Kotlin が 2.3.20 未満の場合は、Koin コンパイラープラグインを適用せず、停止して報告します。Kotlin がインストール済みの SKIE がサポートする最高バージョンを超えている場合は、SKIE を追加せず、停止して報告します。

ワークフロー

• 以下の各手順について1つずつ ToDo を作成し、順番に実行します。
• このタスクが4つのワークフロー（bootstrap、adopt-existing、add-module、CI/hooks）のどれに該当するかを明示します。該当するチェックリストだけに従ってください。チェックリスト同士は内容を繰り返さず、相互にリンクしています。

新しいプロジェクトのブートストラップ

• 判断表から対象の構成を選びます（CMP アプリか Android 専用か）。
• templates/project/ のキットの骨組みを配置します。ルート設定、ルートビルドファイル、gradle.properties、gradle/libs.versions.toml、build-logic/、compose-architecture テンプレートの :core:mvi と :core:error、:core:designsystem、:feature:notes、コンポジションルート（CMP では :composeApp と :androidApp、Android 専用では :app）を含めます。:data:<domain> モジュールは、2 つ目の機能で同じデータが必要になった場合にのみ追加します（bootstrap.md を参照）。
• install-guards.sh でガードをインストールします。すべてのモジュールを .composekit.conf に登録し、セットアップの説明箇所にすべてのキーを記載します（bootstrap.md を参照）。プロジェクトで always を記録していない限り、UI_MODEL は when-needed のままにします。
• AGENTS.md／CLAUDE.md にプロジェクトの ## Project decisions セクションを作成します（bootstrap.md を参照）。enforcement.md のキット有効化を示す 1 行のポインターを追加します。
• 古い画面を手作業でコピーせず、compose-feature スキャフォールドで最初の機能を作成します。
• 以下の検証ゲートを実行します。

既存プロジェクトにキットを導入する

• scripts/audit-project.sh を実行し、adopt-existing.md に基づいてギャップレポートを作成します。プロジェクトを compose-architecture スキルで定義された既存プロジェクトのケース 1、2、3 に分類します。
• プロジェクトに一貫性がある場合（ケース 2）は、現在の変更に大規模な書き換えを含めないようにします。移行は別のタスクとして提案します。
• 段階的に計画します。まずガードを WARN モードで導入し、次にコンベンションプラグインを導入し、その後、新機能のみに基本契約を適用します。
• プロジェクトで維持する逸脱ごとに ## Project decisions を作成し、その理由を一度だけ記載します。
• 以下の検証ゲートを実行します。

モジュールの追加または切り出し

• 所有するコンベンションプラグインを適用します。モジュールファイルにはプラグインエイリアス、名前空間、依存関係だけを記述します。
• タイプセーフなプロジェクトアクセサーで依存関係を宣言します。api() はルール 2 に従う場合のみ使用します。
• モジュールを .composekit.conf に登録し、run-checks.sh を実行します。
• 新しいモジュールの Koin モジュールをコンポジションルートに登録します。防止する問題： コンパイル済みモジュールに、実行時バインディングが解決されない状態が残ること。
• コンポジションルートから切り出す場合は、同じ変更内でルート側の該当部分を削除します。

CI とエージェントフックの接続

• CI ジョブから個別のチェックではなく、レジストリである scripts/composekit/run-checks.sh を呼び出します。新しいチェックはレジストリに 1 行として追加します。
• エージェントフック（Claude Code／OpenCode／Cursor）で、Compose の変更を完了する前にレジストリを実行します。スニペットは install-guards.sh で出力し、ユーザーの同意なくユーザー設定に書き込まないでください。
• キットを有効化します。enforcement.md の 1 行のポインターと、任意の SessionStart フックを設定します。

判断表

対象の構成

要件	構成
1 つのコードベースで Android、iOS、Desktop、Web に対応	CMP アプリ：共有 :composeApp KMP モジュールと薄い :androidApp シェル、および Xcode プロジェクト（bootstrap.md を参照）
現在も今後も Android のみ	Android 専用：:app と :core:*、:data:*、:feature:*（bootstrap.md を参照）

AGP プラグインの構成（まず AGP のバージョンを確認）

libs.versions.toml の内容	構成
AGP 9 以降	共有モジュールでは com.android.kotlin.multiplatform.library を kotlin { android { … } } ブロックとともに使用します。Android のエントリポイントは別の :androidApp モジュールに置きます
AGP 9 未満	com.android.library を維持し、AGP 9 の構成を適用しないでください。副次的な移行は行わず、作業を停止して報告します

段階的に導入する（既存プロジェクトの場合 → 計画を立てます。ケースは compose-architecture スキルに記載されています）

ケース	計画
ケース 1（新規開発、またはキットに沿った構成）	最初のモジュールからキットを厳密に適用します
ケース 2（一貫性のある別のアーキテクチャ）	今回の変更ではプロジェクトのパターンに従い、キットへの移行は別タスクにします
ケース 3（一貫性がなく、複数のパターンが競合）	新しいコードにはキットを適用し、一貫性のなさを明示して、移行は別途提案します

注意すべき兆候

考え	実際には
「早くリリースするために、タグのロジックはひとまず :app に置いておこう」	いいえ。ルール 6：ルートは一時的な足場であり、恒久的な置き場所ではありません。まず断り、その後で機能モジュールを作成します。
「ガード設定は省略しよう。後で整理すればいい」	いいえ。ルール 4：登録されていないものはガードされません。完了前に登録します。
「今回の変更でキットに全面的に書き換えよう」	いいえ。ルール 5：段階的に進め、まずは WARN モードを使います。一貫性のあるプロジェクトでは、今回の変更も既存のパターンに従います。
「対象ブロックをこのモジュールにコピーしよう。モジュールは 1 つだけだから」	いいえ。ルール 1：ターゲットは規約プラグインが管理します。コピーはすぐに数十個に増えます。
「api() を使おう。コンパイルできるから問題ない」	いいえ。ルール 2：api() を使うには、漏出する型と、その型を明記したコメントが必要です。それ以外は implementation() を使います。
「このバージョンはモジュールのファイルに固定しよう。カタログはライブラリ用だから」	いいえ。ルール 7：すべてのバージョンは libs.versions.toml に一度だけ記載します。
「CI からガードスクリプトを 1 つ呼び出せば十分だ」	いいえ。ルール 10：CI はレジストリを呼び出します。スクリプトを 1 つだけ呼び出すと、ずれが生じる別のレジストリになります。
「ユーザーの設定にフックを今書き込もう。ユーザーも望んでいるはずだ」	いいえ。スニペットを表示します。同意なしに書き込んではいけません。
「このプラグイン ID で正しそうだ。覚えている」	立ち止まって今すぐ確認します（スタンス項目 1）。存在しないプラグイン ID を指定すると、同期時にすべてのモジュールで失敗します。

検証

• scripts/composekit/run-checks.sh（またはスキルの scripts/run-checks.sh <project-root>）が終了コード 0 で終了します。
• scripts/audit-project.sh <project-root> の出力を確認し、ブートストラップの不足点と既存プロジェクトへの導入ケースの分類を確認します。
• ライブラリ、データ、機能モジュールのビルドファイルにターゲット、SDK、ツールチェーンのブロックがありません。rg -n "compileSdk|minSdk|targetSdk|jvmTarget|jvmToolchain" --glob '*.gradle.kts' <module-dirs> の結果が、build-logic/ とコンポジションルートのシェルモジュール以外では空です。
• モジュールのビルドファイルにバージョンの記載がありません。すべての座標が libs. アクセサーを通じて解決されます。
• すべての api( 行に、漏出する型を明記したコメントがあります。
• すべてのモジュールディレクトリが .composekit.conf に登録されています。プロジェクトで使用するすべての .composekit.conf キーが、セットアップの説明箇所に記載されています。
• プロジェクトの AGENTS.md／CLAUDE.md に、キットを有効化するための 1 行のポインターと ## Project decisions セクションがあります。
• CI ワークフローが run-checks.sh を呼び出します。レジストリにはチェックごとに 1 行があり、スクリプトが存在しない場合は失敗します。
• 変更したモジュールが同期され、共通メタデータと 1 つのプラットフォーム向けにコンパイルされます。
• 変更内で言及したすべてのプラグイン ID と DSL ブロックについて、libs.versions.toml のバージョンに対応する現行の公式ドキュメントで確認済みですか？ はい／いいえ。

参照情報の確認

このタスクに必要な参照のみを読み込みます。参照は1階層までです。

• モジュールを追加する場合は、module-graph.md も読んでください。

• モジュールのバインディングを接続する場合は、dependency-injection.md も読んでください。

• bootstrap.md — 新規プロジェクトのワークフロー：ターゲットの選択、モジュールのスケルトン、ガードのインストール、最初の機能、## Project decisions、.composekit.conf のすべてのキー。

• adopt-existing.md — 監査チェックリスト、ギャップレポートの形式、段階的な導入順序、WARN モードのガード、移行を決して強制してはならないもの。

• convention-plugins.md — プラグインのセット、それぞれの担当範囲、stability-config の接続、AGP 9 の構成。

• dependency-rules.md — api と implementation の使い分け、依存方向のチェック、アクセサー、コンポジションルートのルール。

• version-catalog.md — 命名、バンドル、検証の習慣、最低バージョン、複合ビルド。

• enforcement.md — install-guards.sh、CI ジョブ、エージェントフック、キットの有効化、安定性ベースライン。

• distribution.md — デスクトップ向けパッケージング、署名と公証、CI マトリックス、キャッシュ。