architecture-decision-record

Files (1)

• SKILL.md

SKILL.md (first lines)

# Architecture Decision Records

## ADR Template

Every ADR follows this structure:

```markdown
# ADR-NNN: Title of the Decision

## Status

[Proposed | Accepted | Deprecated | Superseded by ADR-NNN]

## Context

What is the issue that we are seeing that motivates this decision or change?
Describe the forces at play (technical, political, social, project-related).
Include any constraints, requirements, or assumptions.

## Decision

What is the change that we are proposing and/or doing?
State the decision in full sentences using active voice.
Be specific about what will be done.

## Consequences

What becomes easier or more difficult because of this decision?
List both positive and negative consequences.
Include any follow-up actions required.
```

## When to Write an ADR

Write an ADR for any decision that meets one or more of these criteria:

| Trigger                                    | Example                                         |
|--------------------------------------------|-------------------------------------------------|
| Adopting or replacing a technology         | Switching from REST to GraphQL                  |
| Changing an architectural pattern          | Moving from monolith to microservices           |
| Infrastructure decisions                   | Choosing a cloud provider or database           |
| API design choices                         | Choosing pagination strategy                    |
| Authentication/authorization strategy      | Adopting OAuth2 with PKCE                       |
| Data model decisions                       | Choosing between SQL and NoSQL                  |
| Cross-cutting concerns                     | Standardizing error handling or logging         |
| Process or convention changes              | Adopting conventional commits                   |
| Build/deployment decisions                 | Choosing CI/CD platform                         |
| Decisions that are hard to reverse         | Anything with significant migration cost        |

### Do NOT Write an ADR For

- Routine implementation choices with low impact
- Temporary decisions that will be revisited within days
- Individual code-level decisions that are covered by style guides
- Choices that are trivially reversible

## Status Lifecycle

```
Proposed  -->  Accepted  -->  Deprecated
                          -->  Superseded by ADR-NNN
```

| Status                  | Meaning                                                          |
|-------------------------|------------------------------------------------------------------|
| **Proposed**            | Under discussion, not yet decided                                |
| **Accepted**            | Decision has been agreed upon and should be followed             |
| **Deprecated**          | No longer relevant due to changes in the project or environment  |
| **Superseded by ADR-NNN** | Replaced by a newer decision; link to the replacement          |

### Rules

- An ADR is immutable once accepted; never edit the original text
- To change a decision, write a new ADR that supersedes the old one
- Update the old ADR's status to "Superseded by ADR-NNN"
- Keep deprecated and superseded ADRs in the repository for history

## Evaluating Alternatives

Use a structured comparison for every ADR with multiple options.

### Pros/Cons Matrix

```markdown
### Option A: PostgreSQL

**Pros:**
- Mature, well-understood RDBMS
- Strong ACID guarantees
- Excellent tooling ecosystem

**Cons:**
- Horizontal scaling requires additional tooling
- Schema migrations needed for changes

### Option B: MongoDB

**Pros:**
- Flexible schema for evolving data models
- Built-in horizontal scaling (sharding)

**Cons:**
- Weaker transaction support (multi-document)
- Team has limited operational experience
```

### Weighted Criteria Matrix

For complex decisions, score each option against weighted criteria:

```markdown
| Criteria              | Weight | PostgreSQL | MongoDB | DynamoDB |
|-----------------------|--------|------------|---------|----------|
| Team expertise        | 5      | 5          | 2       | 2        |
| Scalability           | 4      | 3          | 4       | 5        |
| Query flexibility     | 4      | 5          | 3       | 2        |
| Operational cost      | 3      | 3          | 3       | 4        |
| ACID compliance       | 3      | 5          | 3       | 3        |
| **Weighted Total**    |        | **80**     | **57**  | **60**   |

From Claude-Code-Community-Ireland/claude-code-resources, MIT.

More from Claude-Code-Community-Ireland/claude-code-resources