Architectural Decision Records

Architectural Decision Records are a quick and lightweight way to capture decisions around architecture. There are many resources on the Web about them, and this one is quite good.

Create an ADR in these situations:

1. No choice was obviously best for an architectural decision
2. You need to reverse or revise a previous decision

In both cases, write the ADR just before the team begins the work—not when the work is merely planned.

If a team disagrees with an ADR that applies to their work (case 2), they should create a new ADR that supersedes and references the previous one.

You do not need an ADR for first-time decisions that had a clear, obvious answer.

When any arch decision is made, involve the right people (think 'no surprises') once decision is made, and make a new ADR in Jira.

Please read the details here to understand the lifecycle and how the ADR process does not restrict what your team can develop.