ADR tooling for 2026: Log4Brains, adr-tools, and how to pick the right approach

Architecture decision records have been around long enough that the format debates have mostly settled. Whether your team uses Nygard's four-field template, MADR's structured comparison format, or something homegrown, the structural differences between formats are minor compared to the difference between having records and not having them. The format question is a one-hour discussion. The tooling question is what determines whether the practice survives contact with reality.

Tooling matters for a specific reason: ADRs are only useful if the person who needs to understand a decision can find it. A directory of markdown files that nobody knows exists is a documentation theatre — it creates the appearance of a decision trail without providing the actual value. Tooling is how you solve findability, consistency, and the maintenance burden of keeping the index current. The three main tooling approaches each make a different trade-off on those dimensions.

What ADR tooling actually needs to do

Before comparing tools, it's worth being explicit about what problems tooling is actually solving. There are four things a team needs from their ADR system, and different tools address them differently.

Write: making it easy to create a new record in the correct format, numbered correctly, linked to related records, stored in the right location. This is the friction-reduction problem. If creating a record takes more than two minutes, it won't get created in the heat of a sprint cycle.

Store: keeping the records in a location where they survive team turnover, codebase migrations, and build system changes. Git-adjacent storage (a docs/decisions/ directory in the repo) has the best survival rate — it travels with the code it describes and is backed up by normal code backup practices.

Find: allowing someone who doesn't know a decision exists to discover it. Findability requires either a searchable index or a URL structure that's legible enough that people know where to look. A flat directory with 200 markdown files has near-zero findability for someone who just joined the team.

Maintain: updating the status of records when decisions are superseded, deprecated, or amended. Without maintenance, an ADR index accumulates outdated records that give the wrong answer to the people who read them. The ADR lifecycle — how records move from Proposed to Accepted to Superseded — is a tooling problem as much as a process problem.

With those four requirements in mind, here's how the main tooling options stack up.

adr-tools: the CLI approach

adr-tools, created by Nat Pryce (who co-authored the original ADR concept with Michael Nygard), is the most widely used ADR creation tool. It's a Bash script that manages records in a local directory, with commands for common operations: adr new "Use PostgreSQL for the primary data store" creates a numbered file from a template; adr list shows all records; adr link creates cross-references between records.

The default template follows Nygard's format: Title, Status, Context, Decision, Consequences. If your team uses a different template format, you can point adr-tools at a custom template file. The Markdown ADR template variants work well as drop-in replacements.

adr-tools does the write problem well. Creating a record is fast, the numbering is automatic, and the CLI pattern is familiar to developers who live in the terminal. For small teams — two to five engineers working in a single repository — this is often the only tooling you need. The records live in the repo, they're readable in any text editor or on GitHub, and they survive indefinitely without maintenance beyond git commits.

Where adr-tools breaks down:

No browser-accessible view. The records are markdown files in a directory. Reading them requires navigating the repository. For teams where non-engineers need to understand past decisions — product managers, designers, new hires doing orientation — "go find the docs/decisions/ folder" is a barrier. GitHub renders markdown, so a GitHub link works, but it's not the same as a curated, searchable documentation site.

Link management is manual. adr-tools can create links between records, but it doesn't maintain them. If a record is superseded by a later decision, you need to edit both files to reflect the relationship. In practice, teams either update both files carefully (takes discipline at scale) or end up with partial link graphs that are misleading when read.

No cross-repo index. For teams working across multiple repositories — a common pattern for microservices, monorepo-adjacent architectures, or platform teams — adr-tools has no mechanism for creating a unified index. Each repo has its own decisions/ directory; there's no way to ask "what was the cross-cutting API versioning decision that affected all three of these services?"

Bash-only. adr-tools assumes a Unix environment with Bash. Windows teams using WSL can use it, but it's an additional friction point. There are ports and alternatives (adr-log, adr-viewer, various npm packages), each with different command syntax and different maintenance status.

For teams that fit its assumptions — Unix-native, single-repo, engineer-only readership — adr-tools is the right choice. It's simple, it's been maintained for a decade, and its lack of dependencies means it won't break when a build system changes. But those constraints are real, and teams that outgrow them tend to either layer a documentation site on top or migrate to a heavier approach.

Log4Brains: the documentation site approach

Log4Brains takes a different approach: rather than creating records, it publishes them. You write ADRs as markdown files (compatible with any template format), and Log4Brains generates a searchable static documentation site from them, typically deployed to GitHub Pages or Netlify. The interface is a full-text search UI with filtering by status, date, and tags — a genuine solution to the findability problem that adr-tools doesn't address.

The write workflow is compatible with adr-tools. Many teams use adr-tools to create records and Log4Brains to serve them — the CLI handles write friction, the documentation site handles find. Log4Brains ships its own log4brains adr new command as well, which scaffolds records in its expected format with tags and categories.

Log4Brains' strength is the browsing experience. Non-engineers can navigate the documentation site without needing repository access. The search is fast and full-text, so someone asking "why did we pick Kafka over RabbitMQ" can find the answer without knowing which numbered record contains it. For teams documenting cross-cutting platform decisions that affect multiple roles, this is the most important thing a tool can provide.

Where Log4Brains breaks down:

Build chain dependency. Log4Brains is built on Next.js. Publishing the documentation site requires running a Node.js build process. For teams with an established CI/CD pipeline, adding a documentation build step is straightforward. For smaller teams where nobody owns the deployment, this step is often the first thing to break. When Next.js releases a major version with breaking API changes, the Log4Brains build fails silently until someone investigates. Teams that have adopted Log4Brains consistently report that the site "went down" at some point when a dependency update caused a build failure that went unnoticed for weeks.

Maintenance bandwidth requirement. The dependency problem is manageable if someone owns it. For teams with a dedicated DevEx or platform engineering function, updating a docs build pipeline is a normal task. For startups and small teams where every engineer is a product engineer, it tends to accumulate as "someone should fix the ADR site" in the backlog until the site has been dark long enough that nobody remembers to check it.

Configuration overhead for multi-repo. Log4Brains can aggregate records from multiple repositories, but setting up the aggregation requires configuration that's per-deployment, not per-repo. For platforms teams managing a dozen services, the aggregation setup is a meaningful investment.

Log4Brains is the right choice when your team has the following conditions: you need non-engineer readability, you have CI/CD capacity to maintain a documentation build, and you're willing to invest in initial configuration. For teams where those conditions hold — typically engineering-mature companies with a platform or DevEx function — Log4Brains provides the most complete tooling solution currently available.

The MADR directory approach

The MADR format (Markdown Architectural Decision Records) is primarily a template specification, but it's worth discussing as a tooling approach because the MADR community's recommendation is a specific directory pattern that works without any additional tooling dependencies.

The approach: maintain a docs/decisions/ directory with a numbered naming convention (0042-use-postgresql.md) and a hand-maintained README.md index file that links to each record. New records are created by copying a template file; the README is updated manually when records are added. No CLI, no build step, no deployment.

The MADR template itself is more structured than Nygard's four-field format. It includes a "Considered Options" section where each evaluated alternative is listed, a pros/cons table for each option, and explicit links to related decisions. For decisions with multiple evaluated alternatives — which is most architecture decisions worth documenting — the MADR structure produces a more useful record than Nygard's "Context / Decision / Consequences" framing. Our guide to documenting architecture decisions covers the format choice in detail.

The MADR directory approach's strengths are simplicity and survivability. There are no dependencies to break. The README index is a text file that any tool can read. The records are portable — they work with adr-tools, Log4Brains, GitHub's markdown renderer, and any documentation platform the team might adopt later. Teams that start with this approach rarely need to migrate away from it; the records accumulate cleanly over years.

The weakness is findability. A README with 80 links is navigable. A README with 300 links is not. Full-text search requires GitHub's built-in search or a separate step. For teams that outgrow the directory approach, the natural upgrade path is to add a Log4Brains documentation site on top — the records are already compatible.

Wiki integrations: Notion and Confluence

Some teams prefer to keep documentation where non-engineers already are — Notion or Confluence — rather than maintaining a separate records system adjacent to the code. This is a legitimate choice, and Notion ADR templates and Confluence ADR templates exist specifically for this use case.

The main trade-off is git proximity. Records that live in the repo travel with the code they describe — a future engineer can check out a three-year-old commit and see which decisions were active at that point in the codebase's history. Records that live in Notion or Confluence are one database export away from being severed from that history, and they don't show up in code review diffs when decisions are updated. For architecture decisions tied closely to implementation — "why is this function structured this way?" — git-adjacent storage is more useful. For product, process, and organizational decisions that aren't tied to specific code, wiki storage is fine.

Teams that use Notion or Confluence for product and process decisions while using a git-adjacent system for architecture decisions often get the best of both: the wiki gives non-engineers a home for decisions in their natural habitat; the repo gives engineers a traceable history for technical calls.

The choice by team type

Rather than recommending one tool universally, here's a rough decision tree based on team characteristics:

If your team is two to five engineers, working primarily in one repository, with no immediate need for non-engineer access to the ADR index: start with the MADR directory approach or adr-tools. Zero dependencies, zero maintenance burden, everything lives in the repo. Staleness is the main risk at this scale, and it comes from not reviewing records, not from tooling failures.

If your team has non-engineers who need to navigate past decisions, or if you're documenting cross-cutting platform decisions that affect multiple roles: invest in Log4Brains, but budget for the maintenance overhead. Assign explicit ownership of the documentation build to a specific person or team rotation. Without ownership, the site will go dark within a year.

If you're working across multiple repositories and need a unified ADR index: the right answer depends on whether you have the engineering capacity to configure Log4Brains' multi-repo aggregation. If yes, Log4Brains with the aggregation setup is the most complete solution. If not, a convention-based approach — consistent naming and directory structure across all repos, with a single "ADR registry" README that links to each repo's local index — is more likely to survive.

If your team is primarily in Notion or Confluence for documentation: use the wiki for non-technical decisions and a lightweight git-adjacent approach (MADR directory or adr-tools) for architecture decisions. Don't fight the team's existing documentation gravity; build alongside it.

The problem all ADR tools share

The tooling comparison above assumes that decisions are making it into the tool. That assumption is where the argument breaks down in practice.

ADR tooling — all of it, regardless of which approach — is a write layer. It assumes that when a decision is made, someone sits down and writes a record. The tooling reduces the friction of that writing step. adr-tools makes creating the file faster; Log4Brains makes the resulting record more findable; MADR's structured template makes the record more complete. All of these are genuine improvements to the writing experience.

But the decision wasn't made in the writing step. It was made two days earlier, in a ChatGPT session where the engineer evaluated three architectural patterns, explored the trade-offs of each against the team's specific constraints, and concluded with a recommendation. Or it was made in a Claude session where the PM worked through the user research implications of two product approaches. The deliberation — the reasoning, the alternatives, the constraints — happened before anyone opened an ADR template.

The gap between the deliberation and the record is where most decision reasoning disappears. By the time someone sits down to write the ADR, they're summarizing a conclusion rather than documenting a deliberation. The reasoning gets compressed to a paragraph. The alternatives that were genuinely evaluated get reduced to a brief list. The constraint that made alternative B infeasible doesn't make it into the "Consequences" section because it felt obvious at the time.

The result is records that answer "what was decided" but not "why was this the right choice given the constraints at the time" — which is the question that matters when the team encounters the decision six months later and needs to assess whether the constraints have changed.

This is a pre-tooling problem, and it's worth being explicit about it: no ADR tool can help with reasoning that was never extracted from the AI chat sessions where it was produced. The WhyChose extractor sits at this earlier layer — it identifies the AI chat sessions where decisions were deliberated, surfaces the reasoning and alternatives for review, and produces a starting draft that can be written into whichever ADR format the team uses. The relationship isn't competitive with adr-tools or Log4Brains; it's upstream of them.

ADR tooling and the review checklist

Regardless of which tooling approach you adopt, the quality of individual records depends on what goes into them at write time. Our ADR review checklist before merging covers the specific things a reviewer should verify before a record enters the repository: that the context section actually explains the constraint (not just describes the situation), that the alternatives section covers options that were genuinely evaluated (not ones added after the decision was made to provide the appearance of deliberation), and that the status and links are correctly set.

That checklist applies independently of tooling. adr-tools doesn't enforce it; Log4Brains doesn't validate it; the MADR template's structure encourages it but doesn't require it. Record quality is ultimately a process question, not a tooling question — but it's worth building the checklist into your tooling workflow so it becomes the default path.

Where this leaves you

The tooling question doesn't have a universal right answer, but it has a reasonably clear framework:

Small teams and simple repos: MADR directory approach or adr-tools, no build dependencies, records in the repo. The write friction is low enough that the approach survives without a dedicated owner.

Teams with non-engineer readability requirements: Log4Brains with explicit ownership of the deployment pipeline. The documentation site solves a real problem; the maintenance cost is real; both need to be acknowledged.

Teams in wikis: hybrid approach — wiki for non-technical decisions, git-adjacent for architecture. Fight the documentation gravity only where it matters (code-adjacent decisions).

All teams: address the pre-ADR problem. The tooling choice is downstream of the extraction problem — getting the reasoning out of AI chat sessions and into a format that any of these tools can use. The best ADR tooling system in the world produces incomplete records if the deliberation that produced the decision never makes it from the chat session to the template.

The ADR tools that have survived a decade of adoption have done so because they're simple, not because they're comprehensive. The teams with the best decision trails are usually the ones that picked something boring and consistent and maintained it without ceremony — not the ones that optimized for the most sophisticated tooling setup. Pick the approach that fits your team's actual constraints, not the one that looks best in a tooling comparison article.