# Firmware Dev Executor

> 基于项目记忆、硬件接口、需求和本地构建工具实现、编译、调试和修复 MCU 固件。适用于生成 BSP/driver/app 代码、维护 Keil/CMake/Make 工程、解析编译错误、实现协议解析、参数存储、校准、UI 逻辑、第三方库移植或执行“最小测试闭环”的嵌入式开发任务。强调人管物理世界，AI 管信息世界。

- Skill: `tsaiguohua/firmware-dev-executor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tsaiguohua/firmware-dev-executor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tsaiguohua/firmware-dev-executor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tsaiguohua (https://skillmd.com/u/tsaiguohua)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tsaiguohua/firmware-dev-executor

---


# 固件开发执行

先读项目记忆、硬件接口和产品需求，再写固件。必须从底层往上，小步验证。

核心边界：**人管物理世界，AI 管信息世界。**

- 人负责：上电、带载、观察、温升、过流、异常声音、真实安全、关键产品判断。
- AI 负责：读资料、看源码、看日志、收敛假设、生成最小改动、设计下一轮最小测试。

不要把编译通过当成硬件验证，不要把 AI 的推断当成板端事实。

## 必要上下文

- MCU 型号、封装、板卡版本。
- 硬件接口速查表、开发板资源模型和危险输出清单。
- 产品行为需求和验收标准。
- 现有项目结构和构建命令。
- 代码分层和命名规则。
- 验证方式：编译日志、串口输出、调试器/SWD、示波器、人工观察。

缺关键上下文时，先建立 TODO 或提出一个聚焦问题，不要编造硬件事实。

## 开发顺序

1. 编译/运行基线。
2. GPIO 安全默认态。
3. UART 日志或最小调试通道。
4. 逐个外设：ADC、PWM、I2C、SPI、定时器、中断、DMA。
5. BSP 抽象：有效电平、板级语义、安全动作。
6. component：parser、CRC、环形缓冲、滤波、参数存储。
7. app 功能模块。
8. app_workflow 业务编排。
9. 集成测试并更新调试记录。

底层外设未验证前，不要直接写业务逻辑。

## 最小测试闭环

每一轮只推进一个最小目标，不要一次改一堆。

标准闭环：

1. 明确一个最小目标  
   例如“让 USART1 打印 BOOT OK”“让 LED0 按 1Hz 闪烁”“读取 W25Q128 ID”“按键按下打印事件”。

2. 明确当前证据  
   读取接口表、需求、手册摘录、现有代码和编译日志，说明依据。

3. 只做最小改动  
   修改最少文件、最少逻辑。不要顺手重构无关模块。

4. 编译或静态检查  
   能编译就编译；不能编译要说明缺什么工具链。

5. 给出板端验证步骤  
   明确人要观察什么：串口输出、LED、波形、电压、继电器动作、温升。

6. 等待反馈再进入下一轮  
   没有反馈前，不要继续叠加更多功能。

输出格式：

```markdown
## 本轮最小目标
- ...

## 修改范围
- ...

## 验证方法
- 编译:
- 上板:
- 期望现象:

## 需要人工反馈
- ...

## 下一轮候选
- ...
```

## 架构规则

- `main.c` 只做初始化、tick 消费、周期任务调度。
- `driver` 只表达 MCU 外设机制。
- `bsp` 表达板级含义：引脚、有效电平、安全默认态、硬件资源。
- `component` 必须产品无关。
- `app` 模块负责产品行为。
- `app_workflow` 负责跨模块编排。
- 私有全局变量和私有函数优先使用 `static`。
- 避免失控的全局变量和隐藏跨模块依赖。
- ISR 中不要阻塞，不做复杂耗时逻辑。
- ISR/main 或多任务共享数据必须考虑临界区、锁、队列或原子访问。
- 检查错误码、超时、部分读写、缓冲区边界。

## 安全规则

- 危险输出必须先初始化到安全状态，再使能外设。
- 继电器、电机、加热、阀、高压 PWM、电源使能在未验证前不得带真实负载冒进测试。
- 首次验证危险输出时，优先空载、断开功率级、限流电源或示波器测信号。
- AI 不得声称“硬件已验证”，只能说“代码已编译/逻辑已检查/建议这样验证”。
- 需要板端观察时，明确告诉工程师要看什么。

## 编译修复闭环

1. 有构建命令就运行。
2. 完整读取错误和日志。
3. 按根因分组。
4. 修改最小责任范围。
5. 重新构建。
6. 记录改动原因。

同类错误反复出现时，不要盲改，先检查工程文件、include 路径、生成文件、宏、链接脚本和工具链配置。

## 硬件反馈格式

需要工程师反馈现象时，要求使用：

```markdown
## 现象
- 上电行为:
- 串口输出:
- 指示灯/屏幕/继电器/电机:
- 测量值/波形:
- 是否发热/异响/过流:

## 复现步骤
1. ...

## 期望行为
- ...
```

## 常见任务的最小目标示例

- GPIO/LED：只验证一个引脚能按安全电平翻转。
- UART：只验证启动打印和回显，不同时加入完整协议。
- I2C：只扫描/读取一个器件 ID 或固定寄存器，不先写复杂业务。
- SPI Flash：只读取 JEDEC ID，不先写擦除。
- PWM：先空载输出低频低占空比波形，不直接接功率负载。
- ADC：先读取固定通道原始值和参考电压，不先做复杂滤波。
- 参数存储：先读默认值和 CRC 校验，不先写入真实生产参数。
- OLED/UI：先显示一行固定文本，再做菜单和按键导航。
- 协议解析：先解析一帧固定样例，再接真实串口流。

## 常见坑

- 代码能编译，但上电不安全。
- 有效电平猜错，继电器或负载误动作。
- 一轮改动太大，无法判断哪个修改引入问题。
- 产品行为没定义清楚，导致代码反复改。
- 小屏 UI 代码逻辑正确，但布局和体验不对。
- 构建、下载、反馈通道没稳定就追求全自动。