Probes 使用最佳实践

Probes 更适合处理目标清晰、上下文充分、可以验证的工程任务。开始一次对话前，先说明目标、现象、允许动作和成功标准，通常比一句宽泛的“帮我看看”更容易得到可落地的结果。

1. 先让 Probes 理解项目

首次打开一个项目时，建议先让 Probes 阅读当前 VS Code 工作区，梳理工程结构、构建入口和关键文件。不要一开始就要求它大范围修改代码。

请先阅读当前项目，不要修改文件。
请总结项目结构、主要构建方式、关键源码目录，以及你建议我优先提供哪些上下文。

确认 Probes 对项目有基本理解后，再进入具体问题。

2. 把任务写成可验证的问题

一次高质量任务通常包含这些信息：

• 想完成什么
• 当前观察到什么
• 相关文件、日志或截图
• 允许 Probes 做什么
• 暂时不要做什么
• 什么结果算成功

示例：

我想定位 USART1 没有输出日志的原因。
当前现象是烧录后串口没有任何输出，波特率 115200 8N1。
请先检查启动文件、时钟初始化、GPIO 和 USART1 初始化代码。
这一轮只分析原因和验证步骤，不要修改代码。
成功标准：给出最可能的 1 到 3 个原因，并说明每个原因如何验证。

3. 复杂任务先要方案

当任务涉及多个文件、构建、烧录或硬件调试时，建议先让 Probes 给出计划。确认计划合理后，再允许它修改代码或执行命令。

请先给出排查方案和修改计划。
计划中需要包含：要读取的文件、判断依据、可能修改的范围、构建命令和硬件验证步骤。
在我确认之前，不要修改文件。

这样可以避免任务范围过早扩大，也方便您判断 Probes 的方向是否正确。

4. 明确允许动作和边界

Probes 可以读取工作区、分析代码、修改文件、运行命令或整理验证步骤。是否允许这些动作，建议在任务里直接说清楚。

你可以读取并修改 `drivers/uart` 相关文件，可以运行构建。
不要修改板级引脚定义以外的模块。
修改后请说明改动文件、构建结果和下一步硬件验证方式。

如果您只想先分析，不希望修改文件，可以明确写：

这一轮只分析原因和下一步验证方式，不要修改文件。

5. 用真实证据闭环

嵌入式任务不能只根据代码推断结果。涉及硬件行为时，请尽量提供真实证据：

• 构建日志
• 串口日志
• 调试变量
• 示波器或逻辑分析仪截图
• 芯片手册或板卡资料
• 烧录和复测结果

没有真实证据时，可以要求 Probes 明确区分“代码侧已确认”和“仍需硬件验证”。

6. 修改代码前先保存版本

在让 Probes 修改代码前，建议先确认 Git 状态，并保存一个可回退版本。

请先检查当前 Git 状态，并建议我在修改前如何保存当前版本。
暂时不要修改文件。

完整操作方式见 使用 Git 管理代码版本。

7. 一次对话只处理一个主题

如果一个对话里混入太多无关问题，Probes 可能会被旧上下文干扰。建议：

• 一个硬件现象对应一个任务。
• 一个 bug 修复完成后再开始下一个。
• 需求变化较大时，新开对话并重新说明目标。
• 多次修正仍不收敛时，总结已知信息后重新开始。

8. 常见低效写法

写法	问题	更好的写法
帮我看看为什么不行	范围太大，没有目标	请定位 cmake --build build 的链接错误
直接修好这个工程	目标不可验证	先让串口 boot 日志恢复输出
你随便改	风险太高	只修改 USART 初始化相关文件
看完整个项目	上下文噪声太多	先看 Core/Src、Drivers 和构建配置
应该已经好了吧	缺少证据	请根据构建日志和硬件现象说明验证结论

9. 推荐任务模板

我想完成什么：

当前观察到什么：

相关文件、日志或截图：

你可以做什么：

请先不要做什么：

成功标准：

修改后请输出：
1. 根因判断
2. 修改文件
3. 构建或验证结果
4. 仍需我在硬件上确认的步骤

按照这个方式使用 Probes，可以让每一次代码修改都有清晰边界、验证路径和复盘结果。