Recently, I've begun to work on a green-field project. Everything has to be done from scratch. Technical decisions needed to be made in order for the project to be launched. The team is really great and debates around architecture are a necessity in order for everyone to see the big picture, prevent errors in design and gain cohesion around a shared vision of what the architecture should be. Collective knowledge is key to avoiding architectural mistakes.

I'm really in favor of having everyone conscious of the aftermath of such decisions. Problem was that up until a month ago, technical decisions were constantly challenged, keeping us from moving forward. These decisions were not shared among team members as some of us forgot the real reasons behind these decisions in the first place and that we agreed on them.

I'm really not a fan of paperwork, but I do have a passion for history. I also have a limited space in my brain for remembering everything that happened which led to a certain decision. Software projects involve too many things to remember, so documenting key events in the life of a project is of paramount importance.


Imagine a project where Bob the newcomer comes in and asks this question.

Why did you chose framework A instead of framework B?
Why is it that service A manages both of these concepts?

Sooner or later, there will be a newcomer on the project having such naive yet poignant remarks. If Bob asks this question, then Alice, who's coming in next month on the project, will probably have the same train of thought.

Writing down architectural decisions

Photo by j zamora / Unsplash

Architectural Decisions Records (ADR) must be documented. It's likely that these written decisions will be of use later when people who made this decision will be either out of the project or will have forgotten about them.

ADR have many advantages :

  • record decisions based on objective facts
  • remove sentimental or unspoken reasons
  • capture the context in which the decision was made

ADR have this beautiful side effect of synthetizing context and the options which were compared and put in balance with the decision. Often better decisions will be made using this format. During debates, people can be more or less influential and it's really easy to get lured into a poor decision by thinking too fast. ADR should be approved when things cool down and with a clear mind, thinking solely about their written content. All in all, the goal of ADR is to remove bias.

Content of Architecture Decision Records

ADR can have many formats, and I encourage to have your own. Examples of ADR templates on GitHub will be useful to write your own template.

Basically, ADR have the following outline :

  1. Summary
  2. Context
  3. Options
  4. Decision
  5. Consequences

It's important to at least follow this order as it should be the order of analysis. Many are those who jump to solutions before even registering the problem and its context. Options must be studied in order to answer as much as possible to the context and the decision should be made on the option that suits best the context.

It is important that an ADR is relative to a specific context and should the context evolve, a new ADR can (and probably should) be made to address the new context. Although the ADR remains valid, if the context has changed, a new ADR must be made.

Put architectural decisions in a safe but accessible place

All ADRs must be in the same place. It's possible to have them on a network drive, or on a git repository. What's essential is that they are accessible to everyone on the team.

Personally, I place ADR in a special git project which concerns the application's architecture in order not to pollute the rest of the codebases, most of which are in separate git repositories, but that's all up to you.

Involve everyone

Photo by rawpixel / Unsplash

Anyone who wants in on architecture decisions should participate, whether it be developers, architects, business people, UI, UX. Practically anyone who's impacted by an architectural decision needs to be present during the decision and read, write, and agree on the ADR.

What's a good time to write an architectural decision

ADR should be written down whenever a decision needs to be made. It's important to log it right away when the decision is fresh so that everyone involved can agree on the written decision.

Please note that ADR should not be held back until project breaks, but right when a decision is made, in order to avoid forgetting details.


Architectural Decision Records track a project's architectural decisions. Decisions are made in a certain context and options are evaluated. ADR capture these in a factual manner. ADR then need to be archived in a place where anyone can read them.

Since ADR are made based on a certain context, it is clear that if this context has changed, then the ADR can be challenged. ADR are far from congealing architecture, they allow anyone on the team to make enlightened questionings based on factual evidence and not on a distorted souvenir.