Back to Details

blast-radius

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Blast radius

Blast radius（影响范围）

Find what a change breaks somewhere else, before it ships. Use for "blast radius of X", "what could this break", or reviewing a small diff you don't trust yet.
Companion to 
how
and 
why
. 
how
tells you what the code does. 
why
tells you why it's shaped that way. Blast radius tells you what it breaks somewhere else.
Listing the callers is not the job. The agent can grep those in a second. The job is the breakage grep won't show you.
在变更发布之前，找出它会在其他位置破坏什么。适用于“X 的影响范围”“这可能破坏什么”，或审查你目前还无法信任的小型 diff。
它是 
how
和 
why
的配套方法。
how
告诉你代码做什么；
why
告诉你它为何采用这种结构；Blast radius 则告诉你它会在其他位置破坏什么。
仅列出 caller 并不是任务本身。agent 只需一秒钟就能用 grep 找到它们。真正要找出的是 grep 无法显示的破坏性问题。

Don't trust your own writeup

不要相信自己的书面分析

A blast-radius writeup that sounds right is worthless. It reads as convincing whether or not it's true. So don't hand back the writeup. Find the one or two facts the whole thing depends on and prove them by running code.
一份听起来合理的 blast-radius 书面分析毫无价值。不管真假，它读起来都很有说服力。因此，不要只交回这份分析。找出整个结论所依赖的一两个事实，并通过运行代码来证明。

How sure are you

你的证据有多充分

For each fact the change's safety depends on, get it as far down this list as is cheap, and say where it stopped.
  1. You said so. Worthless on its own.
  2. You pointed at the line. A real 
    file:line
    , or the library's own source.
  3. You showed the bad case can't happen. You walked the failure step by step and it doesn't reach.
  4. You ran it. A script or test that calls the real code and fails loud if you're wrong.
  5. You reproduced it in the running app.
Step 4 is usually one small script that imports the same library the app ships and calls the exact function you're worried about.
对于变更安全性所依赖的每个事实，尽可能以低成本推进到下面清单的更高级别，并说明证据止于哪一级。
  1. 你只是这么说过。单独来看毫无价值。
  2. 你指出了具体行。真实的 
    file:line
    ，或所调用 library 自己的 source。
  3. 你证明了坏情况不会发生。你逐步走查了失败路径，发现它到不了该处。
  4. 你实际运行了它。某个 script 或 test 会调用真实代码，一旦你错了就会明确报错。
  5. 你在运行中的 app 中复现了它。
第 4 级通常只需编写一个小 script，import 应用发布时使用的同一个 library，并调用你担心的那个确切函数。

Steps

步骤

  1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Use 
    why
    step 2 to pull the PR and commits.
  2. Find the one fact it's safe because of. Most changes that look risky are safe because of a single fact, like "this call only drops already-dead cache entries and does nothing else". Find that fact. If it holds, most risky cases are cleared at once. Spend your time here, not on a long list of maybes.
  3. Look where grep stops. Read the source of the library you call, and check its pinned version and any local patch. Work out when things run: microtasks, unmount and teardown, Solid versus React. Follow what a symbol search misses: the JSON an API returns, a DB column, a wire format, another language reading the same bytes, a feature flag, code three hops downstream.
  4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed. List the ones you checked and cleared separately. Same rules as 
    why
    . Cite a real 
    file:line
    , a search that finds nothing is still an answer, and never make up a caller or an API.
  5. Prove the one fact. Write a script or test that runs the real code, run it, and paste what happened.
  6. For a big or wide change, run it as an 
    arena
    . Ask several models the same question and merge the answers. Different models catch different real bugs.
  1. 阅读变更。查看 diff、它新增、修改和删除的 symbols，以及它现在的行为有哪些不同，包括 diff 没有明说的部分。使用 
    why
    的步骤 2 获取 PR 和 commits。
  2. 找出它之所以安全所依赖的那个事实。大多数看似有风险的变更，都是因为某个单一事实而安全的，例如“这个调用只会删除已经失效的 cache 条目，不会做其他事情”。找出这个事实。如果它成立，大多数看似有风险的情况就会同时被排除。把时间花在这里，而不是列出一长串可能的问题。
  3. 看看 grep 会止步的地方。阅读所调用 library 的 source，检查其 pinned version 和任何 local patch。弄清楚这些逻辑何时运行：是在 microtasks 中、在 unmount 和 teardown 阶段，还是受 Solid 与 React 差异的影响。追踪 symbol 搜索会遗漏的东西：API 返回的 JSON、DB column、wire format、由另一种语言读取相同字节的代码、feature flag，以及下游三跳处的代码。
  4. 如实评估每项风险。给它一个真实的发生可能性和真实的代价。保留已经确认的风险。把你检查过并排除的风险单独列出。规则与 
    why
    相同。引用真实的 
    file:line
    ；一次什么都没找到的 search 仍然是答案；绝不编造 caller 或 API。
  5. 证明那个关键事实。编写一个运行真实代码的 script 或 test，执行它，并粘贴实际发生的结果。
  6. 对于大型或影响范围很广的变更，将其作为 
    arena
    运行。向多个 model 提出同一个问题并合并答案。不同 model 能捕获不同的真实 bug。

What to hand back

应当交付的内容

  • What it does. What changed, including the part that isn't obvious.
  • The one fact it's safe because of. State it, say which step you got it to, and show the proof. If you couldn't prove it, write unproven.
  • Risks. Each names how it breaks, the 
    file:line
    , how likely and how bad, and how to check. Paste the proof for the ones that matter.
  • Cleared. What you checked and why it's fine.
  • Before you merge. The cheapest test or repro that catches the real bug, including the script you wrote.
Write it through 
unslop
, cite real code, and strip anything private before it goes anywhere public.
Reply: the writeup above, with the one safety fact either proven or marked unproven.
  • 它做了什么。 变更了什么，包括其中不明显的部分。
  • 它之所以安全所依赖的那个事实。 陈述该事实，说明你将证据推进到了哪一级，并展示 proof。如果无法证明，就将其标记为 
    unproven
    。
  • 风险。 每项风险都要说明如何造成破坏、对应的 
    file:line
    、发生可能性和严重程度，以及如何检查。对重要风险粘贴 proof。
  • 已排除。 你检查了什么，以及它为什么没有问题。
  • 合并之前。 能捕获真实 bug 的最低成本 test 或 repro，包括你编写的 script。
使用 
unslop
成文，引用真实代码，并在内容流向任何公开渠道前移除所有私密信息。
回复： 上述书面分析，其中那个安全性事实要么已经得到证明，要么被标记为 
unproven
。