# ADR — Architecture Decision Record

## Назначение

Зафиксировать архитектурное решение в `.agent/decisions/NNN-slug.md` так, чтобы будущий агент (или человек) мог понять: что решили, почему, какие альтернативы рассматривали, какие последствия.

ADR создаются по явной команде пользователя: «запиши это как решение», «/adr», «сделай ADR для текущего подхода».

## Когда вызывать

- Принято неочевидное архитектурное решение (выбор БД, паттерна, библиотеки, структуры модулей).
- Решение может измениться в будущем — стоит зафиксировать контекст.
- Есть trade-off, который нужно объяснить следующему агенту.

Не вызывать для очевидных вещей: «используем pytest», «классы называем в PascalCase».

## Вход

- Контекст решения: что обсуждалось, какие варианты сравнивались, что выбрали.
- `.agent/decisions/index.json` — текущий список ADR (для нумерации).
- `.agent/context/project-state.md` — текущее состояние проекта.

## Шаги

### 1. Определить номер

Прочитать `.agent/decisions/index.json`. Следующий номер = max существующих + 1. Если файла нет — создать, начать с 001.

### 2. Slug

Короткое имя в kebab-case, отражающее суть: `use-sqlite-for-mvp`, `auth-via-jwt-cookies`, `modular-monolith`.

### 3. Записать ADR

Создать `.agent/decisions/{NNN}-{slug}.md` по шаблону `TEMPLATES/adr-NNNN.md`:

```markdown
# {NNN}. {Заголовок}

**Дата:** {YYYY-MM-DD}
**Статус:** Accepted | Superseded by {NNN} | Deprecated

## Контекст

{Что за проблема. Какие ограничения. Что нужно было решить.}

## Решение

{Что выбрали. Коротко и конкретно.}

## Альтернативы, которые рассмотрели

### {Альтернатива 1}
{Описание. Почему не выбрали.}

### {Альтернатива 2}
{Описание. Почему не выбрали.}

## Последствия

### Положительные
- {что становится лучше}

### Отрицательные
- {что становится хуже или сложнее}

### Инварианты
- {что не должно сломаться, чтобы решение оставалось валидным}
```

### 4. Обновить index.json

```json
{
  "version": "3.0.0",
  "decisions": [
    { "id": "001", "title": "Использовать SQLite для MVP", "file": "001-use-sqlite-for-mvp.md", "status": "Accepted" }
  ],
  "last_updated": "{timestamp}"
}
```

### 5. Если есть supersession

Если новый ADR отменяет старый — в старом ADR поставить `Статус: Superseded by {NNN}` и добавить ссылку. В новом — в контексте упомянуть, что отменяет.

## Выход

- `.agent/decisions/{NNN}-{slug}.md`
- Обновлённый `.agent/decisions/index.json`

## Связанные команды

- **/invariant-tests** — после ADR можно зафиксировать инварианты как задачи в manifest.
- **/alt-arch** — если хочется явно зафиксировать альтернативу до решения.