home / skills / openclaw / skills / adr-gen

adr-gen skill

safe

This skill generates Architecture Decision Records from your context, capturing decisions, alternatives, and reasoning for future reference.

npx playbooks add skill openclaw/skills --skill adr-gen

Review the files below or copy the command above to add this skill to your agents.

Files (8)

SKILL.md

2.4 KB

---
name: adr-gen
description: Generate Architecture Decision Records with AI. Use when documenting technical decisions.
---

# ADR Gen

"Why did we use Redis instead of Memcached?" Six months later, nobody remembers. This tool generates Architecture Decision Records from your context. Captures the decision, the alternatives considered, and the reasoning. Future you will thank present you.

**One command. Zero config. Just works.**

## Quick Start

```bash
npx ai-adr "We chose PostgreSQL over MongoDB for our user data"
```

## What It Does

- Generates properly formatted ADR documents
- Documents the context and problem being solved
- Lists alternatives that were considered
- Explains the decision and its reasoning
- Notes consequences and trade-offs

## Usage Examples

```bash
# Generate an ADR from a decision
npx ai-adr "Switching from REST to GraphQL for our public API"

# Include context about your constraints
npx ai-adr "Using Kafka for event streaming" --context "High throughput, multi-consumer"

# Output to your docs folder
npx ai-adr "Adopting TypeScript" --output docs/adr/001-typescript.md
```

## Best Practices

- **Write ADRs when you make decisions** - Not six months later when you forgot why
- **Include the alternatives** - What else did you consider? Why didn't you pick those?
- **Be honest about trade-offs** - Every decision has downsides. Document them.
- **Number your ADRs** - 001-database-choice.md, 002-auth-provider.md, etc.

## When to Use This

- Making a significant technical decision
- Onboarding new team members who ask "why did we..."
- Preparing for architecture reviews
- Building a knowledge base of your technical choices

## Part of the LXGIC Dev Toolkit

This is one of 110+ free developer tools built by LXGIC Studios. No paywalls, no sign-ups, no API keys on free tiers. Just tools that work.

**Find more:**
- GitHub: https://github.com/LXGIC-Studios
- Twitter: https://x.com/lxgicstudios
- Substack: https://lxgicstudios.substack.com
- Website: https://lxgicstudios.com

## Requirements

No install needed. Just run with npx. Node.js 18+ recommended.

```bash
npx ai-adr --help
```

## How It Works

The tool takes your decision statement, researches common alternatives and trade-offs for that technology choice, then generates a structured ADR document following the standard format: Title, Status, Context, Decision, Consequences.

## License

MIT. Free forever. Use it however you want.

Overview

This skill generates Architecture Decision Records (ADRs) with a single command so teams capture why technical choices were made. It creates properly formatted ADR documents that record context, alternatives, decision reasoning, and consequences. No configuration required — just supply the decision and optional context and the tool outputs a ready-to-save ADR.

How this skill works

The skill accepts a decision statement and optional context, then researches typical alternatives and trade-offs for that choice. It assembles a standard ADR structure: Title, Status, Context, Decision, Alternatives, and Consequences. You can direct output to a file or pipe it into your docs folder for versioned documentation.

When to use it

When making a significant architecture or technology choice
During design reviews or before shipping a major feature
Onboarding new team members who ask why decisions were made
Building a searchable knowledge base of technical decisions
Recording trade-offs and consequences for future maintenance

Best practices

Create an ADR at the time of the decision, not retroactively
Include all meaningful alternatives and why they were rejected
Be explicit about constraints and requirements that drove the choice
Note short-term and long-term consequences, including migration costs
Number and store ADRs in your docs repo to keep history traceable

Example use cases

Document choosing PostgreSQL over MongoDB for user data with reasons and trade-offs
Record switching an API from REST to GraphQL including alternatives considered
Capture the decision to adopt Kafka for event streaming with context like throughput needs
Generate ADR for adopting TypeScript, with consequences for developer workflow and build tooling
Output ADRs directly into a docs/adr folder for repo-based knowledge

FAQ

Do I need to install anything?

No install is required; it runs via npx with Node.js 18+ recommended.

Can I include custom context or constraints?

Yes — pass a context flag or include details in the input to tailor the ADR to your situation.