[adrianmsmith]

Anything that relies on files having names like 0001-foo isn't going to work nicely if you are using Git, merge/pull requests and branches, with developers working on features independently.

I'm going to see that 0024 was the last file and add a 0025, and you while working on your feature will see the same and add a file with the same number. This will have to be noticed and resolved via renaming files during rebase and merge, etc., which is pointless busywork and easy to get wrong.

Also, I don't see why these need to be ordered sequentially at all. Surely e.g. a file like "architecture.md" or individual files like "database.md" would be better? If you change the code and that involves changing the architecture, you also update the document. You are free to include information such as why you made the change, alternatives and why they were not chosen etc., just as with this 0001-foo.md.

If you are joining a team and want to learn about the database, it's much easier to open "database.md" and find the current state, vs. reading through 0001 through 0245 where 0009 introduces why MySQL is used, 0051 explains why PostgreSQL is now being used instead of MySQL, 0121 introduces some changes, and so on. Having individual files like that is like reading Git diffs from start to finish where what you really want is the current state.

[meaboutsoftware]

Each architecture decision record should be added after the decision of the entire team. Then one folk can be assigned to add the ADR to the repo. It will work fine even if you do feature branches (battle-tested but you need to keep you branches short). In case of trunk-based development, there is no problem multiple feature branches.

The idea of ADR is to be immutable. Having multiple, ordered ADRs that touch e.g. the database works similarly to event sourcing - you have the entire history of all changes that were done within the context.

If you want to keep the entire history with changes in a single file called "database", then that's fine but the most important thing is to keep the history of decisions.

Having a single file with only the last decision is not the optimal idea as you lose the entire history.