”Just one small change”#

The mother of all requirement jokes; every other bit is a variation on it.

Its lethality comes from an asymmetry: the person making the request can only see the interface, not what’s behind it. What they see is a table gaining a column; what they don’t see is how many APIs read that table, how many jobs join it, whether there’s caching, whether there’s an export, whether someone is building reports on it.

So the judgment “small change” is completely correct within the information they have. What’s wrong isn’t their judgment—it’s their visibility.

”Just build one like Taobao”#

The full version of this sentence is usually: “It doesn’t need that many features, just build one like Taobao, start with something simple.”

The problem isn’t how much work “build one like Taobao” is—it’s that “doesn’t need that many features” is a statement that cannot be used for acceptance. The acceptance criteria live in the requester’s head and only materialize when they’re standing in front of the finished product. So the project marches precisely to that classic moment: the thing is done, and the requester says “this isn’t what I wanted.”

Translated into engineering language, this sentence actually means: “I don’t have a requirements document, but I know you did it wrong."

"You start building, and once it’s done I’ll know what I want”#

This sounds like a cop-out, but it describes the true shape of requirements.

Requirements aren’t a list sitting somewhere waiting to be collected; they’re more like a physical quantity that can only be measured by observation—users don’t know what they don’t want until they see something. The entire theoretical basis of prototyping is this one sentence.

The real problem isn’t this sentence—it’s that after saying it, there’s no next step: no walkthrough, no feedback checkpoint, no written agreement that “this version is not the final acceptance.” That turns it into a gamble with no guardrails.

”A rainbow of black”#

A legendary moment in the design world, usually accompanied by “make the logo bigger and smaller at the same time” or “make this font look more premium.”

Its relationship to programmers is this: it’s just another form of “add a field.” The requester is describing a feeling, while the implementer needs a set of parameters. Feelings can’t be compiled directly, and when nobody claims the translation work in between, it becomes a back-and-forth tug of war.

”This is simple, right? Just add a button”#

Adding the button itself is indeed simple. What’s not simple is everything that happens after the button is pressed—especially when nothing should happen after it’s pressed (insufficient permissions, conditions not met). That part usually isn’t written into the requirements, but someone has to write it.

”The requirements haven’t changed, I just added a clarification”#

This is the most dangerous line in the entire collection.

The previous five just make the timeline longer; this one makes the timeline impossible to commit to. Because “clarification” means the boundary of the requirement is open: any verbal addition can be retroactively claimed as “that’s what I meant all along.”

It has an even more insidious form: the change doesn’t disappear, it just moves from the meeting to a private chat. Three months later, looking back at git log, there’s no record explaining why this feature ended up the way it did.

1. The three blast-radius questions#

Don’t answer “how long” directly. Ask three questions first—at this point, “I don’t know” is the professional answer:

• Which piece of data is changing? Find that table, that field, then see who reads it.
• Whose behavior changes? Just the internal admin panel, or can external users see it?
• How do we verify it works? A change with no acceptance method is a change with no finish line.

Make it a habit: after every verbal change, go back and add a line to the ticket. One sentence is enough, like “2026-09-26 addendum: list must be sorted by last login time descending.” This isn’t process ritual—it’s the only archaeological evidence three months from now.

2. Making changes cheaper: expand-contract#

“Renaming a field” is a death sentence in the traditional approach because it must be done all at once—change the code, change the database, deploy simultaneously. Expand-contract (also called parallel change) breaks it into three steps, each of which can be deployed and rolled back independently:

1
--Step 1 expand: only add, don't modify, don't delete. Old code still runs
2
ALTER TABLE users ADD COLUMN full_name VARCHAR(100);  --MySQL 8.0.12+ can be INSTANT
3

4
--The application layer enters a dual-write period: when writing name, also write full_name; reads still read name

1
--Step 2 migrate: backfill historical data in batches
2
--The key is LIMIT + looping, don't let a single UPDATE lock the entire table
3
UPDATE users SET full_name = name
4
WHERE full_name IS NULL
5
ORDER BY id
6
LIMIT 1000;

1
--Step 3 contract: switch reads to full_name, observe for one to two release cycles, and confirm no one is writing to the old column
2
--Only then delete
3
ALTER TABLE users DROP COLUMN name;

The value of the three steps isn’t technical sophistication—it’s that it turns one “big bang” into three rollback-able small operations. If anything goes wrong at any step, just revert; no need for “the whole team pulls an all-nighter + prays.”

The same approach applies to APIs: add the new field first (expand), let all callers migrate (migrate), confirm the old field has no users, then remove it (contract). This is also why “adding fields is easy, removing fields is hard”—adding happens in the expand phase, removing happens in the contract phase, with an entire migration period in between.

3. Using flags to decouple “deploy” and “release”#

A feature is half-written, and the requester says “let’s ship half and see.” Fight it with branches, and you’ll end up with a feature/new-list-v2 branch that’s been alive for three months and an afternoon where every merge feels like defusing a bomb.

With a flag it’s much simpler:

1
if (flags.enabled('show-last-login', { userId })) {
2
  renderLastLogin(user);
3
}

The code can be merged into main first (deployed but not active), then rolled out by whitelist (canary), then fully—or turned off at any time. “Deploy” and “release” become two independent actions, which is one of the cheapest ways to make changes cheaper.

The cost is that flags accumulate. So every flag should have a deletion date, otherwise three years later you’ll have an archaeological site of two hundred if that nobody dares touch.

4. Freeze windows, and “break big changes into small ones”#

Not accepting new requirements the day before a release isn’t bureaucracy—it’s risk management. The cost of big changes isn’t the average, it’s the tail. If a change absolutely must go in before release, break it into several small changes and ship them separately.

The reverse also holds: if a change can’t be broken down, it’s probably not a “small change.” That sentence itself is a great phrase for requirement reviews.

5. Replace documents with something that runs#

The solution to requirement ambiguity isn’t writing longer documents (nobody reads them)—it’s giving something clickable as early as possible. An ugly prototype that runs can expose in ten minutes ambiguities that would take three months to surface in a document.

This is also compressing that change cost curve: moving the moment of “discovering something needs to change” from the coding phase to the prototyping phase.