Claude CodeでQtアプリを開発する手順 — QML/C++の実装ポイント

QtのドキュメントがQML向けの開発環境として挙げるのは、Qt CreatorとQt VS Tools、Qt Extension for VS Codeなどです。Claude Codeはこの一覧に入っておらず、QML専用のコード解析プラグインも標準では用意されていません。ファイル編集とシェルコマンド実行という汎用機能だけでQt/CMakeプロジェクトを組み立てることになるため、CLAUDE.mdでの文脈共有とビルド権限の設定が実装の質を左右します。本記事ではCMakeプロジェクトの雛形作り、QMLとC++の役割分担、ビルド権限の与え方、よくあるつまずきを順に扱います。

Claude CodeでQtアプリを作るとはどういうことか

QtのGetting Startedページは、UIの作り方を2つの経路に分けて案内しています。QMLで宣言的にUIを組む「Design UIs」の経路と、Qt本体の導入などアプリケーション開発を案内する「Develop applications」の経路です。ページ末尾には「C++のAPIでUIを作りたいならQt Widgetsを使う」という一文があり、QML(Qt Quick)とQt WidgetsがそれぞれUI実装の選択肢になっています。

Claude Codeはこの選択自体を代行しません。どちらの経路を取るかは開発者が決め、Claude CodeにはCLAUDE.mdやプロンプトで「QMLでUIを書く」「Qt WidgetsのC++コードを書く」と明示する必要があります。

開発を始める前に用意するもの

Qt本体のインストールに加えて、ビルドツールと対応コンパイラーが必要です。

この段階でClaude Codeに丸投げする必要はありません。インストーラーのGUI操作は人間が行い、Claude Codeにはインストール後のSDKパスとCMakeのバージョンをCLAUDE.mdへ書き渡す方が確実です。

Claude CodeにQtプロジェクトの文脈を渡す — CLAUDE.mdの書き方

Claude Codeは新規セッションのたびにCLAUDE.mdを読み込みます。Qt/CMakeプロジェクトでは、ビルドコマンドとQtのバージョン、ディレクトリ構成をここに書いておくと、毎回同じ説明を繰り返さずに済みます。

既存プロジェクトなら/initコマンドが手がかりになります。Claude Codeがコードベースを解析し、ビルドコマンドやテスト手順、プロジェクトの慣習を発見してCLAUDE.mdの下書きを自動生成します。すでにCLAUDE.mdがある場合は上書きせず、改善案を提示する動作です。

/init

CLAUDE.mdの例は次のようになります。

# Qtデスクトップアプリ
 
## ビルド
- 初回: `cmake -S . -B build`
- 以降: `cmake --build build`
- テスト: `ctest --test-dir build`
 
## 構成
- UI: QML(`src/qml/`配下)
- ロジック: C++静的ライブラリ`businesslogic`(`src/businesslogic/`)
- `build/`配下はCMakeの生成物。moc_*.cppやui_*.hを直接編集しない

CLAUDE.mdは1ファイルあたり200行未満が目安です。長くなったら、特定のファイルを触るときだけ読み込まれるパス限定ルールへ分けられます。自分のビルドディレクトリのパスのような個人用のメモは、CLAUDE.local.mdに分けて.gitignoreに加えます。CLAUDE.mdの階層構造そのものはClaude Code memoryの三層構造にまとめています。

QMLの規約だけを.qmlファイルの作業中に読ませたいなら、.claude/rules/にYAMLフロントマター付きのルールファイルを置きます。

---
paths:
  - "src/qml/**/*.qml"
---
 
# QMLの規約
- ロジックはC++側に置き、QMLは表示と入力の受け渡しに絞る
- 変更後は`cmake --build build`が通ることを確かめる

QMLでUIを、C++でロジックを — 役割分担をどう伝えるか

QMLは「ユーザーインターフェース仕様とプログラミング言語」と定義され、宣言的でJSON風の読みやすい構文にJavaScript式とプロパティバインディングを組み合わせられる点が特徴です。ボタン1つのUIは次のように書けます(Qtのドキュメントに掲載されているサンプルです)。

import QtQuick
import QtQuick.Controls
 
ApplicationWindow {
    width: 400
    height: 400
    visible: true
 
    Button {
        id: button
        text: "A Special Button"
        background: Rectangle {
            implicitWidth: 100
            implicitHeight: 40
            color: button.down ? "#d6d6d6" : "#f6f6f6"
            border.color: "#26282a"
            border.width: 1
            radius: 4
        }
    }
}

Qt QuickはこのQMLの標準ライブラリで、ビジュアル要素やアニメーション、モデル/ビュー、パーティクル・シェーダー効果までを提供します。UI側をQMLで書き、データ処理やファイルI/Oといったロジックだけを既存のC++クラスに任せる構成が考えられます。

Qtのドキュメントが案内するQMLの開発環境は、Qt Creator、Qt VS Tools、Qt Extension for VS Codeです。LSP対応のIDEなら、QML Language Serverも使えるとされています。QML用のコード解析プラグインが標準では無いため、Claude CodeはQMLファイルをプレーンテキストとして編集します。

QMLについては標準の状態で補完や構文チェックが働かないので、プロパティ名の綴りや存在しないシグナルへの接続は、人間側で見る前提にします。C++側には、編集直後に診断を返すclangd-lspプラグインがあります。ターミナルのセッションで使え、クラウドセッションでは動きません。cmake --buildが通るのは、C++とCMakeの側が整った印にとどまります。QMLの記述は、起動して画面を動かして確かめます。

C++のオブジェクトをQMLへ公開する方法は、Qtのドキュメントに「QML and C++ Integration」という専用の概要ページがあります。この領域の実装を頼むときは、該当ページの記述を貼り付けてから指示すると、誤りが減ると考えられます。

CMakeプロジェクトの雛形をClaude Codeに書かせる

CMakeの入門ページは、コンソールアプリからWidgets GUIアプリへ段階的に拡張する例を示しています。コンソールアプリの最小構成は次の形です。

cmake_minimum_required(VERSION 3.16)
project(helloworld VERSION 1.0.0 LANGUAGES CXX)
 
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
find_package(Qt6 REQUIRED COMPONENTS Core)
 
qt_standard_project_setup()
 
qt_add_executable(helloworld
    main.cpp
)
 
target_link_libraries(helloworld PRIVATE Qt6::Core)

qt_standard_project_setup()はCMAKE_AUTOMOCを自動でONにし、QtのMeta-Object Compiler(moc)を必要なタイミングで透過的に呼び出す設定を仕込みます。qt_add_executable()にヘッダーファイルを明示的に列挙する必要はなく、これはヘッダーを個別に登録する必要があったqmakeとの違いです。qmakeの書き方でヘッダーをqt_add_executable()の引数に並べる提案が出たら、CMake+AUTOMOCでは不要だと伝え直します。CLAUDE.mdに一行書いておけば、毎回言わずに済みます。

Qt WidgetsでGUIアプリにする場合は、find_packageの対象をWidgetsに変え、.uiファイルを追加し、Windows/macOSでコンソールウィンドウを出さないためのターゲットプロパティを足します。

find_package(Qt6 REQUIRED COMPONENTS Widgets)
 
qt_standard_project_setup()
 
qt_add_executable(helloworld
    mainwindow.ui
    mainwindow.cpp
    main.cpp
)
 
target_link_libraries(helloworld PRIVATE Qt6::Widgets)
 
set_target_properties(helloworld PROPERTIES
    WIN32_EXECUTABLE ON
    MACOSX_BUNDLE ON
)

qt_standard_project_setup()は同時にCMAKE_AUTOUICもONにし、.uiファイルをQtのUser Interface Compiler(uic)へ自動的に渡します。.uiファイルを追加する別の方法として、qt_add_ui()コマンドも使えます。WIN32_EXECUTABLEとMACOSX_BUNDLEを付け忘れると、Windowsでアプリと一緒にコンソールウィンドウが残ったままになります。

プロジェクトが育ってきたら、ロジックを静的ライブラリへ切り出す構成もサンプルとして示されています。qt_add_library(businesslogic STATIC businesslogic.cpp)でライブラリターゲットを作り、target_link_libraries(helloworld PRIVATE businesslogic Qt6::Widgets)でアプリ側から参照する形です。画像などのリソースはqt_add_resources()でQtリソースシステムに登録し、":/images/logo.png"のようなパスでC++側から読み込みます。Claude Codeにこの分割を指示するときは、「UIターゲット」「ロジックライブラリ」という単位そのものをCLAUDE.mdの構成図として書いておくと、ファイルの置き場所で迷いにくくなります。

ビルドとテストの実行権限をClaude Codeに与える

Bashコマンドは、lsやcat、grepのような組み込みの読み取り専用コマンドを除き、既定で確認を求められます。cmakeやctestは読み取り専用のコマンドではないので、最初は承認を求められます。settings.jsonのpermissions.allowに書いておくと省けます。

{
  "permissions": {
    "allow": [
      "Bash(cmake -S . -B build)",
      "Bash(cmake --build build *)",
      "Bash(ctest --test-dir build *)"
    ],
    "deny": [
      "Edit(build/**)"
    ]
  }
}

ルールの分かれ目は、末尾の*の前に空白を置くかどうかです。

もう一つ、複合コマンドの扱いに注意が要ります。cmake --build build && ctest --test-dir buildのように&&でつなぐと、各コマンドがそれぞれ許可ルールに一致する必要があります。ビルドとテストを1行にまとめる習慣があるなら、2本のルールを両方入れておきます。

denyのEdit(build/**)は、Claude Codeのファイル編集ツールに掛かるルールです。CLAUDE.mdに「生成物を編集しない」と書くだけでなく、ツール側でも止められます。ただし公式は、ファイルを名指しせずに内部で読み書きするサブプロセスには、このルールが及ばないと説明しています。cmakeがbuild/に生成物を書く動作はこちらに入ると考えられます。denyを入れても、ビルドは通常どおり回ります。

使っているバージョンで書式を確かめる方法として、--allowedToolsの説明がヘルプに出ます。

claude --version
claude --help | grep -A2 "allowedTools"

出力は次のようになります。

2.1.289 (Claude Code)
  --allowedTools, --allowed-tools <tools...>
      Comma or space-separated list of tool names to allow (e.g. "Bash(git *)
      Edit")

ヘルプの例もBash(git *)と、空白を置く書式です。ルールの優先順位はClaude Codeの/permissionsコマンド、settings.jsonの全項目はClaude Code settings.json完全ガイドにまとめています。

Claude CodeでQt開発をするときによくあるつまずき

• ビルドが極端に遅い: Qtの入門ページは、ビルドディレクトリをウイルス対策ソフトの除外対象に加えるよう案内しています。Claude Codeが繰り返しビルドを回す運用では、この差が積み重なります
• qt_standard_project_setup()の呼び忘れ: 呼び忘れると自動処理が働かず、mocやuicの生成が行われません。Claude Codeが書いたCMakeLists.txtでは、この一行の有無を最初に見ます
• 生成物の書き換え: build/配下のmoc_.cppやui_.hを直された場合は、次のビルドで変更が消えます。CLAUDE.mdの注意書きとEdit(build/**)のdenyが、この事態を防ぐ手段です

まとめ

C++とCMakeの側は、clangd-lspの診断とビルドの成否という手がかりをClaude Code自身が得られます。QMLの側は起動して見るまで手がかりが乏しいため、QMLの比率が高い画面ほど人間の確認が増えます。QMLとQt Widgetsのどちらで書くかは、この確認負担の差も含めて決める材料になります。