Блок 3 Презентация

Планирование с ADR и диаграммами — Презентация

Продолжительность: ~10 минут Цель: Убедить студентов, что планирование с AI — это суперсила, а не узкое место. Представить режим Plan, ADR и диаграммы Mermaid.

Вступительный крючок (1 мин)

Скажите что-то вроде:

“Поднимите руку, если вы когда-нибудь начинали ‘быстрое изменение’, которое превратилось в двухдневный рефакторинг. Да — я тоже. А теперь представьте то же самое, но с AI, который может редактировать 30 файлов в минуту. Без плана AI не просто помогает копать яму быстрее — он помогает копать не ту яму быстрее.

Этот блок о единственной привычке, которая отличает людей, продуктивных с AI, от людей, просто занятых с AI: планирование перед действием.”

Ключевой тезис: Скорость без направления — это просто хаос. Режим Plan превращает Claude из пулемёта для генерации кода в точный инструмент.

Режим Plan — Подумай, прежде чем действовать (3 мин)

Что такое режим Plan?

  • Два способа войти в него:
    • Введите /plan в беседе
    • Нажмите Shift+Tab для переключения между режимами Plan и Act
  • В режиме Plan Claude будет анализировать, рассуждать и составлять план — но НЕ будет редактировать файлы, выполнять команды или вносить изменения
  • Думайте об этом как о разнице между хирургом, изучающим МРТ, прежде чем взять скальпель

Что вы получаете от режима Plan:

  • Список файлов, которые нужно изменить
  • Порядок операций
  • Потенциальные риски или ломающие изменения
  • Возможность сказать “нет, давайте сделаем иначе”

Почему это важно:

  • Контекст стоит дорого. Каждый неверный поворот сжигает токены и время. Двухминутный план может сэкономить 20 минут возврата назад.
  • Это инструмент коммуникации. Вывод режима Plan можно вставить в описание PR, показать команде или использовать как чеклист.
  • Он ловит недопонимание рано. Если план Claude не совпадает с тем, что вы имели в виду, вы узнаете об этом до того, как он отредактирует 15 файлов.

Покажите на экране: Переключите Shift+Tab в Claude Code и покажите, как меняется индикатор режима.

Когда эскалировать в ultraplan

  • Локальный /plan лучше, когда терминала достаточно и нужен быстрый цикл “подумал -> проверил”
  • /ultraplan — это облачная версия планирования: он отправляет задачу из вашего CLI в Claude Code on the web в plan mode
  • Лучше всего подходит для миграций, многошаговых инфраструктурных изменений и задач, где инлайн-комментарии в браузере удобнее, чем ответы цельным текстом в терминале

Фраза, которую можно произнести вслух:

“Если /plan — это доска рядом с вашим столом, то /ultraplan — это комната дизайн-ревью. Claude готовит план удалённо, я открываю браузер, комментирую конкретные секции, прошу доработать спорные места и только потом выбираю, где запускать реализацию.”

Важно: ultraplan находится в research preview и требует Claude Code on the web плюс GitHub-репозиторий.

Architecture Decision Records (3 мин)

Что такое ADR?

“ADR — это как коммит-сообщения для решений. Коммит-сообщение говорит, что изменилось. ADR говорит, почему.”

  • Лёгкие markdown-документы
  • Обычно следуют стандартному шаблону: Title, Status, Context, Decision, Consequences
  • Нумеруются последовательно: 001-dark-theme.md, 002-add-caching.md и т.д.
  • Живут в репозитории — прямо рядом с кодом, который описывают

Почему ADR, а не wiki/Confluence/Notion?

  • Они под контролем версий. Запись решения эволюционирует вместе с кодом.
  • Они легко находятся. ls docs/adr/ — готово. Не нужно искать по wiki.
  • Они переживают текучку кадров. Люди уходят. Репозитории остаются.
  • Их можно ревьюить в PR. Кто-то может прокомментировать “Я не согласен с этим решением” прямо в код-ревью.

Шаблон, который мы будем использовать:

# ADR-001: [Title]
- Status: [Proposed / Accepted / Deprecated / Superseded]
- Date: [Date]
- Context: [Why are we making this decision?]
- Decision: [What did we decide?]
- Consequences: [What happens as a result?]
- Alternatives Considered: [What else did we think about?]

Интересный факт: ADR были популяризированы Майклом Найгардом в 2011 году. С тех пор их приняли команды в GitHub, Spotify и Shopify. Формат намеренно короткий — если ваш ADR длиннее одного экрана, это, вероятно, дизайн-документ, а не запись решения.

Диаграммы Mermaid — Диаграммы как код (2 мин)

Что такое Mermaid?

  • Текстовый язык для описания диаграмм
  • Вы пишете что-то вроде: 
    graph LR
  A[User :30080] --> B[NodePort]
  B --> C[Service]
  C --> D[Pod :3000]

    …и это рендерится как настоящая диаграмма

  • GitHub, GitLab и Notion рендерят Mermaid нативно в markdown-файлах

Почему Mermaid для документации инфраструктуры?

  • Видны в диффах. Когда вы добавляете новый сервис, изменение диаграммы видно в диффе PR.
  • Без внешних инструментов. Никаких Lucidchart, draw.io, “а где ссылка на Figma?”
  • Claude отлично их генерирует. Опишите архитектуру на обычном языке — получите диаграмму обратно. Итерируйте, пока не будете довольны.

Три диаграммы, которые мы создадим:

  1. Топология инфраструктуры — DigitalOcean Droplet > кластер k3s > поды и сервисы
  2. Поток трафика — User > NodePort 30080 > Service > Pod :3000 (как запрос доходит до приложения)
  3. Пайплайн деплоя — git push > GitHub Actions > Docker build > registry > ArgoCD > k3s

Покажите на экране: Быстрый пример диаграммы Mermaid, отрендеренной на GitHub.

План тёмной темы (1 мин)

Подготовка к практике:

“На практике мы будем планировать изменение тёмной темы для ai-coderrank. Не реализовывать — это будет в Блоке 4. Только планировать.

Вот что мы попросим Claude сделать:

  1. Войти в режим Plan и проанализировать текущую систему тем
  2. Создать ADR, объясняющий, почему мы добавляем тёмную тему
  3. Сгенерировать три диаграммы Mermaid, документирующие нашу инфраструктуру
  4. Всё проверить и убедиться, что мы довольны, прежде чем написать хоть строку кода

К концу у нас будет план, в котором мы уверены, документация, которая впечатлит любого ревьюера, и чёткая дорожная карта для Блока 4.”

Заключение (30 сек)

“Планирование — это не противоположность быстрого движения. Планирование и есть быстрое движение — вы просто загружаете мышление вперёд. Давайте сделаем это.”

Частые вопросы студентов

В: Можно ли использовать режим Plan для всего? О: Можно, но он наиболее ценен для многофайловых изменений, архитектурных решений или чего угодно, для чего вы обычно рисовали бы на доске. Для быстрого исправления бага? Просто спросите Claude напрямую.

В: ADR заменяют дизайн-документы? О: Нет. ADR — для решений. Дизайн-документы — для проектирования. ADR может сказать “Мы выбрали PostgreSQL вместо MongoDB”. Дизайн-документ опишет схему, стратегию индексирования и план миграции. ADR — это минуты; дизайн-документы — это часы.

В: Mermaid поддерживает все виды диаграмм? О: Большинство — блок-схемы, диаграммы последовательности, диаграммы классов, диаграммы состояний, диаграммы Ганта, ER-диаграммы и другие. Он не заменяет специализированные инструменты для сложного UML, но для инфраструктурных диаграмм и диаграмм потоков — отлично подходит.

Готовы проверить себя?

Пройти квиз →