干嵌入式这些年我最深的一个感受是真正写业务逻辑的时间并没有多少大量时间都耗在查手册、调寄存器、看编译报错、翻工程配置上。尤其是状态机这种又啰嗦又容易出错的东西手写switch-case能写到怀疑人生。所以当Claude Code这类AI编程工具能在终端里直接读工程、改代码、跑编译的时候我第一反应是这东西用在STM32上是不是有点过猛了但用了大半年之后结论很明确——它确实能干活而且干得比我想象中扎实。这篇文章是【嵌入式软件AI编程】系列的第一篇我会把基于STM32和Claude Code这套组合的实操流程、踩过的坑、验证过的提示词写法完整交代一遍。适合正在做嵌入式开发、想用AI编程提升效率但又不想被网上花里胡哨的演示带偏的人。1. 为什么嵌入式软件也该用AI编程1.1 从状态机到寄存器嵌入式开发的真实痛点嵌入式软件和纯后端、纯前端有个本质区别它离硬件太近。你写一个简单的按键控制LED背后至少牵扯到GPIO模式配置、上下拉电阻、时钟使能、消抖策略有时候还得考虑中断优先级和外设总线冲突。这些内容在IDE里不会自动补全在AI编程没有出现之前全靠人肉翻参考手册和数据手册。一个稍微像样点的设备要同时处理按键、串口指令、定时器超时、外部中断各种事件交错在一起如果一上来就用if-else硬堆代码很快会变成一坨没法维护的意大利面。这也是为什么我一直强调嵌入式软件架构的第一课应该从状态建模开始。把系统拆成“状态”、“事件”、“转移规则”三要素用状态机去收敛复杂度。状态机的表达方式非常固定一个枚举量、一个事件变量、一张转移表。正因为模式固定、逻辑边界清晰它反而是AI编程最容易发挥优势的场景之一。你只要把状态和事件定义清楚AI几乎不会在结构上犯错剩下的事情就是填动作函数。1.2 AI编程在嵌入式领域能做什么、不能做什么先说能做什么。以Claude Code为代表的AI编程工具擅长四类嵌入式工作第一生成样板代码。GPIO、UART、I2C、SPI的初始化HAL库/LL库的调用模板这些代码重复度高、格式固定AI一次能生成一大片基本不用怎么改。第二写状态机框架。给定状态和事件AI可以稳定输出转移表、动作函数和状态处理骨架。第三分析报错。把编译器的错误输出贴给它通常能直接指出是头文件路径问题、类型不匹配还是宏定义冲突。第四批量重构。比如把所有裸printf换成带时间戳的日志宏人工做容易漏AI反而更稳。不能做什么也很明确。AI不会替你做需求分析不会替你确认硬件连接对不对更不会替你看示波器和逻辑分析仪。它生成的寄存器配置、时序参数最终仍然要由人去查手册确认。把这个边界搞清楚AI编程在嵌入式里就是提效利器边界不清它就成了埋雷工具。拿主流工具横向比一下。Claude Code的优势不在“补全”而在“执行”。像GitHub Copilot和不少IDE插件主要做行内补全和聊天问答但对工程文件本身没有操作能力。Claude Code是终端里的Agent形态它能直接读工程文件、批量修改代码、执行编译命令然后根据编译结果自己修错。对嵌入式项目这种“改一个文件要联动多个头文件和构建脚本”的场景Agent形态明显更合适。工具交互方式能否执行命令工程级修改适合嵌入式场景Claude Code终端Agent可以可以很合适Codex终端/API有限有限可尝试CursorIDE内对话有限可以需要配合手动编译CopilotIDE补全否否辅助为主1.3 这套组合适合谁如果你已经能独立开发STM32基础项目知道怎么用CubeMX配置时钟、怎么接ST-Link那这套组合能帮你把重复劳动省下来。如果你是想入门的嵌入式软件新人AI编程也能当“陪练”但前提是你得先能看懂它生成的代码否则出了Bug只能干瞪眼。最不适合的是那种完全不懂嵌入式、指望AI全包的人AI生成的代码跑不到板子上最后锅还是得自己背。2. 环境搭建把Claude Code跑起来2.1 安装Node.js与Claude Code命令行工具Claude Code是一个npm包前提是机器上有Node.js版本建议18以上。装好之后先检查node -v npm -v然后全局安装Claude Codenpm install -g anthropic-ai/claude-code安装完成之后终端输入claude就能启动交互界面。第一次启动会让你做身份认证用Anthropic账号登录或者通过环境变量ANTHROPIC_API_KEY指向你的模型访问入口。如果你同时使用多个API供应商或本地模型做对比cc-switch这个小工具很实用。它本质上是替你管理多套API配置把不同的环境变量、Base URL、Key都存成方案切换的时候一键换掉不用反复改系统环境变量也不用改代码。这里有个实战建议不要一上来就折腾各种插件和MCP服务先在终端里把Claude Code跑通让它能读取你的工程文件、能执行你指定的编译命令比什么配置都重要。很多网上教程让新手大量安装MCP实际上一开始根本用不上反而增加了排查问题的难度。Claude Code本身的能力已经覆盖了绝大多数嵌入式开发需求。2.2 初始化STM32工程的标准姿势STM32工程的初始化我依然建议用STM32CubeMX生成。原因很简单时钟树、外设引脚、中断优先级这些内容可视化配置比纯手写可靠太多。CubeMX可以生成CMake工程也可以生成Makefile工程选CMake会舒服一些因为Claude Code在文本工程里改构建脚本很顺手。CubeMX里有两个关键点容易踩坑。一个是调试接口必须选SWD否则生成代码后ST-Link根本连不上芯片。另一个是时钟树配置如果外部晶振没焊或不稳定最好先用内部HSI时钟等板子稳定了再切外部晶振。我第一次让AI改时钟配置时就遇到过板子直接跑不起来的情况最后发现是PLL参数在CubeMX里没配好。生成之后把工程目录交给Claude Code之前先手动验证一遍编译链路是通的。以CMake工程为例cmake -S . -B build cmake --build build如果你的工具链在系统PATH里并且Cross-compilation配置没漏这两条命令就能生成elf文件。编译通过之后再把Claude Code拉进这个目录它就能基于真实工程上下文干活了。2.3 给Claude Code提供一个“可记忆”的项目环境Claude Code有项目记忆机制在工程根目录放一个CLAUDE.md文件它每次启动都会先读这个文件。我强烈建议在这个文件里写清楚三样东西编译命令怎么写、烧录命令怎么写、本项目有哪些代码规范。拿我最近一个STM32F103C8T6的小项目举例# 项目规范 - 芯片型号STM32F103C8T6 - 构建工具CMake arm-none-eabi-gcc - 编译命令cmake --build build - 烧录命令openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c program build/my_app.elf verify reset exit - 代码规范应用层代码放在Core/Src/app.c头文件放Core/Inc/app.h - 禁止修改STM32CubeMX生成的初始化代码如需修改走CubeMX重新生成有了这个文件就不用每次对话都重复交代硬件型号和编译方式。这也是Claude Code比IDE内AI插件体验好的一个细节它有长期记忆而不是每次开新会话都失忆。你还应该在CLAUDE.md里声明“修改代码前先列出改动计划”这个习惯在后面会救你很多次。3. 用Claude Code写第一个嵌入式状态机3.1 提示词怎么写Claude Code才愿意干对活嵌入式场景里AI编程提示词的关键不是语气好不好而是约束给得够不够紧。最常见的反例是直接一句“帮我实现按键控制LED”出来的代码可能能用但跟你的工程结构完全对不上接口莫名其妙最后还是要人肉改半天。我常用的提示词结构是固定的五段式身份、环境、任务、约束、输出格式。下面是我实测过的一段提示词用来在STM32工程里生成按键状态机你是资深嵌入式软件工程师。 项目路径当前工作目录芯片是STM32F103C8T6使用HAL库构建方式是CMake。 任务在Core/Src/app.c里用一个状态机实现按键控制LED。 要求 1. 状态定义IDLE、PRESSED、RELEASED、LONG_PRESS。 2. 10ms定时器中断中调用app_key_scan()函数对按键做消抖按下持续超过1000ms触发LONG_PRESS事件。 3. 每次进入RELEASED状态时翻转LED。 4. 事件类型需要单独定义枚举KEY_NONE、KEY_DOWN、KEY_UP、TIMER_TICK。 5. 状态处理用switch-case实现每个case里只写事件判断和动作状态转移逻辑单独抽一个函数。 6. 不要在main.c里加任何业务代码只允许通过app_init()和app_process()两个接口接入。 7. 新增的头文件声明放到Core/Inc/app.h。 输出格式 先给出状态转移表再给完整代码最后给出main.c接入方式的说明。这段提示词之所以有效是因为把“怎么做”的约束几乎全部给足了。嵌入式AI编程和Web开发不太一样嵌入式更怕AI自由发挥因为硬件资源摆在那里乱发挥就是编译不过或者跑飞。你给的约束越具体AI生成的代码越接近“可直接上板”的状态。3.2 实操过程从零到编译通过启动Claude Code后把它引导到工程目录cd ~/work/my_project claude在交互界面里把上面那段提示词粘进去。Claude Code会先读取CLAUDE.md然后浏览Core/Src目录下的源码接着开始生成代码。生成过程中终端会展示它读了哪些文件、改了哪些文件。这一步你能亲眼看到AI的工作方式先理解工程再动手改而不是凭空冒出代码。生成出来的核心代码大致是这个风格typedef enum { APP_STATE_IDLE 0, APP_STATE_PRESSED, APP_STATE_RELEASED, APP_STATE_LONG_PRESS } app_state_t; typedef enum { APP_EVENT_NONE 0, APP_EVENT_KEY_DOWN, APP_EVENT_KEY_UP, APP_EVENT_TIMER_TICK } app_event_t; static app_state_t app_state APP_STATE_IDLE; static uint8_t app_key_debounce_cnt 0; static uint16_t app_key_press_cnt 0; void app_key_scan(uint8_t key_level) { // 消抖计数30ms稳定后产生事件 if (key_level 0) { if (app_key_debounce_cnt 3) { app_key_debounce_cnt; } else if (app_state APP_STATE_IDLE) { app_state APP_STATE_PRESSED; app_key_press_cnt 0; } } else { app_key_debounce_cnt 0; } } void app_process(void) { switch (app_state) { case APP_STATE_PRESSED: if (app_key_press_cnt 100) { app_event APP_EVENT_KEY_DOWN; app_state APP_STATE_LONG_PRESS; // 长按动作 } break; case APP_STATE_RELEASED: // 翻转LED HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin); app_state APP_STATE_IDLE; break; default: break; } }注意这只是示意代码实际经过Claude Code生成的代码会配合你的HAL库版本、引脚宏定义做调整。生成完代码后我习惯在对话里追加一句现在执行cmake --build build如果有编译错误你先自己分析并修复修复完再重新编译直到编译通过再告诉我结果。这句指令非常关键。Claude Code会在它自己的Shell里执行编译命令然后读取报错信息自己迭代修复。我第一次跑这条流程的时候它遇到一个C语言语法问题宏定义的括号没配对自己改了重编两轮就过了。这种编译-报错-修复的闭环是Claude Code和普通聊天AI的明显分水岭。编译通过之后用OpenOCD烧录上板。烧录命令在CLAUDE.md里已经写好了你甚至可以直接让Claude Code执行烧录命令然后看返回的烧录日志。第一次上板如果遇到“找不到芯片”之类的报错别慌后面一节我会专门聊排查方法。3.3 Claude Code的工程级操作能力读代码、批量改、跑命令单看一个状态机可能还体现不出Agent的价值。真正让Claude Code好用起来的是它能以一个知道整个工程布局的人的身份参与开发。比如你让它“找出工程里所有直接操作GPIO寄存器的地方改成通过HAL库调用”它会把整个Core/Src下的代码搜索一遍列出清单然后批量替换。这种任务让我自己干少说半小时还要担心漏改交给AI去改再人工review一遍差异效率完全不在一个量级。再比如“K210与STM32通讯”这种场景本质上就是嵌入式软件里常见的协议解析。让Claude Code基于现有UART驱动写一个数据帧解析状态机定义帧头、长度、CRC校验字段它能直接把处理逻辑给你搭好。我已经不止一次用这种方式在半天内把别人一周的工作量压缩到一天而且代码质量还在线。这里要补一句重要提醒AI改完代码一定用git diff确认改动内容。Claude Code内置了快照回滚机制改坏了随时可以回到之前的版本。我把这个机制当成最后一道保险但更重要的是养成“每次改动先diff再放行”的习惯。即使AI是你的结对工程师代码最终签字的还是你。4. 上板调试与常见问题排查4.1 编译烧录OpenOCD与“no stm32 target found”完全排查嵌入式开发绕不开烧录调试。我用OpenOCD配合ST-Link比较多命令也很固定openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c program build/my_app.elf verify reset exit如果你第一次跑这条命令大概率会遇到一个经典报错Error: no STM32 target found! If your product embeds Debug Authentication, please perform a device mass erase or set RDP to 0.这个报错我帮不少人排查过。原因五花八门但九成集中在下面几类整理成表格方便对着查现象可能原因检查步骤SWD连线正确但找不到目标ST-LINK驱动或固件太旧用STM32CubeProgrammer更新ST-LINK固件目标板不上电或供电不稳板子没单独供电先用万用表量3.3V和GNDSWDIO/SWCLK接反接线错误核对杜邦线SWDIO接PA13、SWCLK接PA14芯片被读保护RDP等级不为0CubeProgrammer里解除读保护做mass erase新系列芯片调试认证开启Debug Authentication默认开启按提示做DA unlock或直接全片擦除复位引脚被拉低仿真器连了NRST但板上复位电路异常拔掉NRST连线再试如果你用的是STM32CubeProgrammer同样的问题在GUI里会显示得更直观。连接不上时第一步永远不要怀疑芯片坏了先检查供电、调试接口配置、SWD接线这三个老三样。我在实操时见过太多“芯片烧死”的案例最后都是没供电或者SWD引脚被复用了。还有个容易被忽略的点如果在CubeMX配置里把SWDIO或SWCLK引脚复用成了其他功能那烧录口就废了。所以CubeMX里必须把调试接口选成SWD生成代码后再让AI改应用逻辑这个顺序不要颠倒。4.2 让Claude Code参与调试读日志、分析栈回溯烧录进去之后调试才是大头。我以前调试HardFault的习惯是串口打印现在多了个新搭档让Claude Code直接分析日志。比如状态机跑一段时间莫名卡死我会让板子通过串口把当前状态、事件、关键变量周期性发出来然后把日志文件路径告诉Claude Code让它分析状态机在哪个状态陷入循环。它能在日志里定位出“长时间停留在PRESSED状态说明消抖事件没有触发”之类的结论比人肉看日志快很多。如果是HardFault可以让Claude Code生成一个栈回溯辅助函数把PC指针和LR寄存器的值在异常发生时打出来然后把寄存器dump丢给它它往往能定位到具体是哪个函数越界。这里有个实操心得给Claude Code看日志时不要一股脑把上万行日志全贴进对话它会消耗大量上下文而且容易抓不住重点。正确做法是让它去读日志文件用awk或grep提炼出关键行再基于提炼结果分析。这既省token又让结论更聚焦。4.3 常见问题速查表最后整理一份实操下来遇过的高频问题以及对应的处理方式问题现象解决方案Claude Code安装后命令不存在claude: command not found检查npm全局bin目录是否在PATH重装npmClaude Code额度限制提示对话中途显示weekly limit相关提示合理拆分任务用/compact压缩历史大任务分多次会话完成上下文过长导致回答变蠢AI开始重复问同一个问题用/compact整理上下文或在CLAUDE.md里精简项目规范编译工具链找不到arm-none-eabi-gcc: No such file把GCC工具链bin目录加进PATH或改CLAUDE.md里的绝对路径CubeMX重新生成后代码被覆盖app.c被还原应用层代码独立放到app.c不要放在main.c或CubeMX管理文件里AI生成的HAL函数与库版本不匹配编译报错找不到函数在CLAUDE.md中锁定HAL库版本并提供库目录路径烧录后板子没反应程序没跑起来先检查时钟配置、Boot0跳帽、供电再用调试器看PC指针位置OpenOCD一直连不上目标前面提到的no target found对照4.1表格逐项排查Claude Code的额度提示是会被不少人忽略的。它会在你每周用量快满的时候出现一条提示比如你的weekly limit被临时提升到某个比例这种信息。嵌入式开发往往需要长时间连续对话建议把大任务拆小一次对话专注一件事不要在一个会话里既写状态机又做烧录脚本又调日志那样很快就撞到上下文或额度上限。我是习惯按一个会话解决一个模块的粒度来使用体验稳定很多。再分享一个最近的体会。我现在越来越把Claude Code当成一个不需要休息的结对工程师但心里始终有一条底线AI生成的硬件相关配置最后一定是我自己翻数据手册确认。软件逻辑可以大胆交给AI寄存器时序必须自己把关。文件开头写清楚状态转移表注释、每次让AI改代码之前先让它列出改动计划这两个小习惯帮我少踩了太多坑。这个系列后续我会接着讲怎么用MCP把串口数据喂给Claude Code做自动调试闭环这一篇先把环境、状态机、烧录排查这几块打扎实后面的路就好走了。