Qtの設定 - Claude Code サブエージェント

概要

Claude Codeは、ターミナルベースのAI支援開発ツールであり、コマンドラインから直接Claude AIにコーディングタスクを依頼することができる。

サブエージェントとは、Claude Codeに対して特定の分野やタスクに特化した指示を与えるためのプロンプトテンプレートのことである。
また、料理におけるレシピ集のようなものであり、標準化された仕様を参照することにより一貫した品質の成果物を効率的に作成することができる。

これにより、プロジェクト全体で一貫した品質とコーディング規約を維持することができる。

サブエージェント環境を整備することにより、以下に示すメリットが得られる。

プロジェクト構造の標準化
コーディング規約の統一
テスト戦略の明確化
エラーハンドリングのベストプラクティスの適用
開発効率の向上とコード品質の保証

Claude Codeとサブエージェントを組み合わせることにより、Qt/C++コンソールアプリケーション開発の効率と品質を大幅に向上させることができる。

サブエージェント環境を構築する主要なステップを以下に示す。

.claudeディレクトリの作成
サブエージェント仕様書 (Qt-Cpp-Console-Agent.md) の配置
テンプレートファイルの配置 (.claude/templates/)
Claude Codeでのタスク依頼 (サブエージェントファイルを明示的に参照)
生成されたコードの検証とビルド
テストの実行と品質確認

サブエージェントは生きた文書であり、プロジェクトとともに成長し進化させるべきものである。
定期的な見直しと改善により、より効果的な開発環境を構築できる。

サブエージェントを活用することにより、一貫した高品質なコードを効率的に生成し、開発チーム全体の生産性を向上させることができる。

サブエージェントの概念

サブエージェントとは

サブエージェントは、Claude Codeに対して特定の技術スタックやプロジェクトタイプに特化した開発方針を伝えるための文書である。
この文書には、プロジェクト構造の定義、コーディング規約、命名規則、エラーハンドリング戦略、テスト方法、デザインパターンの適用方針等が含まれる。

サブエージェントファイルをプロジェクトに配置することにより、Claude Codeは一貫性のあるソースコードを生成できるようになる。
これは、経験豊富な開発者がプロジェクトに参加したかのように、定められた規約とベストプラクティスに従ったコードが自動生成される。

サブエージェントの役割

サブエージェントは、プロジェクト全体の設計思想と品質基準を決定する役割を果たす。

開発標準の定義と維持
コード品質の保証
チーム間の知識共有
新規参加者へのオンボーディング支援
ベストプラクティスの文書化

サブエージェントファイルは固定されたものではなく、プロジェクトの成長とともに進化させるべき文書である。
プロジェクト固有の要件が明確になったら、サブエージェント仕様やテンプレートをカスタマイズしていくことができる。

サブエージェント仕様書 (Qt/C++コンソールアプリケーション)

Qt/C++コンソールアプリケーション開発向けのサブエージェント環境の構築方法について記載する。

仕様書の構成

Qt/C++コンソールアプリケーション開発向けのサブエージェント仕様書は、以下に示すセクションで構成される。

基本方針と開発哲学
プロジェクトの基本的な考え方と、複数のアプローチを比較検討する際の指針を定義する。

Qtモジュールや外部ライブラリの選択基準、Qt5とQt6の互換性に関する方針を含む。

Qtバージョン対応とビルドシステム
Qt6を主要ターゲットとしつつ、Qt5との互換性を考慮する方針を定義する。

CMakeLists.txtを主要なビルドシステムとする。

コーディング規約とベストプラクティス
命名規則、モダンC++の活用方法、括弧とフォーマット、クラス設計の構造を定義する。

全てのクラスは、private変数、protected変数、public変数、privateメソッド、protectedメソッド、publicメソッドの順序で記述する。

エラーハンドリングとロギング
Qtにおけるエラーハンドリング戦略とロギングフレームワークの使用方法を定義する。

Qt6のqCDebug、qCWarning、qCCritical、qCInfoマクロを使用した構造化ロギングを実装する。

パフォーマンスと非同期処理
大量のデータ処理や時間のかかる操作に対する非同期処理パターンを定義する。

QThreadやQtConcurrentの適切な使用方法、メモリ効率の最適化手法を含む。

テスト戦略とテストコード
Qt Testフレームワークを使用したテスト方法を定義する。

正常系、異常系、境界値、パフォーマンステストの全てをカバーする。

デザインパターンの適用
推奨されるデザインパターンとQtフレームワーク特有のパターンを定義する。

Singleton、Factory、Strategy、Observer、Command、Stateパターン等の適用方針を含む。

外部ライブラリの選定と統合
推奨される外部ライブラリとその統合方法を定義する。

ライセンス確認、依存関係管理、クロスプラットフォーム対応の考慮事項を含む。

セキュリティとデータ保護
機密情報の扱い、データ暗号化、入力検証とサニタイゼーションを定義する。

国際化とローカライゼーション
Qtの国際化機構の使用方法を定義する。

コード品質と保守性
関数の設計原則、コードの再利用性、コンパイラ警告への対応を定義する。

プロジェクト構成とディレクトリ構造
推奨されるディレクトリ構造を定義する。

命名規則

サブエージェント仕様では、以下の命名規則を定義している。

クラス名:
PascalCase

例: DataProcessor、FileManager、ConfigurationLoader
メソッド名 (関数名)
camelCase

例: processData、loadConfiguration、calculateStatistics
定数
UPPER_SNAKE_CASE

例: MAX_BUFFER_SIZE、DEFAULT_TIMEOUT_MS、CONFIG_FILE_VERSION
メンバ変数
m_プレフィックス付きcamelCase

例: m_userName、m_dataBuffer、m_isInitialized
静的メンバ変数
s_プレフィックス付きcamelCase

例: s_instanceCount、s_defaultConfig

クラス設計の構造

全てのクラスは、以下に示す順序でメンバを定義する。

private変数セクション
protected変数セクション
public変数セクション
privateメソッドセクション
protectedメソッドセクション
publicメソッドセクション

コンストラクタはexplicitキーワードを付与し、QObjectを継承する場合はparent引数を受け取るようにする。

ドキュメンテーションコメント

全てのクラス、メソッド、重要なメンバ変数
Doxygenスタイルのドキュメンテーションコメントを記述する。
クラスのドキュメント
@briefでクラスの目的を1行で記述、詳細な説明を複数行で追加、必要に応じて使用例を@codeブロックで示す。
メソッドのドキュメント
@briefでメソッドの機能を1行で記述、@paramで各引数の説明を記述、@returnで戻り値の説明を記述、@noteで重要な注意事項を記述する。

テンプレートファイル

テンプレートファイルの種類

サブエージェント環境には、具体的なコード例として以下のテンプレートファイルを含める。

template_CMakeLists.txt
CMake設定ファイルのテンプレート
template_class_header.hpp
クラスヘッダファイルのテンプレート
template_class_implementation.cpp
実装ファイルのテンプレート
template_test_class.cpp
テストクラスのテンプレート
template_README.md
READMEファイルのテンプレート

これらのテンプレートファイルは、単なる基本的な例ではなく、実際のプロダクション環境で直接使用できる品質を目指して設計されている。

クラスヘッダファイルのテンプレート

クラスヘッダーファイルのテンプレートは、以下に示す要素を含む。

インクルードガード
必要なヘッダーファイルのインクルード (QtとSTLの両方)
クラス全体のDoxygenコメント
クラス定義 (指定された順序でメンバを配置)
全てのメソッドに対するDoxygenコメント
シグナルとスロットの適切な定義

例えば、テンプレートでは、CSVファイルを読み込んで統計情報を計算するCsvDataProcessoクラスを例として実装する。

実装ファイルのテンプレート

実装ファイルのテンプレートは、以下の特徴を持つ。

ロギングカテゴリの定義 (Q_LOGGING_CATEGORY)
全てのメソッドに対する詳細なDoxygenコメント
適切なエラーハンドリング (戻り値チェック、エラーログ出力、シグナル発行)
C++ 17機能の活用 (std::optional、std::accumulate、std::minmax_element等)
ストリーミング処理によるメモリ効率の最適化
進捗通知のためのシグナル発行
日本語コメントによる実装の説明

CMakeLists.txtのテンプレート

CMakeLists.txtのテンプレートは、以下に示す機能を含む。

ビルドタイプのデフォルト設定 (指定がない場合はRelease)
デバッグビルドとリリースビルドでの最適化オプションの明示的な設定
GCC/Clang/MSVCの両方に対応したコンパイラ設定
Qt 6を優先し、必要に応じてQt 5へのフォールバック機能
厳格なコンパイラ警告設定 (警告をエラーとして扱う)
オプショナルな外部ライブラリの扱い (spdlog、CLI11等)
FetchContentを使用した自動ダウンロード機能
Address Sanitizerのオプショナル有効化
テストの有効化とCTestとの統合
ビルド情報の詳細な出力

デバッグビルドでは最適化を無効化してデバッグ性を最大限に高め、リリースビルドでは最大限の最適化を行う。

オプショナルな外部ライブラリは、option()コマンドで使用可否を制御、find_package()でシステム検索を行い、見つからない場合はFetchContentで自動ダウンロードする。

テストファイルのテンプレート

テストファイルのテンプレートは、以下に示すテストケースを含む。

正常系テスト
正常なCSVファイルの読み込み、ダブルクォート付きフィールドの処理、統計計算の正確性
異常系テスト
存在しないファイルのエラーハンドリング、不正なヘッダ行のエラーハンドリング、混在データの統計計算
境界値テスト
空のファイル、ヘッダーのみのファイル、単一レコード、非常に長いフィールド値、多数の列、大きなファイル、フィールド数不一致
パフォーマンステスト
ファイル読み込みのパフォーマンス (QBENCHMARK使用)、演算処理のパフォーマンス、メモリ効率

テストクラスは、QObjectを継承し、テストメソッドをprivate slotsとして定義する。
initTestCaseメソッドでテスト全体の初期化、cleanupTestCaseメソッドでテスト全体のクリーンアップを行う。

境界値テストでは、generateLargeCsvFileヘルパーメソッドを実装して、テストケースごとに異なるサイズのファイルを簡単に生成できるようにしている。

パフォーマンステストでは、QBENCHMARKマクロを使用して同じ処理を複数回実行し、平均実行時間を測定する。
これにより、コードの変更がパフォーマンスに与える影響を定量的に評価できる。

README.mdのテンプレート

README.mdのテンプレートは、サブエージェント仕様で要求されている全ての必須項目を含む。

プロジェクト概要
プロジェクトの目的と主要機能の説明
必要な環境
Qt 6 / Qt 5、C++コンパイラ、CMake、オプション要件
ビルド方法
基本的なビルド手順、リリースビルド、デバッグビルド、プラットフォーム固有の注意事項
実行方法
コマンドラインオプション、使用例、設定ファイル、環境変数
テストの実行方法
全てのテストの実行、個別のテスト実行、テストカバレッジの取得
プロジェクト構成
ディレクトリ構造の説明
トラブルシューティング
よくある問題と解決方法
APIドキュメント
Doxygenを使用したドキュメント生成方法
コントリビューション
貢献ガイドライン
ライセンス情報

ファイル配置

ディレクトリ構造

サブエージェント関連のファイルは、プロジェクトルートに作成する.claudeディレクトリに配置する。
ドットで始まる名前は、多くのシステムで隠しディレクトリとして扱われるため、通常の作業ディレクトリとは区別される。

推奨されるディレクトリ構造を以下に示す。

プロジェクトルート/
├── .claude/
│   ├── Qt-Cpp-Console-Agent.md          (サブエージェント仕様書)
│   └── templates/
│       ├── template_class_header.hpp
│       ├── template_class_implementation.cpp
│       ├── template_CMakeLists.txt
│       ├── template_test_class.cpp
│       └── template_README.md
├── CMakeLists.txt
├── README.md
├── src/
├── include/
├── tests/
└── build/

.claudeディレクトリの直下には、メインのサブエージェント仕様書であるQt-Cpp-Console-Agent.mdを配置する。
これが、Claude Codeに対する包括的な指示書となる。

templatesディレクトリには、具体的なコード例やテンプレートファイルを配置する。
Claude Codeは、サブエージェント仕様とテンプレートの両方を参照することで、より正確で実用的なコードを生成することができる。

ファイル配置のメリット

このような構造でファイルを配置することにより、以下に示すメリットが得ることができる。

サブエージェント仕様とテンプレートの明確な分離
プロジェクトメタ情報の一元管理
Gitリポジトリでの容易な共有
チーム全体での設計思想の共有
新規参加者のオンボーディング支援

.claudeディレクトリをGitリポジトリに含めることにより、プロジェクトの設計思想とベストプラクティスを文書化して永続化できる。

Claude Codeでの使用方法

基本的な使用手順

サブエージェント環境を構築したら、以下に示す手順でClaude Codeを使用する。

プロジェクトディレクトリに.claudeディレクトリとテンプレートファイルを配置
ターミナルでプロジェクトディレクトリに移動
Claude Codeを起動
サブエージェント仕様を参照するタスクを依頼

タスクを依頼する時は、サブエージェントファイルを明示的に参照することにより、より確実に指示を伝えることができる。

# 例 : CSVファイル処理アプリケーションの作成依頼

.claude/Qt-Cpp-Console-Agent.mdのサブエージェント仕様に厳密に従って、CSVファイルを読み込んで統計情報を計算するQt 6コンソールアプリケーションを作成してください。

機能として、コマンドライン引数でCSVファイルパスを指定、ヘッダ行の自動検出、数値以外のデータの適切なスキップ、エラー発生時の詳細なログ出力、
結果の標準出力への整形表示が必要です。

また、完全な単体テストも同時に作成してください。

Claude Codeは、サブエージェント仕様を読み込み、テンプレートファイルを参照しながら、一貫性のある高品質なコードを生成する。
生成されるファイルは、全てサブエージェント仕様で定義された規約に準拠する。

テンプレートの参照

特定のテンプレートを参照する場合は、以下に示すように指示する。

.claude/Qt-Cpp-Console-Agent.mdのサブエージェント仕様に従い、.claude/templates/内のテンプレートを参考にして、
ログファイルを解析するQt6コンソールアプリケーションを作成してください。

特に、境界値テストとパフォーマンステストを含む包括的なテストスイートを作成してください。

フィードバックと修正

生成されたコードが期待と異なる場合は、具体的にフィードバックを与える。

LogParserクラスのparseLineメソッドで、ログレベルの抽出に失敗した場合のエラーハンドリングが不足しています。

サブエージェント仕様のエラーハンドリングセクションに従って、詳細なログ出力とエラーシグナルの発行を追加してください。

Claude Codeは、サブエージェント仕様を再度参照して、適切に修正したコードを生成する。

生成されたコードの検証

Claude Codeがコードを生成したら、以下に示す事柄を確認する。

ファイル構成
CMakeLists.txt、ソースファイル、ヘッダファイル、テストファイルの配置
クラス構造
指定された順序 (private変数、protected変数、public変数、privateメソッド、protectedメソッド、publicメソッド)
Doxygenコメント
全てのメソッドに@brief、@param、@returnが付与されているか
括弧
全て半角で記述されているか
C++ 17機能
std::optional、std::string_view等が適切に使用されているか
エラーハンドリング
ファイル操作やデータ処理でエラーチェックが行われているか
ロギング
qCDebug、qCWarning等のQtのロギング機構が使用されているか

ビルドとテストの実行

生成されたコードをビルドして動作を確認する。

コンパイラ警告が表示されないことを確認する。
サブエージェント仕様では、警告ゼロを目標としているため、警告が表示された場合はClaude Codeに修正を依頼する。

# ビルドディレクトリの作成
mkdir build
cd build

# CMakeの実行
cmake ..

# ビルド
cmake --build .

# テストの実行
ctest

# または詳細出力
ctest --verbose

サブエージェントのカスタマイズ

プロジェクト固有の拡張

プロジェクトを進めていく中で、サブエージェント仕様を改善する必要が出てくることがある。
サブエージェントファイルは固定されたものではなく、プロジェクトの成長とともに進化させるべき生きた文書である。

例えば、特定の外部ライブラリを頻繁に使用することが分かった場合、そのライブラリの使用方法やベストプラクティスのセクションをサブエージェント仕様に追加する。
あるいは、プロジェクト固有の命名規則やデザインパターンが確立された場合、それらをサブエージェント仕様に追記する。

変更履歴の管理

サブエージェントファイルを更新する際は、変更履歴をコメントとして残すことを推奨する。
ファイルの最後に変更履歴セクションを作成し、いつ、なぜ、何を変更したかを記録する。

これにより、将来的にサブエージェントの設計判断を振り返ることができる。

複数のサブエージェントの管理

プロジェクトが大きくなると、複数のサブエージェントを使い分けることが有効になる場合がある。
例えば、Qt/C++の一般的な開発にはQt-Cpp-Base-Agent.mdを使用し、特定のドメイン向けには専用のサブエージェントファイルを作成する。

Qt-Cpp-Base-Agent.md
基本的なQt/C++開発の仕様
Qt-Database-Agent.md
データベース処理に特化した仕様
Qt-Network-Agent.md
ネットワーク通信に特化した仕様
Qt-GUI-Agent.md
GUIアプリケーション開発に特化した仕様

例えば、.claudeディレクトリ内に複数のマークダウンファイルを配置して、タスクを依頼する際に複数のサブエージェントを組み合わせて指示できる。

Qt-Cpp-Base-agent.md と Qt-Database-Agent.mdの両方の仕様に従って、PostgreSQLデータベースにアクセスするクラスを作成してください。

例 : ログファイル解析ツールの開発

プロジェクトの作成

以下の例では、サブエージェントを使用してログファイル解析ツールを開発する手順を示す。

まず、プロジェクトディレクトリを作成し、.claudeディレクトリとテンプレートファイルを配置する。

mkdir <プロジェクト名  例 : log-analyzer>
cd <プロジェクト名  例 : log-analyzer>

mkdir .claude
mkdir .claude/templates

次に、サブエージェント仕様書とテンプレートファイルを.claudeディレクトリにコピーする。

Claude Codeを起動し、以下に示すように依頼する。

.claude/Qt-Cpp-Console-Agent.mdのサブエージェント仕様に従って、テキストベースのログファイルを解析し、
エラーレベル別の統計情報を表示するQt 6コンソールアプリケーションを作成してください。

正規表現を使用してログパターンをマッチングし、日時、ログレベル、メッセージを抽出する機能が必要です。
また、大きなログファイルに対応するため、ストリーミング処理を実装してください。

Claude Codeは、サブエージェント仕様に基づいて、適切なクラス設計を行い、それぞれに対するヘッダファイルと実装ファイルを生成する。
例えば、LogParserクラス、LogEntryクラス、StatisticsCalculatorクラス等が生成される。

生成されたコードは、すべてサブエージェント仕様で定義された構造で記述され、Doxygenコメントが完備されている。
エラーハンドリングも適切に実装されており、ファイルが存在しない場合やパース失敗時には詳細なエラーメッセージがログに出力される。

生成されるファイルの例

Claude Codeが生成する主要なファイルを以下に示す。

CMakeLists.txt
プロジェクト全体のビルド設定
src/main.cpp
エントリーポイント
include/LogParser.h
ログパーサークラスのヘッダー
src/LogParser.cpp
ログパーサークラスの実装
include/LogEntry.h
ログエントリークラスのヘッダー
src/LogEntry.cpp
ログエントリークラスの実装
tests/test_LogParser.cpp
ログパーサーのテストコード
tests/CMakeLists.txt
テスト用のビルド設定
README.md
プロジェクトの説明とビルド方法

全てのクラスは、private変数セクション、protected変数セクション、public変数セクション、privateメソッドセクション、protectedメソッドセクション、publicメソッドセクションの順序で定義される。

テストの実行結果

生成されたテストコードには、正常系、異常系、境界値、パフォーマンステストが含まれている。

CTestを実行すると、以下のようなテスト結果が表示される。

Test project /path/to/log-analyzer/build
    Start 1: test_正常なログファイルの読み込み
1/10 Test #1: test_正常なログファイルの読み込み .....   Passed    0.02 sec
    Start 2: test_存在しないファイルのエラーハンドリング
2/10 Test #2: test_存在しないファイルのエラーハンドリング   Passed    0.01 sec
    Start 3: test_空のファイル
3/10 Test #3: test_空のファイル .......................   Passed    0.01 sec
    Start 4: test_統計計算の正確性
4/10 Test #4: test_統計計算の正確性 ...................   Passed    0.03 sec
    Start 5: test_パフォーマンス_ファイル読み込み
5/10 Test #5: test_パフォーマンス_ファイル読み込み .....   Passed    0.15 sec

100% tests passed, 0 tests failed out of 10

全てのテストがパスすることを確認して、ソースコードの品質が保証される。

トラブルシューティング

サブエージェント仕様に従わないコードが生成される

Claude Codeが生成したコードがサブエージェント仕様に従っていない場合、以下に示す事柄を確認する。

サブエージェントファイルが正しい場所 (.claude/Qt-Cpp-Console-Agent.md) に配置されているか
タスクの依頼時にサブエージェントファイルを明示的に参照しているか
サブエージェント仕様の該当セクションが明確で具体的に記述されているか

サブエージェント仕様の該当セクションを見直し、指示が明確で具体的かどうかを確認する。
必要に応じて、サブエージェント仕様をより詳細に、より明確に改訂する。

コンパイルエラーが発生する

生成されたコードでコンパイルエラーが発生する場合、以下に示す事柄を確認する。

Qt 6 または Qt 5が正しくインストールされているか
CMakeLists.txtでQt 6 / Qt 5が正しく検索されているか
必要な外部ライブラリがインストールされているか
コンパイラがC++ 17以降に対応しているか

エラーメッセージを確認して、具体的な問題をClaude Codeにフィードバックする。

テストが失敗する

生成されたテストが失敗する場合、以下に示す事柄を確認する。

テストデータが正しく生成されているか
期待値が実装と一致しているか
テストの独立性が確保されているか (他のテストに依存していないか)

失敗したテストのエラーメッセージを確認し、原因を特定する。
実装に問題がある場合は実装を修正し、テストに問題がある場合はテストを修正する。

その他

サブエージェント仕様の定期的な見直し

プロジェクトが進むにつれて、サブエージェント仕様を定期的に見直し、改善する。
新しいベストプラクティスや技術が登場した場合は、積極的に取り入れる。

チーム内での共有

サブエージェント仕様とテンプレートファイルをGitリポジトリに含め、チーム全体で共有する。
これにより、ソースコードの一貫性がさらに向上し、チームメンバー間の知識共有が促進される。

段階的な導入

大規模なプロジェクトでサブエージェントを導入する場合は、段階的に導入することを推奨する。
まず小さなコンポーネントやモジュールから始めて、効果を確認しながら徐々に適用範囲を拡大する。

ドキュメントの充実

サブエージェント仕様だけでなく、プロジェクト全体のドキュメントを充実させる。
README.md、API ドキュメント、設計ドキュメント等を整備して、プロジェクトの理解を容易にする。

CI /CD

GitHub ActionsやGitLab CI等を使用して、コミットごとに自動ビルドとテストを実行する。
これにより、サブエージェント仕様に従ったコードが継続的に品質を維持していることを確認できる。