architecture-decisions

Original：🇺🇸 English

Translated

Architecture Decision Records and living architecture documentation. Activate when making technology choices, defining system boundaries, recording architectural decisions, or creating/updating ARCHITECTURE.md. Covers ADR format, decision governance, design facilitation, and architectural review.

2installs

Sourcejwilger/agent-skills

Added on2026-02-23

NPX Install

npx skill4agent add jwilger/agent-skills architecture-decisions

SKILL.md Content

View Translation Comparison →

Architecture Decisions

Value: Communication -- architecture decisions recorded before implementation ensure every contributor (human or agent) understands why the system is shaped the way it is. Decisions made in silence are decisions lost.

Purpose

Teaches the agent to record architecture decisions before implementing them, maintain a living architecture document, and facilitate structured decision-making. Prevents the common failure mode where architecture emerges accidentally and rationale is lost.

Practices

Record Decisions Before Implementation

Never implement a structural change without first recording the decision. An architecture decision is any choice that affects system structure, technology stack, domain boundaries, integration patterns, or cross-cutting concerns.

Identify the decision: what problem motivates this choice?
Document alternatives: at least two realistic options with tradeoffs
Record the chosen approach and its consequences
Only then proceed to implementation

Do:

Record decisions when they are made, while context is fresh
One decision per record -- keep them atomic
State decisions in active voice: "We will use PostgreSQL for event storage"
Acknowledge negative consequences honestly

Do not:

Document decisions after implementation as retroactive justification
Bundle multiple decisions into one record
Omit alternatives -- a decision without alternatives is not a decision

Maintain the Living Architecture Document

docs/ARCHITECTURE.md

is the single authoritative source for current system architecture. It describes WHAT the architecture IS, not WHY it became that way (the WHY lives in decision records).

Structure:

markdown

# Architecture

## Overview
High-level system description

## Key Decisions
Current architectural choices (link to decision records)

## Components
Major system components and their responsibilities

## Patterns
Patterns in use (event sourcing, CQRS, etc.)

## Constraints
Current constraints and known tradeoffs

Update this document whenever a decision changes the architecture. Keep it current -- a stale architecture document is worse than none.

Use ADR-as-PR Format

When the project uses GitHub, architecture decision records live as PR descriptions, not standalone files. This gives decisions a natural lifecycle:

Open PR = proposed decision, under review
Merged PR = accepted decision
Closed PR = rejected decision
New PR with "Supersedes #N" = revised decision

Each ADR PR:

Branches independently from main (
```
adr/<slug>
```
)
Updates
```
docs/ARCHITECTURE.md
```
with the current decision
You MUST use
```
references/adr-template.md
```
for the PR description as the full decision record
Gets labeled
```
adr
```
for discoverability

When GitHub PRs are not available, record the architecture decision in the commit message of the commit that updates

docs/ARCHITECTURE.md

. Use the same template structure (Context, Decision, Alternatives, Consequences). The commit message becomes the decision record, and

git log -- docs/ARCHITECTURE.md

becomes the decision history.

Facilitate Decisions Systematically

When multiple architectural decisions are needed (new project, major redesign):

Inventory decision points across categories: technology stack, domain boundaries, integration patterns, cross-cutting concerns
Present the agenda to the human for review before facilitating
For each decision: present context, present 2-4 options with tradeoffs, let the human choose, record immediately
Never batch -- record each decision individually so they can be reviewed and accepted independently

Review for Architectural Alignment

Before approving implementation work, verify it aligns with documented architecture:

Does it follow patterns documented in ARCHITECTURE.md?
Does it respect domain boundaries?
Does it introduce new dependencies or patterns not yet decided?
If it conflicts, record a new decision before proceeding

Enforcement Note

This skill provides advisory guidance. It instructs the agent to record decisions before implementation but cannot mechanically prevent implementation without a decision record. The agent follows these practices by convention. If you observe implementation proceeding without a decision record, point it out.

Verification

After completing work guided by this skill, verify:

Every structural change has a corresponding decision record
```
docs/ARCHITECTURE.md
```
reflects the current architecture
Each decision record states context, alternatives, and consequences
No decision was recorded retroactively after implementation
Decision records are atomic (one decision per record)

If any criterion is not met, record the missing decision before proceeding.

Dependencies

This skill works standalone. For enhanced workflows, it integrates with:

event-modeling: Completed event models surface the decision points that need architectural choices (technology, boundaries, integration patterns)
domain-modeling: Domain model constraints inform bounded context boundaries and aggregate design decisions
code-review: Reviewers verify implementation aligns with documented architecture decisions

Missing a dependency? Install with:

npx skills add jwilger/agent-skills --skill event-modeling