madr-gen

madr-gen

A Claude Code plugin that automatically analyzes your session to detect architectural decisions and generates mADR (Markdown Any Decision Records) documents.

What It Does

Every time you make a significant architectural decision in a Claude Code session — choosing a library, adopting a pattern, deciding on a structure — madr-gen finds it and asks if you want to document it. Documents are stored in docs/decisions/ following the MADR 4.0 format.

Installation

Claude Code has a built-in plugin system. Run the following two commands inside Claude Code to install madr-gen:

Step 1 — Register this repository as a marketplace

/plugin marketplace add JiHongKim98/madr-gen

Step 2 — Install the plugin

/plugin install madr-gen@JiHongKim98/madr-gen

That's it. The /madr command is now available in every session.

Scope options

By default the plugin is installed for your user (all projects). You can change the scope with --scope:

Scope	Command	Effect
user (default)	--scope user	Available in all projects
project	--scope project	Stored in .claude/settings.json, shared with teammates via git
local	--scope local	Project-local only, gitignored

# Example: share with teammates via version control
/plugin install madr-gen@JiHongKim98/madr-gen --scope project

Other plugin commands

/plugin                                           # Open the interactive plugin UI
/plugin marketplace list                          # List registered marketplaces
/plugin update madr-gen@JiHongKim98/madr-gen     # Update to latest version
/plugin uninstall madr-gen@JiHongKim98/madr-gen  # Remove the plugin
/plugin disable madr-gen@JiHongKim98/madr-gen    # Disable without uninstalling

Usage

Run the /madr command at any point during or at the end of a session:

/madr          # Interactive: analyze session and select which ADRs to create
/madr scan     # Quick scan: show detected decisions without writing files
/madr init     # Initialize docs/decisions/, generate ADR index, and inject setup block into CLAUDE.md

How It Works

madr-gen runs a 4-phase pipeline:

Phase 1: Detection (parallel)
  └─ decision-detector (Sonnet)
     ├─ Reads JSONL session logs from ~/.claude/projects/<project>/
     ├─ Extracts User/Assistant conversation text
     └─ Cross-references with git diff/log

Phase 2: Validation (sequential)
  └─ duplicate-checker (Haiku)
     └─ Reads docs/decisions/README.md index (status-aware)
        → only compares against active (Accepted/Proposed) ADRs
        → classifies each as: new / update / supersede / duplicate

Phase 3: Selection (interactive)
  └─ AskUserQuestion (multi-select)
     └─ Lists detected decisions with category, action type, and confidence

Phase 4: Writing (parallel)
  └─ madr-writer (Sonnet) × N
     ├─ Creates or updates NNNN-kebab-case-title.md in docs/decisions/
     └─ Regenerates docs/decisions/README.md index

Output Format

ADR files follow the MADR 4.0 template:

docs/decisions/
├── README.md                          # Auto-generated ADR index (status table)
├── 0001-use-react-for-frontend.md
├── 0002-adopt-repository-pattern.md
└── 0003-use-vitest-for-testing.md

Each file contains:

---
status: accepted
date: 2026-03-04
decision-makers: kimjihong
supersedes: "0001"       # optional: links to the ADR this decision replaces
---

# Use React for Frontend

## Context and Problem Statement
...

## Decision Drivers
* ...

## Considered Options
* React
* Vue
* Svelte

## Decision Outcome
Chosen option: "React", because ...

### Consequences
* Good, because ...
* Bad, because ...

What Gets Detected

Category	Examples
Technology	Library choices, framework selection, build tools
Architecture	Design patterns, module structure, API design
Convention	Naming rules, error handling, code style
Infrastructure	CI/CD, deployment, cloud services
Refactoring	Migration strategy, deprecation decisions

Configuration

Create .madr-gen.json in your project root to customize behavior:

{
  "adrDirectory": "docs/decisions",
  "templateStyle": "full",
  "language": "auto",
  "autoSuggest": true,
  "categories": [
    "technology",
    "architecture",
    "convention",
    "infrastructure",
    "refactoring"
  ]
}

Option	Default	Description
adrDirectory	docs/decisions	Where ADR files are stored
templateStyle	full	"full" (all sections) or "minimal" (context, options, outcome only)
language	auto	"auto" matches session language, or force with "en", "ko", etc.
autoSuggest	true	Whether to suggest existing ADR updates alongside new ones

Helper Scripts