Claude CodeでJetpack Compose開発を進める手順 — 環境構築から実装フローまで

Jetpack ComposeはUIをコードで宣言する仕組み

Jetpack Composeは、AndroidアプリのUIをKotlinの関数で宣言的に組み立てるツールキットです。画面の見た目と状態を@Composable関数として書き、状態が変わるとComposeが再描画すべき範囲を判断します。XMLレイアウトを差分更新する従来のView方式とは、UIを表現する単位そのものが違います。

Claude CodeはこのCompose特有の仕組みを内蔵しているわけではありません。ファイルの読み書きとコマンド実行を担う汎用のコーディングエージェントで、Kotlinのコードも他言語と同じ経路で編集します。公式ドキュメントは、状態管理・ライフサイクル・Modifier・副作用・パフォーマンスをFoundationセクションにまとめています。レイアウトやMaterial Design 3への対応は、Designセクションの担当です。Claude Codeにとって重要なのはこの構造で、どのファイルがどの層に属するかをCLAUDE.mdで示しておくと、修正の的が外れにくくなります。

View方式のコードベースをComposeへ移行する作業も対象に含まれます。公式ドキュメントのAdopting Composeセクションには、View-based UIとの相互運用APIや移行戦略がまとまっています。既存アプリに部分的にComposeを組み込む場合は、ここが起点になります。

開発環境の作り方 — Android StudioとAndroid CLIの2つの入り口

Compose開発の入り口は2つあります。Android Studioを使うか、コマンドラインのAndroid CLIを使うかです。どちらもプロジェクトの作成自体はGoogle側のツールが担い、Claude Codeはその後のコード編集を引き受けます。

Android StudioはCompose向けの新規プロジェクトテンプレートと、UIやアニメーションをその場でプレビューできる編集機能を備えます。新規プロジェクトを作る際、言語の選択肢はKotlinのみです。最小APIレベルは21以上を選びます。

Android Studioを開かず端末だけで完結させたい場合は、Android CLIのandroid createが使えます。テンプレート名を省くと、空のCompose activityのテンプレートが使われます。--nameは必須で、出力先は--outputで指定します。

android create --name="MyApp" --application-id=com.example.myapp --output=./my-app

選べるテンプレートはandroid create --listで一覧できます。公式の例にはempty-activity-composeのようなテンプレート名と、--min-sdk=30のような最小SDKの上書きが載っています。生成したプロジェクトでClaude Code CLIを起動すれば、編集を始められます。

もう一つ、android initというコマンドがあります。Android CLIの公式ページによると、実行するとandroid-cli skillがインストールされます。これでエージェントがAndroid CLIの使い方を把握できます。

CI環境や共有マシンのようにIDEを開けない場所でも、考え方は同じです。Claude Code CodespacesでDevContainer開発を始める手順が参考になります。

CLAUDE.mdでComposeプロジェクトの前提を共有する

CLAUDE.mdは、コードから読み取れない前提をClaudeに渡すためのファイルです。毎回のセッション開始時に読み込まれ、/initを実行するとコードベースを解析してビルドコマンドやテスト手順を拾った雛形が生成されます。Composeプロジェクトでは、ビルド・テストのコマンドに加えて、状態の持ち方の方針を書いておくと効きます。

# ビルドとテスト
- ビルドは `./gradlew build` で確認する
- 単体テストは `./gradlew testDebugUnitTest` で走らせる
 
# Compose規約
- 状態はComposable関数の外(呼び出し元かViewModel)に持たせる(state hoisting)
- 新規のComposable関数はstatelessを優先し、プレビュー用に@Previewを添える
- Material Design 2ではなくMaterial Design 3のコンポーネントを使う

公式ドキュメントは、1つのCLAUDE.mdを200行以内に収める目安を示しています。長くなると文脈を圧迫し、指示が守られにくくなるためです。Compose規約のうちKotlinファイルを触るときだけ要るものは、.claude/rules/に分けると、対象ファイルを読み書きしたときだけ文脈に入ります。ファイル冒頭のpathsに対象のパターンを書きます。

---
paths:
  - "**/*.kt"
---
 
# Composeの書き方
- Composable関数の第1引数は`modifier: Modifier = Modifier`にする
- 副作用は`LaunchedEffect`など副作用用のAPIに閉じ込める

pathsを書かないルールは、起動時にすべて読み込まれます。

宣言型UIの実装フローをClaude Codeでどう回すか

基本のループは、Claudeが@Composable関数を編集し、./gradlewでビルドとテストを走らせ、結果を読んで直すという流れです。Compose固有の工程は、見た目の確認だけです。

3段目のプレビュー描画は、Android CLIが提供する手段です。android studio render-compose-previewは、Android Studioのレイアウト描画エンジンで@Preview関数を描画します。Android Studio Quail 2以上が必要です。--projectには、Android Studioで開いているプロジェクトの名前かパスを渡します。

android studio render-compose-preview \
  --output-image-file=preview_detail.png \
  --print-semantics \
  app/src/main/java/com/example/myapp/ui/DetailScreen.kt \
  DetailScreenPreview

--print-semanticsを付けると、アクセシビリティのセマンティクスツリーがJSONで出力されます。ボタンやテキストの位置・境界といった情報を、画像と並べてエージェントが読めます。出力先を省くと一時ファイルにPNGが作られます。

テストの合否を軸にしてターンを閉じる進め方の細部は、Claude Codeでテスト駆動開発(TDD)を回す手順にまとめています。複数のComposable関数を並行して直す場面では、サブエージェントで作業を分担すると本流の文脈が汚れません。画面ごとに担当を分けて実装させ、結果だけをメインセッションで受け取る形です。使い分けの具体パターンはClaude Codeのサブエージェント完全活用で扱っています。

gradlewの承認を先に通しておく

Bashコマンドは、組み込みの読み取り専用コマンドを除いて承認が必要です。この一覧に載っているのはls・cat・grepや、読み取りだけのgitなどで、./gradlewは含まれません。

承認ダイアログで「Yes, and don't ask again」を選ぶと、そのコマンドの許可がリポジトリ単位で.claude/settings.local.jsonに保存されます。ビルドとテストを何十回も回す前に、決まったコマンドだけを.claude/settings.jsonで許可しておく方法もあります。

{
  "permissions": {
    "allow": [
      "Bash(./gradlew build)",
      "Bash(./gradlew testDebugUnitTest)"
    ]
  }
}

ルールはコマンド全文との一致で判定されます。Bash(./gradlew *)のようにワイルドカードで書くと./gradlew publishも通るので、上のように必要なタスクを個別に書くと範囲を絞れます。長いタスクを渡して離席する場合は、許可していないコマンドで承認待ちのまま止まることがあります。

Android StudioとClaude Codeを直結するJetBrainsプラグイン

Claude CodeはJetBrainsのプラグインを通じて主要IDEと連携でき、対応にはAndroid Studioも含まれています。IntelliJ IDEA・PyCharm・WebStorm・PhpStorm・GoLandと並ぶ対応IDEの一つです。

導入は2段階です。まずClaude Code CLI本体をインストールし、次にJetBrains Marketplaceから公式プラグインを追加してIDEを再起動します。プラグインはCLIを同梱しないので、claudeがPATHにないと「Cannot launch Claude Code」の通知が出ます。

Android Studioの統合ターミナルでclaudeを起動すれば、これらの機能はすべて有効になります。外部ターミナルから接続する場合は/ideコマンドを使います。claude --helpには、起動時にIDEへ自動接続する--ideフラグも載っています。

診断共有には注意点があります。Claude Codeは編集のたびに自動でIDEの診断結果を取りに行くわけではなく、getDiagnosticsツールの呼び出しが必要です。Composeコンパイラ関連のlint警告を踏まえて直してほしいときは、「IDEの診断を確認してから直してください」のように明示的に頼みます。

プラグインの利用に追加の契約は不要です。Pro・Max・Team・EnterpriseいずれかのClaude有料サブスクリプションか、Claude Consoleアカウントがあれば動きます。

PostToolUseフックでフォーマッタやlintを自動化する

ファイル編集のたびに必ず実行したい処理は、フックに移します。フックはClaude Codeのライフサイクル上の特定タイミングで動くシェルコマンドで、判断をモデルに委ねずに済みます。Edit・Writeツールが走った直後に発火するPostToolUseを使うと、Kotlinファイルを保存するたびにフォーマッタやlintを走らせられます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/kotlin-format.sh"
          }
        ]
      }
    ]
  }
}

設定は.claude/settings.jsonに書き、プロジェクトルートに置いたものはチーム全体に共有されます。スクリプトにはイベントのJSONが標準入力で渡されるので、jqで編集されたファイルのパスを取り出します。公式のフォーマッタ例も同じ作りです。

#!/bin/bash
# 標準入力のJSONから編集されたファイルのパスを取り出す
FILE=$(jq -r '.tool_input.file_path // empty')
# Kotlinファイル以外は何もしない
case "$FILE" in
  *.kt|*.kts) ;;
  *) exit 0 ;;
esac
# 整形に失敗したら、内容をstderrに出してexit 2で終わる
if ! OUT=$(ktlint -F "$FILE" 2>&1); then
  echo "$OUT" >&2
  exit 2
fi

動作を確かめるなら、ktlintの代わりに引数を表示するだけのスタブを置き、擬似のJSONを標準入力に流します。.ktではスタブが呼ばれてexit 0、.mdでは何も実行されずexit 0、スタブが失敗を返すとexit 2です。実際の整形コマンドは、手元で使っているものに置き換えます。

終了コードの扱いには差があります。hooksのリファレンスによると、exit 0のときのstderrはデバッグログにだけ残り、Claudeには見えません。PostToolUseでexit 2を返すと、ツールはすでに実行済みですが、stderrがClaudeに届きます。lintの失敗内容を直させたいなら、exit 2で終わらせる作りが向きます。

よくあるつまずき

規約を書かずに頼むと既存のView方式に引きずられやすい

Composeの規約を明示しないまま「画面を実装して」とだけ頼むと、規約を知らないまま書くことになります。View方式のコードが多いリポジトリでは、既存パターンを踏襲した命令的な更新処理が混じり得ます。state hoistingや@Previewの付け方をCLAUDE.mdに書いておくと、新規コードの傾向が揃います。

相互運用の境界を決めずに頼むと変更が広がりやすい

既存のView方式アプリに部分的にComposeを導入する場面では、変更の範囲が広がらないよう備えておくと安全です。公式ドキュメントのAdopting Composeセクションが示す相互運用APIの範囲に収めるなら、対象のファイルと変更してよい境界をプロンプトで先に区切っておきます。

フォーマッタの失敗がClaudeに伝わらない

フックのスクリプトが1で終わると、ツールの結果はそのまま受け入れられ、stderrの内容はClaudeに伝わりません(ユーザー側にはhook errorの通知とstderrの1行目が出ます)。lintで落ちたことをClaudeに見せたいときは、終了コードを2にします。判断に迷ったら、まずスクリプトを手で実行して終了コードを見ます。

プレビューの描画に失敗する

render-compose-previewはAndroid Studio Quail 2以上が必要なコマンドです。接続先は--pidでStudioのプロセスを、--projectでプロジェクトの名前かパスを指定できます。開いているプロジェクト名はandroid studio checkで調べられます。

見た目では気づけないラベル欠落やタッチ領域の不足は、semanticsのテストで落としてClaude Codeに直させる手順で扱っています。

Claude CodeでのCompose開発、向いている場面・向かない場面

まとめ

上の表で◎が付くのは、型と呼び出し元を読めば完結する作業です。△の動きや触感のように静止画で足りない作業は、実機での確認を人の側に残します。

見た目の確認だけは、render-compose-previewで画像を渡す経路を用意するかどうかで、Claude Codeに任せられる範囲が変わります。