Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

在合入前，找出改动会在别处弄坏什么。用于「X 的 blast radius」「这会弄坏啥」，或你还不信的小 diff。

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.

和 how、why 配套。how 说代码做什么；why 说为什么长成这样；blast radius 说它会在别处弄坏什么。

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.

列调用方不是本职。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.

  6. 你嘴上这么说。单靠这个没用。

  7. 你指到了那一行。真实的 file:line，或库自己的源码。

  8. 你证明坏情况到不了。逐步走失败路径，到不了。

  9. 你跑过了。脚本或测试调用真实代码，错了会大声失败。

  10. 你在正在跑的应用里复现了。

Step 4 is usually one small script that imports the same library the app ships and calls the exact function you’re worried about.

Step 4 通常就是一小段脚本：import 应用同样那份库，调用你担心的那个函数。

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.

  7. 读改动。diff、增改删的符号、现在行为哪里不同（含 diff 没写明的部分）。用 why 的 step 2 拉 PR 和 commits。

  8. 找出「因为这条事实所以安全」的那一条。多数看起来危险的改动，其实靠一条事实就安全，比如「这次调用只删已死的 cache 条目，别的什么都不做」。找到它；成立的话，多数风险一次清掉。时间花在这，别堆一长串 maybe。

  9. 看 grep 停在哪。读你调用的库源码，核对 pinned 版本和本地 patch。搞清何时执行：microtask、unmount/teardown、Solid vs React。追符号搜索漏掉的：API 返回的 JSON、DB 列、wire format、另一门语言读同一段字节、feature flag、下游三跳处的代码。

  10. 对每条风险诚实。给真实发生概率和真实代价。保留已确认的风险；已核查并排除的单独列。规则同 why。引用真实 file:line；搜不到也是答案；绝不编造 caller 或 API。

  11. 证明那条关键事实。写脚本或测试跑真实代码，跑完，贴结果。

  12. 大改或面广的改动，按 arena 跑：多个模型问同一题，合并答案。不同模型会抓到不同的真 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.

  • 它做了什么。 改了啥，含不明显的部分。

  • 因此安全的那条事实。 说清楚，到了上面哪一级，并给出证明。证不了就写 unproven。

  • 风险。 每条写清怎么坏、file:line、多可能、多严重、怎么查。要紧的贴证明。

  • 已排除。 查了什么、为什么没事。

  • 合入前。 能抓住真 bug 的最便宜测试或复现，含你写的脚本。

Write it through unslop, cite real code, and strip anything private before it goes anywhere public.

经 unslop 写出来，引用真实代码；公开前剥掉一切隐私。

Reply: the writeup above, with the one safety fact either proven or marked unproven.

回复： 上面那份报告，那条安全事实要么已证明，要么标成 unproven。