重构前必须确认cmake target依赖关系完整，确保所有源文件和头文件被正确纳入target，并通过target_include_directories暴露路径，否则clion重构可能漏改或失效。
重构前必须确认 CMake target 依赖关系是否完整
CLion 的重构（如 Rename、Change Signature、Extract Method）依赖准确的符号索引，而索引质量直接受 CMakeLists.txt 中 target_sources 和 target_include_directories 配置影响。如果某个头文件没被任何 target 显式包含，或源文件未加入 target，重构可能漏改、跳过引用，甚至报 “Cannot resolve symbol” 却仍允许执行。
- 检查所有用户代码是否归属某个
add_executable或add_librarytarget - 确保
include/路径通过target_include_directories(... PUBLIC)暴露给依赖方，而非仅靠全局include_directories() - 对 STM32 项目，特别注意 HAL 库头文件路径是否通过
target_include_directories正确传递，否则Refactor → Rename在HAL_UART_Transmit调用处可能失效
Change Signature 修改函数时参数类型不一致会静默失败
CLion 的 Change Signature（Ctrl+F6）能自动更新调用点，但前提是原调用实参能隐式转换为目标新参数类型。一旦类型不兼容（例如把 int* 改成 std::vector<int>&</int>），它不会报错，而是跳过该调用点——你在编辑器里看不到任何提示，但编译必然失败。
- 执行前先用
Find Usages（Alt+F7）确认所有调用位置，人工检查实参兼容性 - 涉及指针/引用变更时，优先在头文件中改声明，再用
Generate Definitions（Shift+Ctrl+D）同步更新定义，比直接Change Signature更可控 - 对 HAL 回调函数（如
HAL_GPIO_EXTI_Callback），不要用Change Signature修改签名——它是 CMSIS 定义的固定接口，强行改会导致链接错误
跨文件重构时注意头文件 include 路径与模块边界
当你在 App/ 目录下对一个定义在 BSP/ 中的类执行 Refactor → Move 或 Extract Class，CLion 默认只移动 .cpp 文件，.h 文件可能留在原处，或生成相对路径错误的 #include。更麻烦的是，若目标目录无对应 CMake target，移动后代码将无法编译。
- 移动前确认目标目录已有可构建的 target（如
add_library(bps INTERFACE)），且 source group 结构与 CMake 匹配 - 移动后立即检查新生成的
#include路径：应为#include "bsp/gpio.h"而非#include "../BSP/gpio.h" - 对嵌入式项目，避免把硬件相关符号（如寄存器宏、
__IO类型）从Drivers/移到App/——这会破坏抽象层，且 CLion 无法校验 CMSIS 头文件的预处理器约束
别依赖“自动重命名文件”意图操作
当重命名一个类（如 class SensorDriver）时，CLion 会弹出 “Rename file to SensorDriver.h” 建议，但这个操作只改文件名，不更新 CMakeLists.txt 中的 target_sources 条目，也不修正其他文件中已存在的 #include "old_name.h"。
- 手动编辑
CMakeLists.txt，把旧文件路径替换成新路径 - 用
Find in Files（Ctrl+Shift+F）全局搜索旧文件名，包括字符串和注释中的误引 - 对 STM32 项目，CubeMX 生成的
main.h或stm32f4xx_hal_conf.h绝对不要用此意图重命名——它们是 HAL 初始化链的关键入口，改名等于切断整个启动流程
stm32f4xx_hal_conf.h），这些都得你亲手核对。
