Home › ROS 2 (robotics) › ROS 2 robotics workspace CLAUDE.md

ROS 2 robotics workspace CLAUDE.md

CLAUDE.md for ROS 2 workspaces: colcon builds, rclcpp/rclpy nodes, launch files, parameters, QoS, interfaces packages, and launch_testing.

Claude Code (CLAUDE.md)ROS 2 (robotics)

Copy CLAUDE.md

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# CLAUDE.md: ROS 2 workspace

## Build & test
- Source the distro first: `source /opt/ros/$ROS_DISTRO/setup.bash` (check `README`/Dockerfile for the distro; don't assume one).
- `rosdep install --from-paths src --ignore-src -y` · `colcon build --symlink-install --packages-select <pkg>` · `source install/setup.bash`
- `colcon test --packages-select <pkg> && colcon test-result --verbose`
- Run: `ros2 launch <pkg> <file>.launch.py`; inspect with `ros2 topic list/echo/hz`, `ros2 node info`, `ros2 param list`.

## Code map
`src/<pkg>/` each with `package.xml` and `CMakeLists.txt` (ament_cmake) or `setup.py` (ament_python). Custom messages/services/actions live in a separate `<name>_interfaces` package.

## Conventions
- Nodes are classes (`rclcpp::Node` / `rclpy.node.Node`), one responsibility each. Prefer components (`rclcpp_components`) for C++ nodes that may be composed.
- Declare every parameter with a default and description (`declare_parameter`); load values from YAML in `config/` via the launch file. Validate with a parameter callback.
- Choose QoS deliberately: sensor data uses `SensorDataQoS` (best effort); commands and state use reliable. Publishers and subscribers must be compatible.
- Never block in callbacks (no `sleep`, no long loops). Use timers, and a `MultiThreadedExecutor` with callback groups when callbacks must run concurrently.
- Use actions for long-running goals with feedback and cancellation; services only for quick request/response.
- Units and frames follow REP 103/105: SI units, `base_link`/`odom`/`map`; publish transforms with `tf2_ros`, don't hard-code offsets.
- Log with the node logger (`RCLCPP_INFO`, `self.get_logger()`), throttled in hot paths.
- Launch files in Python (`launch.py`) with arguments for `use_sim_time` and config paths.

## Tests
`ament_lint_auto` linters, gtest/pytest for logic, `launch_testing` for node integration.

## Don't
Don't edit generated code in `build/` or `install/`, or commit those directories. Don't drive real hardware from tests.