Nguyen Le PhongNguyen Le Phong

Keeping Architecture Decisions Small Enough to Revisit

A practical reflection on making architecture decisions small, explicit, and revisitable so teams can learn without turning every choice into a permanent monument.

The architecture conversation started beside a whiteboard that still had traces from yesterday's meeting. Someone drew three boxes, then paused before adding the fourth. The question was not whether the design could handle the next feature. The harder question was whether the decision we were about to write down would still be easy to revisit after three more teams depended on it.

A small engineering group calmly reviews interface cards and a light architecture sketch around an office table.
Small architecture decisions leave room for evidence to arrive without making the team feel trapped by yesterday's certainty.

Some architecture decisions become too large before they are understood. They try to settle the naming, the boundaries, the storage model, the ownership model, the rollout path, and the future migration in one impressive document. The document looks serious, but the team quietly loses the ability to learn. If one assumption changes, the whole decision feels politically expensive to touch.

A smaller decision has a different texture. It says what is being decided now, what is deliberately not being decided yet, and which signal would cause the team to reopen the choice. That last part matters. A decision without a revisit condition can turn into a memory test. Six months later, nobody knows whether the choice still fits or whether people are protecting it because it once had a meeting.

For example, a team might choose a repository interface before it chooses the final persistence strategy. It can say: we need a stable usecase contract now; PostgreSQL is the current implementation; if query volume or tenant isolation pressure changes, we will revisit indexing and storage without changing the handler contract. That is still architecture. It is just architecture with less theater around certainty.

Small does not mean vague. A revisitable decision should still name the invariant it protects. It should explain which boundary owns which behavior. It should record the trade-off in plain language. The difference is that it avoids pretending today's evidence is complete. The team protects the important shape without carving every detail into stone.

This habit is especially useful when a system is growing across people. New teammates need more than code. They need to know which decisions are load-bearing and which ones are temporary scaffolding. If every choice is described with the same confidence, the team cannot tell what can be safely changed. A small decision note helps future readers separate intent from accident.

The discipline is to leave a handle for the next conversation. Date the decision. Name the owner. Link the example that made it necessary. Write the condition that would make it wrong. Then move. The team does not need a perfect architecture memory. It needs enough trace to keep learning without restarting from rumor.

When a decision is small enough to revisit, architecture becomes less like a verdict and more like stewardship. The team can respect yesterday's reasoning without becoming loyal to yesterday's limits. If you look at one architecture choice in your current system, can you tell what evidence would let the team change its mind?

What did you think?