Please create .clinerules to guide cline to generate best possible C++ code and develop new features or fix bugs.

C++ Project Guidelines for Cline

General Principles

• Always use modern C++ standards (C++17 or later, prefer C++20 where possible).
• Prioritize readability, maintainability, and performance.
• Follow the Rule of Zero: Prefer standard library types and RAII to avoid manual resource management.
• When developing new features or fixing bugs, provide complete, compilable code snippets with necessary includes and context.
• Explain changes briefly in comments or a summary message, including rationale for decisions.

Code Style & Patterns

• Naming Conventions:
  • Use snake_case for variables and functions (e.g., int user_count).
  • Use CamelCase for classes and structs (e.g., class UserManager).
  • Use ALL_CAPS for constants (e.g., const int MAX_USERS = 100;).
• Headers and Includes:
  • Use forward declarations where possible to minimize dependencies.
  • Organize includes: standard library first, then third-party, then project headers.
  • Use #pragma once for header guards.
• Smart Pointers and Ownership:
  • Prefer std::unique_ptr for exclusive ownership.
  • Use std::shared_ptr only when shared ownership is necessary.
  • Avoid raw pointers for ownership; use them only for observation (with const where possible).
• Error Handling:
  • Use std::expected (C++23) or std::optional for fallible functions; fall back to exceptions for truly exceptional cases.
  • Log errors using a consistent logging framework (e.g., spdlog if available).
  • Never use goto for error handling.
• Concurrency:
  • Use std::thread, std::mutex, and higher-level abstractions like std::future.
  • Avoid race conditions by design; use thread-safe patterns.
• Patterns:
  • Apply RAII for resources (files, locks, etc.).
  • Use the Factory pattern for complex object creation.
  • Prefer composition over inheritance.

Testing Standards

• Write unit tests using a framework like Google Test (gtest) for all new functions and bug fixes.
• Aim for 80%+ code coverage on new/changed code.
• Include tests for edge cases, errors, and performance-critical paths.
• For features: Provide integration tests to verify interactions.
• For bug fixes: Add a regression test that fails without the fix.
• Structure tests in a tests/ directory mirroring the source structure.

Documentation Requirements

• Add Doxygen-style comments to public functions, classes, and headers.
  • Example: /// Brief description. \param input Description. \return Description.
• Update README.md with new features, including usage examples.
• For bug fixes, add entries to CHANGELOG.md in semantic versioning format.
• When generating code, include inline comments explaining non-obvious logic.

Developing New Features

• Break down features into small, incremental changes.
• Ensure backward compatibility unless specified otherwise.
• Profile for performance impacts and optimize only if necessary (e.g., using tools like perf or Valgrind).
• Consider thread-safety and exception-safety in designs.

Fixing Bugs

• Reproduce the bug with a minimal example or test case.
• Identify root cause and explain it in the fix summary.
• Apply the fix minimally; avoid unrelated changes.
• Verify the fix doesn't introduce new issues (run full test suite).

Tools and Build

• Assume CMake for build system; generate CMakeLists.txt snippets if needed.
• Use static analysis tools like clang-tidy for code suggestions.
• Compile with -Wall -Wextra -Werror -std=c++20 flags for strict checking.