adr-assistant

Dexploarer's avatarfrom Dexploarer

Helps create, analyze, and maintain Architecture Decision Records

⭐2stars🔀1forks📁View on GitHub🕐Updated Nov 28, 2025
[Architecture Design]

When & Why to Use This Skill

The ADR Assistant is a specialized Claude skill designed to streamline the creation, analysis, and maintenance of Architecture Decision Records (ADRs). It helps engineering teams document the rationale behind technical choices, evaluate alternatives with data-driven research, and maintain a consistent architectural history. By automating template generation and indexing, it ensures that critical design decisions are transparent, searchable, and aligned with project standards.

Use Cases

  • Evaluating and documenting technology stack choices, such as comparing GraphQL vs. REST or selecting a primary database provider.
  • Generating structured ADR files that include detailed pros, cons, and trade-offs to justify complex architectural shifts.
  • Maintaining a searchable historical record of technical decisions to facilitate seamless developer onboarding and architectural audits.
  • Analyzing existing records to identify potential conflicts, dependencies, or superseded decisions when proposing new system changes.
  • Automating the research of industry alternatives using Deepwiki to ensure decisions are based on current best practices.
nameADR Assistant
descriptionHelps create, analyze, and maintain Architecture Decision Records
triggerCreating architectural decisions, evaluating alternatives, documenting technical choices

ADR Assistant Skill

I autonomously help with Architecture Decision Records when you're making architectural or technical decisions.

When I Activate

I trigger when you're:

  • Discussing technology choices
  • Evaluating alternatives
  • Making architectural decisions
  • Documenting technical choices
  • Updating existing ADRs

What I Provide

1. ADR Analysis

  • Review existing ADRs in ${WORKSPACE_DIR}/adr/
  • Identify related decisions
  • Check for conflicts or dependencies
  • Suggest improvements

2. ADR Creation

  • Generate next ADR number (currently 0012+)
  • Follow established template structure
  • Research alternatives using Deepwiki
  • Document consequences and tradeoffs
  • Include implementation timeline

3. ADR Template Structure

# NNNN. Title

Date: YYYY-MM-DD

## Status
Proposed | Accepted | Deprecated | Superseded

## Context
- Current situation
- Pain points
- Requirements
- Drivers

## Decision
What we decided and why

## Alternatives Considered
- Alt 1: Pros/Cons/Reason for rejection
- Alt 2: ...

## Consequences
- Positive
- Negative
- Neutral
- Risks with mitigations

## Implementation
- Action items
- Timeline
- Success metrics

## References
- Links to docs, commits, related ADRs

## Notes
- Additional insights

4. Best Practices

  • Use Deepwiki to research similar ADRs
  • Consider 3-5 alternatives minimum
  • Document concrete consequences
  • Include measurable success metrics
  • Link to related ADRs
  • Update ADR README index

Current ADR Index (as of 2025-11-07)

  • 0001: Use Bun as Primary Package Manager
  • 0002: Adopt Turbo for Monorepo Build Orchestration
  • 0003: Migrate from Docker to RAILPACK for Railway Deployment
  • 0004: Use PostgreSQL for Primary Database
  • 0005: Adopt ElizaOS for AI Agent Framework
  • 0006: Enforce TypeScript Strict Typing Standards
  • 0007: Real Gameplay Testing with Playwright
  • 0008: Adopt Privy HD Wallets for User Wallet Management
  • 0009: Semi-Automated Asset Approval Workflow
  • 0010: Meshy.ai API Integration for 3D Asset Generation
  • 0011: VRM Avatar System Architecture

Next number: 0012

Example Usage

User: "Should we use GraphQL or REST for our new API?"

Me: I notice you're evaluating API architecture. Let me help create ADR-0012.

I'll:

  1. Research GraphQL vs REST using Deepwiki
  2. Analyze your current tech stack (Elysia, TypeScript)
  3. Consider Hyperscape-specific requirements
  4. Document alternatives with detailed pros/cons
  5. Propose decision with implementation plan
  6. Create ADR file at adr/0012-api-architecture-choice.md
  7. Update ADR README index

Integration with Project

  • Follows ADR template from existing records
  • Updates README.md index automatically
  • Links to related ADRs
  • Aligns with project standards (CLAUDE.md)
  • Uses Deepwiki for research