Use when documenting significant technical or architectural decisions that need context, rationale, and consequences recorded. Invoke when choosing between technology options, making infrastructure decisions, establishing standards, migrating systems, or when team needs to understand why a decision was made. Use when user mentions ADR, architecture decision, technical decision record, or decision documentation.
Documents significant technical decisions with context, alternatives, and consequences. Invoked when choosing technologies, establishing standards, migrating systems, or when user mentions ADRs or decision records.
/plugin marketplace add lyndonkl/claude/plugin install lyndonkl-thinking-frameworks-skills@lyndonkl/claudeThis skill inherits all available tools. When active, it can use any tool Claude has access to.
resources/evaluators/rubric_adr_architecture.jsonresources/examples/database-selection.mdresources/methodology.mdresources/template.mdDocument significant architectural and technical decisions with full context, alternatives considered, trade-offs analyzed, and consequences understood. ADRs create a decision trail that helps teams understand "why" decisions were made, even years later.
Trigger phrases: "ADR", "architecture decision", "document this decision", "why did we choose", "decision record", "technical decision log"
An Architecture Decision Record is a document capturing a single significant decision. It includes:
Quick Example:
# ADR-042: Use PostgreSQL for Primary Database
**Status:** Accepted
**Date:** 2024-01-15
**Deciders:** Backend team, CTO
## Context
Need to select primary database for new microservices platform.
Requirements: ACID transactions, complex queries, 10k+ QPS at launch.
## Decision
Use PostgreSQL 15+ as primary relational database.
## Alternatives Considered
- MySQL: Weaker JSON support, less robust constraint handling
- MongoDB: No ACID across documents, eventual consistency issues
- CockroachDB: Excellent but adds operational complexity we can't support yet
## Consequences
✓ Strong consistency and data integrity
✓ Excellent JSON support for semi-structured data
✓ Team has deep PostgreSQL experience
✗ Vertical scaling limits (will need read replicas at 50k+ QPS)
✗ More complex to shard than DynamoDB if we need it
Copy this checklist and track your progress:
ADR Progress:
- [ ] Step 1: Understand the decision
- [ ] Step 2: Choose ADR template
- [ ] Step 3: Document the decision
- [ ] Step 4: Validate quality
- [ ] Step 5: Deliver and file
Step 1: Understand the decision
Gather decision context: what decision needs to be made, why now, who decides, constraints (budget, timeline, skills, compliance), requirements (functional, non-functional, business), and scope (one service vs organization-wide). This ensures the ADR addresses the right problem.
Step 2: Choose ADR template
For technology selection (frameworks, libraries, databases) → Use resources/template.md. For complex architectural decisions with multiple interdependent choices → Study resources/methodology.md. To see examples → Review resources/examples/ (database-selection.md, microservices-migration.md, api-versioning.md).
Step 3: Document the decision
Create adr-{number}-{short-title}.md with: clear title, metadata (status, date, deciders), context (situation and requirements), decision (specific and actionable), alternatives considered (with pros/cons), consequences (trade-offs, risks, benefits), implementation notes if relevant, and links to related ADRs. See Common Patterns for decision-type specific guidance.
Step 4: Validate quality
Self-check using resources/evaluators/rubric_adr_architecture.json. Verify: context explains WHY, decision is specific and actionable, 2-3+ alternatives documented with trade-offs, consequences include benefits AND drawbacks, technical details accurate, understandable to unfamiliar readers, honest about downsides. Minimum standard: Score ≥ 3.5 (aim for 4.5+ if controversial/high-impact).
Step 5: Deliver and file
Present the completed ADR file, highlight key trade-offs identified, suggest ADR numbering if not provided, recommend review process for high-stakes decisions, and note any follow-up decisions needed. Filing convention: Store ADRs in docs/adr/ or architecture/decisions/ directory with sequential numbering.
For technology selection:
For architectural changes:
For standards and conventions:
For deprecations:
Do:
Don't:
resources/template.mdresources/methodology.mdresources/examples/database-selection.md, resources/examples/microservices-migration.md, resources/examples/api-versioning.mdresources/evaluators/rubric_adr_architecture.jsonADR Naming Convention: adr-{number}-{short-kebab-case-title}.md
adr-042-use-postgresql-for-primary-database.mdCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.