[scottlamb]

Yuck.

The attitude I like to have is that the author can choose to do the design (doc + approval, or live discussion, some kind of buy in) first or go straight to the PR.

If the design is agreed on first, reviewers would need a really good reason to make the author go back and rethink the design—it happens, sometimes a whole team misses something, but it should be very rare. Usually, there's just implementation things, and ones that are objective improvements or optional. (For project style preferences, there should be a guide to avoid surprises.)

If the author goes straight to a PR, it's an experiment, so they should be willing to throw it away if someone says "did you think about this completely different design (that might be simpler/more robust/whatever)".

This is not the approach suggested by this article, and I'm okay with that. I tend to work on high reliability infrastructure, so quality over velocity, within reason.

[dfee]

I like this - and I think it’s a natural reality. When trust is low (for many reasons, including joining a new team), it may reduce risk to start with a design doc.

[scottlamb]

There are a lot of reasons anyway I like to have the design doc around. A few:

* I think the designs are often better when people write down their goals, non-goals, assumptions, and alternatives rather than just writing code.

* Reading previous designs helps new people (or even LLMs I guess) understand the system and team design philosophy.

* It helps everyone evaluate if the design still makes sense after goals change.

* It helps explain to upper management (or promotion committee in a large company) the work the author is doing. They're not gonna dig into the code!

...so it's usually worth writing up even if not as a stage before implementation starts. It can be a quick thing. If people start using a LLM for the writing, your format is too heavy-weight or focused on style over substance.

There's definitely a negative side to approval stages before shipping, as this article points out, but when quality (reliability, privacy/security, ...) is the system's most important attribute, I can't justify having zero. And while getting the design approved before starting implementation isn't necessary, it should avoid the bad experience tombert had of having to redo everything.