ROS 2 エンジニアリングスキル

単一責任の原則: このスキルは、ROS 2 開発向けの API リファレンス & コードテンプレートガイド です。 ROS 2 APIの正しい使い方と避けるべき間違いを説明します。CI/CD オーケストレーション、 インシデント対応、データ分析、デプロイメント自動化は行いません — これらは別のスキルカテゴリです。

ROS 2 開発向けの段階的公開スキルです — 最初のワークスペースから本番環境でのフリート展開まで対応します。 以下の各セクションで重要な決定枠組みを提供し、詳細なパターン、コードテンプレート、アンチパターンは references/ ディレクトリに格納されています。コードを書く前に関連するリファレンスファイルをご覧ください。

このスキルの使い方

段階的公開 — すべてを一度に読まないでください。 このスキルは層状に構成されています。現在のタスクに必要な部分だけをロードしてください：

1. このファイル (SKILL.md) — 常にロードされます。決定ルーティング、基本原則、落とし穴、 アンチパターンを含みます。簡単な質問への回答と設計決定を行うのに十分です。
2. references/*.md — オンデマンドでロードします。下の Decision Router を使用して、 ユーザーの現在のタスクに関連した 1～2 ファイルを選択してください。20 個のリファレンスファイルすべてを 読まないでください — コンテキストを浪費し混乱を招きます。
3. scripts/ — ユーザーがコード生成、QoS チェック、またはローンチ検証が必要な場合のみ実行します。 これらはツールであり、読み物ではありません。

ステップ:

1. ワークスペースに .skill-runs.log が存在する場合、最後の数行を読んで以前のセッションで何が行われたか、 どのような問題が発生したかを理解してください。
2. ユーザーが何を構築しているかを特定してください (下の Decision Router を参照)。
3. 詳細なガイダンスについて、のみ マッチする references/*.md ファイルを読んでください。
4. コードを生成する前に AI pitfalls テーブルを確認してください。
5. 作成するすべての成果物に Core Engineering Principles を適用してください。
6. 複数のドメインが交差する場合 (例: Nav2 + ros2_control)、両ファイルを読みますが、 推奨事項が競合する場合は安全性 > 決定性 > シンプルさ を優先します。

実行ログ: Stop フックは、セッションサマリーをワークスペースの .skill-runs.log に自動的に追記します。 これにより、前回検証されたものと見つかった問題が確認でき、過去の間違いを繰り返さないようにできます。

Decision router

ユーザーが行っていること	読むべき資料
ワークスペース、パッケージ、ビルド設定の作成	references/workspace-build.md
ノード、エクゼキューター、コールバックグループの作成	references/nodes-executors.md
トピック、サービス、アクション、カスタムインターフェース、QoS	references/communication.md
ライフサイクルノード、コンポーネント読み込み、コンポジション	references/lifecycle-components.md
ローンチファイル、条件付きロジック、イベントハンドラー	references/launch-system.md
tf2、URDF、xacro、robot_state_publisher	references/tf2-urdf.md
ros2_control、ハードウェアインターフェース、コントローラー	references/hardware-interface.md
リアルタイム制約、PREEMPT_RT、メモリ、ジッター	references/realtime.md
Nav2、SLAM、コストマップ、ビヘイビアツリー	references/navigation.md
MoveIt 2、プランニングシーン、把持パイプライン	references/manipulation.md
カメラ、LiDAR、PCL、cv_bridge、深度処理	references/perception.md
ユニットテスト、統合テスト、launch_testing、CI	references/testing.md
ros2 doctor、トレーシング、プロファイリング、rosbag2	references/debugging.md
Docker、クロスコンパイル、フリートデプロイメント、OTA	references/deployment.md
Gazebo、Isaac Sim、sim-to-real、use_sim_time	references/simulation.md
SROS2、DDS セキュリティ、証明書、サプライチェーン	references/security.md
micro-ROS、MCU/RTOS、XRCE-DDS、rclc	references/micro-ros.md
マルチロボットフリート、Open-RMF、DDS ディスカバリースケール	references/multi-robot.md
メッセージタイプ、単位、共分散、フレーム規則	references/message-types.md
ROS 1 マイグレーション、ros1_bridge、ハイブリッド運用	references/migration-ros1.md

横断的関心事: セキュリティ、エラーハンドリング、QoS は単一のリファレンスファイルに限定されません — データパスが信頼境界を越えるとき、ノードがハードウェアを所有するとき、または通信の信頼性が重要なときは常に適用してください。 ユーザーの特定の状況にどの横断的関心事が適用されるかについてはご自身の判断を使用してください。

コア工学原則

これらは、ドメインに関係なく、作成するすべての ROS 2 成果物に適用されます。

1. ディストリビューション認識

<!-- LAST_UPDATED: 2026-03-30 — このテーブルは 6 ヶ月ごと、または新しいディストリが利用可能になったときに確認してください。 --> <!-- NEXT_REVIEW: 2026-09-30 -->

古さ警告: 以下のテーブルは 2026-03-30 に最後に検証されました。 現在の日付がそれから 6 ヶ月以上先の場合、 https://docs.ros.org/en/rolling/Releases.html で EOL 日付と機能サポートを再確認してから このテーブルに依存してください。更新するときは、上記の LAST_UPDATED と NEXT_REVIEW コメントの両方を変更してください。

ユーザーがターゲットとする ROS 2 ディストリビューションを常に確認してください。主な違い：

機能	Foxy (EOL)	Humble (LTS)	Jazzy (LTS)	Kilted (non-LTS)	Rolling
EOL	2023 年 6 月 (終了)	2027 年 5 月	2029 年 5 月	2025 年 11 月	Rolling
Ubuntu	20.04	22.04	24.04	24.04	Latest
デフォルト DDS	Fast DDS	Fast DDS	Fast DDS	Fast DDS	Fast DDS
Zenoh サポート	—	—	—	Tier 1	Tier 1
型説明サポート	いいえ	いいえ	はい	はい	はい
サービスイントロスペクション	いいえ	いいえ	はい	はい	はい
EventsExecutor	いいえ	いいえ	実験的	安定版 (+ rclpy)	安定版 (+ rclpy)
デフォルト bag 形式	sqlite3	sqlite3	MCAP	MCAP	MCAP
ros2_control インターフェース	N/A (別)	2.x	4.x	4.x	Latest
CMake 推奨	ament_target_deps	ament_target_deps	いずれか	target_link_libs	target_link_libs

ユーザーが指定しない場合、最新の LTS (Jazzy) をデフォルトとしてください。 Dockerfile、CI、ドキュメントで正確なディストリを指定し、ビルドの再現性を確保してください。

2. C++ vs Python の決定

個人的な好みではなく、ノードのロールに基づいて言語を選択してください。

rclcpp (C++) を使用する場合:

• ノードが ≥100 Hz で実行される制御ループにある
• 決定性メモリアロケーションが重要である (リアルタイムパス)
• ノードがハードウェアドライバまたはコントローラープラグイン
• プロセス内ゼロコピー通信が必要である

rclpy (Python) を使用する場合:

• ノードはオーケストレーション、監視、またはパラメータ管理
• 頻繁な反復がある迅速なプロトタイピング
• PyTorch、TensorFlow などのネイティブ Python ML フレームワークを多用
• ノードがレイテンシー臨界パスにない

混合スタックは一般的です。 典型的なロボットには C++ ドライバ/コントローラーと Python オーケストレーション/監視があります。 注: component_container (コンポジション) は pluginlib 経由でのみ C++ コンポーネントをロードします。 Python ノードは別プロセスとして実行されますが、ローンチファイルを共有でき、 ゼロオーバーヘッドのプロセス内 DDS で通信できます。

プロセス内通信 は、プロセスを共有するすべてのノード (コンポーザブルコンポーネントだけではない) で動作します。 use_intra_process_comms(true) で同一プロセスで実行化されたすべてのノードは、ゼロコピー転送を使用できます。

3. パッケージ構造規則

すべてのパッケージは以下のレイアウトに従うべきです。ワークスペース全体の一貫性により、 オンボーディング時間が短縮され、CI スクリプトが移植可能になります。

my_package/
├── CMakeLists.txt          # または setup.py (純粋 Python)
├── package.xml             # format 3、<depend> タグ付き
├── config/
│   └── params.yaml         # デフォルトパラメータ
├── launch/
│   └── bringup.launch.py   # Python ローンチファイル
├── include/my_package/     # C++ 公開ヘッダー (ライブラリの場合)
├── src/                    # C++ ソースファイル
├── my_package/             # Python モジュール (ament_python または混合の場合)
├── test/                   # gtest、pytest、launch_testing
├── urdf/                   # URDF/xacro (該当する場合)
├── msg/ srv/ action/       # カスタムインターフェース (専用の *_interfaces パッケージが推奨)
└── README.md

インターフェース定義を *_interfaces パッケージに分離し、 ダウンストリームパッケージが実装を取得することなくインターフェースに依存できるようにしてください。

4. パラメータ規律

• すべてのパラメータを型、説明、範囲、デフォルトと共にノードコンストラクタで宣言します — 決して未宣言パラメータを使用しないでください。
• ParameterDescriptor を FloatingPointRange または IntegerRange と共に使用して 数値範囲を指定します。パラメータサーバーは範囲外の値をセット時に拒否します。
• 関連パラメータを名前空間接頭辞の下にグループ化します： controller.kp、controller.ki、controller.kd。
• config/params.yaml からデフォルトを読み込み、ローンチ時の上書きを許可します。
• 動的な再設定については、set_parameters_callback を登録し、 受け入れる前に新しい値をアトミックに検証します。

5. エラーハンドリング哲学

• ノードはエラーを黙って飲み込んではいけません。適切な重大度でログし、 その後安全なアクション (モーション停止、ヘルプリクエスト、エラー状態への遷移) を実行します。
• アドホックな真偽値フラグの代わりに、ライフサイクルノードのエラー遷移を優先します。
• サービスを呼び出すときは、「サービス利用不可」および「フューチャータイムアウト」の場合を常に明示的に処理します。
• ハードウェアドライバについては、一時的なエラー (リトライとバックオフ) と 致命的エラー (FINALIZED に遷移してオペレーターに通知) を区別します。

6. サービス品質 (QoS) のデフォルト

これらのプロファイルから始めて、使用例に応じて調整してください：

使用例	信頼性	永続性	履歴	深さ	デッドライン	ライフスパン
センサーストリーム	BEST_EFFORT	VOLATILE	KEEP_LAST	5	—	—
コマンド速度	RELIABLE	VOLATILE	KEEP_LAST	1	100 ms	200 ms
マップ (ラッチ)	RELIABLE	TRANSIENT_LOCAL	KEEP_LAST	1	—	—
診断	RELIABLE	VOLATILE	KEEP_LAST	10	—	—
パラメータイベント	RELIABLE	VOLATILE	KEEP_LAST	1000	—	—
アクションフィードバック	RELIABLE	VOLATILE	KEEP_LAST	1	—	—
セーフティハートビート	RELIABLE	VOLATILE	KEEP_LAST	1	500 ms	1 s

QoS ミスマッチは「パブリッシュしたが誰も受信していない」の第 1 原因です。 デバッグ時に ros2 topic info -v で互換性を常に確認してください。

DEADLINE と LIFESPAN はセーフティクリティカルシステムで重要です。DEADLINE は指定された期間内に メッセージが到着しないときにイベントを発火します (古いデータを検出)。LIFESPAN は配信前に 指定された期間より古いメッセージを破棄します (古いデータで動作することを防止)。 詳細な API と例については references/communication.md セクション 9 を参照してください。

7. 命名規則

エンティティ	規則	例
パッケージ	snake_case	arm_controller
ノード	snake_case	joint_state_broadcaster
トピック	/snake_case ns 付き	/arm/joint_states
サービス	/snake_case	/arm/set_mode
アクション	/snake_case	/arm/follow_joint_trajectory
パラメータ	snake_case (ドット ns)	controller.publish_rate
フレーム	snake_case	base_link、camera_optical
インターフェース	PascalCase.msg/srv/action	JointState.msg

8. スレッド安全性とコールバック

• MutuallyExclusiveCallbackGroup はコールバックをシリアライズします — ロックなしで共有状態に対して安全ですが、 スループットを制限します。
• ReentrantCallbackGroup は並列実行を許可します — std::mutex (C++) または threading.Lock (Python) で 共有状態を保護する必要があります。
• コールバック内からサービスを呼び出す: サービスクライアントは、呼び出すコールバックとは 別の MutuallyExclusiveCallbackGroup におかなければなりません。そうでない場合、 エクゼキューターはデッドロックします — コールバックは応答を待つのに対し、エクゼキューターはそれを配信できません。 常に async_send_request をレスポンスコールバック付きで使用してください； エクゼキューターコールバック内で spin_until_future_complete を使用しないでください。
• タイマーまたはサブスクリプションコールバック内でブロッキング作業 (ファイル I/O、長い計算、sleep) を デフォルトエクゼキューターで決して行わないでください。専用スレッドにオフロードするか、 MultiThreadedExecutor をリエントラントグループで使用します。
• rclcpp では、サブスクリプションコールバックで std::shared_ptr<const MessageT> を優先します — 不要なコピーを避け、プロセス内ゼロコピー通信を有効にします。

9. ライフサイクルファースト設計

ハードウェアドライバ、センサーパイプライン、プランナー、コントローラーなど、 リソースを所有するすべてのものにライフサイクル (管理) ノードをデフォルトとしてください。

                 ┌──────────────┐
  create() ──►  │  Unconfigured │
                 └──────┬───────┘
            on_configure │
                 ┌──────▼───────┐
                 │   Inactive    │
                 └──────┬───────┘
            on_activate  │
                 ┌──────▼───────┐
                 │    Active     │
                 └──────┬───────┘
           on_deactivate │
                 ┌──────▼───────┐
                 │   Inactive    │
                 └──────┬───────┘
            on_cleanup   │
                 ┌──────▼───────┐
                 │  Unconfigured │
                 └──────┬───────┘
           on_shutdown   │
                 ┌──────▼───────┐
                 │   Finalized   │
                 └───────────────┘

これにより、システムマネージャー (ローンチファイル、オーケストレーター、またはオペレーター) は リソースがいつ割り当てられるか、ノードがいつ処理を開始するか、そしてどのようにシャットダウンするかについて 明示的な制御が可能になります。また、エラーリカバリーを予測可能にします。

10. ビルドと CI の衛生

• 開発には colcon build --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo を使用； デプロイメントには Release を使用します。
• -Wall -Wextra -Wpedantic を有効にして、CI で警告をエラーとして扱います。
• colcon test を --event-handlers console_cohesion+ で実行して、テスト出力がパッケージごとにグループ化されます。
• rosdep.yaml で rosdep キーをピンして、再現可能な依存関係解決をします。
• CI で /opt/ros/、.ccache/、build//install/ をキャッシュして、ビルド時間を 60～80% 削減します。

一般的なアンチパターン

アンチパターン	害	修正
ノード状態のグローバル変数	コンポジションを破壊、テスト不可	状態をクラスメンバーとして保存
マルチノードプロセスの main() での spin()	他のノードを飢えさせる	MultiThreadedExecutor またはコンポーネントコンポジションを使用
ハードコードされたトピック名	ロボット間の再利用を破