The industry is selling you a pretty convincing story about AI coding assistants.
Give them a two-line requirement, they say, and AI will take care of the rest: architecture, code, tests, the lot. But what happens when generating code becomes faster than understanding what that code is actually doing?
If you’re a software engineer trying to spend less time fighting AI hallucinations and more time building reliable, predictable workflows, this issue is for you.
Hey! As you know, I’m trying out a new format for the newsletter, and I’d love to hear what you think about it! Please take just 1 minute to complete this short survey.
In today’s issue, we dive into The A-Side and take a closer look at Structured Prompt-Driven Development (SPDD). We’ll walk through the workflow loop that helps keep your intent aligned with the code, and why doing the analysis first matters more than jumping straight into the canvas.
And there’s more:
The Read-Only Memory: Donald E. Knuth once offered a $2.56 reward for finding errors in his books. A small detail that says a lot about his approach to technical work, and about being open about mistakes.
The Open Thread Club: What happens when a C-Level demo goes well enough that, suddenly, your demo is expected to become a production application?
The Rendezvous: A quick look at upcoming SRE, CloudNative, and Python events in Salt Lake City, London, and Rapperswil.
Before you continue, if you enjoy my work and would like to support the newsletter, I’d really appreciate it if you shared it with a fellow engineer:
💚 On WhatsApp | 💙 On LinkedIn | 🩵 Bluesky
Or simply forward this email to someone who might find it useful.
Thanks, as always, for reading.
The Read-Only Memory
Do you know who Donald E. Knuth is?
Donald Ervin Knuth is an American computer scientist and mathematician. He is a professor emeritus at Stanford University. He is the 1974 recipient of the ACM Turing Award, informally considered the Nobel Prize of computer science.[4] Knuth has been called the “father of the analysis of algorithms”.
But that’s not the main reason why I mention Donald today. Watch this out!I found on his Standfor’s web page that Knuth personally pays $2.56 to anyone who finds a genuine error in his books. It is not merely a symbolic reward; he has maintained the system for decades and publishes lists of errors so that readers can verify them. There is something highly unusual for an academic of his stature in publicly turning his own mistakes into an opportunity for others to contribute.
Who would you say NEVER would do that from the nowadays technology spectrum? Write it in a comment!
In this section, we will focus on biographies of computer pioneers, forgotten historical whitepapers that remain entirely relevant, and independent blog posts that question the status quo of our industry.
Would you like to suggest some? I hear you! 👇🏻
The Open Thread Club
Today’s topic on The Open Thread Club, I think, is happening in those companies where innovation is the goal of the company. Lately, I've read about many “AI Labs” created either as a whole company or as dedicated/supperpowered group/team.
How to build a quick prototype that everybody knows will be declared production-ready just after the demo?
— Anonymous streessed developer
That question summarizes the question that arrived in my mailbox a couple of months ago.
This developer told me, in detail:
We have to develop an AI-based project and demo it to the C-Level board.
We need several apps to make this happen.
We have a very demanding timeline to deliver value.
My concern is that if we build these apps without a minimum level of testing and CI/CD, and the project proves its value, we could end up in trouble when we need to iterate and make it production-ready because of the technical debt we’ve accumulated.
First, did you face the situation when a prototype becomes automagically into a production-ready product just because the C-Level member (you choose) says so? Because this is the case of this person.
Second, do not try to fight that situation: you will fail. Instead, you can do something else.
📖 My take: Do implement those minimal tests and the complete CI/CD, even if your requirements say “do not lose time on that”. You are a developer accountable for the work you do and, as such, you have to ensure you put in place the right quality to ensure the success of your apps.
Depending on the project, the right level of X is different. When you work on a project like the one described:
You will avoid too many tests and focus on the happy path to ensure that your next changes do not f*ck up the app.
You will implement the automatic CI/CD run. For me, the automation is included in the minimum. Why? You need speed to deliver new versions of your app fast, and the automation gives you precisely that.
Hope this helps!
In this space, we will address real dilemmas about architecture, technical friction, or leadership situations you send anonymously.
Instead of giving theoretical or dogmatic answers, I will respond with honesty, sharing my own past mistakes in similar situations and the lessons I took away when trying to solve them.
You can start participating RIGHT NOW! Click the button below and tell me your story so I can answer in the next issue 👇🏻
The Rendezvous
KubeCon & CloudNativeCon North America 2026. KubeCon is one of my favourites, and it’s coming next November 9th to 12th in Salt Lake City, Utah.
If you’re in an SRE role, this is for you. In London, the Observability and SRE Summit will happen on 21st and 22nd of October.
For those Python lovers in Europe, the Swiss Python Summit will happen in Rapperswil on October 22nd and 23rd.
If you go to some of those, tell us how it goes!
A radar of events about software engineering and technical leadership.
The priority here is not to be exclusively massive conferences, but to give visibility to smaller, local encounters or emerging initiatives. If you are organizing a conference or know of an event worth sharing, the channel is open for you to send it to me and share it with the community.
Do you own an event or summit? Drop me an email! 👇🏻
The A-Side
In the previous chapter, we introduced what SPDD is and the problem that it tries to solve.
Now, we go a bit deeper.
🔍 Why Analysis Comes Before the Canvas
There is another important distinction in SPDD that is easy to miss.
The workflow does not necessarily go directly from requirements to the REASONS Canvas. There is an analysis step in between. Why?
☝🏼 Because before deciding how to change a system, we need to understand the system we already have.
The analysis step examines relevant parts of the codebase and domain, identifies concepts, dependencies, risks, and possible design directions, and uses that information to create the context for the structured prompt.
A useful way to think about the distinction is:
Analysis asks: “What do we know about the problem and the existing system?”
REASONS asks: “Given that understanding, what exactly are we going to build?”
This separation is important because otherwise it would be very easy to ask an LLM to design a solution without giving it enough knowledge about the system it is changing.
And that is exactly the type of situation where AI assistants can confidently produce technically valid but contextually wrong solutions.
🗝️ The SPDD Workflow
The exact commands depend on the tooling, but the OpenSPDD implementation provides a useful concrete representation of the SPDD workflow.
The core flow is roughly:
Business requirement
↓
Analysis
↓
REASONS Canvas
↓
Code generation
↓
Validation / tests
↓
Human review
↓
Sync
↺OpenSPDD currently provides commands for the main steps:
/spdd-analysis
Analyzes the requirement and relevant parts of the existing codebase.
The goal is to understand domain concepts, current implementation, risks, and possible design directions.
/spdd-reasons-canvas
Turns that understanding into the structured REASONS Canvas.
This is where requirements, entities, approach, structure, operations, norms, and safeguards are made explicit.
/spdd-generate
Uses the Canvas to generate code task by task.
The idea is that the model is no longer improvising the whole solution from a short prompt. It is executing a more explicit implementation plan.
/spdd-prompt-update
Used when the requirement or intended behavior changes.
This is an important distinction.
If we discover that the business requirement was wrong or incomplete, the intent should change first.
That gives us:
Requirement change
↓
Prompt update
↓
Code update/spdd-sync
Used when the implementation changes without changing the intended behavior, for example because of a refactoring or implementation-level correction.
That produces the reverse direction:
Code change
↓
Sync
↓
Prompt updatedOpenSPDD currently also provides optional commands such as /spdd-story, /spdd-api-test, /spdd-code-review, and /spdd-reverse, but they are not the core of the workflow.
The important part is therefore not memorizing the commands.
The important part is understanding the loop.
🔄 The Interesting Part: Prompt ↔ Code
For me, this is the part that makes SPDD more interesting than a sophisticated prompt template.
The relationship between intent and implementation works in both directions.
When behavior changes
Suppose the original requirement was:
Premium customers can exceed their monthly usage quota.
Later, the business changes its mind.
Now Premium customers must also respect a quota.
That is a behavior change.
The intent has changed, so we update the structured prompt first.
New requirement
↓
Update REASONS Canvas
↓
Generate / modify code
↓
Review and testWhen implementation changes
Now suppose the behavior is still correct, but we refactor BillingService because we want to introduce a different internal abstraction.
☝🏼 That is an implementation change.
The intent has not changed.
We can therefore change the code first and synchronize the structured prompt afterwards.
Refactoring
↓
Code changes
↓
Sync CanvasThis distinction is one of the most useful ideas in SPDD.
A behavior change means intent has changed.
A refactoring means implementation has changed while intent remains the same.
If the code changes its behavior but the prompt does not reflect that change, the two artifacts are now telling different stories. That is effectively Prompt Debt.
And like technical debt, it may not hurt immediately. It tends to become expensive later, when someone uses the outdated artifact as the basis for the next change.
👩🏻💻 What Changes for Engineers?
This is where SPDD becomes more than an AI tooling discussion.
If AI becomes increasingly capable of writing implementation code, some engineering skills become even more important.
1. Abstraction First
Before asking AI to implement a feature, we need to understand the objects, boundaries, responsibilities, collaborations, and constraints involved.
The interesting engineering question becomes less:
“Can I write this class?”
and more:
“Should this responsibility exist here in the first place?”
That is not a new software engineering skill.
AI simply makes it more visible.
2. Alignment
Someone still needs to define what the system should do, what it should not do, and which constraints cannot be violated.
SPDD makes those decisions explicit in the structured prompt.
The goal is to resolve important disagreements before implementation rather than discovering them after hundreds of generated lines have already been produced.
3. Iterative Review
AI-generated code still needs human review.
In fact, the more code generation becomes automated, the more important it becomes to have a disciplined review loop.
That does not necessarily mean reading every generated line with equal attention.
It means reviewing the right things at the right level:
Does the implementation match the requirement?
Does the design fit the existing architecture?
Are the domain concepts correct?
Are the safeguards being respected?
Are the generated tests actually validating the intended behavior?
SPDD tries to make that review easier by giving reviewers something to inspect before the implementation itself is generated.
⚖️ What SPDD Does, and What It Doesn’t
There is a temptation to interpret a framework like this as a way to make AI-generated code predictable.
That would be going too far.
SPDD does not eliminate LLM uncertainty, and it does not guarantee architectural correctness or software quality.
The authors explicitly describe the goal as keeping the model’s non-determinism within more controllable boundaries rather than eliminating it altogether.
That distinction matters.
SPDD can make intent more explicit.
It can make design decisions easier to review.
It can make successful prompts reusable.
It can provide a mechanism for keeping those artifacts aligned with the implementation.
But humans still have to decide whether the requirements are correct, whether the architecture makes sense, whether the trade-offs are acceptable, and whether the resulting software actually works.
That is probably the most useful way to think about the methodology.
Alright! Wrapping up for today.
✨ Takeaways
What interests me about SPDD is not the prompt template itself.
We’ve been writing structured requirements, architecture documents, coding standards, design documents, checklists, and implementation plans for years.
The more interesting idea is the lifecycle.
Instead of:
Requirement → Chat → Code → DoneSPDD proposes something closer to:
Requirement
↓
Understanding
↓
Analysis
↓
Structured design
↓
Implementation
↓
Validation
↓
Synchronization
↺The prompt becomes part of the engineering system.
It captures not only what we want to build, but also the reasoning, structure, constraints, and implementation decisions that guide the AI.
And because the artifact is kept alongside the code, that knowledge has a chance to survive the individual chat session, the individual developer, and the individual change.
That is the part I want to experiment with.
Because perhaps the interesting shift in AI-assisted software development isn’t that machines are getting better at writing code.
Perhaps it is that engineers are going to spend more of their time deciding what the code should mean before asking a machine to write it.
And that brings us back to the original question:
What happens when generating code becomes faster than understanding it?
Frameworks like SPDD are an attempt to make sure our engineering process keeps up.
In the AI era, software development may become less of a contest of model IQ and more a question of how effectively engineers can use their cognitive bandwidth to define, review, and evolve the systems they are building.
Be safe,
Marcos.