Skip to main content
skill CX Codex

adr-architecture — Claude Code skill: writes ADRs with trade-offs

adr-architecture turns an architecture choice into a written decision record with context, rejected options and consequences, then scores the draft against a rubric.

no license 118 installs ★ 203 updated 2026-09-01

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add lyndonkl/claude --skill adr-architecture -a claude-code
Open on GitHub

What adr-architecture does

The skill runs a five-step workflow. It starts by pulling the decision context: who decides, what constraints and requirements apply. Then it picks a template, writes adr-{number}-{short-title}.md, checks the draft against a rubric and suggests a home in docs/adr/ or architecture/decisions/.

Resources ship with it: resources/template.md for technology choices, resources/methodology.md for decisions where several choices depend on each other, and three worked examples covering a database pick, a move to microservices and API versioning. Each record holds context, the decision itself, the alternatives weighed, consequences and a status.

Quality is scored with resources/evaluators/rubric_adr_architecture.json. The floor is 3.5, and the skill tells you to aim for 4.5 when a decision is contested. Old records stay untouched: status may change, the text does not, and a replacement gets its own file that links back.

What it helps with

  • Record why PostgreSQL won over MySQL
  • Write up a microservices migration with its rollback plan
  • Document an API versioning standard and its exceptions
  • Supersede an outdated decision without losing the trail
  • Score a draft against the rubric before review

Example prompts for the agent

  • Draft an ADR for picking Postgres as our primary database, with the alternatives we rejected
  • Write the ADR for our microservices move using resources/methodology.md and file it under docs/adr/
  • Review adr-012-api-versioning.md against the rubric and list what's missing

How to install adr-architecture

1Skills CLI (Vercel)

npx skills add lyndonkl/claude --skill adr-architecture -a claude-code

2Manually: put the files in place

~/.claude/skills/adr-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/adr-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about adr-architecture

How do I install adr-architecture in Claude Code?

Run npx skills add lyndonkl/claude --skill adr-architecture -a claude-code. The skill file lands at ~/.claude/skills/adr-architecture/SKILL.md.

What does adr-architecture do?

It helps produce an architecture decision record: gathers context, states the decision, the alternatives and the consequences, then checks the text against a rubric.

Can I edit an ADR after it's accepted?

Records stay immutable. Change the status and write a new ADR that points at the old one instead of rewriting it.

Similar skills

All skills for Writing and docs →

From the same set49

The whole set →
one-pager-prd one-pager-prd is a Claude Code skill that turns a feature idea into a one-page spec or PRD with its problem, solution, users, metrics, and scope, before detailed design or development. CX Codex +1 125installs environmental-scanning-foresight environmental-scanning-foresight tracks external trends across six PESTLE dimensions, catches weak signals of change, builds scenario futures, and sets adaptive indicators for early warning. CX Codex +1 120installs scout-mindset-bias-check scout-mindset-bias-check is a Claude Code skill that checks forecasts with Scout Mindset procedures, including when an estimate feels emotional or stuck at 50/50. CX Codex +1 119installs domain-research-health-science domain-research-health-science structures health science and medical evidence synthesis using PICOT framing, formal bias checklists, and GRADE certainty scoring. CX Codex +1 119installs constraint-based-creativity constraint-based-creativity — a skill that makes the model invent inside tight limits, such as a small budget or a fixed format, so brainstorming stops circling the same answers. CX Codex +1 115installs translation-reframing-audience-shift translation-reframing-audience-shift rewrites content for a different audience: technical docs to business cases, strategy to action steps, expert text to plain language. CX Codex +1 115installs meta-prompt-engineering The meta-prompt-engineering skill turns unclear prompts into structured instructions with a defined role, task steps, constraints, and quality checks. Use it when an agent’s responses vary between runs. CX Codex +1 114installs systems-thinking-leverage systems-thinking-leverage turns a tangled problem into a mapped system with ranked intervention points, built on feedback loops and Meadows' leverage ladder. CX Codex +1 114installs

Project sponsors

Companies that keep this analytics open