From framework-dev
Use this skill when documenting architectural decisions during framework planning. Provides ADR templates, numbering schemes, and integration with the decisions log.
How this skill is triggered — by the user, by Claude, or both
Slash command
/framework-dev:architecture-decision-recordsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill provides guidance on documenting architectural decisions using the ADR format, ensuring all significant choices are recorded with context, rationale, and consequences.
This skill provides guidance on documenting architectural decisions using the ADR format, ensuring all significant choices are recorded with context, rationale, and consequences.
An Architecture Decision Record captures:
ADRs create a decision history that:
# ADR-{NNN}: {Title}
**Date:** {YYYY-MM-DD}
**Status:** PROPOSED | ACCEPTED | DEPRECATED | SUPERSEDED
**Deciders:** {Who made this decision}
## Context
{Describe the situation that requires a decision. What is the problem?
What forces are at play? What constraints exist?}
## Decision
{State the decision clearly. Use active voice: "We will..."}
## Alternatives Considered
### Alternative 1: {Name}
- **Description:** {What is this option?}
- **Pros:**
- {Pro 1}
- {Pro 2}
- **Cons:**
- {Con 1}
- {Con 2}
- **Source:** {URL to official documentation}
### Alternative 2: {Name}
- **Description:** {What is this option?}
- **Pros:**
- {Pro 1}
- **Cons:**
- {Con 1}
- **Source:** {URL}
## Rationale
{Why was this option chosen over others? What tipped the balance?}
## Consequences
### Positive
- {Positive consequence 1}
- {Positive consequence 2}
### Negative
- {Negative consequence 1}
- {Trade-off accepted}
### Neutral
- {Other implications}
## Related Decisions
- ADR-{NNN}: {Related decision}
## References
- {URL 1}
- {URL 2}
PROPOSED → ACCEPTED → [DEPRECATED | SUPERSEDED]
↓ ↓ ↓
Rejected In effect Replaced by new ADR
| Status | Meaning |
|---|---|
| PROPOSED | Under discussion, not yet decided |
| ACCEPTED | Decision made, in effect |
| DEPRECATED | No longer relevant (system changed) |
| SUPERSEDED | Replaced by a newer ADR |
ADR-{Category}{Sequence}
Categories:
0XX - Project Setup (tooling, CI/CD)
1XX - Architecture (patterns, structure)
2XX - Technology (frameworks, libraries)
3XX - Data (database, storage)
4XX - Security (auth, encryption)
5XX - Integration (APIs, third-party)
6XX - Operations (deployment, monitoring)
Examples:
ADR-001 - Use TypeScript
ADR-101 - Adopt Hexagonal Architecture
ADR-201 - Choose React for Frontend
ADR-301 - Use PostgreSQL for Primary Database
ADR-401 - Implement JWT Authentication
Write an ADR when:
| Scenario | Example |
|---|---|
| Choosing technology | Database, framework, library |
| Architecture pattern | Microservices vs monolith |
| Significant trade-off | Performance vs maintainability |
| Breaking change | Major API redesign |
| Security decision | Authentication method |
| Reversing previous decision | Changing database |
Don't write ADRs for:
Date: 2025-01-03 Status: ACCEPTED Deciders: Framework Orchestrator, User
The application needs a primary database for storing user data, tasks, and relationships. The data is highly relational with complex queries needed. Expected scale is 100K users initially, growing to 1M.
We will use PostgreSQL as the primary database.
Our data model is inherently relational (users have tasks, tasks have subtasks, etc.). PostgreSQL's strong ACID compliance and mature tooling outweigh MongoDB's flexibility benefits for this use case. The JSON column type provides flexibility where needed.
Record decisions about:
Record decisions about:
Record decisions about:
All ADRs go in: .framework-blueprints/01-discovery/decisions-log.md
Or as individual files:
.framework-blueprints/
└── decisions/
├── ADR-001-typescript.md
├── ADR-101-hexagonal-architecture.md
└── ADR-301-postgresql.md
For rapid documentation during sessions:
### D{NNN}: {Title}
**Chose:** {Option}
**Over:** {Rejected options}
**Because:** {One-line rationale}
**Source:** {URL}
**Trade-off:** {What we accept}
Before finalizing an ADR:
When a decision needs to change:
**Status:** SUPERSEDED by ADR-302
When a decision is no longer relevant:
**Status:** DEPRECATED
**Note:** Feature was removed in v2.0
npx claudepluginhub ankurjain1121/framework-developer-agentCaptures architecture decisions as structured ADR files during coding sessions. Detects decision moments, logs context, alternatives, and rationale alongside code in docs/adr/.
Creates, maintains, and manages Architecture Decision Records (ADRs) to capture context and rationale behind significant technical decisions.
Guides creation, maintenance, and management of Architecture Decision Records (ADRs) using MADR templates to capture context, trade-offs, and rationale for significant technical decisions.