VS Code ADR Template — Extensions, Snippets, and Workspace Setup

Why VS Code is the natural home for ADR practice

ADRs are short, structured Markdown files that live in the same repository as the code they govern. VS Code handles Markdown natively with live preview (Ctrl+Shift+V on Windows/Linux, Cmd+Shift+V on Mac), syntax highlighting, outline navigation via the Explorer panel, and integrated git — everything needed to write, diff, and commit an ADR without leaving the editor.

The workflow that works in practice: engineer starts a feature branch, writes code, opens a new doc/decisions/0043-choose-postgres.md file using a workspace snippet, fills in the template alongside the implementation, commits ADR and code in the same PR. VS Code makes this workflow possible without switching contexts — the ADR is just another file in the same tree as the code it explains.

VS Code also makes ADRs easier to navigate than most alternatives. The Explorer panel shows the doc/decisions/ folder as a first-class part of the project structure. The Search (Ctrl+Shift+F) works across ADR text the same way it works across code — useful when looking for "all ADRs that mention Redis" or "what did we decide about authentication". GitLens adds author and age annotations to each ADR file, making it easy to see which decisions are recent versus long-standing.

The ADR Manager extension

The most purpose-built VS Code extension for ADR practice is ADR Manager by mnater-dev (mnater-dev.adr-manager). It provides a command palette workflow for creating, viewing, and managing ADRs without leaving VS Code.

What the extension does:

• Auto-numbered ADR creation. The ADR Manager: Add ADR command prompts for a title and creates a new file with the next available number — the same behavior as adr new "My title" from the adr-tools CLI, but from the VS Code command palette without requiring Bash or Node.
• Template selection. Supports both Nygard and MADR format templates, configured in your .adr-dir or package configuration. The generated file opens immediately in the editor ready to fill in.
• ADR list view. A sidebar panel listing all ADRs by number with status badges (Proposed, Accepted, Deprecated, Superseded). Clicking an entry opens the file — useful for teams with 30+ ADRs where the file list becomes hard to navigate.
• Supersession linking. When marking an ADR as Superseded, the extension prompts for the superseding ADR number and inserts the Superseded by reference in both files automatically — the same bidirectional-linking requirement covered in the ADR supersession pattern.

Install via Extensions panel (Ctrl+Shift+X), search "ADR Manager", or run code --install-extension mnater-dev.adr-manager. The extension requires a .adr-dir file in the project root pointing to your ADR directory (e.g., doc/decisions), which is the same convention used by adr-tools.

If your team already uses adr-tools from the CLI, ADR Manager reads from the same .adr-dir configuration — the two tools are compatible and many teams use both, depending on whether they're working in terminal or VS Code at the time.

Workspace snippets for ADR templates

VS Code workspace snippets are the lightest-weight way to add ADR template support without installing anything. Snippets are stored in .vscode/<name>.code-snippets and committed with the repository, so every contributor gets them automatically.

Nygard format snippet

Create .vscode/adr.code-snippets with the following content:

{
  "Nygard ADR": {
    "scope": "markdown",
    "prefix": "adr-nygard",
    "description": "Nygard-format architecture decision record",
    "body": [
      "# ADR-${1:NNNN} — ${2:Title}",
      "",
      "**Status:** ${3|Proposed,Accepted,Deprecated,Superseded|}",
      "**Date:** $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE",
      "**Deciders:** ${4:name, name}",
      "",
      "## Context",
      "",
      "${5:What is the issue we're seeing that motivates this decision?}",
      "",
      "## Decision",
      "",
      "${6:What is the change we're proposing or have agreed on?}",
      "",
      "## Consequences",
      "",
      "**Positive:**",
      "- ${7:Benefit one}",
      "",
      "**Negative:**",
      "- ${8:Trade-off one}",
      "",
      "## Alternatives Considered",
      "",
      "### ${9:Alternative}",
      "- ${10:Why we evaluated it}",
      "- Rejected because: ${11:reason}",
      ""
    ]
  }
}

Type adr-nygard in a Markdown file and press Tab to expand. The numbered tab stops ($1, $2, etc.) let you move through the template sections with Tab, filling in each field in order. The Status field uses a choice list (|Proposed,Accepted,Deprecated,Superseded|) that presents a dropdown on expansion.

The ADR number ($1) is not auto-incremented — you fill it in manually or use the ADR Manager extension. The date is auto-filled from the CURRENT_YEAR, CURRENT_MONTH, CURRENT_DATE variables, which VS Code resolves to today's date at snippet expansion time.

MADR format snippet

Add a second snippet entry to the same file for teams using MADR format:

  "MADR": {
    "scope": "markdown",
    "prefix": "adr-madr",
    "description": "MADR (Markdown Architectural Decision Records) template",
    "body": [
      "# ${1:Short title of the architectural decision}",
      "",
      "**Status:** ${2|Proposed,Accepted,Deprecated,Superseded|}",
      "**Date:** $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE",
      "",
      "## Context and Problem Statement",
      "",
      "${3:Describe the context and problem statement.}",
      "",
      "## Decision Drivers",
      "",
      "- ${4:Driver one}",
      "",
      "## Considered Options",
      "",
      "- ${5:Option one}",
      "- ${6:Option two}",
      "",
      "## Decision Outcome",
      "",
      "Chosen option: \"${7:option}\", because ${8:reason}.",
      "",
      "### Positive Consequences",
      "",
      "- ${9:Outcome}",
      "",
      "### Negative Consequences",
      "",
      "- ${10:Trade-off}",
      ""
    ]
  }

Both snippets can coexist in the same .code-snippets file. Engineers choose the format by typing the corresponding prefix: adr-nygard or adr-madr.

Markdown tooling: markdownlint and Code Spell Checker

Two extensions improve ADR quality across the entire team without requiring any ADR-specific knowledge:

markdownlint (davidanson.vscode-markdownlint)

markdownlint by David Anson enforces consistent Markdown structure. For ADRs, the most valuable rules are:

• MD001 / heading-increment — heading levels must increment by one. Catches ADRs where someone uses ### directly after #, skipping ##. ADRs with irregular heading levels are harder to parse programmatically and fail Log4Brains rendering.
• MD025 / single-title — only one # heading per file. ADRs must have a single top-level title (the ADR name); a second # heading usually means someone formatted a section as a title instead of a second-level heading.
• MD041 / first-line-heading — the first line must be a heading. Catches ADRs that start with frontmatter prose or a metadata block instead of the ADR title.

Add a .markdownlint.json in doc/decisions/ to apply stricter rules specifically to ADR files without tightening rules on README files:

{
  "default": true,
  "MD013": { "line_length": 200 },
  "MD033": false,
  "MD024": { "siblings_only": true }
}

MD013 relaxes the line-length rule (the default 80-character limit is too short for ADR prose — decision rationale rarely fits in 80 characters). MD033 disables the HTML-in-Markdown warning (useful when ADRs embed Mermaid diagrams or HTML tables). MD024 allows duplicate headings within sibling sections (common in Alternatives Considered where each alternative uses the same sub-heading structure).

Code Spell Checker (streetsidesoftware.code-spell-checker)

ADRs are prose documents reviewed by engineers who are not always careful readers of spelling errors in technical docs — but misspellings in an ADR undermine the document's authority in a way that typos in code comments don't. Code Spell Checker flags misspellings including technical terms, and the cSpell:words frontmatter directive lets you add project-specific terminology per-file without disabling the checker globally.

Add a shared word list in .vscode/settings.json for domain vocabulary your team uses repeatedly:

{
  "cSpell.words": [
    "Nygard",
    "MADR",
    "ADR",
    "monorepo",
    "PostgreSQL",
    "idempotent",
    "CQRS",
    "DORA"
  ]
}

This is committed with the repository so all contributors share the word list rather than each suppressing their own false positives individually.

settings.json for ADR directory conventions

A shared .vscode/settings.json makes the ADR workflow consistent across contributors without requiring each engineer to configure their environment:

{
  "files.exclude": {},
  "search.exclude": {
    "doc/decisions/*.md": false
  },
  "files.associations": {
    "doc/decisions/*.md": "markdown"
  },
  "editor.rulers": [120],
  "[markdown]": {
    "editor.wordWrap": "on",
    "editor.quickSuggestions": {
      "comments": "off",
      "strings": "off",
      "other": "off"
    }
  },
  "markdownlint.config": {
    "MD013": { "line_length": 200 }
  }
}

Key settings:

• search.exclude set to false for ADR files. VS Code's default search excludes some common documentation paths. Explicitly including doc/decisions/*.md ensures that workspace-wide search (Ctrl+Shift+F) always searches ADR content — critical for finding related decisions before writing a new one.
• editor.wordWrap: "on" for Markdown. ADR prose is long-form. Line wrapping is more readable for writing and review. Disable quickSuggestions in Markdown to prevent IntelliSense popups from interrupting prose writing.
• editor.rulers at 120. A soft ruler at 120 characters provides a visual guide without enforcing hard wrapping. Longer lines are acceptable in ADRs (tables, code blocks, long technical terms), but the ruler helps keep prose readable.

Recommended workspace extensions list

Add a .vscode/extensions.json to recommend extensions to new contributors when they open the repository:

{
  "recommendations": [
    "mnater-dev.adr-manager",
    "davidanson.vscode-markdownlint",
    "streetsidesoftware.code-spell-checker",
    "eamodio.gitlens",
    "yzhang.markdown-all-in-one"
  ]
}

When a contributor opens the repository for the first time, VS Code prompts to install these extensions. This eliminates the "I didn't know ADR Manager existed" problem on new team members.

GitHub Copilot for drafting ADR sections

GitHub Copilot Chat (available in VS Code via the github.copilot-chat extension) can draft ADR sections from code context. The workflow that works in practice:

Context section from a diff

Open the Source Control panel, stage a commit, then open Copilot Chat and paste the diff with a prompt:

Based on this diff, write the Context section of a Nygard ADR. Focus on:
- What problem this change solves
- What constraints made other approaches less suitable
- What the system looked like before this change

[paste diff here]

Copilot produces a starting Context section that is usually 60–80% complete. The gap is what Copilot doesn't know: the performance numbers that drove the decision, the incident that made this urgent, the business constraint the team was working around. Fill those in from memory or from the Slack thread / ChatGPT session where the decision was actually made.

Consequences section from a diff

Copilot is strongest on Consequences — it reads the diff and identifies positive outcomes (what's now possible that wasn't before) and negative trade-offs (what gets harder, what's now a new dependency, what's locked in). Prompt:

Based on this diff and its Context (above), list the positive and negative consequences in Nygard ADR format. Be honest about the negative consequences — don't list only positives.

The "be honest about negative consequences" instruction matters: Copilot defaults to positive-consequence-heavy output, which produces ADRs that read as press releases rather than honest decision records.

Alternatives Considered from inline comments

If you've added inline code comments like // Considered Redis here but rejected due to operational complexity or // We evaluated connection pooling via pgBouncer; dropped because..., Copilot can extract and format these as an Alternatives Considered table:

This file contains inline comments explaining why certain approaches were rejected.
Extract them as an Alternatives Considered section in Nygard ADR format, one subsection per alternative.

This approach is most useful for teams that write rejection comments at the time of implementation — the inline comments preserve the reasoning that would otherwise vanish by the time the ADR is written. The WhyChose extractor handles the parallel case: if the decision was worked through in a ChatGPT or Claude session rather than as inline comments, the extractor surfaces that session and produces the same Alternatives Considered raw material from the AI conversation rather than from the code.

What Copilot cannot reliably do

Copilot generates plausible-sounding Alternatives Considered sections, but "plausible" is not the same as "what your team actually evaluated." A Copilot-generated Alternatives section lists the obvious alternatives to any decision (switch to Redis; use a managed service; add caching) without knowing which of those your team actually investigated vs rejected without investigation. Use Copilot's Alternatives output as a list of candidates to verify — check which ones were genuinely considered and add specific rejection reasons for those. Delete the ones your team never evaluated.

Integrating VS Code ADR workflow with adr-tools

Many teams use adr-tools (the Bash CLI by Nat Pryce) for ADR creation and numbering, then edit the resulting files in VS Code. The two tools are complementary:

• adr new "Use Postgres as the primary data store" creates doc/decisions/0043-use-postgres-as-the-primary-data-store.md with the next available number and today's date pre-filled.
• VS Code immediately shows the new file in the Explorer panel. The workspace snippet is not needed for creation — the adr CLI handles it. The snippet is useful for one-off ADRs created directly in VS Code without the CLI.
• The ADR Manager extension reads from the same .adr-dir file that adr-tools writes, so both tools see the same ADR directory.

If you use Log4Brains for the web view of your ADRs, it also reads from the same doc/decisions/ directory. The VS Code ADR editing workflow, adr-tools CLI, and Log4Brains web view form a coherent toolchain without any integration code: they all read and write the same Markdown files in the same directory.

VS Code tasks for ADR automation

VS Code tasks (.vscode/tasks.json) can automate repetitive ADR operations that are awkward from the command palette:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "New ADR",
      "type": "shell",
      "command": "adr new '${input:adrTitle}'",
      "presentation": { "reveal": "always", "panel": "new" },
      "problemMatcher": []
    },
    {
      "label": "Generate ADR TOC",
      "type": "shell",
      "command": "adr generate toc",
      "presentation": { "reveal": "always" },
      "problemMatcher": []
    },
    {
      "label": "Serve ADR docs (Log4Brains)",
      "type": "shell",
      "command": "npx log4brains preview",
      "isBackground": true,
      "presentation": { "reveal": "always", "panel": "shared" },
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "adrTitle",
      "description": "ADR title (becomes the filename slug)",
      "type": "promptString"
    }
  ]
}

The "New ADR" task prompts for a title, runs adr new, and opens the new file. The Log4Brains task starts a local preview server in the background — the VS Code terminal stays open but doesn't block the editor. Run tasks via Ctrl+Shift+P → "Tasks: Run Task".

From VS Code to WhyChose: closing the loop

The VS Code workflow handles everything from the moment you start writing an ADR. What it doesn't handle is recovering the reasoning that happened before the writing: the architecture discussion in a ChatGPT session three weeks ago, the trade-off comparison in a Claude.ai conversation from last month, the constraint articulation that happened in a team AI chat and was never written into a Markdown file.

The WhyChose extractor operates on your ChatGPT or Claude conversation export and surfaces the sessions where architectural decisions were deliberated. It produces structured output — decision summary, alternatives, constraints, consequences — that maps directly onto the ADR template sections you fill in VS Code. The workflow:

1. Export your ChatGPT history (Settings → Data Controls → Export) or Claude conversations (Settings → Data Controls → Export).
2. Run the WhyChose extractor on the export to surface decision-dense sessions.
3. Use the extractor output to fill the Context, Alternatives Considered, and Consequences sections in VS Code — replacing the "I can't remember what we evaluated" problem with a structured record of what was actually discussed.

This is the difference between an ADR written from memory (typically thin Alternatives Considered, vague Context) and an ADR written from the original deliberation session (specific constraints named, alternatives with precise rejection reasons). VS Code is where the ADR is written. WhyChose is where the raw material for writing it comes from.