/cpp-rules

name: cpp-rules
description: "C++ coding rules: style, patterns, security, testing. Triggers: .cpp, .cc, .cxx, .hpp, .h, CMakeLists.txt, Makefile, GoogleTest, clang-tidy."
effort: medium
user-invocable: false
allowed-tools: Read

C++ Rules

These rules come from `app/rules/cpp/` in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in C++. Apply them when writing or reviewing C++ code.

C++ Coding Style

Naming

• PascalCase: classes, structs, enums, type aliases, concepts.
• camelCase or snake_case: functions, methods, variables (be consistent per project).
• UPPER_SNAKE: macros, compile-time constants.
• Prefix member variables with `m_` or suffix with `_` (pick one convention).
• Namespace names: lowercase, short (`namespace io`, `namespace util`).

Modern C++ (17/20/23)

• Use `auto` for iterator types and complex template deductions.
• Use `std::optional<T>` instead of sentinel values or pointers for optional returns.
• Use `std::variant` over union types. Use `std::visit` for dispatch.
• Use `std::string_view` for non-owning string parameters.
• Use structured bindings: `auto [key, value] = *map.begin();`.
• Use `constexpr` for compile-time evaluation. Prefer over macros.

Memory Management

• Use RAII exclusively. Every resource acquisition is an initialization.
• Use `std::unique_ptr` for exclusive ownership (default choice).
• Use `std::shared_ptr` only when ownership is genuinely shared.
• Never use raw `new`/`delete`. Use `std::make_unique` / `std::make_shared`.
• Use `std::span<T>` (C++20) for non-owning views over contiguous data.

Functions

• Pass small types by value. Pass large types by `const&`.
• Use `[[nodiscard]]` on functions whose return value must not be ignored.
• Use `noexcept` on functions that do not throw (move constructors, destructors).
• Limit function parameters to 4. Use structs for configuration objects.
• Use trailing return types for complex template return deductions.

Includes and Dependencies

• Use `#pragma once` or include guards. Prefer `#pragma once` for simplicity.
• Order: corresponding header, C++ stdlib, third-party, project headers.
• Forward-declare in headers when possible to reduce compile times.
• Minimize header dependencies. Use the Pimpl idiom for ABI stability.

Avoid

• Raw pointers for ownership. Use smart pointers.
• C-style casts. Use `static_cast`, `dynamic_cast`, `const_cast`.
• Macros for constants or functions. Use `constexpr` and templates.
• `using namespace std;` in headers. Acceptable in .cpp files with caution.
• `std::endl` -- use `'\n'` (endl flushes the buffer unnecessarily).

Formatting

• Use clang-format with a committed `.clang-format` file.
• Use clang-tidy for static analysis and automated modernization.
• Max line length: 100-120 characters.
• Braces: use Allman or K&R consistently per project.

C++ Frameworks

CMake

• Use modern CMake (3.14+): target-based, not directory-based.
• Use `target_link_libraries` with `PUBLIC`/`PRIVATE`/`INTERFACE` visibility.
• Use `FetchContent` for dependency management. Avoid manual submodule vendoring.
• Set `CMAKE_CXX_STANDARD 20` (or 23) at the project level.
• Use `target_compile_options` for per-target flags, not global `add_compile_options`.
• Export targets with `install(TARGETS ... EXPORT ...)` for library consumers.

Boost

• Use Boost.Asio for async networking and I/O.
• Use `boost::beast` for HTTP/WebSocket built on Asio.
• Use `boost::json` or `nlohmann/json` for JSON parsing.
• Prefer C++ stdlib equivalents when available (e.g., `std::optional` over `boost::optional`).
• Link only the Boost libraries you actually use. Many are header-only.

Qt

• Use signals and slots for event-driven communication.
• Use `QObject` parent-child ownership for automatic memory management.
• Use `QML` for declarative UI. Keep business logic in C++ backend.
• Use `QThread` with worker objects (moveToThread), not subclassing QThread.
• Use smart pointers for non-QObject resources. QObject children are auto-deleted.

gRPC

• Define services in `.proto` files. Generate C++ stubs with `protoc`.
• Use async server with `CompletionQueue` for high-throughput services.
• Use `grpc::ClientContext` for per-call deadlines and metadata.
• Use interceptors for logging, auth, and metrics.
• Set deadlines on every RPC call to prevent hanging.

Networking (Asio)

• Use `io_context` as the event loop. Run from one or more threads.
• Use `co_await` (C++20 coroutines) with Asio for clean async code.
• Use `strand` for serializing access to shared state across handlers.
• Use `steady_timer` for timeouts and periodic tasks.
• Handle errors via `error_code` parameter, not exceptions, in async callbacks.

Database

• Use `libpq` (PostgreSQL) or `SOCI` for database access.
• Use prepared statements exclusively. Never concatenate SQL strings.
• Use connection pooling for multi-threaded server applications.
• Use `SQLite` via `sqlite3` C API with RAII wrappers for embedded use cases.

Package Management

• Use `vcpkg` or `Conan 2` for dependency management.
• Pin dependency versions in `vcpkg.json` or `conanfile.py`.
• Use CI caching for build artifacts and dependency downloads.
• Prefer pre-built binary packages for CI speed.

C++ Patterns

Error Handling

• Use exceptions for truly exceptional conditions. Use return types for expected failures.
• Use `std::expected<T, E>` (C++23) or `Result<T, E>` pattern for recoverable errors.
• Use `std::error_code` / `std::error_category` for system-level errors.
• Use `noexcept` on functions that must not throw (destructors, move operations).
• Catch by `const&`. Never catch by value (slicing) or pointer.

RAII Patterns

• Wrap every resource (memory, file, lock, socket) in an RAII type.
• Use `std::lock_guard` or `std::scoped_lock` for mutex management.
• Use `std::unique_lock` when deferred locking or condition variables are needed.
• Use `std::fstream` (auto-clo