api-first

1. Как генерить код из документации

/ IT Community Day
Как генерить код из
документации
Герман Реус
Яндекс-бэкендер
HR-Tech

2. Содержание

01
01 Что такое Docs-First (contract-first) - и почему это полезно
02
02 Генерация кода как часть процесса разработки
03
03 Как внедрить это в вашей команде, рецепт идеальной документации
04
05
2

3. Что за Docs-First

01
Что за Docs-First

4. Docs-First (или contract-first) — разработка контрактов, требований, проведение полного системного анализа перед написанием

кода.
4

5. Суть концепции

С Docs-first
Без Docs-first
1. Бизнес принес задачу
2. Проводим системный анализ
− Собираем контекст задачи,
проектируем решение
− Коммитим контракты
(openapi, proto, etc…)
− Заполняем документацию
3. Начинаем кодить
1. Бизнес принес задачу
2. Договорились «как делаем»
3. Начинаем кодить
− Собираем контекст
− Создаем API
− Документация
5

6. Без Docs-first

нашли проблему
ТЗ
Собираем
контекст
Прикидывае
м решение
Кодим
долгий трудный цикл
6

7. C Docs-first

нашли проблему
ТЗ
Собираем
контекст
Проектируем
решение
Описываем
доку
Кодим
более быстрый цикл
(все это внутри одного agile витка)
7

8. Плюсы

Минусы
1. Быстрее собирается ТЗ
1. Требует дисциплины
2. Легко параллелить работу
(back, front, QA)
2. Длинный
подготовительный этап
3. Дока читается лучше кода
3. Дополнительный шаг в
цикл разработки
4. Соглашения фиксируются и
не теряются
4. Дока устаревает
(можно автоматизировать)
5. Планирование крупных
изменений
8

9. Результат

1. Более прогнозируемые
сроки разработки
2. Меньше ошибок и багов
3. Быстрее онбординг на
проект
9

10. Подходит

1. Big tech системам – снизить
неопределенность
2. Микросервисам – потому
что много контрактов
3. Проектам с большой
командой – уменьшить
расходы на коммуникацию
10

11. При чем тут ИИ

02
При чем тут ИИ

12. Без Docs-first, но с ИИ

нашли проблему
ТЗ
Собираем
контекст
Прикидывае
м решение
Вайбкодим
12

13. C Docs-first + ИИ

нашли проблему
1 промпт
ТЗ
Собираем
контекст
Проектируем
решение
Описываем
доку
Вайбкодим
+
MCP
=
Полный
контекст
13

14. Специальный промпт для ИИ

14

15.

2 уточняющих
промпта
15

16.

1 уточняющий
промпт
16

17.

✅
0 уточняющих
промптов
17

18. Плюсы

1. Тратим меньше токенов
2. Сильно сокращается время
на разработку
(сильнее чем с обычным
вайбкодингом – около 10
минут на задачу)
18

19. Как прийти к этому всей командой

03
Как прийти к этому всей
командой

20. Как генерить код из доки

01
01 Иметь в наличии
03
05
- AI-IDE
- базу знаний (документацию)
- MCP
02
04
06
20

21. Требования к инструментам

Подзаголовок
AI-IDE
Подзаголовок
MCP
Подзаголовок
База
знаний
- Редактирование кода
- Доступ к MCP
- Для всех внешних
систем
В примерах – Yandex Code
Assistant
В примерах – Tracker,
Wiki
- Легко редактируется и
читается всеми
группами
пользователей
- Доступа для чтения
ИИ
- Поддерживает
диаграммы как код
(plantUML, Mermaid)
В примерах – Yandex
Wiki
21

22. Как генерить код из доки

01
01 Иметь AI-IDE и MCP
02
02
03 Покрыть докой часть кода
04
05
06
22

23. Структура документации

Подзаголовок
User
Story
(не
для
ИИ)
в две строки
Подзаголовок
Техническая
документация
(для
ИИ)
в две строки
Текстовое описание требований от
бизнеса
Техническое описание архитектуры и
поведения системы.
Пишет – бизнес аналитик
Пишет - dev/SA в процессе системного
анализа
Формат – человеко-читаемое
текстовое описание
Формат – схемы, алгоритмы, диаграммы
23

24. Структура тех. доки для ИИ

Подзаголовок
Ендпоинты
Подзаголовок
Подзаголовок
- Ссылка на код
контракта (не текстом)
- Алгоритм работы
ендпоинта
24

25.

01
02
03
04
05
06
25

26. Структура тех. доки для ИИ

Подзаголовок
Ендпоинты
Подзаголовок
End-2-end
- Ссылка на код
контракта (не текстом)
- Алгоритм работы
ендпоинта
Объединяет ендпоинты в
сквозной процесс
Подзаголовок
- Сиквенс диаграмма
процесса
- Описание шагов
26

27.

01
02
03
04
05
06
27

28. Структура тех. доки для ИИ

Подзаголовок
Ендпоинты
Подзаголовок
End-2-end
Подзаголовок
Общие
блоки
- Ссылка на код
контракта (не текстом)
- Алгоритм работы
ендпоинта
Объединяет ендпоинты
в сквозной процесс
- Модели данных
- Статусные модели
- Ролевые модели и
доступы
- Сиквенс диаграмма
процесса
- Описание шагов
28

29.

01
02
03
04
05
06
29

30. Формат тех. доки для ИИ

01
01 Структура подобна структуре
02
03
04
05
06
системы
30

31. Формат тех. доки для ИИ

Подзаголовок
Подзаголовок
Подзаголовок

32. Формат тех. доки для ИИ

01
01 Структура подобна структуре
02
02 Страницы разбиты на небольшие
03
04
05
06
системы
блоки
32

33.

33

34.

01
02
03
04
05
06
ИИ с этим ок
34

35. Формат тех. доки для ИИ

01
01 Структура подобна структуре
02
02 Страницы разбиты на небольшие
03
03 Оставляйте перекрестные ссылки
04
04 Опишите в системном промпте как
05
06
системы
блоки
читать документацию
35

36. Как генерить код из доки

01
01 Иметь AI-IDE и MCP
0302 Вести изменения теперь через
02
03 Покрыть докой часть кода
04
05
06
доку
36

37. Как вести изменения

Разделять
as-is и to-be
Подзаголовок
Подзаголовок
Подзаголовок
Чтобы
идентифицировать
нужные изменения
37

38.

38

39. Как вести изменения

Разделять
as-is и to-be
Подзаголовок
Писать
в
тикет
что
Подзаголовок
именно сделать
Чтобы
идентифицировать
нужные изменения
Чтобы ИИ понял что
делать
Подзаголовок

40.

01
02
03
04
05
06
Скоуп задачи в тикете ограничивается контекстом ИИ
40

41. Специальный промпт для ИИ

41

42. Как генерить код из доки

01
01 Иметь AI-IDE и MCP
0302 Вести изменения теперь через
02
03 Покрыть докой часть кода
0404 Валидируйте доку с помощью ИИ
05
06
доку
42

43. Валидация доки через ИИ

43

44. Как генерить код из доки

01
01 Иметь AI-IDE и MCP
0302 Вести изменения теперь через
02
03 Покрыть докой часть кода
0404 Валидируйте доку с помощью ИИ
05
06
доку
Успех!
44

45. Предостережения

01
01 Не генерьте доку
02
03
04
05
06
45

46. Предостережения

01
01 Не генерьте доку
02
Вне
скоупа
нейронки
02
03
04
05
- проектирование архитектуры, контрактов
- настройка инфры
- определение стратегии тестирования
06
46

47. Предостережения

01
01 Не генерьте доку
02
Скоуп
нейронки
02
03
04
03 Договаривайтесь с командой
05
06
47

48.

«
AI нас заменит –
только если кто-то
сможет сказать четкое
Лао Цзы
ТЗ
(теперь мы это умеем)
48

49. Вопросы?