---
name: content-tutorial-structure
description: >
  Структурирует технический туториал — prerequisites, цель «после прочтения сможешь
  X», нумерованные шаги с командами и проверками, troubleshooting, cleanup. Не
  пишет полный текст: создаёт корректный скелет, в который автор досыпает детали.
  Используй, когда «написать туториал», «оформить пошаговую инструкцию», «how-to»,
  «tutorial»,«гайд по развёртыванию», «инструкция, как сделать X».
---

# content-tutorial-structure — Скелет технического туториала

Цель: дать читателю **повторяемый** путь от исходного состояния к цели. Не теория, не эссе — пошаговая инструкция, где каждый шаг проверяем.

Перед началом прочитай:
- `~/.claude/rules/content-voice.md`
- `~/.claude/rules/content-formatting.md` — раздел про туториалы
- `~/.claude/rules/sre-runbook-template.md` — стиль исполняемых процедур (туториал близок к runbook'у по принципам команд)

## Шаг 1. Определи scope

Спроси:
- **цель туториала**: «после прочтения читатель сможет _<глагол + результат>_»
  - примеры: «развернуть Postgres-кластер с replication на 3 нодах», «настроить OAuth-логин через Google в Express-приложении», «измерить heap-аллокации в Go-сервисе»
- **исходное состояние читателя**: что у него есть, что предполагается
- **финальное состояние**: что должно работать в конце
- **платформа / стек**: версии, ОС, облако

Если цель размытая («туториал по k8s») — **остановись и помоги вычленить конкретику**. Туториал «по k8s» невозможен — возможен «развернуть minikube + deploy stateless API + expose via Ingress».

## Шаг 2. Сложи скелет

```markdown
# <Название: глагол + результат>

> **Цель:** после прохождения туториала ты сможешь _<конкретно>_.
> **Время:** ~X минут.
> **Уровень:** новичок / средний / продвинутый.

## Что понадобится

- <тулинг: версия>
- <тулинг: версия>
- <доступ: где взять>
- <облако/окружение, если применимо>

## Шаг 1. <Глагол + что>

<1-2 строки контекста: что делаем и зачем.>

```<lang>
<команда>
```

**Проверка:** <ожидаемый результат / команда, подтверждающая успех>

## Шаг 2. <Глагол + что>

...

## Шаг N. <Глагол + что>

...

## Проверка финального состояния

<команда или сценарий, который проверяет, что всё работает end-to-end>

## Troubleshooting

### <Симптом 1>

**Причина:** ...
**Решение:** ...

### <Симптом 2>

...

## Cleanup

<команды, чтобы откатить всё созданное — если читатель не хочет оставлять>

## Что дальше

<2-3 ссылки: углубление темы, related туториалы, доки>
```

## Шаг 3. Согласуй скелет

Покажи пользователю **только структуру** (заголовки шагов и краткое описание каждого), без полного текста. Спроси:
- все ли шаги нужны?
- ничего не пропущено между шагами?
- порядок логичный?

После подтверждения — переходи к заполнению.

## Шаг 4. Заполни шаги

Для каждого шага:

- **Глагол первым** в заголовке: «Установи kubectl», «Создай namespace», «Проверь подключение»
- **Контекст** — почему делаем (1-2 строки, не лекция)
- **Команда(ы)** в code block с языком, **готовые к копипасту** (см. `sre-runbook-template.md`)
- **Проверка** — команда или ожидаемый вывод, чтобы читатель убедился, что шаг прошёл

Каждый параметр, который читатель должен заменить — объясни **где его взять**:
```bash
kubectl apply -f deploy.yaml -n <namespace>
# <namespace> — имя из шага 2, например "demo-app"
```

## Шаг 5. Troubleshooting

3-5 типичных проблем, с которыми сталкиваются. Для каждой:
- **симптом** (как читатель увидит)
- **причина** (почему случилось)
- **решение** (что сделать)

Не пиши troubleshooting на гипотетические проблемы — только на те, которые реально случались.

## Шаг 6. Cleanup

Команды, чтобы откатить созданное. Это важно — без cleanup читатель боится экспериментировать.

## Шаг 7. Самопроверка

- **прошёл ли** ты туториал глазами впервые? Каждый шаг ясен без контекста статьи?
- **команды копипастабельны**? Нет ли `<your-thing>` без объяснения?
- **версии указаны**? Через 6 месяцев туториал не должен ломаться от того, что вышел новый minor.
- **проверки после каждого шага**? Иначе читатель не знает, где ошибся.

## Шаг 8. Покажи и спроси

Покажи финальный скелет с заполненными шагами. Спроси:
1. Принять
2. Расширить какой-то шаг (нужны детали)
3. Сжать (туториал получился длинным)
4. Добавить раздел (security, production-readiness, alternatives)

## Чего не делать

- не пиши туториал на сценарий, который сам ни разу не проходил — даже частично выдуманные команды убивают доверие
- не объясняй основы стека внутри туториала — линкуй внешние доки
- не делай «всё в одной статье» — туториал на 50+ минут лучше разбить
- не пиши команды с placeholder'ами вроде `<your-cluster>` без объяснения
- не пропускай раздел проверки — это то, что отличает туториал от блог-поста