Best practices

Promote ownership. Each project team member should be empowered to create and own an ADR. This practice distributes architectural research work among team members and offloads that work from the solutions architect or team lead. It also fosters a sense of ownership in the decision-making process. This helps the team adopt those decisions faster instead of treating them as decisions that were imposed from higher levels of the organization.

Preserve ADR history. ADRs should have a change history, and each change should have an owner. When the ADR owner updates the ADR, they should change the status of the old ADR to Superseded, note their changes in the change history of the new ADR, and keep the old ADR in the decision log.

Schedule regular review meetings. If you are on a new (greenfield) project, the ADR process can be quite intense in the beginning. We recommend that you establish a cadence of regular ADR discussion and review meetings before or after the daily standup. With this approach, the defined ADRs will stabilize in two or three sprints, and you can build a solid foundation with fewer meetings.

Store ADRs in a central location. Each project member should have access to the collection of ADRs. We recommend that you store the ADRs in a central location and reference them on the main page of your project documentation. There are two popular options for storing ADRs:

• A Git repository, which makes it easier to version ADRs

• A wiki page, which makes the ADRs accessible to all team members

Address non-compliant code. The ADR process doesn’t solve the issue of non-compliant legacy code. If you have legacy code that doesn’t support the established ADRs, you can either update the outdated code base or artifacts gradually, while introducing new changes, or your team can decide to refactor the code explicitly by creating technical debt tasks.