ADR (Architecture Decision Record)
Create and maintain Architecture Decision Records following a consistent template
Best use case
ADR (Architecture Decision Record) is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Create and maintain Architecture Decision Records following a consistent template
Teams using ADR (Architecture Decision Record) should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/adr-architecture-decision-record/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How ADR (Architecture Decision Record) Compares
| Feature / Agent | ADR (Architecture Decision Record) | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Create and maintain Architecture Decision Records following a consistent template
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# ADR (Architecture Decision Record) Skill Create and maintain Architecture Decision Records following a consistent template. ## Trigger Conditions - A new architecture decision needs to be documented - An existing ADR needs to be superseded or updated - User invokes with "create ADR" or "document decision" ## Input Contract - **Required:** Decision context (what problem are we solving?) - **Required:** Options considered (at least 2 alternatives) - **Optional:** Constraints, evaluation criteria, stakeholders ## Output Contract - ADR document in markdown format with: Status, Date, Context, Decision, Consequences, Alternatives Considered - Numbered sequentially (ADR-NNN) in the `docs/adr/` directory - Links to related ADRs (supersedes, relates-to) ## Tool Permissions - **Read:** All project files, existing ADRs, architecture docs - **Write:** `docs/adr/` directory - **Search:** Codebase for implementation evidence ## Execution Steps 1. Gather the decision context from user or triggering event 2. Search existing ADRs for related decisions 3. Determine the next ADR number 4. Draft the ADR using the standard template 5. Link to related ADRs and relevant code/config 6. Write the ADR file to `docs/adr/ADR-NNN-<title>.md` ## Success Criteria - ADR has all required sections filled in - Status is set (Proposed, Accepted, Deprecated, Superseded) - Consequences section includes both positive and negative impacts - File is written to the correct location with proper naming ## Escalation Rules - Escalate if the decision has >$1K/month cost implications - Escalate if the decision affects regulatory compliance - Escalate if no clear winner among alternatives ## Example Invocations **Input:** "We need to decide between PostgreSQL and DynamoDB for the order service" **Output:** ADR-005-order-service-database.md with context (high write volume, need transactions), decision (PostgreSQL for ACID guarantees), consequences (operational overhead, need connection pooling), alternatives (DynamoDB rejected due to transaction limitations).
Related Skills
agentic_architecture
Enforces high-level architectural thinking, separation of concerns, and scalability checks before coding.
agentic-jumpstart-architecture
Architecture guidelines for Jarvy CLI - codebase structure, tool implementation patterns, registry system, platform-specific code organization, and module conventions.
Advanced Clean Hexagonal Architecture
Apply Clean Architecture and Hexagonal (Ports & Adapters) patterns for domain isolation and testability. Use when designing system boundaries, creating ports/adapters, or structuring domain-driven applications.
ActiveRecord Query Patterns
Complete guide to ActiveRecord query optimization, associations, scopes, and PostgreSQL-specific patterns. Use this skill when writing database queries, designing model associations, creating migrations, optimizing query performance, or debugging N+1 queries and grouping errors.
active-record-db
This skill should be used when the user asks about Active Record models, database migrations, queries, associations (belongs_to, has_many, has_one, has_and_belongs_to_many), validations, callbacks, scopes, database schema design, SQL optimization, N+1 queries, eager loading, joins, or database-specific features (PostgreSQL, MySQL, SQLite). Also use when discussing ORM patterns, data modeling, or database best practices. Examples:
acc-architecture-doc-template
Generates ARCHITECTURE.md files for PHP projects. Creates layer documentation, component descriptions, and architectural diagrams.
1k-architecture
OneKey monorepo architecture and code organization. Use when understanding project structure, package relationships, import rules, or component organization. Triggers on architecture, structure, packages, imports, hierarchy, dependencies, monorepo, organization.
microservices-architecture
Microservices architecture patterns and best practices. Use when designing distributed systems, breaking down monoliths, or implementing service communication.
architecture-patterns
Padrões de arquitetura de software - Decisões OBJETIVAS sobre design de sistemas
u09955-decision-journal-maintenance-for-accessibility-services
Operate the "Decision Journal Maintenance for accessibility services" capability in production for accessibility services workflows. Use when mission execution explicitly requires this capability and outcomes must be reproducible, policy-gated, and handoff-ready.
rails-architecture
Guides modern Rails 8 code architecture decisions and patterns. Use when deciding where to put code, choosing between patterns (service objects vs concerns vs query objects), designing feature architecture, refactoring for better organization, or when user mentions architecture, code organization, design patterns, or layered design.
mvvm-architecture
Expert MVVM decisions for iOS/tvOS: choosing between ViewModel patterns (state enum vs published properties vs Combine), service layer boundaries, dependency injection strategies, and testing approaches. Use when designing ViewModel architecture, debugging data flow issues, or deciding where business logic belongs. Trigger keywords: MVVM, ViewModel, ObservableObject, @StateObject, service layer, dependency injection, unit test, mock, architecture