grounding-before-coding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Grounding before coding

编码前的摸底调研

REQUIRED BACKGROUND: the

principal-engineering

skill.

必备背景知识：

principal-engineering

技能。

Overview

概述

Before writing a spec, a fix, or a first line: map the real code and data. Quote

file:line

. Run the query. The cost of grounding is minutes; the cost of building on a wrong belief is the whole change plus the incident it causes.

在编写规格说明、修复方案或第一行代码之前：梳理真实的代码和数据。引用

文件:行号

。执行查询。摸底调研仅需花费数分钟，但基于错误判断进行开发的代价却是整个变更工作加上其引发的事故。

The discipline

核心准则

Read the implementations, not the names. A method called
```
validate
```
that does not validate is common enough to be the default assumption. Verify what a thing does before building on what it is called.
Quote your evidence. Every load-bearing claim in your plan gets a
```
file:line
```
, an exact query result, or a command output. A claim you cannot back gets said out loud as unbacked, not silently assumed.
Never guess conventions. How this repo names things, wires dependencies, handles errors, or runs tests is discoverable in minutes. Guessing conventions is how changes arrive that are correct in isolation and wrong in the codebase.
Trust code, not status. A document's or ticket's self-reported state is not evidence of execution state; adjudicate with the code and the history (
```
git log -S <symbol>
```
, grep the tree) before building on it. Measured on one real backlog import, roughly half the self-reported statuses were stale.
Reproduce before fixing. For bugs: see the failure happen before changing anything. A fix for an unreproduced bug is a guess wearing a diff.
Look for the landmines. The output of grounding is a map: the touchpoints, the current behavior (quoted), and the invariants a change must not break. Tests named after old bugs, guards with explanatory comments, and constants encoding hard-won thresholds are the scars that mark where the landmines were.

关注实现逻辑，而非命名。 名为
```
validate
```
却不执行验证逻辑的方法十分常见，这应是默认的预判。在基于命名开展工作前，务必先确认其实际功能。
引用实证依据。 计划中每一个核心论断都需附上
```
文件:行号
```
、精确的查询结果或命令输出。对于无法提供依据的论断，需明确指出其缺乏支撑，而非默认其成立。
绝不猜测约定俗成的规则。 代码库的命名规则、依赖注入方式、错误处理逻辑或测试运行方式，都能在数分钟内查明。猜测规则会导致变更在孤立场景下可行，但在整个代码库中却存在问题。
信任代码，而非状态标识。 文档或工单的自我声明状态并非实际执行状态的依据；在基于此开展工作前，需通过代码和历史记录（如
```
git log -S <symbol>
```
、全局grep）进行确认。在一次真实的待办事项导入测试中，约有一半的自我声明状态已失效。
先复现问题，再进行修复。 对于Bug：在进行任何修改前，先复现故障。针对未复现Bug的修复，本质上只是披着代码差异外衣的猜测。
排查潜在隐患。 摸底调研的产出是一份“地图”：包含变更涉及的关联点、当前的实际行为（带引用），以及变更不得破坏的不变规则。以旧Bug命名的测试、带有解释性注释的防护逻辑，以及记录着来之不易的阈值的常量，都是标记潜在隐患位置的“伤疤”。

What grounding is not

摸底调研的边界

Not reading everything: map what the change touches plus one ring around it, at the depth the risk demands.
Not a substitute for asking: when the code cannot answer an intent question (why is this threshold 7?), the history or the owner can; an unanswerable question becomes a named assumption, never a silent one.
Not re-grounding what this session already established: ground once, cite it after.

并非通读所有内容：仅梳理变更涉及的范围及其周边关联部分，深度取决于风险程度。
并非替代沟通：当代码无法回答意图类问题（如“为什么这个阈值设为7？”）时，可查看历史记录或询问代码所有者；对于无法解答的问题，需明确将其列为假设，而非默认其成立。
无需重复调研已确认的内容：只需调研一次，后续直接引用即可。

Common mistakes

常见误区

Theorizing from the framework's documentation about what the project's code does. The project forked, wrapped, or misused the framework; the tree tells you which.
Grounding the happy path only. The invariants live in the error paths and the edge-case guards.
Trusting a prior session's summary of the code over the code. Summaries route; the tree decides.
Skipping grounding because the task "looks like" a previous one. The signal that pattern-matches a known case may have a different cause; check that the evidence supports this case.

基于框架文档推断项目代码的行为。项目可能对框架进行了分叉、封装或误用，代码本身会告诉你实际情况。
仅调研正常流程。不变规则往往存在于错误处理流程和边界条件防护逻辑中。
信任之前的代码总结而非代码本身。总结仅作指引，代码才是最终依据。
因任务“看似”与之前的类似而跳过调研。看似匹配已知场景的信号可能有不同的成因，需确认实证是否支持当前场景。