2026年05月21日
このブログは「Introducing the AI Code Documentation Skills for Qt」の抄訳です。
Qt/C++ および QML コードのリファレンスドキュメントを作成する作業は、これまで2つの方法に頼ってきました。ソースコードと乖離しがちな手書きの Markdown ファイルを維持し続けるか、コードベース全体にアノテーション付きのコメントブロックを記述するツールチェーンを使うかです。Qt ドキュメントスキルは、開発者の生産性を高める第3の選択肢を提供します。ソースファイルを AI エージェントに渡すだけで、構造化された開発者向けの Markdown リファレンスドキュメントを数秒で生成できます。
構造化されたコードドキュメントをAI エージェントで正確に生成
2つのドキュメントスキル qt-cpp-docs と qt-qml-doc は、それぞれ Qt 固有のソースファイルを対象とし、独立した Markdown リファレンスドキュメントを生成します。
これらのスキルはコメントに頼るのではなく、実際のソースコードを読み込み、実装から動作と意図を推測して、権威ある API ドキュメントとして読める出力を生成します。生成されたドキュメントは Markdown を受け付けるあらゆるドキュメントパイプライン（GitHub Wiki、静的サイトジェネレーター、社内開発者ポータルなど）ですぐに活用できます。
いずれのスキルも Qt 固有のコードに特化しています。シグナルとスロット、Q_PROPERTY 宣言、QML バインディング、Qt モジュール依存関係、QML タイプ登録、Qt モデル/ビュー契約といった Qt のイディオムを深く理解しており、その知識がドキュメントの出力に反映されます。解析とドキュメント構造は Qt プロジェクト向けに最適化されており、Qt Widgets、Qt Quick、Qt Quick Controls、および Qt/C++ バックエンドコードに対して最も精度の高い結果を生成します。
動画：GitHub Copilot における Qt C++ コードドキュメントの様子（一部シーケンスは短縮・加速されています）
AI エージェントによる Qt コードドキュメントの自動化
qt-cpp-docs スキルは Qt/C++ ソースファイル（.h、.hpp、.cpp）を対象として動作します。Q_OBJECT とシグナル/スロットを持つ Qt クラス、通常の C++ クラスと構造体、フリー関数ヘッダーとユーティリティ API、main.cpp のようなアプリケーションエントリポイントなど、Qt プロジェクトにおける C++ ファイルの全範囲をカバーします。
qt-qml-doc スキルは .qml ファイルを対象とし、QML コンポーネント、Qt Quick モジュール、および Qt Quick アプリケーションのリファレンスドキュメントを生成します。いずれのスキルも1回につき1ファイルを対象として動作するよう設計されており、現時点ではプロジェクト全体を一括処理する機能はありません。複数ファイルのプロジェクトでは、ファイルごと、または関連する少数のファイルのグループごとにスキルを実行してください。
コードドキュメントスキルはどのような場合にトリガーされますか？
Qt ドキュメントスキルは、開発者が Qt/C++ または QML ソースファイルのドキュメント作成を依頼したときに起動します。「このクラスをドキュメント化して」「QML コンポーネントのドキュメントを書いて」「このヘッダーの API ドキュメントを作って」「Qt アプリのドキュメントを作成して」といったフレーズや、ソースファイルを貼り付けてドキュメント作成を依頼するだけで起動します。
スキルはドキュメント化の対象がウィジェット、データモデル、サービスクラス、QML ビルディングブロックなどの再利用可能なコンポーネントか、トップレベルのアプリケーションエントリポイントかを自動的に判別し、それに合わせてドキュメント構造を調整します。再利用可能なクラスやコンポーネントには、使用例を含む完全な API リファレンスが生成されます。main.cpp のようなアプリケーションエントリポイントには、Qt アプリケーションのセットアップ、コマンドラインの処理、トップレベルオブジェクトの生成、イベントループの起動をカバーする起動シーケンスの説明が生成されます。
AI コードドキュメントスキルの動作の仕組み
スキルが起動すると、これまで開発者がソースコードを読み込み、すべてのプロパティ、シグナル、メソッド、列挙型を手動で抽出し、それぞれの説明文を記述し、コードの進化に合わせて同期を保ち続ける必要があったドキュメント作成ワークフローを引き継ぎます。各ステップで行われる処理は以下のとおりです。
ステップ1 — 事前確認：既存ドキュメントのチェック
ソースファイルを読み込む前に、両スキルは対象のドキュメントがすでに存在するかどうかを確認します。ドキュメントの出力先は、ソースファイルと同じ場所にある doc/ サブディレクトリです。ドキュメントが見つかった場合、スキルは開発者に対して「既存のドキュメントを更新する」「ドキュメント済みのファイルをスキップする」「すべてをゼロから再生成する」「キャンセルする」のいずれかを確認します。
ステップ2 — ソース解析
スキルはソースファイルを丁寧に読み込み、パブリック API の全体を抽出します。Qt/C++ ファイルの場合、パブリック API（完全にドキュメント化）、プロテクテッド API（サブクラス化セクションに別途ドキュメント化）、プライベートメンバー（スキップ）を区別します。ヘッダーファイルが権威ある API 定義として扱われ、実装ファイルは動作、副作用、および意図に関するコンテキストを補完します。
QML ファイルの場合、スキルはルート要素とそのベースタイプ、すべての宣言されたプロパティ、すべてのカスタムシグナル、およびすべての JavaScript 関数を特定します。
ステップ3 — コンテキストと依存関係の分析
1つのソースファイルだけではプロジェクト全体の文脈を把握することはできません。両スキルはプライマリソースと並行して関連ファイルを読み込み、そのファイルがプロジェクト内でどのような役割を果たしているかの全体像を構築します。
このコンテキストはドキュメントに直接反映されます。「プロジェクト構造と依存関係」セクションには、クラスがビルド依存関係として必要とする Qt モジュール、コンポーネントをインポートまたはインスタンス化するファイル、および依存するプロジェクト内部の型が記述されます。
ステップ4 — ドキュメント生成
API 全体とコンテキストが揃うと、スキルは構造化された Markdown リファレンスドキュメントを生成します。ドキュメントの構造は、ドキュメント化するファイルの種類によって決まります。
Qt/C++ クラスのドキュメントには以下が含まれます。
- クラスの概要とプロジェクト構造
- クラス階層と役割（継承チェーンの説明付き）
- Q_PROPERTY 宣言（READ、WRITE、NOTIFY 列を含む Markdown テーブル）
- 列挙型（Q_ENUM / Q_FLAG の値と説明）
- シグナル、パブリックスロット、Q_INVOKABLE メソッド、パブリックメソッド（各サブセクション）
- プロテクテッド仮想メソッドとイベントハンドラー
- 所有権とライフサイクル、スレッドセーフ性
- QML 公開（クラスが QML で使用するために登録されている場合のみ）
- クラス間の連携と外部通信（ネットワーク、IPC、シリアル）
- 使用例（再利用可能なクラスのみ）
QML コンポーネントのドキュメントには以下が含まれます。
- コンポーネントの概要とプロジェクト構造
- コンポーネント階層と役割
- プロパティ（型、デフォルト値、必須、説明列を含む Markdown テーブル）
- シグナルとメソッド（各サブセクション）
- コンポーネント間の連携
- 使用例（再利用可能なコンポーネントのみ）
ステップ5 — 品質チェックと出力
保存前に、各スキルはサイレントな品質チェックを実行します。
ドキュメントはソースファイルの隣にある doc/ サブディレクトリに出力されます。単一ファイル Foo.h の場合、出力は doc/Foo.md となります。単一の QML コンポーネント Button.qml の場合、出力は doc/Button.md です。すべてのコンポーネントを一覧表示する index.md は、同一実行で2つ以上のファイルをドキュメント化した場合にのみ生成されます。
画像：Claude Desktop における QML コードドキュメントのスクリーンキャプチャ
コードドキュメントスキルの制約
いずれのスキルも Qt 固有のコードに特化しています。qt-cpp-docs スキルは Qt プロジェクト向けに設計されており、Qt クラス階層、メタオブジェクトシステム、Qt モジュール依存関係、および QML 統合パターンを理解しています。汎用的な C++ ドキュメントツールではないため、Qt のイディオムを使用していないファイルは、Qt 固有のセクションを持たない通常の C++ クラスとしてドキュメント化されます。
同様に、qt-qml-doc は Qt Quick および Qt QML コンポーネント向けに設計されており、非 Qt の JavaScript や一般的なウェブフロントエンドコードのドキュメント化には対応していません。
いずれのスキルも Markdown 形式のみを出力します。QDoc 形式、HTML、PDF、その他のドキュメント形式は生成されません。
スキルは1回につき1つの C++ または QML ファイルを対象として動作するよう設計されています。1つのコマンドで数十ファイルにわたるプロジェクト全体の一括ドキュメント化は現時点では非対応です。大規模なプロジェクトでは、ファイルごとまたはモジュールごとにスキルを実行してください。
生成されたドキュメントの精度は、スキルがソースファイルとその直接のコンテキストから読み取れる内容に依存します。リポジトリをまたいだ依存関係、生成コード（uic、moc）、ソースツリーに存在しないサードパーティヘッダーは完全には解析されません。実装ファイルなしでヘッダーのみから推測されたドキュメントは、パブリック API を正確に説明しますが、実装にのみ現れる副作用、前提条件、スレッドセーフ性の詳細が欠ける場合があります。
いずれのスキルも、コードから推測した動作を説明するドキュメントを生成します。ソースのコメントが存在しない、または曖昧な場合、スキルは命名規則、型、使用コンテキストに基づいて妥当な推測を行います。安全性が重視される、または仕様駆動のコードベースで作業する開発者は、生成されたドキュメントを出発点として扱い、公開前に正式な仕様と照合してレビューしてください。
Tested With動作確認済み環境
スキルは Claude Code CLI、Claude Desktop、および VS Code 向け GitHub Copilot での動作を確認しています。Claude Sonnet 4.6、GPT 5.4、Gemini 3.1 Pro では良好な結果が得られます。詳細なドキュメント作成タスクには、常に最新のフロンティアモデルの使用を推奨します。
スキルの入手方法
Qt エージェントスキルは Qt GitHub リポジトリから入手できます。 https://github.com/TheQtCompanyRnD/agent-skills
または、Claude マーケットプレイスからプラグインとして公式の Qt ドキュメントスキルを直接インストールすることもできます（「qt-development」で検索してください）。
