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

IDE統合として名前が挙がるのは、Qt CreatorとQt VS Tools、Qt Extension for VS Codeの3つです。Claude Codeはこの一覧に入っておらず、QML向けの構文チェックやコード補完は提供されません。ファイル編集とシェルコマンド実行という汎用機能だけでQt/CMakeプロジェクトを組み立てることになるため、CLAUDE.mdでの文脈共有とビルド権限の設定が実装の質を左右します。本記事ではCMakeプロジェクトの雛形作り、QMLとC++の役割分担、ビルド権限の与え方、よくあるつまずきを順に扱います。

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

QtのGetting Startedページは、UIの作り方を2つの経路に分けて案内しています。QMLで宣言的にUIを組む「Design UIs」の経路と、C++でアプリケーション全体を組み立てる「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本体のインストールに加えて、ビルドツールと対応コンパイラーが必要です。

• Qtのインストール: Getting Startedページの案内に沿って、QtオンラインインストーラーからQt本体(またはQt Design Studio)を導入します
• CMake: CMakeのビルドマニュアルは「CMakeは開発プロジェクトのビルドプロセスを簡略化するツールで、MakefileやNinjaファイルなどのビルドシステムを自動生成する」と説明しています。Qt 6のプロジェクトはCMakeでビルドするのが標準の経路です
• C++17対応コンパイラー: Qt 6はC++17以降をサポートするコンパイラーを要求します。CMakeLists.txtでCMAKE_CXX_STANDARDを17に固定しておくと、コンパイラーが古い場合にCMakeがエラーを出します
• CMake 3.16以上: cmake_minimum_required(VERSION 3.16)が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で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++クラスに任せる構成が一般的です。

ここで注意したいのが、Claude CodeにはQML向けの言語サーバー連携がない点です。Qt Creatorの組み込みサポートに加え、Qt VS ToolsとQt Extension for VS Code、そして「LSP対応のIDEなら使えるQML Language Server」が案内されています。Claude Codeはこのいずれでもなく、QMLファイルもプレーンテキストとして編集します。プロパティ名の綴りミスや存在しないシグナルへの接続は、実際にcmake --buildが通るかで確認するのが確実で、Claude Codeの提案をそのまま信用しないのが安全です。QMLとC++の橋渡し(C++オブジェクトをQMLへ公開する方法)には「QML and C++ Integration」という専用ページが別途用意されているので、Q_PROPERTYやQ_INVOKABLEを使う実装をClaude Codeに書かせる前に、該当ページの該当箇所を貼り付けてから指示すると誤りが減ります。

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との違いです。Claude Codeが古い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)へ自動的に渡します。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に与える

Claude Codeはデフォルトでは任意のBashコマンドの実行前に確認を求めます。CMakeのビルドやテストを都度承認するのは煩雑なので、settings.jsonのpermissions.allowにパターンを登録しておきます。許可ルールの書式は次の形です。

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

cmake -S . -B build
cmake --build build

このallowパターンを登録しておけば、Claude Codeはビルド・テストのたびに確認を挟まずコマンドを実行できます。ルールの書き方や優先順位の詳細はClaude Codeの/permissionsコマンド、settings.jsonの全項目はClaude Code settings.json完全ガイドにまとめています。ビルドディレクトリそのものへの書き込みは許可していても、moc/uicが生成する中間ファイルを編集対象にする権限ではない点は区別しておきます。

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

• ビルド生成物を編集してしまう: build/配下のmoc_*.cppやui_*.hはCMakeがソースから自動生成するファイルです。元のヘッダーや.uiファイルを直さず生成物側を書き換えると、次のビルドで変更が消えます。CLAUDE.mdにbuild/を編集対象外と明記しておきます
• ヘッダーの明示登録: CMake+AUTOMOCではqt_add_executable()にヘッダーを列挙する必要がありません。qmake時代の書き方を提案してきたら、AUTOMOCが有効な構成だと伝え直します
• qt_standard_project_setup()の呼び忘れ: この呼び出しがないとCMAKE_AUTOMOCとCMAKE_AUTOUICが有効にならず、シグナル/スロットの接続やUIファイルの読み込みでビルドエラーになります
• Windowsのコンソールウィンドウ残留: WidgetsアプリでWIN32_EXECUTABLE ONを付け忘れると、GUIウィンドウと一緒に黒いコンソール画面が開いたままになります
• 見た目を確認できない: Claude Codeはビルドが通るかまでは確認できますが、実際に描画されたウィンドウを見ることはできません。レイアウトや配色はビルド成功をもって完了とせず、実機で起動して目視確認します

まとめ

CLAUDE.mdにビルドコマンドとディレクトリ構成を書き、CMakeLists.txtの雛形(qt_standard_project_setup()によるAUTOMOC/AUTOUIC、Widgets向けのターゲットプロパティ)を最初に固め、settings.jsonでビルド・テストコマンドを許可しておく。この3点を用意しておけば、QMLでのUI実装とC++でのロジック実装をファイル単位でClaude Codeに任せられます。ビルド成果物を編集対象にしないことと、見た目は実機で確認することの2点は、人間の作業として最後まで残ります。