ADR Guard

Português (Brasil) · Documentation portal · Markdown documentation · Changelog

Understand architectural decisions. Record the reasoning. Keep the history trustworthy.

ADR Guard is a lightweight .NET command-line tool for creating, validating, reviewing, and indexing Architecture Decision Records (ADRs). It keeps decision documentation consistent in local development and CI without making architectural decisions for your team.

What is an ADR?

An ADR is a short document that explains one consequential software decision: the context that required it, the option selected, and the benefits and costs that follow. ADRs help future contributors understand why a system was shaped a certain way—not only what the code does.

New to the practice? Follow the progressive guide:

1. What is an ADR?

2. Why and when should a team use ADRs?

3. Write and validate your first ADR

Related MCP server: AdrMcp

What ADR Guard does

• creates offline Proposed ADRs from Minimal, Extended, or constrained Custom templates;

• validates canonical structure, filenames, statuses, required sections, links, IDs, and supersession relationships;

• supports separate, opt-in MADR 4.0 validation;

• generates a deterministic Markdown index only after validation succeeds;

• supports Git-aware incremental checks, diagnostic baselines, and JSON/SARIF reports;

• offers opt-in, advisory architecture impact analysis from explicit ADR-to-code mappings;

• verifies opt-in architectural drift and fitness evidence without evaluating MSBuild or treating missing evidence as compliance;

• offers opt-in, human-reviewed AI drafting and technical review with explicit providers and context;

• integrates with GitHub Actions, VS Code, versioned container images, and an optional independently packaged MCP server for compatible agents.

Validation confirms deterministic documentation rules. It does not approve technical merit, authorize a decision, or turn AI output into an accepted architecture.

Install

Install the published .NET Tool from NuGet.org:

dotnet tool install --global RodriOliveira.AdrGuard
adr-guard --version

Update an existing installation with dotnet tool update --global RodriOliveira.AdrGuard. CLI 1.10.0 is published on NuGet.org and in its GitHub Release; CLI 1.11.0 is prepared in source but not published. MCP 1.0.1 is published independently on NuGet.org and GitHub Releases. VS Code 1.1.1 remains a source candidate, while 1.1.0 remains the Marketplace version. See the compatibility matrix for the verified channel-by-channel snapshot instead of inferring publication from source metadata or a tag.

Quick start

From the root of an existing repository:

adr-guard init . --adr-directory docs/adr --template minimal
adr-guard new docs/adr --title "Use PostgreSQL as the order system of record"

Edit the generated Proposed ADR to replace its guidance with your real context, decision, and balanced consequences. Review it with the people affected by the choice, then run:

adr-guard check docs/adr
adr-guard index docs/adr

check validates the ADR set. index validates again and creates or updates docs/adr/README.md; new does not update the index automatically. Read the first ADR tutorial for the complete workflow.

Published CLI 1.10.0 includes the read-only adr-guard doctor [repository] command for local CLI, repository, configuration, ADR-directory, .NET, and optional Git diagnostics. It never applies fixes or accesses the network. See the CLI reference; the command is not available in the older CLI 1.9.0 package.

Choose the right structure

See the selection matrix, complete examples, custom template contract, and MADR compatibility guide.

Integrations

See ADR Guard in action

The ADR Guard demo repository shows the complete GitHub Actions validation cycle: an intentionally incomplete Architecture Decision Record fails deterministic check validation, then passes after the document is corrected. Follow the preserved demonstration pull request, or read the GitHub Action guide for the verified runs.

Repository code quality (optional)

Maintainers can enable SonarQube Cloud checks for .NET coverage, pull-request Quality Gates, and controlled HIGH/BLOCKER issue synchronization. This automation is disabled until explicitly configured and does not affect released products or the normal CI.

Internal runtime architecture

The CLI and MCP server are separate executables that reference the same internal AdrGuard.Core class library. Core owns their shared deterministic parsing, validation, configuration, Git inventory, impact, and drift behavior; it does not depend on either executable and is not a standalone product or NuGet package. Published CLI 1.10.0 and candidate CLI 1.11.0 packages include CLI plus Core. Published MCP 1.0.1 packages MCP plus Core without the CLI executable. VS Code and the GitHub Action remain adapters over the CLI contract and do not reimplement Core rules. See ADR 0008 and the compatibility matrix.

Release status (verified on 2026-11-05): CLI 1.10.0 is published on NuGet.org and in its GitHub Release. MCP 1.0.1 is published independently on NuGet.org and in its GitHub Release. VS Code 1.1.0 is published in the Visual Studio Marketplace, while 1.1.1 remains a source candidate. The Action compatibility tag v1 points to the exact v1.10.0 release commit. See the compatibility matrix for exact component boundaries.

The published ADR Guard for VS Code extension includes the visual ADR list plus guided creation, editing, and settings. These screens require the CLI 1.7.0 form contracts. Extension and CLI versions remain independent.

See the extension source and installation guide and the portal's VS Code Visual Guide for the complete interface walkthrough.

Structured ADR creation and editing are implemented for trusted visual clients such as the VS Code extension. A compatible CLI from the 1.7.0 line exposes new <directory> --form and edit <file> --form as versioned JSON stdin/stdout contracts; they are not interactive terminal forms. The traditional new --title workflow remains the human-facing command-line path, including constrained custom templates. See the creation guide, CLI contract reference, and extension guide. Confirm that both the CLI and extension versions providing the visual forms have been published before relying on them.

The GitHub Marketplace Action and Visual Studio Marketplace extension are published. The moving @v1 tag is published, points to v1.10.0, and supports check, index, opt-in review since v1.1.6, opt-in impact since v1.5.0, and read-only drift since v1.10.0; older v1.9.0 does not expose drift. The extension does not bundle the CLI.

The independent MCP 1.0.1 release can be installed with dotnet tool install --global RodriOliveira.AdrGuard.Mcp --version 1.0.1. See MCP configuration, available tools, VS Code integration, and security and permissions.

Agent Skills (P0 + P1)

Eleven portable Agent Skills cover ADR setup, creation, validation, technical review, lifecycle management, CI setup, when to write ADRs, trade-off analysis, supersession, audits, and team adoption. The skills guide agents in using ADR Guard; they do not install the CLI or make architectural approvals.

npx skills add rodri-oliveira-dev/adr-guard --list
npx skills add rodri-oliveira-dev/adr-guard --skill adr-guard-create --agent codex

The eleven Agent Skills are available on the default branch. See installation, safeguards, and scope to select and install only the workflows you need.

Documentation

• Learn: fundamentals, decision categories, lifecycle, and anti-patterns.

• Use: first ADR tutorial, team adoption, and offline creation.

• Reference: CLI and configuration, compatibility matrix, validation and governance, and full technical index.

• Architecture analysis: impact analysis, architectural drift, diagnostic baselines, and AI review.

• MCP: overview, configuration, tool contracts, and security.

• AI boundaries: CLI review has been published since v1.1.2 and runs explicitly as adr-guard review; deterministic policy enforcement may return exit code 4. See the AI review guide, draft privacy, and review security.

• Project architecture: ADR Guard's own generated ADR index.

English is the default documentation language. Brazilian Portuguese pages use .pt-BR.md and are linked from each translated page.

Build and contribute

The project targets .NET 10. To build and test from source:

dotnet restore AdrGuard.slnx
dotnet build AdrGuard.slnx --configuration Release --no-restore
dotnet test --solution AdrGuard.slnx --configuration Release --no-build

Issues and focused pull requests are welcome. Use the issue tracker for scoped proposals and reproducible bugs, GitHub Discussions for questions, early ideas, and showcases, SUPPORT.md for support guidance, and SECURITY.md for private vulnerability reporting.

Releases and license

Published artifacts and exact version notes are available in GitHub Releases. Repository release notes remain under docs/releases.

ADR Guard is licensed under the MIT License.