RodriOliveira.AdrGuard

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

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, and versioned container images.

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. GitHub Packages is also available as an authenticated secondary registry. See GitHub Releases or the NuGet badge for the current published version.

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.

Choose the right structure

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

Integrations

The GitHub Marketplace Action and Visual Studio Marketplace extension are published. The moving @v1 tag is published and supports check, index, opt-in review since v1.1.6, and opt-in impact since v1.5.0. In v1.6.0, drift is provided through the CLI/direct-container workflow, alongside new and draft; it is not a composite Action mode. The extension does not bundle the CLI.

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.
• 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 --no-restore
dotnet test AdrGuard.slnx --no-build

Issues and focused pull requests are welcome. Use the issue tracker for proposals and reproducible bugs, SUPPORT.md for support, 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.