给 AI 配上锤子和螺丝刀：嵌入式 AI 辅助开发的 Harness Engineering 实践

让 AI 写代码并不难，难的是让 AI 自己验证代码。这篇文章以 STM32F103C8T6 + WS2812 项目为载体，记录了如何通过搭建 Harness（工具+资料+权限），让 AI 从"代码生成器"变成"自主开发者"。

---

关联文章：

• STM32命令行工具链手册-编译烧录调试自动化指南
• WS2812驱动开发与调试经验总结

一、理念转变：从"AI 帮我写代码"到"给 AI 配工具"

1.1 两种开发模式对比

传统模式：AI 作为代码生成器

用户描述需求 → AI 生成代码 → 人工复制 → 手动编译 → 发现错误 → 再次询问 AI → ...

问题：

• AI 无法验证代码是否正确
• 编译错误需要人工反馈
• 调试信息 AI 看不到
• 每次沟通都从零开始

Harness 模式：AI 作为自主开发者

搭建环境 → 提供 Harness（工具+资料+权限）→ AI 自主完成：编码 → 编译 → 调试 → 修复 → 验证

优势：

• AI 可以自主验证代码
• 编译错误 AI 自己读取并修复
• 调试信息 AI 可以自主获取
• 形成闭环，快速迭代

1.2 本项目的选择

本项目采用了 Harness 模式。整个开发过程的核心不是"让 AI 写代码"，而是先搭建一套让 AI 能自主工作的环境。

---

二、Harness Engineering 实践

2.1 什么是 Harness

Harness（工具套件）是 AI 自主工作的基础设施，包含三个要素：

要素	内容	作用
工具	编译器、烧录器、调试器、串口监视器	AI 可以执行操作、获取反馈
资料	数据手册、参考工程、协议文档	AI 基于权威信息工作，而非凭空猜测
权限	文件读写、命令执行、网络访问	AI 可以自主操作，无需人工介入

2.2 实践一：编译烧录工具链

为什么先做这个：让 AI 能自主验证代码

搭建过程：

1. 分析项目结构：发现 EIDE 扩展自带命令行工具

2. 探索工具可用性：

   检查 ~/.eide/tools/
   ├── gcc_arm/        ✓ ARM GCC 工具链
   ├── jlink/          ✓ J-Link V8.50
   └── openocd/        ✓ OpenOCD 备选
   

3. 解决环境兼容性问题：

   问题	解决方案
   Batch 脚本在 Bash 中失败	编写原生 .sh 脚本
   J-Link 不识别 Unix 路径	sed 路径转换
   Glob 搜索超时	缩小范围 + Bash 循环
   脚本移动后路径错误	修正相对路径层级

4. 封装为 Skill：

   .claude/skills/eide-stm32-dev/
   ├── SKILL.md              # Skill 定义
   └── scripts/
       ├── build-flash.sh    # 编译 + 烧录
       ├── clean.sh          # 清理
       └── debug.sh          # 调试
   

效果：AI 可以自己编译 → 看报错 → 修复 → 重试，无需人工介入

实际案例：光效系统开发中，AI 在 3 次编译迭代内完成：

1. 修复按键宏未定义错误
2. 修复枚举类型混用警告
3. 修复正弦表初始化警告

最终达成零警告、零错误。

2.3 实践二：参考资料供给

为什么重要：AI 基于资料理解协议，而非凭空生成

供给方式：

资料类型	内容	作用
协议文档	WS2812相关信息.md	理解 NRZ 协议、时序参数
参考工程	WS2812参考工程分析.md	对比配置差异
PCB 连接表	PCB连接关系表.md	确认引脚映射

实际效果：

• 驱动开发少走弯路：AI 知道 GRB 顺序、800kHz 频率
• 问题定位更精准：对比参考工程发现 DMA 触发方式差异
• 避免硬件踩坑：PCB 连接表防止引脚配置错误

反面案例：

最初未提供 PCB 连接表时，AI 根据"常规配置"猜测引脚，结果：

• LED 引脚猜错 3/4
• OLED I2C 引脚配置错误
• 蜂鸣器引脚不对

教训：硬件相关的信息必须明确提供，AI 无法猜对 PCB 设计。

2.4 实践三：调试能力扩展

串口监视器：

python tools/serial_monitor.py COM8 115200 -r

AI 可以：

• 实时读取设备输出
• 看到调试打印信息
• 验证程序运行状态

GDB 调试：

AI 可以：

• 设置断点
• 读取寄存器
• 查看调用栈
• 分析内存内容

实际案例：WS2812 渐变色问题排查中，AI 通过串口打印 PWM 缓冲区，确认编码正确，定位到传输层问题。

---

三、Superpowers 工作流实践

Superpowers 是 Claude Code 的一套结构化技能系统（skill），提供 brainstorming、writing-plans、code-review 等工作流模板。它不是本项目专用的工具，而是 Claude Code 生态中的通用能力。这里记录的是它在嵌入式场景下的实际应用效果。

3.1 工作流概览

Superpowers 是一套结构化的开发工作流，确保"想清楚再做"：

阶段	工作流	作用
设计	brainstorming	逐层澄清需求，避免返工
规划	writing-plans	分解任务，识别风险
执行	executing-plans	按计划实施，质量可控
审查	code-review	捕获问题，保证质量

3.2 游戏设计：brainstorming 实践

场景：设计消消乐游戏

过程：

brainstorming 工作流通过一次一个问题的方式，逐步澄清：

1. 布局方案：单向布局 vs 双向布局？

   • 选择：单向布局（玩家区 0-2，轨道 3-56，敌方区 57-59）

2. 炮弹设计：单灯还是多灯？

   • 选择：多灯带拖尾效果

3. 碰撞规则：颜色不匹配怎么处理？

   • 选择：不扣命，只消耗玩家炮弹

4. 按键映射：游戏中按键功能？

   • 选择：KEY1/2/3 发射，KEY4 暂停

5. 难度系统：如何递进？

   • 选择：波次递进 + 动态平衡

效果：从模糊想法到精确设计，避免后期返工

对比：如果没有 brainstorming，可能的问题：

• 做到一半发现布局不合理
• 碰撞规则需要推翻重来
• 按键功能冲突

3.3 光效系统：planner + code-review 实践

planner 使用：

AI 自动生成实现计划：

1. 模块化设计：分离颜色工具和光效逻辑
2. 文件架构：WS2812_ColorUtils + WS2812_Effects
3. 实现步骤：按优先级分阶段

code-review 使用：

每次代码变更后，AI 自动审查：

• 类型安全
• 代码规范
• 潜在问题

实际捕获的问题：

• volatile 遗漏（中断共享变量）
• 缓冲区溢出风险（vsprintf → vsnprintf）
• 枚举类型混用警告

3.4 驱动调试：investigate + 自主迭代

WS2812 渐变色问题：

1. 现象：设置全红，显示渐变色

2. investigate 排查：

   • 数据层：打印颜色缓冲区 ✓ 正确
   • 编码层：打印 PWM 缓冲区 ✓ 正确
   • 传输层：检查 DMA 配置 → 发现 CC2 触发问题

3. 自主迭代：

   尝试 1：内存对齐 → 无效
   尝试 2：增加复位周期 → 无效
   尝试 3：修改 DMA 触发方式 → 解决！
   

4. 验证：编译 → 烧录 → 串口确认 → 成功

整个过程 AI 自主完成，无需人工介入。

---

四、效率对比

以下对比仅衡量"单次操作耗时"，不包含 AI 思考和生成代码的时间。AI 生成代码的时间取决于任务复杂度，通常在数秒到数十秒之间。

4.1 传统嵌入式开发

操作	方式	耗时
编译	手动点击按钮	~10s（含操作）
烧录	手动操作 J-Link	~30s
查看输出	眼睛盯着串口助手	持续
定位问题	人工分析	分钟级
修复验证	重新编译烧录	~1min

一个问题的典型周期：2-5 分钟

4.2 AI + Harness 开发

操作	方式	耗时
编译	AI 自主调用脚本	~2s
烧录	AI 自主执行	~0.5s
查看输出	AI 读取串口数据	即时
定位问题	AI 分析错误信息	秒级
修复验证	AI 自动重试	~3s

一个问题的典型周期：5-10 秒

4.3 量化收益

指标	传统方式	AI + Harness	提升
编译周期	~10s	~2s	5x
问题定位	分钟级	秒级	10x+
迭代速度	分钟/次	秒/次	10x+
人工介入	必须	可选	-

实际案例：光效系统开发，3 次编译迭代完成，总耗时 < 1 分钟

---

五、方法论沉淀

5.1 Harness 三要素

Harness = 工具 + 资料 + 权限

要素	检查项
工具	编译器、烧录器、调试器、监视器是否可用？
资料	数据手册、参考代码、硬件文档是否提供？
权限	文件读写、命令执行、网络访问是否开放？

5.2 工作流选择指南

场景	推荐工作流
新功能设计	brainstorming → writing-plans → executing-plans
Bug 修复	investigate → fix → verify
代码变更	code-review 质量保障
复杂重构	writing-plans 先规划

5.3 可迁移到其他项目的经验

1. 先搭环境，再写代码

不要急着让 AI 生成代码。先问：

• AI 能编译吗？
• AI 能烧录吗？
• AI 能调试吗？

如果答案是否定的，先把这些问题解决。

2. 提供权威资料

不要让 AI 凭记忆或猜测。提供：

• 数据手册（协议、时序、寄存器）
• 参考工程（可直接对比）
• 硬件文档（引脚映射、连接关系）

3. 封装可复用能力

把工具链封装为 Skill，下次项目直接复用：

• eide-stm32-dev Skill 可用于其他 STM32 项目
• 脚本稍作修改即可适配

4. 让 AI 闭环验证

AI 写完代码后，让它自己：

• 编译验证
• 烧录测试
• 读取输出
• 分析问题
• 修复重试

不要人工介入这个循环。

---

六、局限性

Harness 模式并非万能。以下是实践中发现的边界：

AI 无法处理的问题：

• 硬件层面：虚焊、电源不稳、信号干扰——AI 只能分析软件和配置，物理问题需要示波器和万用表
• 环境层面：USB 连接断开、驱动安装失败、操作系统兼容性——这些需要人工介入
• 设计层面：PCB 引脚分配、电源拓扑——AI 只能按提供的文档工作，无法替代硬件设计决策

首次搭建成本：

• 工具链脚本编写、Skill 封装、参考资料整理需要额外投入
• 对于一次性小项目，手动开发可能更快
• Harness 的价值在重复迭代中体现：搭建一次，后续项目复用

AI 的常见偏差：

• 倾向于使用熟悉的库/方案，可能忽略目标平台的特殊约束
• 对实时性要求高的场景（中断延迟、DMA 时序），AI 可能需要多次试错才能收敛
• 参考资料的质量直接影响 AI 的输出质量——"垃圾进，垃圾出"仍然成立

---

七、总结

核心观点

1. AI 是执行者，不是魔法：它需要工具、资料、权限才能自主工作

2. Harness 决定 AI 的能力边界：没有编译工具链，AI 无法验证代码；没有调试能力，AI 无法定位问题

3. 工作流保证质量：brainstorming 避免返工，code-review 保证质量

4. 闭环是关键：AI 能自主验证 → 快速迭代 → 高效开发

本项目成果

成果	说明
工具链 Skill	eide-stm32-dev 可复用于其他 STM32 项目
WS2812 驱动	PWM+DMA 方案，稳定驱动 60 颗 LED
消消乐游戏	完整游戏逻辑 + 光效系统
方法论	这篇文章，可迁移到其他项目

适用范围

本文的方法论适用于：

• 嵌入式开发：需要编译、烧录、调试工具链
• 硬件相关项目：需要提供硬件文档和引脚映射
• AI 辅助开发：希望 AI 自主工作而非仅生成代码