JetBrains ADR Template — Live Templates, File Templates, and IntelliJ ADR Workflow

Why JetBrains IDEs work for ADR practice

ADRs are plain Markdown files committed alongside code. JetBrains IDEs treat the project directory as a first-class file tree — the doc/decisions/ folder appears in the Project panel immediately, Markdown files open with live preview in a split pane, and the built-in VCS (Version Control) integration shows ADR history and blame without leaving the IDE.

JetBrains Markdown support is more complete out-of-box than VS Code. The built-in editor includes:

• Split-pane live preview — writes left, rendered HTML right, synchronized scrolling. Toggle with the editor toolbar icons or via View → Appearance → Editor and Preview.
• Mermaid diagram rendering — no extension required. ADRs that include architecture diagrams in Mermaid fenced blocks render live in the preview pane. This matters for ADRs about complex system changes where a sequence or component diagram clarifies the decision.
• Structure tool window — a hierarchical heading outline in the Structure panel (Alt+7) that shows ADR sections by heading level. Useful for navigating long ADRs and verifying the section structure before committing.
• Table formatting — the IDE auto-formats Markdown tables: column widths balance, pipes align. ADRs that include Alternatives Considered as a comparison table benefit from this without any manual alignment.
• Heading folding — individual ADR sections can be folded and expanded in the editor. Useful for long ADRs where you're editing one section and want to collapse the others.

JetBrains IDEs also have stronger refactoring support than VS Code for the code context that surrounds ADR practice. If you're writing an ADR about a change in a Java or Kotlin codebase, the IDE knows the type hierarchy, method signatures, and module structure — useful when writing the Context section, which should describe the existing system.

Live Templates for ADR formats

JetBrains Live Templates expand when you type an abbreviation and press Tab. They support variables, including $DATE$ which resolves at expansion time — equivalent to VS Code's CURRENT_YEAR-CURRENT_MONTH-CURRENT_DATE combination.

Creating the ADR Live Template group

Go to Settings (Ctrl+Alt+S) → Editor → Live Templates. Click the + button on the right and select Template Group. Name the group "ADR". Within the group, click + again to add individual templates.

Nygard format Live Template

Add a new template within the ADR group:

• Abbreviation: adr-nygard
• Description: Nygard-format architecture decision record
• Applicable contexts: Markdown (check "Markdown" in the "Define" list at the bottom)

Template text:

# ADR-$NUM$ — $TITLE$

**Status:** $STATUS$
**Date:** $DATE$
**Deciders:** $DECIDERS$

## Context

$CONTEXT$

## Decision

$DECISION$

## Consequences

**Positive:**
- $POS$

**Negative:**
- $NEG$

## Alternatives Considered

### $ALT$
- $ALT_REASON$
- Rejected because: $ALT_REJECTED$

Click Edit variables to configure the variables:

• DATE — set Expression to date("yyyy-MM-dd") — auto-fills today's date
• NUM — leave blank, fill manually (no auto-increment expression in Live Templates)
• STATUS — set Default value to "Proposed"
• All other variables — leave blank, will be filled by Tab navigation

After setting variables, configure the tab-stop order: check "Skip if defined" for DATE so Tab skips it after it auto-fills. The remaining variables navigate in declaration order: $NUM$ → $TITLE$ → $STATUS$ → $DECIDERS$ → $CONTEXT$ → and so on.

MADR format Live Template

Add a second template in the ADR group for teams using MADR format:

• Abbreviation: adr-madr
• Description: MADR (Markdown Architectural Decision Records) template

Template text:

# $TITLE$

**Status:** $STATUS$
**Date:** $DATE$

## Context and Problem Statement

$PROBLEM$

## Decision Drivers

- $DRIVER$

## Considered Options

- $OPT1$
- $OPT2$

## Decision Outcome

Chosen option: "$CHOSEN$", because $REASON$.

### Positive Consequences

- $POS$

### Negative Consequences

- $NEG$

Set DATE expression to date("yyyy-MM-dd") and STATUS default to "Proposed", same as the Nygard template. Both templates coexist in the ADR group.

Sharing Live Templates across a team

Live Templates are stored in ~/Library/Application Support/JetBrains/IntelliJIdea<version>/templates/ADR.xml on Mac and the equivalent path on Windows/Linux. To share across a team:

1. In Live Templates settings, select the ADR group and use the gear icon → Export to save ADR.xml.
2. Commit ADR.xml to the repository at .idea/live-templates/ADR.xml or a documented location like docs/jetbrains/ADR.xml.
3. Add import instructions to your onboarding docs: Settings → Editor → Live Templates → gear icon → Import → select the XML file.

This is more manual than VS Code workspace snippets (which auto-load from .vscode/*.code-snippets), but achieves the same result once set up. If your team uses JetBrains Settings Sync (via JetBrains Account), Live Templates sync automatically across all IDEs signed into the same account — useful for individual engineers but not for cross-team sharing without a shared account.

File Templates for new ADR files

Live Templates expand within an existing file. File Templates create new files — more useful when you need a correctly-named ADR file like 0043-choose-postgres.md.

Go to Settings → Editor → File and Code Templates → Files tab. Click + to add a new template:

• Name: ADR (Nygard)
• Extension: md

Template text (uses Velocity template syntax for variables):

# ADR-${NUMBER} — ${NAME}

**Status:** Proposed
**Date:** ${YEAR}-${MONTH}-${DAY}
**Deciders:**

## Context

## Decision

## Consequences

**Positive:**
-

**Negative:**
-

## Alternatives Considered

When you right-click the doc/decisions/ folder → New → ADR (Nygard), IntelliJ prompts for the template variables (NUMBER and NAME) before creating the file. The file opens immediately in the editor ready to fill in. The date fields use IntelliJ's built-in Velocity variables ${YEAR}, ${MONTH}, ${DAY} which resolve automatically — you only need to supply NUMBER and NAME.

This is closer to the adr-tools CLI experience than the Live Template approach: it creates a new file with a specific name rather than expanding into an existing document. For teams that prefer IDE-only workflows without the adr CLI installed, File Templates provide the same naming discipline as adr new.

Markdown plugin configuration

JetBrains IDEs ship with a Markdown plugin that handles most configuration without additional setup. A few settings are worth adjusting for ADR practice:

Preview rendering

The Markdown preview renders to a split-pane HTML view. To configure: Settings → Languages and Frameworks → Markdown. Enable Mermaid diagrams if your ADRs include architecture diagrams (this requires accepting the Mermaid rendering engine download). Enable PlantUML if your team uses PlantUML for sequence diagrams in ADRs.

Line length soft wrap

ADR prose lines should wrap at the editor view rather than at a hard column limit. Settings → Editor → General → Soft Wraps → check "Soft-wrap these files:" and add *.md. This applies word wrap to all Markdown files including ADRs without modifying the underlying file.

Inspections for ADR quality

Settings → Editor → Inspections → Markdown → enable:

• Inconsistent heading levels — flags heading level jumps (e.g., # directly to ###), which break Log4Brains rendering and programmatic ADR parsing.
• Missing first heading — flags files where the first line is not a heading. ADRs must start with the ADR title as a top-level heading.

These inspections appear as inline warnings in the editor gutter — the same immediate feedback that markdownlint provides in VS Code, without requiring a separate plugin.

Grazie for ADR prose quality

JetBrains IDEs include Grazie, a built-in spelling and grammar checker for natural language in code comments and Markdown files. For ADR practice, it is the equivalent of Code Spell Checker in VS Code, with the addition of grammar analysis.

Enabling Grazie for Markdown

Settings → Editor → Natural Languages → Grammar → enable "Check grammar" in Markdown files. Grazie is on by default for spelling; grammar checking must be explicitly enabled. For ADRs — which are formal technical prose, not code comments — grammar checking adds meaningful quality: it catches passive voice in the Decision section ("It was decided to…" versus "We chose…"), dangling modifiers in the Context section, and incomplete sentences in Consequences bullet lists.

Grazie Pro for technical vocabulary

Grazie Pro (available via Settings → Plugins → Grazie Pro, requires a JetBrains account) extends the base Grazie checker with technical vocabulary support: it recognises engineering terms like idempotent, PostgreSQL, CQRS, and monorepo without flagging them as spelling errors. For ADR prose, which mixes natural language with technical terminology at high density, Grazie Pro reduces false positives from the spelling checker to near zero.

To add project-specific terminology that Grazie doesn't recognize: Settings → Editor → Natural Languages → Spelling → User dictionaries → add your technical vocabulary. The user dictionary is per-developer (stored in IDE settings), not per-project — for team-wide vocabulary, commit a shared word list and document it in onboarding materials.

adr-tools integration via Run Configurations

If your team uses adr-tools (the Bash CLI by Nat Pryce) for ADR creation and numbering, you can invoke it from within IntelliJ using a Shell Script Run Configuration:

Adding a "New ADR" Run Configuration

1. Run → Edit Configurations → + → Shell Script
2. Name: "New ADR"
3. Script path: leave blank; use "Script text" mode
4. Script text: adr new "$TITLE"
5. Working directory: $ProjectFileDir$
6. Check "Execute in terminal" to see the created file path

This runs adr new from the project root, creating a new numbered ADR file in the doc/decisions/ directory (per the .adr-dir file at the project root). The Run Configuration panel accepts input for the title when you run it. After the run completes, the Project panel refreshes and the new file appears.

Alternatively, use the built-in Terminal (Alt+F12 on Windows/Linux, Opt+F12 on Mac) at the project root to run adr new "title" directly. The terminal opens in the project directory automatically, so the adr CLI runs without changing directories.

adr generate toc Run Configuration

Add a second Run Configuration for adr generate toc to update the table of contents in doc/decisions/README.md after adding new ADRs. Run it via Run → Run "Generate ADR TOC" after each ADR session rather than manually editing the index file.

JetBrains AI Assistant for ADR drafting

JetBrains AI Assistant provides a chat interface embedded in the IDE with access to project context including the current diff, open files, and project structure. For ADR drafting, it works similarly to GitHub Copilot Chat in VS Code:

Context section from a diff

Open the AI Chat tool window (View → Tool Windows → AI Assistant). With a commit staged in the Git tool window, open the AI chat and use the + button to attach the current diff as context. Then prompt:

Based on this diff, write the Context section of a Nygard ADR.
Focus on the problem the change solves, the constraints that shaped the approach,
and what the system looked like before. Output only the Context section in Markdown.

JetBrains AI Assistant has slightly better context awareness for Java and Kotlin projects than Copilot Chat, because the IDE's type system information is available to the AI — it can reference specific interfaces, modules, and patterns in the Context it produces. For Go (GoLand) or Python (PyCharm) projects, the quality difference is less pronounced.

Consequences section from a diff

The Consequences section benefits from AI drafting. Prompt with the diff and request both positive and negative consequences, explicitly asking for negative consequences to avoid a one-sided output:

List the positive and negative consequences of this change in Nygard ADR format.
Positive consequences: what becomes easier, faster, or more reliable.
Negative consequences: what becomes more complex, slower, or creates new dependencies.
Be specific — avoid generic consequences like "improved maintainability".

Alternatives Considered — the same limitation as Copilot

JetBrains AI Assistant generates plausible alternatives from the diff, not the alternatives your team actually evaluated. The AI knows what other approaches exist in general — it doesn't know which ones you considered and rejected with specific reasons. Use AI-generated Alternatives as a candidate checklist: verify which ones you actually evaluated, add the specific rejection reasons you remember, and delete the ones that were never genuinely considered.

The WhyChose extractor handles the case AI drafting cannot: if the decision was worked through in a ChatGPT or Claude session, the extractor surfaces that session and extracts the specific alternatives and rejection reasons from the conversation — the reasoning that exists nowhere else and that no AI can reconstruct from a diff alone.

No JetBrains ADR Manager plugin — approximating the workflow

The VS Code ADR Manager extension (mnater-dev.adr-manager) provides three features that have no direct JetBrains counterpart: command-palette ADR creation with auto-numbering, a sidebar ADR list with status badges, and supersession linking. Here's how to approximate each:

Auto-numbered ADR creation

Use the "New ADR" Run Configuration described above, which calls adr new for auto-numbering. If you can't install adr-tools, write a short shell script that reads the current highest ADR number from doc/decisions/ and creates the next file:

#!/bin/bash
# save as scripts/new-adr.sh
NEXT=$(ls doc/decisions/*.md 2>/dev/null | grep -oP '^\d+' | sort -n | tail -1 | xargs -I{} expr {} + 1)
NEXT=$(printf "%04d" ${NEXT:-1})
TITLE=$(echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')
FILE="doc/decisions/${NEXT}-${TITLE}.md"
cat > "$FILE" <<'EOF'
# ADR-NEXT — TITLE_PLACEHOLDER
**Status:** Proposed
...
EOF
sed -i "s/NEXT/${NEXT}/g; s/TITLE_PLACEHOLDER/$1/g" "$FILE"
echo "Created $FILE"

Add this as a Run Configuration for in-IDE use, or run it from the embedded terminal.

ADR sidebar list

The Project panel in IntelliJ already shows the doc/decisions/ folder with all ADR files listed by filename. Use the Project panel's search (Ctrl+Shift+F filtered to the doc/decisions/ scope) to filter by status value. For teams that want a more visual ADR list, Log4Brains provides a web-based ADR browser from the same Markdown files — run npx log4brains preview in the embedded terminal and open the local URL in a browser alongside IntelliJ.

Supersession linking

Use Find and Replace (Ctrl+H) scoped to doc/decisions/ to update Status fields across related ADRs. When marking ADR 0043 as superseded by ADR 0051, update both files manually: Status: Superseded by ADR-0051 in the old file, Status: Accepted (supersedes ADR-0043) in the new file. The ADR supersession pattern page covers the two-file atomic update protocol in detail.

.editorconfig for ADR files

A project-level .editorconfig applies consistent file settings for ADR Markdown files across all editors and contributors without IDE-specific configuration:

[*.md]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = false
insert_final_newline = true
max_line_length = off

[doc/decisions/*.md]
trim_trailing_whitespace = true
max_line_length = 120

trim_trailing_whitespace = false for Markdown generally (two trailing spaces create a hard line break in CommonMark) but true for doc/decisions/ — ADRs should use blank lines rather than trailing-space line breaks, and trailing whitespace in ADRs shows up as noise in git diff. IntelliJ IDEA reads .editorconfig automatically (Settings → Editor → Code Style → check "Enable EditorConfig support"), so these settings apply in IntelliJ, VS Code, Neovim, and any editor with EditorConfig support.

From JetBrains to WhyChose: closing the loop

The JetBrains ADR workflow handles everything from the moment you start writing: Live Templates for the structure, File Templates for numbered files, AI Assistant for drafting sections, Grazie for prose quality, and adr-tools integration for the CLI workflow your team already uses.

What it doesn't handle is the reasoning that happened before the writing: the architecture discussion in a ChatGPT session, the trade-off comparison in Claude.ai, the constraint surfacing that happened in an AI-assisted design conversation before anyone opened IntelliJ. The WhyChose extractor processes your ChatGPT or Claude conversation export and surfaces the sessions where architectural decisions were deliberated — producing structured output that maps directly onto the ADR sections you're about to fill in.

1. Export your ChatGPT history (Settings → Data Controls → Export) or Claude conversations (Settings → Account → Export Data).
2. Run the WhyChose extractor to surface the decision-dense sessions from your export.
3. Use the extractor output to fill the Context, Alternatives Considered, and Consequences sections in IntelliJ — replacing the "I remember we considered X but I can't reconstruct why we rejected it" problem with the specific reasoning from the original deliberation session.

The ADR sections most engineers struggle with (Alternatives Considered with precise rejection reasons, Context with specific constraints) are precisely the sections the WhyChose extractor produces from AI conversation exports. The JetBrains IDE is where the ADR gets written. WhyChose is where the raw material for writing it comes from.