{
    "version": "https://jsonfeed.org/version/1",
    "title": "Align Blog",
    "home_page_url": "https://docs.align.tech/blog",
    "description": "Engineering decision intelligence from the Align team.",
    "items": [
        {
            "id": "https://docs.align.tech/blog/alternatives-to-adr-tools",
            "content_html": "<p>Architecture decision records are great, and you should write them. But ADR\ntooling shares one assumption: that a decision lives in one file and stays there.\nIf your real decisions live across Slack, GitHub, Jira and Confluence and keep\nchanging, you'll eventually want something that fits that reality. Here are the\nalternatives and how they compare.</p>\n<p>If you haven't picked an ADR tool yet, start with <a class=\"\" href=\"https://docs.align.tech/blog/adr-tools-compared\">ADR tools\ncompared</a>; this piece is about what comes after.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"the-alternatives-by-approach\">The alternatives, by approach<a href=\"https://docs.align.tech/blog/alternatives-to-adr-tools#the-alternatives-by-approach\" class=\"hash-link\" aria-label=\"Direct link to The alternatives, by approach\" title=\"Direct link to The alternatives, by approach\" translate=\"no\">​</a></h2>\n<table><thead><tr><th>Approach</th><th>Examples</th><th>Strength</th><th>Limit</th></tr></thead><tbody><tr><td>Plain ADR files</td><td>adr-tools, Markdown</td><td>Simple, in-repo</td><td>One file, doesn't track change across tools</td></tr><tr><td>Static ADR site</td><td>Log4Brains</td><td>Browsable archive</td><td>Still file-centric, manual updates</td></tr><tr><td>Wiki / docs</td><td>Confluence, Notion</td><td>Familiar, durable</td><td>Goes stale, no conflict detection</td></tr><tr><td>Decision bots</td><td>Slack decision trackers</td><td>Low-friction capture</td><td>Isolated list, no cross-tool links</td></tr><tr><td>Decision graph</td><td><a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a></td><td>Captures + links + catches conflicts across tools</td><td>Not a plain-text-only tool</td></tr></tbody></table>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"what-the-alternatives-are-really-trading-off\">What the alternatives are really trading off<a href=\"https://docs.align.tech/blog/alternatives-to-adr-tools#what-the-alternatives-are-really-trading-off\" class=\"hash-link\" aria-label=\"Direct link to What the alternatives are really trading off\" title=\"Direct link to What the alternatives are really trading off\" translate=\"no\">​</a></h2>\n<p>Every option lands somewhere on two axes: <strong>how low-friction is capture</strong>, and\n<strong>how well does it stay connected and current after capture</strong>.</p>\n<ul>\n<li class=\"\">ADR files and bots are good at one and weak at the other.</li>\n<li class=\"\">Wikis are durable but go stale.</li>\n<li class=\"\">A decision graph is the option built specifically for \"decisions change and\nlive in many places.\"</li>\n</ul>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"when-a-decision-graph-is-the-right-alternative\">When a decision graph is the right alternative<a href=\"https://docs.align.tech/blog/alternatives-to-adr-tools#when-a-decision-graph-is-the-right-alternative\" class=\"hash-link\" aria-label=\"Direct link to When a decision graph is the right alternative\" title=\"Direct link to When a decision graph is the right alternative\" translate=\"no\">​</a></h2>\n<p><a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a> is the alternative when:</p>\n<ul>\n<li class=\"\">Decisions are made across several tools, not just in commits.</li>\n<li class=\"\">Decisions change often enough that any single file goes stale fast.</li>\n<li class=\"\">You have multiple squads and need to catch contradictions between them.</li>\n<li class=\"\">AI agents need to query current decisions, with conflicts already resolved.</li>\n</ul>\n<p>It doesn't replace ADRs. Keep writing ADRs for the big architectural calls and let\nAlign keep them connected to what's actually happening across your tools.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"honest-take\">Honest take<a href=\"https://docs.align.tech/blog/alternatives-to-adr-tools#honest-take\" class=\"hash-link\" aria-label=\"Direct link to Honest take\" title=\"Direct link to Honest take\" translate=\"no\">​</a></h2>\n<p>If you're small and your ADR files are still accurate, you don't need an\nalternative yet, and adopting heavier tooling would be premature. The alternatives\nabove earn their place once \"the decision is in the file\" stops being true,\nwhich for most teams happens somewhere past 50 engineers and a few squads.</p>\n<hr>\n<p><em>Related reading: <a class=\"\" href=\"https://docs.align.tech/blog/adr-tools-compared\">ADR tools compared (2026)</a> and\n<a class=\"\" href=\"https://docs.align.tech/blog/decision-log-software\">Decision log software</a>.</em></p>",
            "url": "https://docs.align.tech/blog/alternatives-to-adr-tools",
            "title": "Alternatives to ADR tools when decisions live across many tools",
            "summary": "ADR tools assume decisions live in one file. When yours live across Slack, GitHub, Jira and Confluence, here are the alternatives and how they compare.",
            "date_modified": "2026-05-27T00:00:00.000Z",
            "author": {
                "name": "The Align Team",
                "url": "https://align.tech"
            },
            "tags": [
                "comparison",
                "adr",
                "alternatives",
                "decision-log"
            ]
        },
        {
            "id": "https://docs.align.tech/blog/align-vs-confluence-decisions",
            "content_html": "<p>If you're an Atlassian shop, Confluence is probably already your system of record,\nand you've likely got a decision-log or ADR space in there. This compares how\nConfluence holds up for engineering decisions versus a decision graph like\n<a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a>, and why the two work well together.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"what-confluence-does-well\">What Confluence does well<a href=\"https://docs.align.tech/blog/align-vs-confluence-decisions#what-confluence-does-well\" class=\"hash-link\" aria-label=\"Direct link to What Confluence does well\" title=\"Direct link to What Confluence does well\" translate=\"no\">​</a></h2>\n<ul>\n<li class=\"\"><strong>It's the official record.</strong> Stable, permissioned, where docs already live.</li>\n<li class=\"\"><strong>Integrates with Jira.</strong> Decisions can reference tickets natively.</li>\n<li class=\"\"><strong>Good for durable, reviewed documents.</strong> Specs, RFCs, runbooks.</li>\n</ul>\n<p>For big, deliberate decisions that warrant a written page, Confluence is a fine\nhome. You should keep using it for those.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"where-confluence-struggles-with-decisions\">Where Confluence struggles with decisions<a href=\"https://docs.align.tech/blog/align-vs-confluence-decisions#where-confluence-struggles-with-decisions\" class=\"hash-link\" aria-label=\"Direct link to Where Confluence struggles with decisions\" title=\"Direct link to Where Confluence struggles with decisions\" translate=\"no\">​</a></h2>\n<ul>\n<li class=\"\"><strong>Decisions don't happen in Confluence.</strong> They happen in Slack, in PR reviews,\nin calls. By the time someone writes the Confluence page (if they ever do), the\ndecision is already old.</li>\n<li class=\"\"><strong>Pages go stale silently.</strong> A decision changes elsewhere; the Confluence page\nkeeps asserting the old answer. Now it's actively misleading.</li>\n<li class=\"\"><strong>Search finds pages, not decisions.</strong> You get documents, not a structured,\nconflict-resolved view of what the org has decided.</li>\n<li class=\"\"><strong>No conflict detection across teams.</strong> Confluence won't tell you that a\ndecision in one team's space contradicts another's.</li>\n<li class=\"\"><strong>Agents get prose.</strong> Coding agents can read a page, but they can't query a\ngraph of current decisions with relationships and conflicts resolved.</li>\n</ul>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"side-by-side\">Side by side<a href=\"https://docs.align.tech/blog/align-vs-confluence-decisions#side-by-side\" class=\"hash-link\" aria-label=\"Direct link to Side by side\" title=\"Direct link to Side by side\" translate=\"no\">​</a></h2>\n<table><thead><tr><th></th><th>Confluence</th><th>Align</th></tr></thead><tbody><tr><td>Capture</td><td>Manual page authoring</td><td>Explicit flag where the decision happens</td></tr><tr><td>Stays current</td><td>Only if someone edits the page</td><td>Yes, tracks supersession across tools</td></tr><tr><td>Cross-tool links</td><td>Jira-centric</td><td>Slack/GitHub/Jira/Teams/Confluence</td></tr><tr><td>Catches conflicts</td><td>No</td><td>Yes, before code ships</td></tr><tr><td>Agent-queryable</td><td>Prose only</td><td>Structured graph via MCP</td></tr><tr><td>Best at</td><td>Durable reviewed docs</td><td>Live decision layer at scale</td></tr></tbody></table>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"they-complement-each-other\">They complement each other<a href=\"https://docs.align.tech/blog/align-vs-confluence-decisions#they-complement-each-other\" class=\"hash-link\" aria-label=\"Direct link to They complement each other\" title=\"Direct link to They complement each other\" translate=\"no\">​</a></h2>\n<p>This isn't rip-and-replace. <a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a> connects to Confluence as\none of its sources, so the decisions captured in Confluence pages become part of\nthe graph alongside the ones from Slack, GitHub and Jira. Keep Confluence for the\nbig written records; let Align keep the whole decision layer connected and current,\nand flag conflicts before they cost you rework.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"when-to-add-align\">When to add Align<a href=\"https://docs.align.tech/blog/align-vs-confluence-decisions#when-to-add-align\" class=\"hash-link\" aria-label=\"Direct link to When to add Align\" title=\"Direct link to When to add Align\" translate=\"no\">​</a></h2>\n<ul>\n<li class=\"\">You're past ~50 engineers, multiple squads, cross-team dependencies.</li>\n<li class=\"\">Your Confluence decision pages have drifted from what teams actually do.</li>\n<li class=\"\">You need AI agents to query current decisions, not read stale wiki pages.</li>\n</ul>\n<hr>\n<p><em>Related reading: <a class=\"\" href=\"https://docs.align.tech/blog/decision-log-software\">Decision log software</a> and\n<a class=\"\" href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide\">Architecture Decision Records: the complete\nguide</a>.</em></p>",
            "url": "https://docs.align.tech/blog/align-vs-confluence-decisions",
            "title": "Align vs Confluence for engineering decisions",
            "summary": "Confluence is the system of record many teams already have. Why it struggles to keep decisions current, and how a decision graph complements it.",
            "date_modified": "2026-05-26T00:00:00.000Z",
            "author": {
                "name": "The Align Team",
                "url": "https://align.tech"
            },
            "tags": [
                "comparison",
                "confluence",
                "decision-log",
                "engineering-decisions"
            ]
        },
        {
            "id": "https://docs.align.tech/blog/align-vs-notion-decision-log",
            "content_html": "<p>Plenty of teams start their decision log as a Notion database. It's a reasonable\nfirst move, and for a small team it can be enough. This is an honest look at where\na Notion decision log works, where it breaks, and when a decision graph like\n<a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a> is the better fit.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"what-notion-does-well\">What Notion does well<a href=\"https://docs.align.tech/blog/align-vs-notion-decision-log#what-notion-does-well\" class=\"hash-link\" aria-label=\"Direct link to What Notion does well\" title=\"Direct link to What Notion does well\" translate=\"no\">​</a></h2>\n<ul>\n<li class=\"\"><strong>Fast to set up.</strong> A database with a row per decision, in minutes.</li>\n<li class=\"\"><strong>Flexible.</strong> Tag, filter, link to other pages, embed context.</li>\n<li class=\"\"><strong>Familiar.</strong> Your team is probably already in Notion.</li>\n</ul>\n<p>If you're a handful of engineers and decisions are infrequent, a Notion table is\na perfectly good decision log. Don't over-engineer it.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"where-a-notion-decision-log-breaks\">Where a Notion decision log breaks<a href=\"https://docs.align.tech/blog/align-vs-notion-decision-log#where-a-notion-decision-log-breaks\" class=\"hash-link\" aria-label=\"Direct link to Where a Notion decision log breaks\" title=\"Direct link to Where a Notion decision log breaks\" translate=\"no\">​</a></h2>\n<ul>\n<li class=\"\"><strong>Manual capture.</strong> Someone has to stop, open Notion, and write the decision.\nAt scale, most decisions never make it in.</li>\n<li class=\"\"><strong>It goes stale.</strong> When a decision changes in Slack or a PR, nobody circles\nback to update the Notion row. The log slowly becomes wrong.</li>\n<li class=\"\"><strong>No links to where work happens.</strong> The Notion entry doesn't connect to the\nGitHub PR, the Jira ticket, or the contradicting decision another team made.</li>\n<li class=\"\"><strong>No conflict detection.</strong> Notion can't tell you that two teams just decided\nopposite things. You find out in code review, or production.</li>\n<li class=\"\"><strong>Hard for agents to use well.</strong> An AI agent can read a Notion page, but it's\nreading prose, not a structured, conflict-resolved decision graph.</li>\n</ul>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"side-by-side\">Side by side<a href=\"https://docs.align.tech/blog/align-vs-notion-decision-log#side-by-side\" class=\"hash-link\" aria-label=\"Direct link to Side by side\" title=\"Direct link to Side by side\" translate=\"no\">​</a></h2>\n<table><thead><tr><th></th><th>Notion decision log</th><th>Align</th></tr></thead><tbody><tr><td>Capture</td><td>Manual, in Notion</td><td>Explicit flag where the decision happens</td></tr><tr><td>Lives where work happens</td><td>No, separate page</td><td>Yes, linked across Slack/GitHub/Jira/Teams/Confluence</td></tr><tr><td>Tracks change over time</td><td>Only if someone edits it</td><td>Yes, supersession chain</td></tr><tr><td>Catches cross-team conflicts</td><td>No</td><td>Yes, before code ships</td></tr><tr><td>Built for AI agents to query</td><td>Prose only</td><td>Structured graph via MCP</td></tr><tr><td>Best at</td><td>Docs, wikis, light logs</td><td>Decision tracking at scale</td></tr></tbody></table>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"when-to-switch\">When to switch<a href=\"https://docs.align.tech/blog/align-vs-notion-decision-log#when-to-switch\" class=\"hash-link\" aria-label=\"Direct link to When to switch\" title=\"Direct link to When to switch\" translate=\"no\">​</a></h2>\n<p>Stay on Notion if you're small and your log is still accurate. Switch when:</p>\n<ul>\n<li class=\"\">You're past ~50 engineers with multiple squads.</li>\n<li class=\"\">Your Notion log has drifted out of sync with reality.</li>\n<li class=\"\">Two teams have shipped contradictory work and nobody caught it in time.</li>\n<li class=\"\">You're putting AI agents to work and need them to query current decisions.</li>\n</ul>\n<p>Notion and Align aren't mutually exclusive. Keep Notion for docs and specs; use\n<a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a> for the live decision layer that has to stay current\nacross tools.</p>\n<hr>\n<p><em>Related reading: <a class=\"\" href=\"https://docs.align.tech/blog/decision-log-software\">Decision log software: how teams track\ndecisions</a> and <a class=\"\" href=\"https://docs.align.tech/blog/why-decisions-get-lost-in-slack\">Why decisions get lost in\nSlack</a>.</em></p>",
            "url": "https://docs.align.tech/blog/align-vs-notion-decision-log",
            "title": "Align vs Notion for tracking engineering decisions",
            "summary": "Notion is great for docs and terrible for keeping engineering decisions current. How a Notion decision log compares to a decision graph, and when to switch.",
            "date_modified": "2026-05-25T00:00:00.000Z",
            "author": {
                "name": "The Align Team",
                "url": "https://align.tech"
            },
            "tags": [
                "comparison",
                "notion",
                "decision-log",
                "engineering-decisions"
            ]
        },
        {
            "id": "https://docs.align.tech/blog/decision-log-software",
            "content_html": "<p>A decision log is a record of the significant choices your team makes: what was\ndecided, why, who was involved, and what changed later. The idea is old and\nsound. The hard part has always been keeping the log current without it becoming\na chore nobody does.</p>\n<p>This is a look at how teams track decisions today, where each approach falls\ndown, and what to look for if you're evaluating decision tracking software.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"the-spectrum-of-decision-logs\">The spectrum of decision logs<a href=\"https://docs.align.tech/blog/decision-log-software#the-spectrum-of-decision-logs\" class=\"hash-link\" aria-label=\"Direct link to The spectrum of decision logs\" title=\"Direct link to The spectrum of decision logs\" translate=\"no\">​</a></h2>\n<p>Most teams move through these in order as they grow:</p>\n<ol>\n<li class=\"\"><strong>The spreadsheet / Notion table.</strong> A row per decision. Works for a while.\nGoes stale the moment people stop updating it, which is about week three.</li>\n<li class=\"\"><strong>Architecture Decision Records.</strong> Markdown files in the repo, one per\ndecision. Better, version-controlled, reviewable. See <a class=\"\" href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide\">the complete\nguide</a>. Still relies on\nsomeone stopping to write the file.</li>\n<li class=\"\"><strong>A Slack /decision bot.</strong> Captures the moment in-channel. Lower friction, but\nthe log lives in a separate list and doesn't connect to the code or tickets.</li>\n<li class=\"\"><strong>Purpose-built decision tracking software.</strong> Captures, links, and surfaces\ndecisions automatically across tools.</li>\n</ol>\n<p>Each step lowers the friction of <em>capturing</em>. The real differentiator at the top\nof the spectrum is what happens <em>after</em> capture.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"why-the-early-options-stall\">Why the early options stall<a href=\"https://docs.align.tech/blog/decision-log-software#why-the-early-options-stall\" class=\"hash-link\" aria-label=\"Direct link to Why the early options stall\" title=\"Direct link to Why the early options stall\" translate=\"no\">​</a></h2>\n<p>Spreadsheets, ADR files, and bots all share one failure mode: the decision gets\ncaptured once and then drifts out of date, because decisions don't stop changing\nafter you log them.</p>\n<p>You log \"we'll use Postgres for the event store.\" Two months later the load\nprofile changes, someone reopens it in a meeting, and the new direction never\nmakes it back to the log. Now the log is actively misleading: it tells new\nengineers and AI agents something that's no longer true.</p>\n<p>The other failure mode is isolation. A decision logged in a spreadsheet has no\nlink to the PR that implemented it, the ticket that tracks it, or the\ncontradicting decision another team just made. It's a record, not a connected\nsource of truth.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"what-to-look-for-in-decision-tracking-software\">What to look for in decision tracking software<a href=\"https://docs.align.tech/blog/decision-log-software#what-to-look-for-in-decision-tracking-software\" class=\"hash-link\" aria-label=\"Direct link to What to look for in decision tracking software\" title=\"Direct link to What to look for in decision tracking software\" translate=\"no\">​</a></h2>\n<p>If you're evaluating tools, the questions that matter at scale:</p>\n<ul>\n<li class=\"\"><strong>Does it capture where decisions happen?</strong> If it requires switching tools and\nfilling a template, adoption will be low. Capture should meet people in Slack,\nGitHub, Jira, Teams and Confluence.</li>\n<li class=\"\"><strong>Does it link across tools?</strong> A decision should connect to the PR, ticket and\ndoc it relates to, not sit in an island.</li>\n<li class=\"\"><strong>Does it track change over time?</strong> Decisions get superseded. The tool should\nshow the chain, not just the latest snapshot.</li>\n<li class=\"\"><strong>Does it catch conflicts?</strong> The highest-value move is flagging when one team's\nnew decision contradicts another's, before code gets written against it.</li>\n<li class=\"\"><strong>Can your AI agents query it?</strong> Increasingly, the consumers of your decision\nlog are coding agents, not just humans. Structured, queryable beats a wiki page.</li>\n<li class=\"\"><strong>Is capture explicit, not passive?</strong> Engineers should control what gets\nrecorded. \"Always listening\" tooling raises trust concerns that kill adoption.</li>\n</ul>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"how-align-fits\">How Align fits<a href=\"https://docs.align.tech/blog/decision-log-software#how-align-fits\" class=\"hash-link\" aria-label=\"Direct link to How Align fits\" title=\"Direct link to How Align fits\" translate=\"no\">​</a></h2>\n<p><a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a> is decision tracking software built for the top of\nthat spectrum. Engineers flag decisions with an explicit action where they happen,\nAlign links them into a graph across your tools, tracks how they change, and\nsurfaces cross-team conflicts before they ship. Humans and AI agents query the\nsame source of truth.</p>\n<p>It's worth being clear about scale: if you're a small, tightly-knit team that can\n\"just ask,\" a spreadsheet or a few ADRs may be all you need. The pain Align\nsolves shows up at 50+ engineers, multiple squads, and cross-team dependencies,\nwhere informal communication has hit its ceiling and decisions are slipping\nthrough the cracks.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"where-to-start\">Where to start<a href=\"https://docs.align.tech/blog/decision-log-software#where-to-start\" class=\"hash-link\" aria-label=\"Direct link to Where to start\" title=\"Direct link to Where to start\" translate=\"no\">​</a></h2>\n<p>Audit your current log honestly: open it and check how many entries are still\naccurate. If it's drifted, that's the signal that capture-and-forget isn't enough\nand you need something that keeps decisions connected to reality. <a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">See how Align\nworks</a>.</p>\n<hr>\n<p><em>Align captures engineering decisions across Slack, GitHub, Jira, Teams and\nConfluence, links them into a queryable graph, and catches cross-team conflicts\nbefore they ship. Related reading: <a class=\"\" href=\"https://docs.align.tech/blog/why-decisions-get-lost-in-slack\">Why decisions get lost in\nSlack</a>.</em></p>",
            "url": "https://docs.align.tech/blog/decision-log-software",
            "title": "Decision log software: how engineering teams actually track decisions",
            "summary": "What a decision log is, why spreadsheets and bots don't scale, and what to look for in decision tracking software for engineering teams in 2026.",
            "date_modified": "2026-05-24T00:00:00.000Z",
            "author": {
                "name": "The Align Team",
                "url": "https://align.tech"
            },
            "tags": [
                "decision-log",
                "decision-tracking",
                "engineering-decisions",
                "tools"
            ]
        },
        {
            "id": "https://docs.align.tech/blog/adr-tools-compared",
            "content_html": "<p>There's no dominant tool for architecture decision records, which is a useful\nsignal in itself: the field is young and most teams are still figuring out what\nthey actually need. This is an honest comparison of the real options, what each\nis good at, and the problem none of them solve.</p>\n<p>If you're new to ADRs, start with <a class=\"\" href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide\">the complete\nguide</a> and come back here\nwhen you're picking tooling.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"the-options-at-a-glance\">The options at a glance<a href=\"https://docs.align.tech/blog/adr-tools-compared#the-options-at-a-glance\" class=\"hash-link\" aria-label=\"Direct link to The options at a glance\" title=\"Direct link to The options at a glance\" translate=\"no\">​</a></h2>\n<table><thead><tr><th>Tool</th><th>Type</th><th>Stores</th><th>Best for</th><th>Watch out for</th></tr></thead><tbody><tr><td>Plain Markdown in <code>/docs/adr</code></td><td>Convention</td><td>Repo</td><td>Almost everyone, to start</td><td>No tooling means no nudges</td></tr><tr><td><a href=\"https://github.com/npryce/adr-tools\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">adr-tools</a></td><td>Bash CLI</td><td>Repo</td><td>Solo / small repos, zero deps</td><td>Bash only, unmaintained-ish</td></tr><tr><td>dotnet-adr</td><td>.NET global tool</td><td>Repo</td><td>.NET shops, templating</td><td>Tied to the .NET toolchain</td></tr><tr><td><a href=\"https://github.com/thomvaill/log4brains\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Log4Brains</a></td><td>CLI + static site</td><td>Repo + site</td><td>Teams wanting a browsable archive</td><td>Another site to host</td></tr><tr><td>adr-manager</td><td>Web UI over GitHub</td><td>Repo (via UI)</td><td>Non-CLI contributors</td><td>Web app dependency</td></tr><tr><td><a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a></td><td>Decision graph</td><td>Across all tools</td><td>Teams past the \"ADRs go stale\" wall</td><td>Not a plain-text-only tool</td></tr></tbody></table>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"plain-markdown-the-honest-default\">Plain Markdown (the honest default)<a href=\"https://docs.align.tech/blog/adr-tools-compared#plain-markdown-the-honest-default\" class=\"hash-link\" aria-label=\"Direct link to Plain Markdown (the honest default)\" title=\"Direct link to Plain Markdown (the honest default)\" translate=\"no\">​</a></h2>\n<p>For most teams, a <code>docs/adr/</code> folder with numbered Markdown files and the Nygard\ntemplate is enough to start, and you shouldn't let anyone talk you out of it. Zero\ndependencies, lives with the code, reviewable in PRs, readable by humans and\nagents. The downside is purely that there's no tooling to prompt you, so it\nrelies on discipline.</p>\n<p>Start here. Adopt a tool only when you feel a specific pain Markdown can't solve.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"adr-tools-nygard\">adr-tools (Nygard)<a href=\"https://docs.align.tech/blog/adr-tools-compared#adr-tools-nygard\" class=\"hash-link\" aria-label=\"Direct link to adr-tools (Nygard)\" title=\"Direct link to adr-tools (Nygard)\" translate=\"no\">​</a></h2>\n<p>The original. Bash scripts that scaffold and number ADRs in the Nygard format.\nGreat if you're in a Unix shell all day and want the numbering and superseding\nlinks handled for you. It's lightweight to the point of being barely a tool,\nwhich is the appeal. Maintenance has been quiet, so don't expect new features.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"dotnet-adr\">dotnet-adr<a href=\"https://docs.align.tech/blog/adr-tools-compared#dotnet-adr\" class=\"hash-link\" aria-label=\"Direct link to dotnet-adr\" title=\"Direct link to dotnet-adr\" translate=\"no\">​</a></h2>\n<p>A .NET global tool with templating support. If your shop is .NET-first, this fits\nyour existing toolchain and gives you more structure than the bash scripts. Less\nrelevant outside that ecosystem.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"log4brains\">Log4Brains<a href=\"https://docs.align.tech/blog/adr-tools-compared#log4brains\" class=\"hash-link\" aria-label=\"Direct link to Log4Brains\" title=\"Direct link to Log4Brains\" translate=\"no\">​</a></h2>\n<p>Logs ADRs from your editor and publishes them as a static knowledge-base site.\nThis is the pick if you want a browsable, searchable archive your whole org can\nread without cloning the repo. The trade-off is you're now hosting and\nmaintaining that site.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"adr-manager\">adr-manager<a href=\"https://docs.align.tech/blog/adr-tools-compared#adr-manager\" class=\"hash-link\" aria-label=\"Direct link to adr-manager\" title=\"Direct link to adr-manager\" translate=\"no\">​</a></h2>\n<p>A web UI for creating and managing ADRs stored as Markdown in GitHub. Good for\nbringing in non-CLI contributors (PMs, architects who don't live in a terminal).\nYou're depending on the web app, but the underlying files stay in your repo.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"the-problem-none-of-them-solve\">The problem none of them solve<a href=\"https://docs.align.tech/blog/adr-tools-compared#the-problem-none-of-them-solve\" class=\"hash-link\" aria-label=\"Direct link to The problem none of them solve\" title=\"Direct link to The problem none of them solve\" translate=\"no\">​</a></h2>\n<p>Every tool above is a better way to <em>write and store</em> ADRs. None of them solve the\nreason ADRs fail in practice: decisions don't stay in the file.</p>\n<p>You write <code>ADR 0007</code>. Six weeks later the decision changes in a Slack thread, a\ndifferent squad ships against the old assumption, and a Jira ticket quietly\ncontradicts the ADR. Nobody updates the file, because the decision happened\nsomewhere the ADR tool can't see. Now you have two sources of truth and two teams\nwho each think they're right.</p>\n<p>The ADR tools all assume the decision lives in one place (the file) and stays\nthere. Real decisions live across Slack, GitHub, Jira and Confluence, and they\nmove. That's the gap.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"when-you-outgrow-adr-tooling\">When you outgrow ADR tooling<a href=\"https://docs.align.tech/blog/adr-tools-compared#when-you-outgrow-adr-tooling\" class=\"hash-link\" aria-label=\"Direct link to When you outgrow ADR tooling\" title=\"Direct link to When you outgrow ADR tooling\" translate=\"no\">​</a></h2>\n<p><a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a> is the next step when you hit that wall. Instead of\nstoring decisions in one file format, it captures them where they actually happen,\nlinks them into a graph across all your tools, and flags when a new decision\ncontradicts an existing one before it ships. It complements ADRs rather than\nreplacing them: keep writing ADRs for the big architectural calls, and let Align\nkeep them connected to reality.</p>\n<p>The signal that you're ready: you're already feeling the \"wait, didn't we decide\nthis differently in Slack last month?\" pain, and your ADRs are drifting out of\nsync with what the org actually does.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"recommendation\">Recommendation<a href=\"https://docs.align.tech/blog/adr-tools-compared#recommendation\" class=\"hash-link\" aria-label=\"Direct link to Recommendation\" title=\"Direct link to Recommendation\" translate=\"no\">​</a></h2>\n<ul>\n<li class=\"\"><strong>Just starting?</strong> Plain Markdown + the Nygard template. Don't overthink it.</li>\n<li class=\"\"><strong>Want a browsable archive?</strong> Log4Brains.</li>\n<li class=\"\"><strong>.NET shop?</strong> dotnet-adr.</li>\n<li class=\"\"><strong>ADRs going stale across tools, multiple squads stepping on each other?</strong> That's\nthe decision-graph problem. <a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">See how Align handles it</a>.</li>\n</ul>\n<hr>\n<p><em>Align captures engineering decisions across the tools your team already uses and\ncatches cross-team conflicts before they ship. Related reading: <a class=\"\" href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide\">Architecture\nDecision Records: the complete\nguide</a>.</em></p>",
            "url": "https://docs.align.tech/blog/adr-tools-compared",
            "title": "ADR tools compared (2026): from CLI scripts to decision graphs",
            "summary": "A practical comparison of architecture decision record tools in 2026: adr-tools, dotnet-adr, Log4Brains, adr-manager, plain Markdown, and when you outgrow all of them.",
            "date_modified": "2026-05-23T00:00:00.000Z",
            "author": {
                "name": "The Align Team",
                "url": "https://align.tech"
            },
            "tags": [
                "adr",
                "architecture-decision-records",
                "tools",
                "comparison"
            ]
        },
        {
            "id": "https://docs.align.tech/blog/shared-context-for-ai-coding-agents",
            "content_html": "<p>Your AI agents have most of the inputs they need. They can read the codebase,\nthe tests, the types, the git history, the open PRs. All of that is\ndeterministic and right there.</p>\n<p>What they can't see is <em>why</em>. Why the retry count is three and not five. Why this\nservice owns that table. Why the team walked back the obvious approach six weeks\nago. That reasoning lives in a Slack thread, a meeting nobody recorded, a Jira\ncomment, or someone's head. The agent never sees it, so it ships code against\ndecisions it doesn't know exist.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"context-engineering-is-the-actual-bottleneck\">Context engineering is the actual bottleneck<a href=\"https://docs.align.tech/blog/shared-context-for-ai-coding-agents#context-engineering-is-the-actual-bottleneck\" class=\"hash-link\" aria-label=\"Direct link to Context engineering is the actual bottleneck\" title=\"Direct link to Context engineering is the actual bottleneck\" translate=\"no\">​</a></h2>\n<p>The capability of frontier models stopped being the limiting factor a while ago.\nAs swyx puts it, context engineering is the new prompt engineering: what matters\nnow is the quality of context the agent operates on, not how clever the model is.\nSimon Maple frames the same shift as \"CI/CD for context\", the focus moving from\nmanaging code to managing the context around it.</p>\n<p>Both are pointing at the same gap. We've gotten good at giving agents the\ndeterministic inputs. We've done almost nothing about the one input that's\nhardest to capture and most expensive to miss: the decisions.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"why-just-put-it-in-claudemd-isnt-enough\">Why \"just put it in CLAUDE.md\" isn't enough<a href=\"https://docs.align.tech/blog/shared-context-for-ai-coding-agents#why-just-put-it-in-claudemd-isnt-enough\" class=\"hash-link\" aria-label=\"Direct link to Why &quot;just put it in CLAUDE.md&quot; isn't enough\" title=\"Direct link to Why &quot;just put it in CLAUDE.md&quot; isn't enough\" translate=\"no\">​</a></h2>\n<p>A <code>CLAUDE.md</code> or a rules file is a great start. But it's a static snapshot, hand-\nmaintained, and it captures conventions, not the live stream of decisions your\norg makes every day. It tells the agent your house style. It doesn't tell the\nagent that yesterday a different squad decided to deprecate the endpoint this\nagent is about to build against.</p>\n<p>Decisions aren't static config. They happen continuously, across tools, and they\nchange. A useful context layer for agents has to track that, not freeze it.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"agents-cant-just-ask\">\"Agents can't just ask\"<a href=\"https://docs.align.tech/blog/shared-context-for-ai-coding-agents#agents-cant-just-ask\" class=\"hash-link\" aria-label=\"Direct link to &quot;Agents can't just ask&quot;\" title=\"Direct link to &quot;Agents can't just ask&quot;\" translate=\"no\">​</a></h2>\n<p>Here's the thing well-run teams discover. Small teams handle missing context by\nasking each other, and it works fine. But an agent can't tap a colleague on the\nshoulder. Even a team with great human communication has to give its agents\nstructured context explicitly, because the agent has no informal channel to fall\nback on.</p>\n<p>So the moment you put agents into a real org, you need the decision context\nwritten down and queryable, whether or not your humans needed it before. The graph\n<em>is</em> the organizational memory agents are missing.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"raw-mcp-access-isnt-the-answer-either\">Raw MCP access isn't the answer either<a href=\"https://docs.align.tech/blog/shared-context-for-ai-coding-agents#raw-mcp-access-isnt-the-answer-either\" class=\"hash-link\" aria-label=\"Direct link to Raw MCP access isn't the answer either\" title=\"Direct link to Raw MCP access isn't the answer either\" translate=\"no\">​</a></h2>\n<p>The tempting shortcut is to point the agent at your tools over MCP and let it\nread everything. The problem is volume and noise. An agent querying raw Slack is\nsifting 50,000 unstructured messages to maybe reconstruct one decision, burning\ntokens and still missing the contradictions.</p>\n<p>An agent querying a decision graph gets the opposite: structured decisions, with\nconflicts and relationships already resolved. One query returns \"here's the\ndecision, here's what superseded it, here's the conflict with the payments\nteam\", instead of thousands of raw messages it has to interpret.</p>\n<p>That's the difference between giving an agent a firehose and giving it an answer.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"what-this-looks-like-in-practice\">What this looks like in practice<a href=\"https://docs.align.tech/blog/shared-context-for-ai-coding-agents#what-this-looks-like-in-practice\" class=\"hash-link\" aria-label=\"Direct link to What this looks like in practice\" title=\"Direct link to What this looks like in practice\" translate=\"no\">​</a></h2>\n<p><a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a> sits in the context pipeline as the decision source\nof truth:</p>\n<ul>\n<li class=\"\">Engineers capture decisions where they happen (Slack, GitHub, Jira, Teams,\nConfluence) with an explicit action, so nothing is passively surveilled.</li>\n<li class=\"\">Align links them into a graph, tracks how they change, and resolves conflicts.</li>\n<li class=\"\">Your agents query the graph through MCP and get structured, current decision\ncontext, the deterministic input they were missing.</li>\n</ul>\n<p>The payoff is agents that build <em>with</em> your org's decisions instead of around\nthem, and humans who stop discovering the contradiction in code review.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"where-to-start\">Where to start<a href=\"https://docs.align.tech/blog/shared-context-for-ai-coding-agents#where-to-start\" class=\"hash-link\" aria-label=\"Direct link to Where to start\" title=\"Direct link to Where to start\" translate=\"no\">​</a></h2>\n<p>If you're already running coding agents, the fastest way to feel this gap is to\nask one to explain a non-obvious design choice in your codebase. It'll guess,\nbecause the reasoning was never anywhere it could read. Closing that gap is what\n<a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a> is for.</p>\n<hr>\n<p><em>Align gives engineering teams and their AI agents one shared, authoritative\nsource of truth for the decisions behind the code. Related reading: <a class=\"\" href=\"https://docs.align.tech/blog/why-decisions-get-lost-in-slack\">Why\ndecisions get lost in Slack</a> and\n<a class=\"\" href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide\">Architecture Decision Records: the complete\nguide</a>.</em></p>",
            "url": "https://docs.align.tech/blog/shared-context-for-ai-coding-agents",
            "title": "Shared context for AI coding agents: the part your agents can't see",
            "summary": "AI coding agents ship code from decisions they can't see. Why context engineering is the real bottleneck, and how a decision graph gives agents the organizational memory they're missing.",
            "date_modified": "2026-05-22T00:00:00.000Z",
            "author": {
                "name": "The Align Team",
                "url": "https://align.tech"
            },
            "tags": [
                "ai-agents",
                "context-engineering",
                "engineering-decisions",
                "llm"
            ]
        },
        {
            "id": "https://docs.align.tech/blog/why-decisions-get-lost-in-slack",
            "content_html": "<p>Most of your team's real decisions don't happen in a doc. They happen in Slack.\nTwo engineers are debating a bug, a third jumps in, someone says \"ok let's go\nwith option 1,\" and that's it. The decision is made. Then the thread scrolls\naway and the reasoning goes with it.</p>\n<p>A few weeks later someone asks \"wait, why does this work this way?\" and nobody\ncan find the answer. It's in Slack somewhere. Good luck.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"this-is-a-scale-problem-not-a-discipline-problem\">This is a scale problem, not a discipline problem<a href=\"https://docs.align.tech/blog/why-decisions-get-lost-in-slack#this-is-a-scale-problem-not-a-discipline-problem\" class=\"hash-link\" aria-label=\"Direct link to This is a scale problem, not a discipline problem\" title=\"Direct link to This is a scale problem, not a discipline problem\" translate=\"no\">​</a></h2>\n<p>If you've got eight engineers in one room, you don't feel this. Someone forgets\nwhy a thing was built a certain way, they ask, somebody remembers. Small,\nwell-run teams genuinely do \"just ask\" and it works.</p>\n<p>It breaks at scale. Past 50 engineers, multiple squads, and cross-team\ndependencies, \"just ask\" stops working because:</p>\n<ul>\n<li class=\"\">The person who made the decision is on a different team, or has left.</li>\n<li class=\"\">The decision touched three squads and none of them saw the others' context.</li>\n<li class=\"\">Nobody remembers which channel, which thread, which week.</li>\n</ul>\n<p>So the failure isn't that your team is sloppy. It's that informal communication\nhas a ceiling, and you've grown past it. The tools that work at ten people quietly\nstop working at a hundred, and nobody notices until the rework starts.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"why-slack-specifically-buries-decisions\">Why Slack specifically buries decisions<a href=\"https://docs.align.tech/blog/why-decisions-get-lost-in-slack#why-slack-specifically-buries-decisions\" class=\"hash-link\" aria-label=\"Direct link to Why Slack specifically buries decisions\" title=\"Direct link to Why Slack specifically buries decisions\" translate=\"no\">​</a></h2>\n<p>Slack is brilliant for conversation and terrible for memory, by design:</p>\n<ul>\n<li class=\"\"><strong>Channels move too fast.</strong> An active channel does hundreds of messages a day.\nA real decision is on screen for an hour, then it's gone.</li>\n<li class=\"\"><strong>Threads are where knowledge goes to hide.</strong> The most detailed technical\ndiscussion happens in threads, which don't show in the main channel. If you\nweren't in the thread, you'll never know it existed.</li>\n<li class=\"\"><strong>Search needs the magic words.</strong> Slack search works if you remember the exact\nphrasing. Decisions made conversationally (\"yeah let's just do the simpler\none\") have no searchable keywords.</li>\n<li class=\"\"><strong>Nothing separates signal from chatter.</strong> There's no native way to mark \"this\nmessage is a decision\" versus \"this is a lunch order.\"</li>\n</ul>\n<p>The result is a workspace full of decisions with zero traceability. Hundreds of\ndecisions, no trail back to any of them.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"the-usual-fixes-and-why-they-dont-hold\">The usual fixes, and why they don't hold<a href=\"https://docs.align.tech/blog/why-decisions-get-lost-in-slack#the-usual-fixes-and-why-they-dont-hold\" class=\"hash-link\" aria-label=\"Direct link to The usual fixes, and why they don't hold\" title=\"Direct link to The usual fixes, and why they don't hold\" translate=\"no\">​</a></h2>\n<p><strong>\"Just write an ADR / Confluence page.\"</strong> Right instinct, and you should. But\nthe decision happened in Slack, and asking everyone to stop, switch tools, and\nwrite it up is friction. Most of the time it doesn't happen, and when the\ndecision later changes in another Slack thread, the doc goes stale and now you\nhave two contradictory sources of truth.</p>\n<p><strong>\"Pin important messages.\"</strong> Pins don't scale past a handful and nobody curates\nthem.</p>\n<p><strong>\"Use a /decision bot.\"</strong> Closer. It captures the moment, but it's still manual,\nit lives in a separate list, and it doesn't connect to the decision when it\nchanges in GitHub or Jira later.</p>\n<p>The pattern: every fix asks a human to do extra work at exactly the moment they're\ntrying to move on. That's why decisions keep slipping through.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"what-actually-fixes-it\">What actually fixes it<a href=\"https://docs.align.tech/blog/why-decisions-get-lost-in-slack#what-actually-fixes-it\" class=\"hash-link\" aria-label=\"Direct link to What actually fixes it\" title=\"Direct link to What actually fixes it\" translate=\"no\">​</a></h2>\n<p>The decision needs to be captured where it happens, linked to everywhere it's\nrelevant, and flagged when something later contradicts it. Three properties:</p>\n<ol>\n<li class=\"\"><strong>Capture in place.</strong> No tool-switching, no template. The decision gets\nrecorded from the conversation it happened in.</li>\n<li class=\"\"><strong>One graph across tools.</strong> The Slack decision links to the GitHub PR that\nimplements it, the Jira ticket that tracks it, the Confluence page that\ndocuments it. One source of truth, not five.</li>\n<li class=\"\"><strong>Catch contradictions before they ship.</strong> When a new decision in one squad's\nchannel contradicts an existing one in another's, someone hears about it\nbefore two teams build against each other.</li>\n</ol>\n<p>That last one is the part no doc or bot gives you, and it's the part that saves\nthe weeks of rework.</p>\n<p>This is what we built <a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a> to do. You connect Slack (and\nGitHub, Jira, Teams, Confluence), engineers flag decisions with a quick explicit\naction (no passive surveillance, you stay in control of what's captured), and\nAlign links them into a graph your team and your AI agents can both query. When\ntwo teams head in contradictory directions, it surfaces the conflict early.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"where-to-start\">Where to start<a href=\"https://docs.align.tech/blog/why-decisions-get-lost-in-slack#where-to-start\" class=\"hash-link\" aria-label=\"Direct link to Where to start\" title=\"Direct link to Where to start\" translate=\"no\">​</a></h2>\n<p>You don't have to boil the ocean. Start by noticing how often someone on your\nteam asks \"didn't we already decide this?\" or \"why does this work this way?\" Those\nquestions are the cost of lost decisions, and once you start counting them you'll\nsee how much they add up to.</p>\n<p>When you're ready to stop paying that cost, <a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">see how Align works</a>.</p>\n<hr>\n<p><em>Align captures engineering decisions across Slack, GitHub, Jira, Teams and\nConfluence, links them into a queryable graph, and catches cross-team conflicts\nbefore they ship. Related reading: <a class=\"\" href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide\">Architecture Decision Records: the complete\nguide</a>.</em></p>",
            "url": "https://docs.align.tech/blog/why-decisions-get-lost-in-slack",
            "title": "Why decisions get lost in Slack (and how to fix it)",
            "summary": "Slack is where engineering decisions happen and where they disappear. Why threads, search and channel speed bury the decisions that matter, and what to do about it as your team scales.",
            "date_modified": "2026-05-21T00:00:00.000Z",
            "author": {
                "name": "The Align Team",
                "url": "https://align.tech"
            },
            "tags": [
                "slack",
                "engineering-decisions",
                "tribal-knowledge",
                "documentation"
            ]
        },
        {
            "id": "https://docs.align.tech/blog/architecture-decision-records-complete-guide",
            "content_html": "<p>An <strong>architecture decision record</strong> (ADR) is a short document that captures one\nsignificant decision: what you decided, why, what you considered, and what it\ncosts you later. One decision per file. Plain text, in the repo, next to the\ncode it governs.</p>\n<p>That's the whole idea. The reason ADRs are having a comeback in 2026 isn't\nnostalgia. It's that AI coding agents now write a lot of your code, and an agent\nthat can't see <em>why</em> something was built a certain way will happily refactor the\nreason away.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"why-adrs-are-back\">Why ADRs are back<a href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide#why-adrs-are-back\" class=\"hash-link\" aria-label=\"Direct link to Why ADRs are back\" title=\"Direct link to Why ADRs are back\" translate=\"no\">​</a></h2>\n<p>For years ADRs were a nice-to-have that most teams skipped. Then two things\nhappened.</p>\n<p>First, teams got bigger and more distributed. Past 50 engineers and a few\nsquads, you can't \"just ask\" anymore. The person who knows why the payment\nservice retries exactly three times has left, or is on holiday, or is in a\ndifferent timezone. The decision lives in someone's head, or in a Slack thread\nthat scrolled off three months ago.</p>\n<p>Second, agents arrived. An AI agent refactoring \"verbose\" retry logic doesn't\nknow that code was written that way after a Black Friday incident double-charged\nthousands of customers. The verbosity <em>was</em> the decision. Strip it and you\nreintroduce the bug. The agent had no way to see the reasoning, because the\nreasoning was never written down anywhere it could read.</p>\n<p>ADRs fix the upstream problem: they put the reasoning somewhere durable, in\nplain text, where both a new hire and an agent can find it.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"what-goes-in-an-adr\">What goes in an ADR<a href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide#what-goes-in-an-adr\" class=\"hash-link\" aria-label=\"Direct link to What goes in an ADR\" title=\"Direct link to What goes in an ADR\" translate=\"no\">​</a></h2>\n<p>Keep it short. If it takes more than ten minutes to write, the format is\nfighting you. The classic Michael Nygard structure is still the best starting\npoint:</p>\n<ul>\n<li class=\"\"><strong>Title</strong> - a short noun phrase. \"Use Postgres for the event store.\"</li>\n<li class=\"\"><strong>Status</strong> - proposed / accepted / superseded.</li>\n<li class=\"\"><strong>Context</strong> - the forces in play. What's true right now that makes this a\nreal decision and not an obvious one.</li>\n<li class=\"\"><strong>Decision</strong> - what you're actually doing, stated plainly.</li>\n<li class=\"\"><strong>Consequences</strong> - what gets easier, what gets harder, what you're now\ncommitted to. This is the part future-you actually needs.</li>\n</ul>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"a-copy-paste-adr-template\">A copy-paste ADR template<a href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide#a-copy-paste-adr-template\" class=\"hash-link\" aria-label=\"Direct link to A copy-paste ADR template\" title=\"Direct link to A copy-paste ADR template\" translate=\"no\">​</a></h2>\n<div class=\"language-markdown codeBlockContainer_WW7a theme-code-block\" style=\"--prism-color:#F8F8F2;--prism-background-color:#282A36\"><div class=\"codeBlockContent_WPHN\"><pre tabindex=\"0\" class=\"prism-code language-markdown codeBlock_WSvM thin-scrollbar\" style=\"color:#F8F8F2;background-color:#282A36\"><code class=\"codeBlockLines_a5KI\"><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token title important punctuation\" style=\"color:rgb(248, 248, 242)\">#</span><span class=\"token title important\"> ADR 0007: Use Postgres for the event store</span><span class=\"token plain\"></span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\" style=\"display:inline-block\"></span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\"></span><span class=\"token list punctuation\" style=\"color:rgb(248, 248, 242)\">-</span><span class=\"token plain\"> Status: Accepted</span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\"></span><span class=\"token list punctuation\" style=\"color:rgb(248, 248, 242)\">-</span><span class=\"token plain\"> Date: 2026-05-20</span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\"></span><span class=\"token list punctuation\" style=\"color:rgb(248, 248, 242)\">-</span><span class=\"token plain\"> Deciders: platform team</span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\" style=\"display:inline-block\"></span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\"></span><span class=\"token title important punctuation\" style=\"color:rgb(248, 248, 242)\">##</span><span class=\"token title important\"> Context</span><span class=\"token plain\"></span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\" style=\"display:inline-block\"></span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\">We need durable, ordered, queryable storage for domain events. We already run</span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\">Postgres in production and the team knows it well. Kafka was considered but adds</span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\">operational surface we don't have the headcount to own yet.</span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\" style=\"display:inline-block\"></span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\"></span><span class=\"token title important punctuation\" style=\"color:rgb(248, 248, 242)\">##</span><span class=\"token title important\"> Decision</span><span class=\"token plain\"></span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\" style=\"display:inline-block\"></span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\">Use a single Postgres table as the event store, with a monotonic sequence</span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\">column for ordering. Revisit if event volume exceeds ~10k/sec sustained.</span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\" style=\"display:inline-block\"></span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\"></span><span class=\"token title important punctuation\" style=\"color:rgb(248, 248, 242)\">##</span><span class=\"token title important\"> Consequences</span><span class=\"token plain\"></span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\" style=\"display:inline-block\"></span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\"></span><span class=\"token list punctuation\" style=\"color:rgb(248, 248, 242)\">-</span><span class=\"token plain\"> Easier: one less system to operate, transactional writes alongside state.</span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\"></span><span class=\"token list punctuation\" style=\"color:rgb(248, 248, 242)\">-</span><span class=\"token plain\"> Harder: we own partitioning/retention ourselves; no built-in fan-out.</span><br></div><div class=\"token-line\" style=\"color:#F8F8F2\"><span class=\"token plain\"></span><span class=\"token list punctuation\" style=\"color:rgb(248, 248, 242)\">-</span><span class=\"token plain\"> Committed: consumers read by sequence, so that column is now load-bearing.</span><br></div></code></pre></div></div>\n<p>Number them sequentially (<code>0001</code>, <code>0002</code>...). Never delete one. When a decision\nchanges, write a new ADR that supersedes the old one and link them. The <em>chain</em>\nof decisions is the value, not any single record.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"adr-tools-compared\">ADR tools, compared<a href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide#adr-tools-compared\" class=\"hash-link\" aria-label=\"Direct link to ADR tools, compared\" title=\"Direct link to ADR tools, compared\" translate=\"no\">​</a></h2>\n<p>There's no dominant tool, which tells you the field is young. What exists:</p>\n<table><thead><tr><th>Tool</th><th>What it is</th><th>Good for</th></tr></thead><tbody><tr><td><code>adr-tools</code> (Nygard)</td><td>Bash CLI, Nygard format</td><td>Solo / small repos, zero deps</td></tr><tr><td><code>dotnet-adr</code></td><td>.NET global tool, templates</td><td>.NET shops</td></tr><tr><td>Log4Brains</td><td>Logs ADRs, publishes a static site</td><td>Teams that want a browsable archive</td></tr><tr><td>adr-manager</td><td>Web UI over Markdown in GitHub</td><td>Non-CLI contributors</td></tr><tr><td>Just Markdown in <code>/docs/adr</code></td><td>No tool at all</td><td>Most teams, honestly</td></tr></tbody></table>\n<p>For a lot of teams, a folder of Markdown files and a numbering convention is\nenough to start. The tooling question only matters once you hit the real\nproblem, which isn't <em>writing</em> ADRs.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"the-real-problem-adrs-go-stale\">The real problem: ADRs go stale<a href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide#the-real-problem-adrs-go-stale\" class=\"hash-link\" aria-label=\"Direct link to The real problem: ADRs go stale\" title=\"Direct link to The real problem: ADRs go stale\" translate=\"no\">​</a></h2>\n<p>Here's what nobody tells you when they recommend ADRs. The hard part isn't the\ntemplate. It's that decisions don't stay in the ADR file.</p>\n<p>You write <code>ADR 0007: use Postgres for the event store</code>. Six weeks later someone\nproposes Kafka again in a Slack thread, a different squad ships against the old\nassumption, and a ticket in Jira quietly contradicts the ADR. Nobody updated\nthe file, because updating the file is friction and the decision happened\nsomewhere else.</p>\n<p>So you end up with two sources of truth: the ADR that says one thing, and the\nactual current state of the org that says another. Both teams think they're\nright. Neither sees the conflict until it shows up as rework.</p>\n<p>This is the gap we built <a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a> to close. ADRs are the\nright instinct: write decisions down. The missing piece is keeping them\nconnected to where decisions actually get made and changed (Slack, GitHub,\nJira, Confluence, calls) and flagging when a new decision contradicts an\nexisting one <em>before</em> it ships, not after.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"where-to-start\">Where to start<a href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide#where-to-start\" class=\"hash-link\" aria-label=\"Direct link to Where to start\" title=\"Direct link to Where to start\" translate=\"no\">​</a></h2>\n<p>You don't need a tool to start. Today:</p>\n<ol>\n<li class=\"\">Add a <code>docs/adr/</code> folder to your main repo.</li>\n<li class=\"\">Drop the template above in as <code>0001-record-architecture-decisions.md</code>\n(the first ADR is always \"we're going to use ADRs\").</li>\n<li class=\"\">Write the next real decision your team makes as <code>0002</code>.</li>\n</ol>\n<p>Then, once you've got a handful and you're already feeling the \"wait, didn't we\ndecide this differently in Slack last month?\" pain, that's the moment a\ndecision graph earns its place. That's the problem <a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a>\nexists for.</p>\n<h2 class=\"anchor anchorTargetStickyNavbar_qasO\" id=\"faq\">FAQ<a href=\"https://docs.align.tech/blog/architecture-decision-records-complete-guide#faq\" class=\"hash-link\" aria-label=\"Direct link to FAQ\" title=\"Direct link to FAQ\" translate=\"no\">​</a></h2>\n<p><strong>What is an architecture decision record?</strong>\nA short document that captures one significant architecture decision: the context,\nthe decision itself, and its consequences. One decision per file, in plain text,\nstored next to the code it governs.</p>\n<p><strong>What should an ADR contain?</strong>\nTitle, status (proposed/accepted/superseded), context (the forces in play),\nthe decision stated plainly, and the consequences (what gets easier, harder, and\nwhat you're now committed to).</p>\n<p><strong>Are ADRs still worth it in 2026?</strong>\nYes, and more than before. AI coding agents will refactor away reasoning they\ncan't see. ADRs put that reasoning somewhere durable that both new hires and\nagents can read.</p>\n<p><strong>What is the best ADR tool?</strong>\nFor most teams, plain Markdown files in <code>docs/adr/</code> are enough to start. Adopt a\ntool (adr-tools, Log4Brains, dotnet-adr) only when you feel a specific pain\nMarkdown can't solve. See <a class=\"\" href=\"https://docs.align.tech/blog/adr-tools-compared\">ADR tools compared</a>.</p>\n<p><strong>Why do ADRs go stale?</strong>\nBecause decisions don't stay in the file. They change in Slack, GitHub and Jira,\nand nobody updates the ADR. Keeping ADRs connected to where decisions actually\nchange is the problem <a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">Align</a> solves.</p>\n<!-- -->\n<!-- -->\n<hr>\n<p><em>Align captures engineering decisions across the tools your team already uses,\nlinks them into a queryable graph, and catches cross-team conflicts before they\nship. <a href=\"https://align.tech/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"\">See how it works</a>.</em></p>",
            "url": "https://docs.align.tech/blog/architecture-decision-records-complete-guide",
            "title": "Architecture Decision Records: the complete guide (2026)",
            "summary": "What architecture decision records are, why teams are bringing them back, a copy-paste ADR template, and how to keep them from going stale across Slack, GitHub, Jira and Confluence.",
            "date_modified": "2026-05-20T00:00:00.000Z",
            "author": {
                "name": "The Align Team",
                "url": "https://align.tech"
            },
            "tags": [
                "adr",
                "architecture-decision-records",
                "engineering-decisions",
                "documentation"
            ]
        }
    ]
}