AI 代码日志全是废话？嵌入式日志规范与调教技巧

AI 辅助嵌入式编程最容易踩的坑：AI 写代码快，但它也擅长制造日志污染。AI 打印的日志可能比较随意，甚至不加打印。

这时候如果我们要人工分析日志，因为日志打印得比较随意，很可能分析不出原因。

可能有人会说：AI 时代，把抓到的日志再喂给 AI，让 AI 分析不就行了。

这当然可行。

但日常开发中，可能还会遇到这种情况：某个突发问题很着急，从问题路径看应该是个比较简单的问题，日志就在目标机上，身后还围着一群人在看你分析日志。

这种情况，能通过简单看下日志就能分析出来的问题，就不用总是跟 AI 老师来回拉扯了。AI 能辅助提效，大部分场景它确实比人快，但并不是所有场景都比人快。

比如某个数据显示有问题、必现问题，这种就是很简单的问题。

• 使用 AI 进行问题分析：得清晰地向 AI 描述问题现象及细节。组织提示词 + AI 思考分析返回结果，整个流程可能要花费 10 分钟。如果 1 次分析结果不对，还得继续补充信息，来回拉扯。
• 人工进行问题分析：只需要筛选 1~2 个日志关键字，基本就可以锁定问题所在。这个流程可能也就 2 分钟。

所以我们让 AI 生成的代码，不仅代码要严谨、健壮、设计清晰、易维护，还需要让 AI 打印清晰且必要的日志，这样人工分析日志时才能很快定位到问题原因。

本文要分享的，就是怎么让 AI 打印的每一条日志都有价值，让日志真正变成能定位问题、闭环诊断的工具。

1. AI 的日志风格

AI 的日志风格，本质上叫防御性日志。

如果没有特别说明，它可能不知道我们的 MCU 主频、波特率、Flash 容量，更不在乎 ISR 里能不能打印。

它只是保守地把发生了什么打出来，越多越好。

但在嵌入式场景里，这会带来三个真实伤害：

• 浪费资源。Flash 存储空间、CPU 时间、串口带宽，全被无意义的日志吃掉。
• 破坏实时性。在 ISR 里裸 printf，轻则丢数据，重则看门狗复位。
• 刷屏掩盖关键行。真正重要的异常信息早就被冲到上一屏。

所以问题不是要不要日志，而是什么样的日志才配被打印出来。

2. 一条有价值的日志长什么样？

一条日志必须能回答五个问题：

这几个字段缺了任何一个，这条日志的价值就要打折扣。

没有时间戳，就无法对齐时序；没有事件码，就没法 grep；没有上下文数据，就只能猜。

3. 把这套规则直接喂给 AI

AI 不会主动遵守规则，除非我们把规则写进它的上下文里。

下面是我实际使用的 Prompt 模板，大家可以直接复制进 Cursor / Claude / Codex 的系统提示或项目规则文件里：

你是一名嵌入式 C 工程师。本项目要求日志必须遵循以下规则，违反任何一条都不允许输出：

1. 统一使用 LOG_ERR / LOG_WARN / LOG_INFO 宏，禁止裸 printf。
2. 日志格式固定为：[时间戳][级别][模块][事件码] 上下文数据
3. 时间戳由宏自动注入，代码里不要手写时间。
4. 所有事件必须使用 EVT_ 开头的枚举，如 EVT_CHARGE_TIMEOUT。
5. ISR 中只允许使用 LOG_ERR，且必须先写 ring buffer，不能裸打印。
6. 正常执行路径默认不打日志；只在错误路径、状态迁移、外部边界处打日志。
7. 每条日志必须包含“能拿来定位问题”的关键变量和当前状态。

如果某条日志不满足以上条件，请删除它或重写它。

把这个规则放进项目上下文之后，AI 生成代码的日志质量会明显不同。

4. AI 该在哪打日志？

规则有了，但位置不对，日志依然会变成噪音。

ISR 里只留证据，错误路径必留痕，状态迁移全记录，正常路径别吱声。

• ISR：绝对不打日志，只写 ring buffer 或置标志位。
• 驱动层：只在 SPI/I2C/UART 失败时打 ERR，记录错误码和重试次数。
• 协议解析层：只在帧头/CRC/长度异常时打 ERR，记录异常位置和原始字节。
• 业务状态机：每次状态迁移都打 INFO，记录"旧状态 → 新状态 + 触发原因"。
• 外部交互边界：进出边界各一条，记录耗时、结果、数据量。

把这些信息扔给 AI，它就知道了该在哪里打日志。

5. 没有规则 vs 有规则限制

没有规则时，先看看 AI 生成的日志大概如：

这是典型 AI 日志：每条 log 都在描述自己在干嘛，但没有一条能帮我们诊断。

有规则限定的版本：

改造后的日志输出，一眼就能看出设备在哪、出了什么事、该修哪：

关键变化：

• 删除了进入函数、退出函数等无意义日志。
• 状态迁移记录了旧状态、新状态和触发原因。
• 错误路径记录了关键变量和当前状态。
• 正常分支一句话都没说。

6. 让 AI 自己当"日志审计员"

有时候我们已经让 AI 写好了代码，但不知道日志有没有问题。这时候可以让 AI 反过来审查。

用这个 Prompt：

请审查下面这段嵌入式 C 代码中的日志，按以下标准给出审计结果：
1. 是否存在裸 printf？
2. 是否每个事件都有 EVT_ 枚举？
3. 是否在 ISR 中裸打印？
4. 是否记录了足够的关键变量和状态？
5. 正常分支是否被过度打印？

请输出：
- 需要删除的日志行（说明原因）
- 需要补充的日志行（说明应添加的字段）
- 需要修改级别的日志行（说明理由）

7. 把日志回灌给 AI，做闭环诊断

日志不只是给人看的，也可以喂回给 AI。

当设备出问题，我们拿到的可能是这样一段 log：

把这段日志贴给 AI，并追加一个诊断 Prompt：

设备在充电过程中报错，以上是串口日志。请根据事件码、状态迁移和上下文数据，分析最可能的根因，并给出下一步验证建议。

因为日志结构清晰，AI 的诊断会出奇地准确。

这就是结构化日志 → AI 诊断的闭环。

8. 总结

AI 不会天然理解嵌入式 C工程师的调试习惯。它只会写它见过的、最安全的、最啰嗦的代码。

真正值钱的能力，不是让 AI 帮你多写代码，而是让它写对代码。

日志就是其中最容易被忽视、但最能体现工程质量的一环。把规则及位置约束给它，让它打印的每一条日志，都是有效清晰的日志。

你项目里有没有被 AI 的日志刷屏到崩溃的经历？