Architecture advice that cites your own system

Prose has no compiler

Ask an AI assistant whether your team should move to microservices, and you get a balanced, well-structured answer about the pros and cons of microservices. It reflects what has been written about microservices in general. It says almost nothing about your system.

Architecture is where AI assistants are most confidently wrong, because the output is prose. Code that is wrong usually fails to compile or fails a test. An architecture recommendation that is wrong reads just as well as one that is right.

Remove the survey

The fix is to stop asking open questions and start asking for decisions grounded in evidence.

Establish the ground first. Before any option is discussed, list the constraints and check which ones are real. "We need to scale" is not a constraint until it is tied to something measured in your system.

Generate options, including doing nothing. Ask for a small number of concrete options, and always include "do nothing" as one of them. It is often the right answer, and including it forces every other option to justify its cost.

Attach a number to every option. An option that cannot be evaluated against something measurable, such as latency, deployment frequency or the number of services a change touches, is a preference, not an option.

Write the decision down. Record it as an architecture decision record that keeps the losing options and why they lost. The next person to question the decision needs the reasoning, not just the outcome.

Plan the migration in increments that revert. Each step should ship on its own and be reversible on its own. A migration that only works once it is finished is a bet, not a plan.

Audit what exists before changing it

Many architecture discussions argue about a system nobody has looked at recently. Asking the assistant to describe the current architecture from the code, with evidence, is often more useful than asking what it should become.

Putting it into practice

Software Architecture Prompts Pro is five prompts that take a decision from context to options, a written decision record, a migration plan in reversible increments, and an audit of the existing architecture. It includes the decision record and increment templates, a worked example, and the common ways AI architecture advice goes wrong.

The same habit of deciding before agreeing applies inside a single feature, where a coding agent settles storage, errors and retries before any spec exists.