architecture-decision-records — community architecture-decision-records, claude-code-onboarding, community, ide skills, Claude Code, Cursor, Windsurf

v1.0.0
GitHub

About this Skill

Ideal for Technical Agents needing structured decision-making capabilities for framework adoption, database technology choice, and security architecture. 🤖 Team onboarding kit for Claude Code AI coding assistant. Pre-configured with agents, skills, slash commands, and MCP integrations for Java 21/Spring Boot WebFlux, Angular, Flutter, PostgreSQL, and Firebase. Clone → install → start building.

kumaran-is kumaran-is
[3]
[2]
Updated: 2/24/2026

Agent Capability Analysis

The architecture-decision-records skill by kumaran-is is an open-source community AI agent skill for Claude Code and other IDE workflows, helping agents execute tasks with better context, repeatability, and domain-specific guidance.

Ideal Agent Persona

Ideal for Technical Agents needing structured decision-making capabilities for framework adoption, database technology choice, and security architecture.

Core Value

Empowers agents to capture context and rationale behind significant technical decisions using structured ADR formats, facilitating informed decisions on API design patterns, new framework adoption, and database technology choice, all while ensuring adherence to security architecture best practices.

↓ Capabilities Granted for architecture-decision-records

Documenting database technology choices
Recording API design pattern decisions
Creating security architecture blueprints
Tracking framework adoption rationales

! Prerequisites & Limits

  • Requires significant technical decision-making context
  • Most useful for major version upgrades or new technology adoptions, less so for minor version upgrades or bug fixes
Labs Demo

Browser Sandbox Environment

⚡️ Ready to unleash?

Experience this Agent in a zero-setup browser environment powered by WebContainers. No installation required.

Boot Container Sandbox

architecture-decision-records

Install architecture-decision-records, an AI agent skill for AI agent workflows and automation. Works with Claude Code, Cursor, and Windsurf with one-command...

SKILL.md
Readonly

Architecture Decision Records

Capture the context and rationale behind significant technical decisions using structured ADR formats.

When to Use This Skill

Write ADRSkip ADR
New framework adoptionMinor version upgrades
Database technology choiceBug fixes
API design patternsImplementation details
Security architectureRoutine maintenance
Integration patternsConfiguration changes

Quick Start

  1. Copy the template: cp docs/adr/template.md docs/adr/NNNN-your-title.md
  2. Fill in: Context, Decision Drivers, Options, Decision, Consequences
  3. PR for review (2+ senior engineers)
  4. Update docs/adr/README.md index after merge

Core Concepts

An Architecture Decision Record captures:

  • Context: Why we needed to make a decision
  • Decision: What we decided
  • Consequences: What happens as a result

ADR Lifecycle

Proposed --> Accepted --> Deprecated --> Superseded
                |
             Rejected

Read reference/adr-lifecycle.md for status transitions, deprecation patterns, and review checklists.

Process

1. Choose a Template

Pick the format that fits the decision's complexity:

Decision ComplexityTemplate
Simple tech selectionY-Statement (one paragraph)
Medium decisionLightweight ADR (0.5-1 page)
Significant architecture changeStandard MADR (1-2 pages)
Retiring a decisionDeprecation ADR
Major cross-team proposalRFC Style (2-4 pages)

Read reference/adr-templates.md for all template formats ready to copy-paste.

2. Write the ADR

  • Start with context -- explain the problem before the solution
  • List 2-3 real alternatives with honest pros/cons
  • State the decision clearly
  • Document both positive and negative consequences with specifics

3. Review and Approve

  • Submit as PR with 2+ senior engineer reviewers
  • Consult affected teams
  • Assess security, cost, and reversibility implications

4. Maintain

  • Update ADR index after acceptance
  • Create implementation tickets
  • Never edit accepted ADRs -- write new ones to supersede

Read reference/adr-examples.md for complete worked examples (PostgreSQL selection, TypeScript adoption, MongoDB deprecation, event sourcing RFC).

Minimal Template (Copy-Paste Starter)

markdown
1# ADR-NNNN: [Title]
2
3## Status
4Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
5
6## Context
7[Why do we need to decide this? What's the problem?]
8
9## Decision
10We will [decision].
11
12## Consequences
13- **Good**: [benefits]
14- **Bad**: [drawbacks]
15- **Mitigations**: [how we'll address the bad]

Common Mistakes

MistakeFix
Writing ADR after implementationWrite during design phase
Listing only one optionAlways include 2-3 real alternatives
Vague consequencesBe specific: "Adds ~200ms latency to checkout"
Editing accepted ADRsWrite new ADR that supersedes
No decision driversList explicit criteria with priorities
Missing rejected ADRsDocument rejected options too

Directory Structure

docs/adr/
  README.md           # Index of all ADRs
  template.md         # Team's ADR template
  0001-use-postgresql.md
  0002-caching-strategy.md

Reference Files

FileContents
reference/adr-templates.mdAll formats: MADR, lightweight, Y-statement, deprecation, RFC
reference/adr-examples.mdComplete worked examples for each format
reference/adr-lifecycle.mdStatus transitions, review checklists, automation with adr-tools

Resources

Error Handling

Conflicting ADRs: When a new decision contradicts an existing ADR, create a superseding ADR that explicitly references and deprecates the old one.

Missing context: If the decision rationale is unclear or incomplete, flag it and request clarification before recording.

FAQ & Installation Steps

These questions and steps mirror the structured data on this page for better search understanding.

? Frequently Asked Questions

What is architecture-decision-records?

Ideal for Technical Agents needing structured decision-making capabilities for framework adoption, database technology choice, and security architecture. 🤖 Team onboarding kit for Claude Code AI coding assistant. Pre-configured with agents, skills, slash commands, and MCP integrations for Java 21/Spring Boot WebFlux, Angular, Flutter, PostgreSQL, and Firebase. Clone → install → start building.

How do I install architecture-decision-records?

Run the command: npx killer-skills add kumaran-is/claude-code-onboarding/architecture-decision-records. It works with Cursor, Windsurf, VS Code, Claude Code, and 19+ other IDEs.

What are the use cases for architecture-decision-records?

Key use cases include: Documenting database technology choices, Recording API design pattern decisions, Creating security architecture blueprints, Tracking framework adoption rationales.

Which IDEs are compatible with architecture-decision-records?

This skill is compatible with Cursor, Windsurf, VS Code, Trae, Claude Code, OpenClaw, Aider, Codex, OpenCode, Goose, Cline, Roo Code, Kiro, Augment Code, Continue, GitHub Copilot, Sourcegraph Cody, and Amazon Q Developer. Use the Killer-Skills CLI for universal one-command installation.

Are there any limitations for architecture-decision-records?

Requires significant technical decision-making context. Most useful for major version upgrades or new technology adoptions, less so for minor version upgrades or bug fixes.

↓ How To Install

  1. 1. Open your terminal

    Open the terminal or command line in your project directory.

  2. 2. Run the install command

    Run: npx killer-skills add kumaran-is/claude-code-onboarding/architecture-decision-records. The CLI will automatically detect your IDE or AI agent and configure the skill.

  3. 3. Start using the skill

    The skill is now active. Your AI agent can use architecture-decision-records immediately in the current project.

Related Skills

Looking for an alternative to architecture-decision-records or another community skill for your workflow? Explore these related open-source skills.

View All

widget-generator

Logo of f
f

f.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source — self-host for your organization with complete privacy.

★ 149.6k
⑂ 0
AI

flags

Logo of vercel
vercel

flags is a Next.js feature management skill that enables developers to efficiently add or modify framework feature flags, streamlining React application development.

★ 138.4k
⑂ 0
Browser

zustand

Logo of lobehub
lobehub

The ultimate space for work and life — to find, build, and collaborate with agent teammates that grow with you. We are taking agent harness to the next level — enabling multi-agent collaboration, effortless agent team design, and introducing agents as the unit of work interaction.

★ 72.8k
⑂ 0
AI

data-fetching

Logo of lobehub
lobehub

The ultimate space for work and life — to find, build, and collaborate with agent teammates that grow with you. We are taking agent harness to the next level — enabling multi-agent collaboration, effortless agent team design, and introducing agents as the unit of work interaction.

★ 72.8k
⑂ 0
AI