agentic-team-templates 0.13.1 → 0.14.0

package/templates/cpp-expert/.cursorrules/performance.md

@@ -0,0 +1,223 @@
+# C++ Performance
+
+Measure first. Understand the hardware. Zero-cost abstractions are the goal.
+
+## Profile Before Optimizing
+
+```bash
+# perf (Linux)
+perf record -g ./myapp
+perf report
+
+# Valgrind callgrind
+valgrind --tool=callgrind ./myapp
+kcachegrind callgrind.out.*
+
+# Google Benchmark for micro-benchmarks
+./benchmarks --benchmark_format=console --benchmark_min_time=2s
+```
+
+### Tools
+
+| Tool | Purpose |
+|------|---------|
+| perf | CPU profiling, cache analysis |
+| Valgrind/Callgrind | Instruction-level profiling |
+| Google Benchmark | Micro-benchmarks |
+| Compiler Explorer | Assembly inspection |
+| heaptrack | Heap allocation profiling |
+| Tracy | Frame profiler (games/real-time) |
+
+## Cache-Friendly Data Structures
+
+```cpp
+// Structure of Arrays (SoA) vs Array of Structures (AoS)
+
+// AoS — bad cache utilization when iterating one field
+struct Particle {
+    float x, y, z;
+    float vx, vy, vz;
+    float mass;
+    int type;
+};
+std::vector<Particle> particles; // Accesses mass? Loads x,y,z,vx,vy,vz too
+
+// SoA — excellent cache utilization for field-wise iteration
+struct Particles {
+    std::vector<float> x, y, z;
+    std::vector<float> vx, vy, vz;
+    std::vector<float> mass;
+    std::vector<int> type;
+};
+// Iterating mass only touches mass data — no waste
+
+// Rule: profile first. SoA matters for hot loops over large datasets.
+```
+
+## Allocation Avoidance
+
+```cpp
+// Pre-allocate containers
+std::vector<Item> items;
+items.reserve(expected_count); // One allocation instead of many
+
+// Small buffer optimization (SBO)
+// std::string already uses SBO (typically 15-22 chars inline)
+// std::function uses SBO for small callables
+
+// Stack allocation for temporary buffers
+std::array<char, 256> buffer; // Stack, not heap
+
+// Object pools for frequent allocation/deallocation
+template <typename T>
+class ObjectPool {
+    std::vector<std::unique_ptr<T>> pool_;
+    std::vector<T*> available_;
+
+public:
+    auto acquire() -> T* {
+        if (available_.empty()) {
+            pool_.push_back(std::make_unique<T>());
+            return pool_.back().get();
+        }
+        auto* obj = available_.back();
+        available_.pop_back();
+        return obj;
+    }
+
+    void release(T* obj) {
+        available_.push_back(obj);
+    }
+};
+```
+
+## Move Semantics for Performance
+
+```cpp
+// Move instead of copy for expensive objects
+std::vector<std::string> build_names(std::span<const User> users) {
+    std::vector<std::string> names;
+    names.reserve(users.size());
+    for (const auto& user : users) {
+        names.push_back(user.name()); // Copy (user is const)
+    }
+    return names; // NRVO — no copy, no move
+}
+
+// Sink parameters: take by value and move
+class Widget {
+    std::string name_;
+public:
+    explicit Widget(std::string name) : name_{std::move(name)} {}
+    // Caller can copy or move into the parameter
+};
+
+// Emplace instead of push_back to construct in-place
+items.emplace_back(arg1, arg2); // Constructs directly in vector
+items.push_back(Item{arg1, arg2}); // Constructs then moves
+```
+
+## constexpr Computation
+
+```cpp
+// Move computation to compile time
+constexpr auto factorial(int n) -> int {
+    int result = 1;
+    for (int i = 2; i <= n; ++i) result *= i;
+    return result;
+}
+static_assert(factorial(5) == 120);
+
+// Compile-time lookup tables
+constexpr auto build_crc_table() {
+    std::array<uint32_t, 256> table{};
+    for (uint32_t i = 0; i < 256; ++i) {
+        uint32_t crc = i;
+        for (int j = 0; j < 8; ++j) {
+            crc = (crc >> 1) ^ ((crc & 1) ? 0xEDB88320 : 0);
+        }
+        table[i] = crc;
+    }
+    return table;
+}
+constexpr auto crc_table = build_crc_table(); // Computed at compile time
+```
+
+## SIMD and Vectorization
+
+```cpp
+// Help the compiler auto-vectorize
+// 1. Use contiguous containers (vector, array)
+// 2. Simple loop bodies without branches
+// 3. No pointer aliasing (use __restrict or std::span)
+
+void add_vectors(float* __restrict out,
+                 const float* __restrict a,
+                 const float* __restrict b,
+                 size_t n) {
+    for (size_t i = 0; i < n; ++i) {
+        out[i] = a[i] + b[i]; // Auto-vectorized by compiler
+    }
+}
+
+// Verify with: -fopt-info-vec (GCC) or -Rpass=loop-vectorize (Clang)
+```
+
+## String Performance
+
+```cpp
+// std::string_view for read-only string operations — zero copies
+void process(std::string_view input) {
+    auto prefix = input.substr(0, 5); // No allocation
+    if (input.starts_with("http")) { /* ... */ }
+}
+
+// Avoid string concatenation in loops
+std::string result;
+result.reserve(total_estimated_size);
+for (const auto& item : items) {
+    result.append(item.name());
+    result.push_back(',');
+}
+
+// fmt::format or std::format over stringstream
+auto msg = fmt::format("User {} logged in from {}", name, ip);
+```
+
+## Compiler Optimization Flags
+
+```cmake
+# Release build
+target_compile_options(${PROJECT_NAME} PRIVATE
+    $<$<CONFIG:Release>:-O3 -DNDEBUG -march=native>
+    $<$<CONFIG:Debug>:-O0 -g>
+    $<$<CONFIG:RelWithDebInfo>:-O2 -g -DNDEBUG>
+)
+
+# Link-Time Optimization
+set(CMAKE_INTERPROCEDURAL_OPTIMIZATION_RELEASE ON)
+```
+
+## Anti-Patterns
+
+```cpp
+// Never: premature optimization without profiling
+// "I think this allocation is slow" — prove it
+
+// Never: virtual function calls in hot loops (unless measured)
+for (auto& item : million_items) {
+    item->process(); // vtable lookup every iteration
+}
+// Consider: CRTP, std::variant, or batch processing
+
+// Never: std::map when std::unordered_map or sorted vector suffices
+std::map<std::string, int> counts; // O(log n) lookup, poor cache locality
+// Use: std::unordered_map or flat_map (C++23)
+
+// Never: shared_ptr for performance-critical paths
+// Atomic reference count operations are expensive
+// Use unique_ptr or raw non-owning pointers
+
+// Never: exceptions in hot paths
+// Exceptions are zero-cost on the happy path but expensive when thrown
+```

package/templates/cpp-expert/.cursorrules/testing.md

@@ -0,0 +1,230 @@
+# C++ Testing
+
+Test behavior. Test edge cases. Test with sanitizers. No excuses.
+
+## Framework Stack
+
+| Tool | Purpose |
+|------|---------|
+| Google Test | Test framework |
+| Google Mock | Mocking |
+| Catch2 | Alternative test framework (header-only) |
+| Google Benchmark | Micro-benchmarks |
+| ASan | Address sanitizer (memory errors) |
+| UBSan | Undefined behavior sanitizer |
+| TSan | Thread sanitizer (data races) |
+| MSan | Memory sanitizer (uninitialized reads) |
+| Valgrind | Memory leak detection |
+
+## Test Structure (Google Test)
+
+```cpp
+class OrderServiceTest : public ::testing::Test {
+protected:
+    void SetUp() override {
+        repo_ = std::make_unique<MockOrderRepository>();
+        inventory_ = std::make_unique<MockInventoryClient>();
+        sut_ = std::make_unique<OrderService>(*repo_, *inventory_);
+    }
+
+    std::unique_ptr<MockOrderRepository> repo_;
+    std::unique_ptr<MockInventoryClient> inventory_;
+    std::unique_ptr<OrderService> sut_;
+};
+
+TEST_F(OrderServiceTest, Create_WithValidItems_ReturnsOrder) {
+    // Arrange
+    EXPECT_CALL(*inventory_, check_availability("SKU-001", 2))
+        .WillOnce(Return(true));
+    EXPECT_CALL(*repo_, save(testing::_))
+        .WillOnce(Return(Order{.id = "order-1"}));
+
+    // Act
+    auto result = sut_->create(CreateOrderRequest{
+        .customer_id = "customer-1",
+        .items = {{"SKU-001", 2}}
+    });
+
+    // Assert
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(result->customer_id, "customer-1");
+    EXPECT_EQ(result->items.size(), 1);
+}
+
+TEST_F(OrderServiceTest, Create_WithInsufficientInventory_ReturnsError) {
+    EXPECT_CALL(*inventory_, check_availability("SKU-001", 100))
+        .WillOnce(Return(false));
+
+    auto result = sut_->create(CreateOrderRequest{
+        .customer_id = "customer-1",
+        .items = {{"SKU-001", 100}}
+    });
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), OrderError::insufficient_inventory);
+}
+```
+
+## Catch2 Alternative
+
+```cpp
+#include <catch2/catch_test_macros.hpp>
+#include <catch2/matchers/catch_matchers_string.hpp>
+
+TEST_CASE("Parser handles edge cases", "[parser]") {
+    SECTION("empty input returns error") {
+        auto result = parse("");
+        REQUIRE_FALSE(result.has_value());
+        REQUIRE(result.error() == ParseError::empty_input);
+    }
+
+    SECTION("valid input returns parsed value") {
+        auto result = parse("42");
+        REQUIRE(result.has_value());
+        REQUIRE(*result == 42);
+    }
+
+    SECTION("overflow returns error") {
+        auto result = parse("999999999999999999");
+        REQUIRE_FALSE(result.has_value());
+        REQUIRE(result.error() == ParseError::out_of_range);
+    }
+}
+```
+
+## Parameterized Tests
+
+```cpp
+struct ParseTestCase {
+    std::string input;
+    std::expected<int, ParseError> expected;
+};
+
+class ParseTest : public ::testing::TestWithParam<ParseTestCase> {};
+
+TEST_P(ParseTest, ParsesCorrectly) {
+    auto [input, expected] = GetParam();
+    auto result = parse(input);
+
+    if (expected.has_value()) {
+        ASSERT_TRUE(result.has_value()) << "Input: " << input;
+        EXPECT_EQ(*result, *expected);
+    } else {
+        ASSERT_FALSE(result.has_value()) << "Input: " << input;
+        EXPECT_EQ(result.error(), expected.error());
+    }
+}
+
+INSTANTIATE_TEST_SUITE_P(ParseTests, ParseTest, ::testing::Values(
+    ParseTestCase{"42", 42},
+    ParseTestCase{"-1", -1},
+    ParseTestCase{"", std::unexpected{ParseError::empty_input}},
+    ParseTestCase{"abc", std::unexpected{ParseError::invalid_format}}
+));
+```
+
+## Mocking
+
+```cpp
+class MockDatabase : public Database {
+public:
+    MOCK_METHOD(std::optional<User>, find_user, (std::string_view email), (const, override));
+    MOCK_METHOD(void, save_user, (const User& user), (override));
+    MOCK_METHOD(bool, delete_user, (std::string_view id), (override));
+};
+
+// Expectations
+EXPECT_CALL(mock_db, find_user("alice@example.com"))
+    .Times(1)
+    .WillOnce(Return(User{.name = "Alice", .email = "alice@example.com"}));
+
+// Matchers
+EXPECT_CALL(mock_db, save_user(
+    Field(&User::email, HasSubstr("@example.com"))))
+    .Times(AtLeast(1));
+```
+
+## Sanitizers
+
+```cmake
+# CMake options for sanitizers
+option(ENABLE_SANITIZERS "Enable ASan and UBSan" OFF)
+
+if(ENABLE_SANITIZERS)
+    target_compile_options(${PROJECT_NAME} PRIVATE
+        -fsanitize=address,undefined
+        -fno-omit-frame-pointer)
+    target_link_options(${PROJECT_NAME} PRIVATE
+        -fsanitize=address,undefined)
+endif()
+
+# Thread sanitizer (separate — incompatible with ASan)
+option(ENABLE_TSAN "Enable Thread Sanitizer" OFF)
+if(ENABLE_TSAN)
+    target_compile_options(${PROJECT_NAME} PRIVATE -fsanitize=thread)
+    target_link_options(${PROJECT_NAME} PRIVATE -fsanitize=thread)
+endif()
+```
+
+```bash
+# Run with sanitizers
+cmake -B build -DENABLE_SANITIZERS=ON
+cmake --build build
+ctest --test-dir build
+
+# Thread sanitizer (separate build)
+cmake -B build-tsan -DENABLE_TSAN=ON
+cmake --build build-tsan
+ctest --test-dir build-tsan
+```
+
+## Benchmarks (Google Benchmark)
+
+```cpp
+#include <benchmark/benchmark.h>
+
+static void BM_VectorPushBack(benchmark::State& state) {
+    for (auto _ : state) {
+        std::vector<int> v;
+        for (int i = 0; i < state.range(0); ++i) {
+            v.push_back(i);
+        }
+        benchmark::DoNotOptimize(v);
+    }
+}
+BENCHMARK(BM_VectorPushBack)->Range(8, 1 << 20);
+
+static void BM_VectorReserved(benchmark::State& state) {
+    for (auto _ : state) {
+        std::vector<int> v;
+        v.reserve(static_cast<size_t>(state.range(0)));
+        for (int i = 0; i < state.range(0); ++i) {
+            v.push_back(i);
+        }
+        benchmark::DoNotOptimize(v);
+    }
+}
+BENCHMARK(BM_VectorReserved)->Range(8, 1 << 20);
+
+BENCHMARK_MAIN();
+```
+
+## Anti-Patterns
+
+```cpp
+// Never: tests that depend on execution order
+// Each test must be independent and self-contained
+
+// Never: testing private implementation details
+// Test public interface and observable behavior
+
+// Never: ignoring sanitizer warnings
+// Every ASan/UBSan/TSan finding is a real bug
+
+// Never: skipping edge cases
+// Test empty input, max values, boundary conditions, error paths
+
+// Never: mocking everything
+// Only mock external dependencies (I/O, network, time)
+// Use real objects for in-process logic
+```