There's a question almost every developer has asked while working on a mature codebase:
"Why was it built this way?"
Sometimes the answer is buried in an old GitHub discussion. Other times, it's hidden in a Slack thread, an outdated document, or, even worse, in the memory of someone who left the company two years ago.
The code tells us how something was implemented. It rarely tells us why a particular approach was chosen, what alternatives were considered, or which constraints influenced the decision.
And that's a problem.
As software engineers, we spend considerable time reviewing code, writing tests, and maintaining documentation. Yet the reasoning behind some of our most important technical decisions often disappears over time.
This is one of the problems I wanted to address when I started building ADR Guard, an open-source tool focused on Architecture Decision Records (ADRs).
More recently, I've been working on bringing that experience directly into Visual Studio Code.
But before discussing the extension, it's worth looking at why architectural decisions deserve more attention in the first place.
Architecture Decisions Are Part of Your System's History
An Architecture Decision Record is a document that captures an important architectural decision, including its context, the approach selected, and its consequences.
The concept is straightforward.
Imagine your team decides to move from synchronous communication between services to an event-driven architecture.
At that moment, everyone probably understands why.
Perhaps you need better resilience. Maybe your services have become too tightly coupled. Or perhaps you're dealing with scalability requirements that the current design cannot comfortably support.
Now imagine someone revisiting that decision two years later.
The system has evolved. The team has changed. New technologies are available, and the original constraints may no longer exist.
Without an ADR, that developer needs to reconstruct the reasoning behind the decision.
With an ADR, they have a starting point.
An ADR isn't meant to prevent architectural decisions from changing. It's meant to make those changes informed and intentional.
Good architecture isn't about making decisions that last forever. It's about understanding the trade-offs we accept and knowing when it's time to revisit them.
The Real Challenge Isn't Writing ADRs
I've noticed that adopting ADRs is often easier than maintaining the practice.
Initially, everything looks promising.
The team creates a docs/adr directory, agrees on a template, and starts documenting important decisions alongside the source code.
A few months later, inconsistencies begin to appear.
Some documents are missing essential sections. Others use different formats. Certain decisions are never updated, even after significant architectural changes.
Eventually, ADRs risk becoming another collection of Markdown files that nobody remembers to consult.
I don't think the problem is necessarily a lack of discipline.
The problem is that we sometimes introduce documentation practices without considering the developer experience around them.
If creating, finding, editing, and validating architectural decisions requires too much effort, the practice becomes increasingly difficult to sustain.
Documentation needs to fit into the development workflow, not compete with it.
That idea became an important part of the ADR Guard project.
ADR Guard: Bringing Structure to Architectural Decisions
ADR Guard is an open-source tool built with .NET to help teams manage Architecture Decision Records throughout their lifecycle.
It doesn't attempt to replace Markdown or introduce a proprietary documentation platform.
ADRs remain regular files in your repository, which means they can be versioned, reviewed through pull requests, and maintained alongside the code they describe.
The CLI supports workflows such as creating records, validating their structure, organizing documentation, and performing incremental checks.
It also supports different ADR formats, including canonical ADRs and MADR 4.0.
The goal is to make architectural documentation more consistent and easier to maintain.
For example, structural validation can identify documents that don't follow the expected format. Teams can also use baselines and automated checks to introduce governance incrementally instead of requiring an entire repository to become compliant overnight.
These capabilities can be integrated into CI/CD workflows, making documentation quality part of the development process.
There is, however, an important distinction.
Validating an ADR doesn't mean approving the architectural decision itself.
A tool can verify structure, required sections, and documented conventions. It cannot replace engineering judgment, architectural discussions, or technical reviews.
And it shouldn't try to.
Bringing ADRs Into Visual Studio Code
While the CLI provides the foundation, I wanted to reduce the friction involved in everyday ADR management.
Most developers already spend a significant portion of their day inside their editor.
So why should working with architectural decisions require a completely separate experience?
That's where ADR Guard for VS Code comes in.
The extension provides a visual interface for common ADR workflows while relying on the existing ADR Guard CLI for the underlying operations.
This separation is intentional: the same core behavior can be used from the terminal, VS Code, or automation pipelines.
Finding Architectural Decisions Without Searching Through Folders
One of the first improvements is discoverability.
The ADR Guard visual dashboard provides direct access to architectural decisions and their metadata.
Instead of manually browsing Markdown files, developers can use a visual list displaying information such as ADR identifiers, titles, statuses, and file locations.
The interface supports searching, filtering by status, sorting, and opening documents directly in the editor.
Searching and filtering ADRs makes architectural context easier to discover.
There's also an ADR Explorer integrated into VS Code, providing another way to navigate records and recognized relationships.
These features might sound simple, but I believe discoverability has a direct impact on whether documentation is actually used.
A decision that's easy to find is much more likely to influence future engineering discussions.
Creating ADRs Without Memorizing Templates
Another area I wanted to improve was ADR creation.
Markdown is a great format for technical documentation, but asking every developer to remember the structure of every supported template introduces unnecessary friction.
The extension provides a visual creation form that helps guide the process.
The Minimal template focuses on the essential elements of an architectural decision.
With the Minimal template, developers can focus on three fundamental questions:
- What is the context?
- What decision are we making?
- What are the consequences?
For decisions requiring more detailed analysis, the Extended template includes additional fields, such as decision drivers, alternatives considered, rationale, risks, and references.
The Extended template helps capture more detailed architectural reasoning and trade-offs.
The extension also supports a Markdown preview before creating the document.
The point isn't to automate architectural thinking. It's to remove repetitive tasks so developers can focus on explaining their decisions clearly.
Editing Existing Decisions Safely
Architectural decisions evolve, and documentation needs to reflect that.
The extension provides visual editing for compatible ADR documents, allowing developers to update their content without manually navigating every Markdown section.
Existing ADRs can be edited through a structured interface inside VS Code.
One detail I consider particularly important is how the extension handles external modifications.
If an ADR changes after being loaded into the editing form, the extension detects the conflict and prevents an outdated version from silently overwriting the newer content.
This is especially relevant in collaborative repositories where multiple developers may be working on the same documentation.
The goal is to provide convenience without sacrificing predictability or data integrity.
Making Validation Part of the Development Workflow
Another useful capability is integration with VS Code's Problems panel.
ADR validation findings appear alongside other development diagnostics in VS Code.
When an ADR violates a supported structural rule, developers can see the corresponding diagnostic without leaving the editor.
Validation can run explicitly, and automatic validation on save is available as an opt-in setting.
The extension also provides workflows for validating changed ADRs against a local Git reference and checking findings against an existing baseline.
I see this as a useful step toward making architectural documentation part of ordinary engineering feedback loops.
We already expect immediate feedback when code violates certain rules. Having similar visibility for ADR structure can help teams maintain documentation standards without relying entirely on manual inspections.
Of course, structural consistency isn't the same thing as architectural correctness. Human review remains essential.
Architecture Governance Shouldn't Become Another Source of Friction
One concern I've had throughout this project is avoiding unnecessary complexity.
It's easy to introduce tools and processes in the name of governance, only to make developers' lives harder.
I believe architecture governance works best when its purpose is clear and its mechanisms are predictable.
That's why the VS Code extension is designed as a user interface over the existing CLI rather than a separate implementation of ADR rules.
It also avoids silently modifying architectural documents during ordinary navigation or validation.
The developer remains responsible for deciding when records should be created or changed.
To me, this is an important principle: good engineering tools should support deliberate decisions, not hide consequential actions behind convenience.
Not Every Technical Decision Needs an ADR
I don't believe every implementation detail should become an architectural record.
That would create unnecessary bureaucracy and eventually reduce the value of the documentation.
ADRs are most useful for decisions that affect the system's structure, establish long-term technical constraints, introduce important dependencies, or involve meaningful trade-offs.
Choosing between two local variable names probably doesn't need an ADR.
Deciding how services communicate, how data ownership is defined, or why a particular persistence strategy was adopted probably deserves one.
The objective isn't to produce more documentation.
It's to preserve the context that future engineers will need to make good decisions.
Final Thoughts
Building ADR Guard has reinforced something I strongly believe about software architecture:
The quality of an architecture depends not only on the decisions we make, but also on our ability to understand and revisit those decisions over time.
An ADR won't solve architectural problems by itself.
But it can preserve valuable engineering context, make trade-offs visible, and provide a foundation for better technical discussions.
ADR Guard for VS Code is one more step toward making that practice easier to adopt and maintain.
The project is open source and continues to evolve. If you work with software architecture, technical leadership, or long-lived systems, I'd be interested in hearing how your team handles architectural decisions.
Do you use ADRs today? And if so, what's been the biggest challenge in keeping them useful?
Try ADR Guard
Install ADR Guard for VS Code — Get the extension from the Visual Studio Marketplace.
Official VS Code Visual Guide — Explore the interface, screenshots, and supported workflows.
ADR Guard on GitHub — Explore the source code, report issues, or contribute.
The VS Code extension uses the ADR Guard CLI, which must be installed separately. Check the official documentation for installation, compatibility, and configuration details.
Top comments (0)