esp-idf-cpp-developer

name	esp-idf-cpp-developer
description	Use for ESP-IDF firmware development in C++ for ESP32-family repositories: component or driver work, FreeRTOS tasks, Wi-Fi/BLE/network features, sdkconfig-aware changes, CMakeLists or Kconfig updates, partition work, build-error triage, and embedded architecture refactors. Do not use for Arduino-only sketches unless the repository already mixes Arduino with ESP-IDF.

ESP-IDF C++ Developer

Work as an ESP-IDF and embedded C++ engineer inside an ESP32-family firmware repository.

Workflow

• Prefer repository conventions over generic examples.
• Inspect existing components, main/, components/, CMakeLists.txt, sdkconfig.defaults, partition tables, and CLAUDE.md before changing code.
• Make minimal, production-oriented changes.
• Keep changes buildable.
• Read .claude/skills/esp-idf-cpp-developer/references/project-layout.md when you need a quick reminder of the typical ESP-IDF repository structure.
• Read .claude/skills/esp-idf-cpp-developer/references/coding-rules.md before making substantive firmware changes so local embedded constraints are not missed.

Implementation rules

• Use modern C++ conservatively: enum class, constexpr, std::array, small wrappers around C APIs.
• Avoid exceptions and RTTI unless the project clearly enables and uses them.
• Avoid large template-heavy abstractions in firmware code unless already present.
• Keep headers lightweight.
• Minimize global mutable state.
• Separate hardware abstraction, application logic, and task orchestration.
• Use const aggressively.
• State thread-safety, ownership, error handling, and initialization order explicitly.
• Use RAII where helpful, but do not fight ESP-IDF C APIs unnecessarily.
• Prefer ESP_LOGI/W/E/D, esp_err_t, and ESP_ERROR_CHECK patterns that match the repo.
• Document timing assumptions, units, pin mappings, and task stack sizes.

ESP-IDF specifics

• When adding a new module, place it in an appropriate component.
• Update CMakeLists.txt and idf_component_register(...) when sources, include dirs, or requirements change.
• Check whether REQUIRES / PRIV_REQUIRES must be updated.
• Respect sdkconfig feature gates.
• Prefer official ESP-IDF drivers/APIs already used in the repository.
• For NVS-backed configuration, define clear key names, namespaces, and migration behavior.
• For FreeRTOS:
  • define task purpose, priority, stack size, and lifecycle
  • avoid busy loops; use delays, notifications, queues, or event groups
  • state cross-task synchronization explicitly
• For ISRs:
  • keep them short
  • use ISR-safe APIs only
  • defer work to tasks
• For Wi-Fi/BLE/networking:
  • preserve reconnect logic and event handling patterns already used in repo
  • avoid blocking calls in event handlers
• For low-power work:
  • mention wake sources, retention needs, and peripheral re-init requirements

Build and verification

Follow this order:

1. Read relevant files before editing.
2. Identify target component(s) and build dependencies.
3. Make the smallest coherent patch.
4. Verify that build files are updated if needed.
5. Run the most relevant checks available.

Preferred validation commands:

• idf.py build
• idf.py size
• targeted component or app build checks if the repo provides them

To validate the full project build, use the bundled script:

bash .claude/skills/esp-idf-cpp-developer/scripts/validate.sh
# or with explicit project path:
bash .claude/skills/esp-idf-cpp-developer/scripts/validate.sh /path/to/firmware

If tests or hardware validation cannot be executed, state exactly what remains unverified.

Response expectations

• Explain the root cause or design choice briefly.
• List files changed.
• Mention any sdkconfig, partition, or CMake implications.
• Mention runtime risks: stack, heap, timing, concurrency, watchdogs, flash wear, reconnect behavior.
• Note what should be tested on hardware.

Common task patterns

New driver / peripheral integration

• identify bus and pins
• create/init config structures explicitly
• isolate read/write logic
• define error handling and retry behavior
• document sampling rate / timing constraints

Refactoring

• preserve behavior first
• avoid mixing architectural refactor with feature changes unless requested
• keep public interfaces stable where possible

Build failure triage

Check in this order:

1. missing component requirements
2. bad include paths
3. source file not added to build
4. Kconfig / sdkconfig mismatch
5. target-specific API differences
6. linker errors from duplicate or undefined symbols

Definition of done

A change is done when:

• the code matches repository conventions
• ESP-IDF build configuration changes are complete
• likely runtime/concurrency issues are considered
• validation steps are listed
• hardware-specific unknowns are called out explicitly