grounding-before-coding

编码前先摸清实际情况

必备背景：principal-engineering 技能。

概述

在编写规范、修复方案或第一行代码之前：先梳理实际的代码和数据。引用 file:line，并运行每个所依据数字背后的查询。

这套纪律

1. 阅读实现，而不是只看名称。 默认认为名为 validate 的方法实际上并未进行验证。先确认事物的实际作用，再依据它的名称开展工作。
2. 引用证据。 计划中的每个关键主张都要附上 file:line、精确的查询结果或命令输出。无法支撑的主张要明确说明，不要想当然。
3. 绝不猜测惯例。 这个仓库如何命名、连接依赖、处理错误或运行测试，几分钟内就能查明。
4. 相信代码，不相信状态。 文档或工单自述的状态不能证明实际执行状态；在此基础上开展工作之前，要结合代码和历史记录（git log -S <symbol>、搜索整个代码树）进行判断。
5. 修复前先复现。 对于 Bug：先观察故障发生，再做任何更改。
6. 在调用路径汇合处修复。 Bug 报告会指出某条路径上的一个症状；编辑之前，先找出所有进入你将要修改代码的路径。如果缺陷存在于共享代码中，防护逻辑就应放在共享位置：这样改动更小，也能修复工单未提及的其他相关路径。只修补报告所提到的路径，修复的是报告，而不是 Bug。
7. 梳理改动不得破坏的不变量。 探查结果应是一张地图：涉及的触点、当前行为（附引文）以及相关不变量。以旧 Bug 命名的测试、带有解释性注释的防护逻辑，以及记录来之不易的阈值的常量，都标示着过去发生过的问题。

探查的边界

• 不必通读所有内容：根据风险所需的深度，梳理改动涉及的部分及其一层相关代码。
• 探查不能代替提问：当代码无法回答意图问题（为什么这个阈值是 7？）时，可以查阅历史记录或询问负责人。无法回答的问题要明确列为假设，绝不能默默带过。
• 不要重复探查本次会话已经确认的内容：探查一次，之后引用即可。

常见错误

• 根据框架文档推断项目代码的行为。项目可能分叉、封装或误用框架；以代码树为准。
• 只探查正常路径。不变量往往藏在错误路径和边界条件防护中。
• 相信先前会话对代码的总结，而不核对代码。开始工作前，先打开总结中提到的文件。
• 因为任务“看起来”像之前做过的任务就跳过探查。与已知案例匹配的信号可能有不同原因；请检查证据是否支持当前案例。