Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

adr-author

/adr-author

Pisze ADR z kontekstem, rozważanymi opcjami i kompromisami, wybraną decyzją i konsekwencjami, np. dla wyboru bazy danych czy frameworku.

Repozytorium
AgentSkills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
14.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
5
Skrypty
1
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 14.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/new_adr.py

Co robi i kiedy

Pisze ADR z kontekstem, rozważanymi opcjami i kompromisami, wybraną decyzją i konsekwencjami, np. dla wyboru bazy danych czy frameworku.

Wyzwalacze z opisu

why did we choose Xwe need to record this decisiondocument this trade-off
Oryginalny opis (EN)

Authors Architecture Decision Records (ADRs) that capture context, considered options with trade-offs, the chosen decision, and its consequences. Use this skill when the user wants to write, draft, document, or revise an architecture decision, an ADR, a design decision record, a technical decision log, or asks "why did we choose X" / "we need to record this decision" / "document this trade-off" for things like database choice, framework selection, API style, build vs. buy, or deprecating a component.

Jak działa

  1. Overview
  2. When a Decision Deserves an ADR
  3. Workflow
  4. ADR Document Structure
  5. Decision Framework: Picking and Comparing Options
  6. Worked Example
  7. Best Practices
  8. Common Pitfalls
Sekcje z nagłówków SKILL.md, w oryginale · 126 linii, 1 017 słów
Podgląd SKILL.md
---
name: adr-author
description: Authors Architecture Decision Records (ADRs) that capture context, considered options with trade-offs, the chosen decision, and its consequences. Use this skill when the user wants to write, draft, document, or revise an architecture decision, an ADR, a design decision record, a technical decision log, or asks "why did we choose X" / "we need to record this decision" / "document this trade-off" for things like database choice, framework selection, API style, build vs. buy, or deprecating a component.
license: MIT
---

# ADR Author

## Overview

An Architecture Decision Record (ADR) is a short, immutable document that captures one
architecturally significant decision: the forces at play (context), the realistic options,
the option chosen, and the consequences that follow. ADRs form an append-only log so future
maintainers can reconstruct *why* the system looks the way it does — not just *what* it does.

This skill produces rigorous ADRs that distinguish facts from opinions, force an honest
options comparison, and make consequences (good, bad, and neutral) explicit.

**Keywords:** ADR, architecture decision record, design decision, technical decision log,
MADR, Nygard, trade-off analysis, options matrix, decision rationale, superseded decision,
build vs buy, framework selection, database choice, API style, architecture governance.

## When a Decision Deserves an ADR

Write an ADR when the decision is **architecturally significant** — it is costly to reverse,
affects multiple teams/components, or constrains future choices. Use the checklist in
`references/significance-checklist.md`. If none of the criteria fire, capture it as a code
comment or a ticket instead, not an ADR.

## Workflow

1. **Confirm significance.** Run the decision through `references/significance-checklist.md`.
   If it does not qualify, tell the user and suggest a lighter-weight record.

2. **Assign an ID and locate the log.** ADRs live in a directory such as `docs/adr/` or
   `doc/architecture/decisions/`. Number them sequentially with a zero-padded prefix:
   `0001-use-postgresql.md`, `0002-adopt-rest-over-graphql.md`. Use
   `scripts/new_adr.py` to scan the directory, compute the next number, and scaffold the file.

3. **Gather context.** Interview the user (or read the codebase) to extract the *forces*:
   business drivers, technical constraints, team skills, deadlines, existing systems,
   non-functional requirements (performance, security, cost, operability). Separate
   objective facts from assumptions — label assumptions explicitly.

4. **Enumerate real options.** List 2-4 genuinely viable options. "Do nothing" is often a
   valid option and should appear when relevant. Reject straw-man options. For each option,
   describe how it works and its pros/cons against the forces from step 3.

5. **Build the options matrix.** Score options against the decision criteria (the
   non-functional requirements that matter most here). See the worked example in
   `examples/database-selection.md`. The matrix makes the trade-off legible; it does not
   replace judgment.

6. **State the decision.** One clear sentence in active voice: "We will use X." Then explain
   the rationale tied directly to the forces and the matrix. Name who decided and when.

7. **Spell out consequences.** Enumerate positive, negative, and neutral consequences.
   Negative consequences are mandatory — every decision has costs. Include follow-up actions,
   new risks, and what becomes harder.

8. **Set status and links.** Status is one of `Proposed`, `Accepted`, `Rejected`,
   `Deprecated`, `Superseded by ADR-NNNN`. Link related and superseded ADRs bidirectionally.

9. **Write the file** from `templates/adr-template.md`, keep it under ~2 pages, and present
   it. Remind the user that accepted ADRs are immutable — to change a decision, write a new
   ADR that supersedes the old one rather than editing it.

## ADR Document Structure

Use the canonical structure (a pragmatic blend of Nygard and MADR):

- **Title** — `ADR-NNNN: <short imperative phrase>`
- **Status** — Proposed / Accepted / Rejected / Deprecated / Superseded by ADR-NNNN
- **Date** — ISO date the status last changed
- **Context** — the forces, constraints, and problem statement (facts vs. assumptions)
- **Decision Drivers** — the criteria that matter (the columns of your options matrix)
- **Considered Options** — each option with how-it-works + pros/cons
- **Decision Outcome** — the chosen option and the rationale
- **Consequences** — positive, negative, neutral; follow-ups and new risks
- **Links** — supersedes / superseded-by / related ADRs and external references

## Decision Framework: Picking and Comparing Options

Compare options against weighted **decision drivers**, not on vibes:

1. Identify the 3-6 drivers that actually matter for *this* decision (e.g., operability,
   team familiarity, cost, latency, vendor lock-in, time-to-market).
2. Optionally weight them if some clearly dominate.
3. Score each option per driver (`++`, `+`, `o`, `-`, `--`, or 1-5).
4. Read the matrix, then **write the narrative** — the matrix informs, judgment decides.
   Document *why* the winning option wins even if it doesn't top every column.

See `examples/database-selection.md` for a complete matrix and narrative.

## Worked Example

`examples/database-selection.md` shows a full ADR choosing between PostgreSQL, MongoDB, and
DynamoDB for a new service — including the drivers, the scored options matrix, the decision
narrative, and honest negative consequences. Use it as the quality bar.

## Best Practices

- **One decision per ADR.** If you're tempted to use "and", split it.
- **Write in the present tense, active voice.** "We will…", not "It was decided that…".
- **Capture the decision when it's made**, while the context is fresh and the alternatives
  are still remembered. ADRs written months later lose the forces.
- **Make assumptions explicit.** Tag anything not verifiable as an assumption; it tells
  future readers what to re-check if reality diverges.
- **Always list negative consequences.** An ADR with only upsides is marketing, not a record.
- **Keep it short.** Two pages max. Detail belongs in linked design docs, not the ADR.
- **Treat accepted ADRs as immutable.** Supersede, don't edit. The log's value is its history.
- **Link bidirectionally.** When ADR-0012 supersedes ADR-0007, update both files.
- **Number consistently** with zero-padding so the directory sorts correctly.
- **Store ADRs in the repo**, next to the code they govern, so they version with it.

## Common Pitfalls

- **Straw-man options.** Listing only the chosen option plus throwaway alternatives. Future
  readers see through it and lose trust in the log. List options you genuinely weighed.
- **Conflating context with decision.** Context describes the problem and forces *before*
  you decided; it must not leak the conclusion.
- **Omitting "do nothing".** Often the real baseline; failing to consider it hides cost.
- **No consequences, or only good ones.** The most-skipped, most-valuable section.
- **Editing an accepted ADR** to reflect a new choice — this destroys the rationale trail.
  Write a superseding ADR instead.
- **Over-long ADRs** that nobody reads. If it needs a design doc, write one and link it.
- **Writing an ADR for a trivial decision.** Use the significance checklist; don't dilute
  the log with reversible, local choices.
- **Vague titles** like "Database decision". Prefer "ADR-0003: Use PostgreSQL for the orders
  service".
Pliki w paczce (5)
  • SKILL.md 7 KB
  • examples/database-selection.md 5 KB
  • references/significance-checklist.md 3 KB
  • scripts/new_adr.py 4 KB
  • templates/adr-template.md 2 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · JayRHa/AgentSkills100MIT
kevin-burns/claude-skills100MIT
leanstacks/lstk100MIT

Migawka bazy z 13.11.2026 · wersja paczki 0f9e590bdb03 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 1 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100adr
    Pisze Architecture Decision Record jako jeden numerowany plik w docs/adr/ z kontekstem, rozważanymi opcjami i wyborem, gdy trzeba udokumentować wybór technologii lub zapisać, dlaczego wybrano X.
  • 100adr-writer
    Zapisuje istotne decyzje techniczne w formacie MADR z kontekstem, opcjami, kompromisami i konsekwencjami oraz prowadzi numerowany dziennik.
  • 100architecture-decisions
    Zapisuje istotne decyzje techniczne jako ADR z kontekstem, opcjami, decyzją i konsekwencjami, aby uzasadnienie przetrwało zmiany w zespole.
  • 90architecture-decision-record
    Dokumentuje istotną decyzję techniczną z kontekstem, alternatywami, konsekwencjami i statusem, jako rejestr decyzji architektonicznych (ADR).
  • 100architecture-decision
    Zapisuje rekord decyzji architektonicznej z kontekstem, opcjami, decyzją i konsekwencjami, gdy wybór jest trudny do cofnięcia.
  • 100architecture-decision-records
    Zapisuje decyzje architektoniczne jako numerowane pliki markdown w docs/adr/ z kontekstem, alternatywami, konsekwencjami i indeksem README.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.