К основному содержанию
скилл CX Codex

adr-writing — скилл для Claude Code: MADR-шаблон и проверка ADR

Скилл adr-writing для Claude Code, который оформляет архитектурные решения в документы ADR по шаблону MADR и проверяет их полноту по чек-листу E.C.A.D.R. Работает также в Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode.

Apache-2.0 254 установок ★ 89 обновлён 2026-09-15

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add existential-birds/beagle --skill adr-writing -a claude-code
Открыть на GitHub

Что делает adr-writing

Скилл ведёт документ через семь шагов: получает следующий номер, собирает связанный код и существующие ADR из docs/adrs/, загружает шаблон из references/madr-template.md, заполняет разделы, проверяет критерии E.C.A.D.R., помечает пробелы маркерами [INVESTIGATE: …] и записывает файл в docs/adrs/NNNN-slugified-title.md.

У каждого шага есть объективное условие прохода — ворота. После исследования контекста нужен список от нуля путей в docs/adrs/ либо явная запись, что каталога нет. После проверки DoD каждая буква E, C, A, D, R должна быть закрыта либо маркером [INVESTIGATE: …]. После записи файл обязан начинаться с --- и валидного YAML-фронтматтера.

Скилл не извлекает решения из переписки и не запускает весь цикл «извлечь — подтвердить — записать». Это отдельные скиллы: adr-decision-extraction и write-adr. Фронтматтер обязателен: минимум status: draft и date: YYYY-MM-DD. Номер берётся из python scripts/next_adr_number.py, при параллельной записи можно запросить диапазон через --count.

Какие задачи решает

  • записать решение в формате MADR
  • проверить ADR по критериям E.C.A.D.R.
  • разметить пробелы в черновике маркерами INVESTIGATE
  • назначить следующий порядковый номер без конфликтов
  • собрать связанные ADR и код перед записью

Примеры запросов агенту

  • Запиши решение о переходе на PostgreSQL в новый ADR
  • Отформатируй черновик по MADR и проверь качество по E.C.A.D.R.
  • Разметь пробелы в ADR маркерами INVESTIGATE, где данных не хватает

Как установить adr-writing

1Через Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill adr-writing -a claude-code

2Вручную: положить файлы

~/.claude/skills/adr-writing/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/adr-writing/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об adr-writing

Как установить adr-writing в Claude Code?

Выполни npx skills add existential-birds/beagle --skill adr-writing -a claude-code. Скилл появится в ~/.claude/skills/adr-writing/SKILL.md.

Что делает adr-writing?

Пишет ADR по шаблону MADR: собирает контекст, заполняет разделы, проверяет критерии E.C.A.D.R. и сохраняет файл в docs/adrs/. Пробелы в данных помечает маркерами [INVESTIGATE: …].

Чем adr-writing отличается от write-adr?

adr-writing только пишет и проверяет документ. Извлечение решений из переписки делает adr-decision-extraction, а полный цикл от извлечения до записи — write-adr.

Исходный текст

SKILL.md · Apache-2.0
---
name: adr-writing
description: "Use when writing or formatting an ADR document using the MADR template, applying Definition of Done (E.C.A.D.R.) criteria, or verifying ADR completeness. Triggers on \"write the ADR\", \"format as MADR\", \"check ADR quality\", \"mark gaps in ADR\". Also triggers when a decision has been extracted and needs to become a document. Does NOT extract decisions from conversations (use adr-decision-extraction) or orchestrate the full extract-confirm-write workflow (use write-adr)."
---

# ADR Writing

## Overview

Generate Architectural Decision Records (ADRs) following the MADR template with systematic completeness checking.

## Quick Reference

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  SEQUENCE   │ ──▶ │   EXPLORE    │ ──▶ │    FILL     │
│  (get next  │     │  (context,   │     │  (template  │
│   number)   │     │   ADRs)      │     │   sections) │
└─────────────┘     └──────────────┘     └─────────────┘
       │                                        │
       │                                        ▼
       │                                 ┌─────────────┐
       │                                 │   VERIFY    │
       │                                 │  (DoD       │
       └─────────────────────────────────│   checklist)│
                                         └─────────────┘
```

## When To Use

- Documenting architectural decisions from extracted requirements
- Converting meeting notes or discussions to formal ADRs
- Recording technical choices from PR discussions
- Creating decision records from design documents

## Workflow

### Gates (objective pass conditions)

Advance to the next step only when the **pass condition** holds. These replace “I explored” / “I verified” with checkable artifacts.

| After | Pass condition |
|-------|----------------|
| Step 2 | **Pass:** You have a written list (bullets in draft preamble, scratch notes, or the ADR body) of **≥0** paths under `docs/adrs/` you consulted for related/superseded ADRs, **or** you explicitly record that `docs/adrs/` is missing or empty after checking. **And** you list **≥1** repo path for related code **or** `N/A` with one-line reason. |
| Step 5 | **Pass:** For each E, C, A, D, R in `references/definition-of-done.md`, the draft either meets that letter’s checklist **or** contains an `[INVESTIGATE: …]` marker scoped to that gap. |
| Step 7 | **Pass:** The ADR file exists at `docs/adrs/NNNN-slugified-title.md`, and a read of the file shows line 1 is `---` and frontmatter parses as YAML. |

### Step 1: Get Sequence Number

**If a number was pre-assigned** (e.g., when called from `/beagle:write-adr` with parallel writes):
- Use the pre-assigned number directly
- Do NOT call the script - this prevents duplicate numbers in parallel execution

**If no number was pre-assigned** (standalone use):
```bash
python scripts/next_adr_number.py
```

This outputs the next available ADR number (e.g., `0003`).

For parallel allocation (used by parent commands):
```bash
python scripts/next_adr_number.py --count 3
# Outputs: 0003, 0004, 0005 (one per line)
```

### Step 2: Explore Context

Before writing, gather additional context:

1. **Related code** - Find implementations affected by this decision
2. **Existing ADRs** - Check `docs/adrs/` for related or superseded decisions
3. **Discussion sources** - PRs, issues, or documents referenced in decision

**Gate:** Meet the Step 2 row in **Gates (objective pass conditions)** before Step 3.

### Step 3: Load Template

Load `references/madr-template.md` for the official MADR structure.

### Step 4: Fill Sections

Populate each section from your decision data:

| Section | Source |
|---------|--------|
| Title | Decision summary (imperative mood) |
| Status | Always `draft` initially |
| Context | Problem statement, constraints |
| Decision Drivers | Prioritized requirements |
| Considered Options | All viable alternatives |
| Decision Outcome | Chosen option with rationale |
| Consequences | Good, bad, neutral impacts |

### Step 5: Apply Definition of Done

Load `references/definition-of-done.md` and verify E.C.A.D.R. criteria:

- **E**xplicit problem statement
- **C**omprehensive options analysis
- **A**ctionable decision
- **D**ocumented consequences
- **R**eviewable by stakeholders

**Gate:** Meet the Step 5 row in **Gates (objective pass conditions)** before Step 6 (use `[INVESTIGATE: …]` where data is missing).

### Step 6: Mark Gaps

For sections that cannot be filled from available data, insert investigation prompts:

```markdown
* [INVESTIGATE: Review PR #42 discussion for additional drivers]
* [INVESTIGATE: Confirm with security team on compliance requirements]
* [INVESTIGATE: Benchmark performance of Option 2 vs Option 3]
```

These prompts signal incomplete sections for later follow-up.

### Step 7: Write File

**IMPORTANT: Every ADR MUST start with YAML frontmatter.**

The frontmatter block is REQUIRED and must include at minimum:
```yaml
---
status: draft
date: YYYY-MM-DD
---
```

Full frontmatter template:
```yaml
---
status: draft
date: 2024-01-15
decision-makers: [alice, bob]
consulted: []
informed: []
---
```

**Validation:** Before writing the file, verify the content starts with `---` followed by valid YAML frontmatter. If frontmatter is missing, add it before writing.

**Gate:** After write, meet the Step 7 row in **Gates (objective pass conditions)** (file on disk, YAML frontmatter present).

Save to `docs/adrs/NNNN-slugified-title.md`:

```
docs/adrs/0003-use-postgresql-for-user-data.md
docs/adrs/0004-adopt-event-sourcing-pattern.md
docs/adrs/0005-migrate-to-kubernetes.md
```

### Step 8: Verify Frontmatter

After writing, confirm the file:
1. Starts with `---` on the first line
2. Contains `status: draft` (or other valid status)
3. Contains `date: YYYY-MM-DD` with actual date
4. Ends frontmatter with `---` before the title

## File Naming Convention

Format: `NNNN-slugified-title.md`

| Component | Rule |
|-----------|------|
| `NNNN` | Zero-padded sequence number from script |
| `-` | Separator |
| `slugified-title` | Lowercase, hyphens, no special characters |
| `.md` | Markdown extension |

## Reference Files

- `references/madr-template.md` - Official MADR template structure
- `references/definition-of-done.md` - E.C.A.D.R. quality criteria

## Output Example

```markdown
---
status: draft
date: 2024-01-15
decision-makers: [alice, bob]
---

# Use PostgreSQL for User Data Storage

## Context and Problem Statement

We need a database for user account data...

## Decision Drivers

* Data integrity requirements
* Query flexibility needs
* [INVESTIGATE: Confirm scaling projections with infrastructure team]

## Considered Options

* PostgreSQL
* MongoDB
* CockroachDB

## Decision Outcome

Chosen option: PostgreSQL, because...

## Consequences

### Good

* ACID compliance ensures data integrity

### Bad

* Requires more upfront schema design

### Neutral

* Team has moderate PostgreSQL experience
```

© existential-birds · Apache-2.0 · existential-birds/beagle

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
develop-adr product-on-purpose Скилл develop-adr для Claude Code оформляет архитектурное решение по формату Майкла Нигарда: фиксирует контекст, выбор и последствия. CX Codex +1 886установок adr-standards microsoft Правило adr-standards встраивает шаблон MADR v4.0.0, формулу Y-Statement и таксономию статусов в папки с архитектурными решениями, чтобы агент писал ADR по стандарту. CX Codex +1 ★ 1 627звёзд репо adr ncklrs Помогает вести записи архитектурных решений по методологии MADR и Олафа Циммермана прямо в чате с агентом. CX Codex +1 146установок 030-architecture-adr-general Juan Antonio Breña Moral Скилл 030-architecture-adr-general ведёт диалог с разработчиком и оформляет архитектурные решения (ADR) для Java-проектов в формате MADR. Помогает зафиксировать выбор базы данных или фреймворка. CX Codex +1 373установок adr-author microsoft Скилл adr-author для Claude Code ведёт от описания архитектурного решения до ADR: собирает контекст, сравнивает варианты и оформляет выбранный шаблон. Фиксирует причины и последствия решения. CX Codex +1 ★ 1 627звёзд репо architecture-decision-record OrchestKit Скилл architecture-decision-record помогает оформлять архитектурные решения в ADR по формату Нига́рда: контекст, решение, последствия и альтернативы. Создаёт основу документа и помогает вести его статус. CX Codex +1 1 500установок

Из того же набора68

Весь набор →
tutorial-docs Скилл tutorial-docs для Claude Code задаёт структуру обучающих руководств по методологии Diataxis. Агент подключает его при написании вводных уроков и пошаговых руководств для новичков. CX Codex +1 273установок bubbletea-code-review Скилл bubbletea-code-review для Claude Code проверяет Go-код BubbleTea-проектов: архитектуру Elm, цикл Update и стили Lipgloss. CX Codex +1 270установок zustand-state Скилл zustand-state для Claude Code помогает создавать хранилища Zustand, выбирать данные селекторами, сохранять их в localStorage и подключать devtools. CX Codex +1 261установок dagre-react-flow Скилл dagre-react-flow настраивает автоматическую раскладку направленных графов в React Flow с помощью dagre. Помогает строить иерархические деревья и выравнивать узлы по направлениям. CX Codex +1 257установок swift-code-review Скилл swift-code-review для Claude Code проверяет Swift-код на ошибки конкурентности, обработки ошибок и управления памятью. Подключается при ревью файлов .swift, в том числе с async/await, actors и Sendable. CX Codex +1 253установок review-verification-protocol Скилл review-verification-protocol обязывает проверить каждую находку перед тем, как внести её в отчёт — читать исходный код, искать контекст, отличать баги от стиля. Снижает ложные срабатывания в ревью. CX Codex +1 252установок pytest-code-review Скилл pytest-code-review проверяет тесты pytest на корректность асинхронных вызовов, скоуп фикстур, параметризацию и пути для моков. Помогает находить утечки и ошибки патчинга до запуска CI. CX Codex +1 239установок sqlalchemy-code-review Скилл sqlalchemy-code-review проверяет SQLAlchemy-код на ошибки в сессиях, связях, запросах и миграциях. Нужен при ревью проектов на SQLAlchemy 2.0 и Alembic. CX Codex +1 228установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой