Design before implementing

If I could say only one thing about how I work, it would be this: I think the whole problem through before writing the first line.

In practice that means a numbered specification versioned alongside the code before implementing; industry standards instead of my own invention, with error handling following RFC 9457 and the public suite in canonical Clean Architecture; and tests and declarative validation as the definition of done, not as a consequence. Of the abstractions that came out of this work, part was generalized and published as packages. See PMQ Suite.

How this works in practice

The specification comes numbered and versioned with the code: the problem, the research on what already exists, the plan and the task list. It is not a ceremonial document. It is where the hard decisions are made while they are still cheap to change.

It has a second reader: this specification is what the agent executes, with the tooling described in AI engineering.

What I look for in this phase:

• What the real problem is, not the request. The request usually already comes with a solution built in, and it is almost never the best one
• What already exists that solves it, in the landscape, in the ecosystem or as a published standard
• Where the thing will hurt in two years: the point that will become debt, and whether it can be avoided cheaply now
• What stays out, explicitly

Why it is not slowness

The obvious objection is that this delays things. In my experience it is the reverse, because the time spent on the specification comes back as decisions that do not need to be redone. The industrial monitoring is the example: treating offline operation as a requirement, and not as a feature to add later, changed the client’s whole architecture. Discovered in the design phase, it cost a conversation. Discovered later, it would have cost the rewrite.