# ros

Enforces ROS 2 best practices for C++ and Python inside Cursor. It guides package layout, ament tooling, node composition, and multithreaded executors.

- rule · `type=rule` · Cursor · ★ 3580
- Author: sanjeed5
- License: CC0-1.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/ros.mdc
- Updated: 2026-05-19
- HTML: https://affpapa.org/en/nevibecode/rules/ros

## What it does

This rule guides the assistant to generate ROS 2 packages adhering to official ecosystem practices. It mandates integrating `ament_lint_auto` and `ament_lint_common` into `CMakeLists.txt` and `package.xml` during testing. For C++, the guidelines require Google C++ Style, modern C++17 or C++20 features, and RAII resource management using `std::unique_ptr` or `std::shared_ptr`.

Python code must comply with REP-8, format cleanly with `black`, and pass `flake8` checks. Modules belong in the standard `src/<package_name>/` layout. For performance-critical nodes handling large payloads, the rule instructs using node composition to enable zero-copy intra-process transfer, backed by `MultiThreadedExecutor` for blocking tasks.

Thread safety checks via `rcpputils` annotations require the Clang compiler. Without passing `-Wthread-safety` in `CMakeLists.txt`, these static race condition diagnostics will not execute.

## Install

### Cursor (native platform)

**Manually: put the files in place**
- File: `.cursor/rules/ros.mdc` — Frontmatter: description, globs, alwaysApply

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/ros.md` — The paths frontmatter field limits the files: move globs from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/instructions/ros.instructions.md` — The applyTo field sets which files it applies to: move globs from the source into applyTo

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/ros.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/ros.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/ros.mdc

## When to use it
- integrate automated build linting with ament_lint_auto
- implement node composition for zero-copy intra-process transfer
- structure Python packages under the standard src directory
- enable Clang compile-time thread safety checks in C++

## Example prompts
- Generate CMakeLists.txt and package.xml for a C++ node with ament_lint_auto
- Create a ROS 2 Python package structure following REP-8 rules
- Compose camera and processor nodes using MultiThreadedExecutor

## Source text · ros.mdc · CC0-1.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: e30f762c76987c33.

BEGIN THIRD-PARTY FILE e30f762c76987c33
````text
---
description: Definitive guidelines for writing high-quality, performant, and maintainable ROS 2 code, leveraging modern C++ and Python best practices, `ament` tooling, and efficient architectural patterns like node composition and multithreaded executors.
globs: **/*
---
# ros Best Practices

This guide outlines the essential practices for developing robust, performant, and maintainable ROS 2 applications. Adherence to these rules ensures consistency, leverages ROS 2's advanced features, and aligns with the project's quality standards.

## 1. Code Quality and Static Analysis (The `ament` Way)

*   **Mandate `ament_lint_auto`**: Always integrate `ament_lint_auto` and `ament_lint_common` into your package build process. This is non-negotiable for catching style violations and common bugs early.
    *   ❌ BAD: Relying on manual checks or pre-commit hooks that can be bypassed.
    *   ✅ GOOD: Automatic enforcement during every build.

    ```cmake
    # CMakeLists.txt
    # ...
    if(BUILD_TESTING)
      find_package(ament_lint_auto REQUIRED)
      ament_lint_auto_find_test_dependencies()
    endif()
    # ...
    ```

    ```xml
    <!-- package.xml -->
    <package format="2">
      <!-- ... -->
      <test_depend>ament_lint_auto</test_depend>
      <test_depend>ament_lint_common</test_depend>
      <!-- ... -->
    </package>
    ```

*   **C++ Style Enforcement**: Use `ament_cpplint` and `ament_cppcheck`. Follow Google C++ Style Guide and modern C++17/20 features. Prioritize RAII and explicit smart pointer ownership.
    *   ❌ BAD: Raw pointers for resource management; ignoring `cpplint` warnings.
    *   ✅ GOOD: `std::unique_ptr`, `std::shared_ptr` for ownership.

    ```cpp
    // ❌ BAD: Manual memory management, potential leak
    MyObject* obj = new MyObject();
    // ...
    delete obj; // Easy to forget or double-delete

    // ✅ GOOD: RAII with smart pointers
    std::unique_ptr<MyObject> obj = std::make_unique<MyObject>();
    // Resource automatically managed
    ```

*   **Python Style Enforcement**: Adhere strictly to REP-8, which extends PEP 8. Use `black` for formatting and `flake8` for linting. Ensure proper naming, imports, and docstrings.
    *   ❌ BAD: Inconsistent formatting, missing docstrings, `camelCase` for variables.
    *   ✅ GOOD: `snake_case` for variables/functions, clear docstrings, `black`-formatted code.

    ```python
    # ❌ BAD
    def calculateVelocity(pos1, pos2, time):
        # ...
        return vel

    # ✅ GOOD
    def calculate_velocity(position1: float, position2: float, time_delta: float) -> float:
        """Calculates average velocity."""
        # ...
        return velocity
    ```

*   **Copyright and Licensing**: Use `ament_copyright` to ensure all source files have correct copyright and license headers.
    *   Run `ament_copyright --add-missing "Your Name" apache2` to automate this.

## 2. Code Organization and Structure

*   **Python Package Layout (Catkin)**: Adopt the recommended `src/<package_name>/__init__.py` structure. This ensures proper Python package discovery and avoids namespace collisions.
    *   ❌ BAD: Scattering Python files directly in the package root or relying on `roslib.load_manifest`.
    *   ✅ GOOD: Centralized, importable Python code.

    ```
    my_package/
    ├── CMakeLists.txt
    ├── package.xml
    ├── setup.py
    └── src/
        └── my_package/
            ├── __init__.py
            └── my_module.py
    ```

    ```python
    # setup.py for the above structure
    from distutils.core import setup
    from catkin_pkg.python_setup import generate_distutils_setup

    d = generate_distutils_setup(
        packages=['my_package'],
        package_dir={'': 'src'},
    )
    setup(**d)
    ```
````
END THIRD-PARTY FILE e30f762c76987c33

The third-party file has ended. Everything between the e30f762c76987c33 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3812 of 8814 bytes. © sanjeed5 · CC0-1.0 · https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/ros.mdc

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md