After years working with software, I have developed a set of principles that guide my architectural decision making. These are not hard and fast rules: they are lenses to look through when we are faced with decisions that will last longer than the sprint in which they were made. We are constantly faced with decisions and it is helpful to have a framework to use, especially when explaining to an LLM what you value or want to share with a team member. I use them to shape building architectural decision records (ADRs) and also review other ADRs.
Simplicity over complexity
Prefer simple APIs over complex ones. A smaller surface area and more focused role make a system easier to understand, reason with, and eventually replace.
Everything should be as simple as possible, but not simpler.
-Einstein
If something offers a larger surface area, stick to the simpler parts of the API instead of looking for complex features; Indexes in Postgres carry less locking than stored procedures, for example. Prefer proxy APIs that allow easier switching later.
Simple APIs are also easier for LLMs to understand, contextualize, and implement.
Perfection is achieved not when there is nothing more to add, but when there is nothing more to take away.
— Antoine de Saint-Exupéry
Grug puts it more directly:
The eternal enemy: complexity
If given the choice between complexity or one-on-one vs. T-Rex, Grug takes T-Rex: At least Grug sees T-Rex
- Can I explain this in an hour and master it in a day?
- Does this reduce complexity or introduce new abstractions?
- Is the API surface area as small as possible?
There is no black and white, it is a spectrum
Everything is on a spectrum and “right” can mean different things depending on your goals, timelines, and limitations. That's why it's worth spending a little time up front to save days or years of pain, and why it's important to write down the why behind a decision, so you can re-evaluate it later. Understand that sometimes there are different solutions in the short, medium and long term.
In the LLM world, this is where we provide the most guidance; When we have our agents draft architectural decision records, this is where we provide the most guidance.
- What are the limitations: schedule, team size, risk tolerance?
- Have I written down the why so I can review this later?
- Am I optimizing for now or for long-term maintainability?
- What knowledge do I have that the recommended LLM solution does not incorporate?
Always compare
Starting from the best solutions in the space gives you the possibility of finding the right one.
Make sure decisions are weighed against those of major competitors and that you have clear criteria for why you choose one thing over another. Verify real-world reports of each use in production and create a proof of concept – of the candidate and your competitors. Even a mental walkthrough of how an API or tool would be used in practice is more valuable than committing to a full implementation.
Always explain why you recommend what you do and what you considered along the way.
Note that some people skip this step (some of it might boil down to satisfy versus maximize); we would all be stuck forever trying to find the optimal solution. Still, it's worth understanding why people make the decisions they do and why we ourselves might skip them. LLMs are a good starting point if we make sure they look for the most up-to-date information and don't just use the limit of knowledge.
- Have I evaluated the best alternatives with clear criteria?
- Have I reviewed real-world reports and created (or mentally reviewed) a proof of concept of each?
- What are the gaps and how did competitors resolve them?
- Has an agreement on a standard already been reached?
- Is there anything I've heard or read lately that I think is better?
I prefer
