[Feature] Add Architecture Decision Record implementation to be used in ArchRule reason

[RoRoche]

Hello,

This Pull Request includes:

• Contracts to define an ADR and its content
• Concrete implementation in Markdown using toString method overriding
• Unit test of a Markdown ADR generation

Resolves #1495

Thank you for reviewing.

Regards.

[hankem]

Thanks for your contribution! While I think it's nice to be able to define MADRs programmatically, this feature seems to be quite independent of ArchUnit. (The only dependency of your classes on ArchUnit is the com.tngtech.archunit.PublicAPI annotation...) Why do you think it should be in ArchUnit and not a separate library?

[RoRoche]

ArchUnit rules reflect key architectural decisions, but the rationale behind those decisions is typically buried in code or comments.

This feature would allow automatic generation of Markdown Architecture Decision Records (ADRs) directly from ArchUnit rules, capturing why a rule exists—not just what it enforces.

Benefits:

• Makes architectural intent and context explicit
• Promotes consistent and visible decision-making
• Helps teams trace rules back to their original reasoning
• Encourages writing meaningful descriptions alongside rules

This would bring ArchUnit closer to being not only a verification tool, but also a lightweight architectural documentation aid.

What is your mind about this explanation?

[hankem]

I fully agree that ArchRules should document the reasoning for the constraints they encode. 👍
(It was probably me who suggested to add the because clause to ArchRule in the early days of ArchUnit...)

This feature would allow automatic generation of Markdown Architecture Decision Records (ADRs) directly from ArchUnit rules

I see that you could use an adr in

ArchRule = /* rule definition */.because(adr.toString());

(which you can already do with any adr defined outside of ArchUnit),
but I didn't see how you could generate an ADR from an ArchUnit rule. 🤔

[RoRoche]

Yes, you're right, it would be more complicated than I think to generate ADR from ArchUnit rule 😢

[RoRoche]

But you are right, the typical use case I target is the following:

ArchRule = /* rule definition */.because(adr.toString());

[RoRoche]

Hi @hankem,

Hope you are doing well.

What do you think about this feature request?

Is it relevant to include it in ArchUnit ? Or do you recommend me to release an independant library?

Thank you for your response (and hoping it could be part of this awesome library 😉).

Regards,
Romain