Not all architecture principles should be treated the same.
Some should be rules. Others should be guidelines.
Explicitly calling out the difference gives teams enough structure to maintain the architectural vision, while still giving engineers room to make good decisions.
Why Architecture Principles Matter
I’ve helped envision, modernize, transform, and fix many platforms throughout my career. One of the most valuable things you can do early in that process is to define a set of architectural principles.
Large transformations take time. Along the way, different engineers and teams will make tons of technical decisions.
A good set of principles helps ground those decisions and ensures the platform you end up with still resembles the platform you originally envisioned.
But the platform doesn’t stop evolving when the project ends.
New requirements appear, new technologies emerge, constraints change, and individual engineers/architects come and go. Your principles need to provide structure without preventing the architecture from evolving.
That’s why I like to separate them into two categories: Rules and Guidelines.
Rules: These Must Remain True
An architecture rule defines something that must remain true about the platform.
For example:
“Data must be encrypted at rest and in transit.”
Or:
“Services within one cell cannot directly communicate with services in another cell.”
These aren’t preferences; they are architectural constraints that engineers must design with rather than decide whether to follow.
Guidelines: This Is How We Prefer to Build
Architecture guidelines provide direction while leaving room for engineers to apply contextual judgment.
For example:
“Services should be stateless whenever practical.”
There may be good reasons for a service to maintain state, and that’s ok.
The guideline establishes the preferred approach, but engineers can deviate when the problem context justifies it.
Why You Need Both
I’ve run into problems when architecture principles are treated entirely as guidelines or entirely as rules.
If everything is a guideline, eventually nothing is a rule.
Someone may have a legitimate reason to deviate. Another team will see that implementation and copy it.
Now the exception becomes precedent, and over time the original principle slowly disappears.
But making everything a rule creates the opposite problem.
Eventually, you’ll encounter a scenario you didn’t anticipate when the principles were written. Now you need an exception.
Once you establish a process for exceptions, that process can quickly become the path of least resistance. The rule slowly becomes a guideline anyway.
Or your platform becomes so rigid with rules that engineers can't meet changing needs.
Explicitly defining which principles are rules and which are guidelines gives you the best of both worlds. Rules protect the architectural characteristics you aren’t willing to compromise. Guidelines give engineers room to make contextual decisions when circumstances change.
This Matters Even More With Coding Agents
Smaller engineering teams have sometimes gotten away without explicitly documenting principles. Engineers learn them through code reviews, architecture discussions, and tribal knowledge.
Coding agents don’t have years of tribal knowledge. They only understand the design constraints they can access.
If we want coding agents to make increasingly larger implementation decisions, we need to explicitly tell them where they have engineering freedom and where they don’t.
Writing down your architecture principles and making them easily accessible to engineers and agents alike is becoming even more important.
Tell an engineer who understands your architecture to retrieve account data. That engineer will instinctively know they should leverage the owning service's API rather than accessing its database directly.
Ask a coding agent to fetch the same data; it might try to connect to the database directly, breaking the “microservices must not share databases” architecture rule.
Ask a coding agent to do something without context, and you’ll get exactly what you asked for, whether it violates your architecture principles or not.
If the agent doesn’t know the rules, it can’t follow them.
Final Thoughts
Architecture principles have always been valuable. Writing them down is more important now than ever.
But don’t just define how you want your platform to look at the end. Be explicit about which principles are rules and which are guidelines.
Good architecture principles should tell engineers and agents where they have freedom to make decisions and where they don’t.