Блок 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:

  • Список файлів, які потрібно змінити
  • Порядок операцій
  • Потенційні ризики або зламні зміни
  • Можливість сказати “ні, давай зробимо інакше”

Чому це важливо:

  • Контекст коштує дорого. Кожен хибний поворот спалює токени і час. 2-хвилинний план може зекономити 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 популяризував Michael Nygard у 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 для інфраструктурної документації?

  • Diff-friendly. Коли додаєте новий сервіс, зміна діаграми видно в diff 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 сек)

“Планування — це не протилежність швидкого руху. Планування і є швидкий рух — просто ви виносите мислення наперед. Ходімо робити.”

Типові запитання студентів

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

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

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

Готові перевірити засвоєне?

Пройти квіз →