Основы
«Вайб‑кодинг» (vibe coding) — популярный термин для описания разработки, где человек формулирует намерение/задачу на естественном языке, а существенную часть кода генерирует LLM/ИИ‑агент, после чего разработчик валидирует результат и направляет итерации. В публичном поле термин связывают с постом Андрея Карпаты в феврале 2025 года, где он описывает практику «полностью отдаться вайбам» и почти не трогать клавиатуру, используя AI‑инструменты. [1]
Главная проблема «вайб‑кодинга» в больших системах: масштаб наказывает за неточность намерения. Чем больше кодовая база, интеграций и команд, тем дороже «догадки» модели и тем выше вероятность дрейфа требований, архитектурного разброда и непредсказуемых регрессий. Поэтому «вайб» в крупных проектах работает не как замена инженерии, а как ускоритель — при условии, что вы добавляете дисциплины намерения, контекста, контрактов, тестов и трассируемости. Эту идею прямо формулируют авторы GitHub Spec Kit: вместо хаотичного «vibe coding» команду спасает предварительная спецификация мотивации, требований и тех. аспектов перед передачей задач агентам. [2]
Ниже — компактный, но «боевой» набор методик/практик (16 штук), которые реально масштабируют AI‑разработку: Spec‑Driven Development (GitHub Spec Kit), AGENTS.md и IDE‑правила, MCP (контекст/инструменты), arc42 и ISO 42010, ADR, C4+Structurizr, RFC/KEP‑процессы, PR/FAQ (Working Backwards), ISO/IEEE/ГОСТ‑требования, API‑first/contract‑first (OpenAPI/AsyncAPI + генерация + Pact), Docs‑as‑Code, BDD/Specification by Example, TDD+пирамида тестов+property‑based testing, DDD+Event Storming, Trunk‑based development+CI/CD, а также архитектурная/безопасностная оценка рисков (ATAM + STRIDE). [3]
Отдельно отмечу: в прикреплённом вами конспекте есть идеи (например, про «vibe engineering» и практические «лайфхаки»), которые полезны как чек‑лист, но не всегда подтверждены первичными источниками — ниже я использую этот материал только как вспомогательное напоминание, а не как доказательство.
Почему «вайб» ломается на масштабе
В малых задачах «вайб‑кодинг» часто выигрывает скоростью: вы быстро получаете черновик и правите. На масштабе появляются четыре системные боли:
Контекст становится распределённым: часть знаний в головах людей, часть — в тикетах/чатах, часть — в коде и инфраструктуре. Если агент не получает явно оформленный контекст, он вынужден «догадываться», и цена ошибки растёт экспоненциально. Именно это и пытаются формализовать современные «AI‑native» процессы: Spec Kit описывает подход как многошаговое уточнение спецификации вместо «one‑shot генерации кода из промпта». [4]
Архитектура становится коммуникацией: в больших системах архитектура — это не «красивые диаграммы», а способ синхронизировать ожидания команд и управлять trade‑off’ами. Поэтому работают шаблоны вроде arc42 (структура архитектурной документации) и стандарты вроде ISO/IEC/IEEE 42010 (требования к описанию архитектуры). [5]
Интеграции и контракты доминируют: современная архитектура — это набор взаимодействий (HTTP, события, очереди). Поэтому API‑first/contract‑first с OpenAPI/AsyncAPI и контрактным тестированием снижает «пространство догадок» модели и стабилизирует совместимость компонентов. [6]
Качество нужно «производить», а не «проверять потом»: в AI‑генерации возрастает риск пропустить крайние случаи, небезопасные допущения и регрессии. Практики TDD и тестовая «пирамида» переносят проверку ближе к моменту генерации кода. [7]
Каталог методик и практик для масштабного «вайб‑кодинга»
Ниже каждая методика дана в одном формате: описание → принципы → когда применять → сильные/слабые стороны → артефакты → инструменты → шаги внедрения → лайфхаки с обоснованием. Если что‑то в первичных источниках не оговорено, помечаю как «не указано».
Spec‑Driven Development через GitHub Spec Kit
Краткое описание. Spec‑Driven Development (SDD) переворачивает классический подход: спецификация перестаёт быть одноразовой «бумагой» и становится центральным артефактом, который ведёт к исполняемой реализации (в том числе через AI‑агентов). [8]
Ключевые принципы. Intent‑first («что и зачем» до «как»), многошаговое уточнение требований, опора на «guardrails» и организационные принципы, итеративность, технология‑агностичность процесса. [4]
Когда применять. Большие фичи, «brownfield»‑модернизация, проекты с несколькими командами/модулями, где стоимость неправильной интерпретации требований высока. [4]
Сильные стороны. Снижает двусмысленность, делает «возврат к намерению» стандартной операцией, помогает делить работу на задачи для агентов, повышает воспроизводимость. [9]
Слабые стороны. Требует дисциплины спецификации (иначе просто «документ ради документа»), начальная стоимость выше, чем «навайбить прототип». (В источнике: детальная оценка трудоёмкости — не указано.) [4]
Артефакты/шаблоны. «Живая» спецификация (обычно Markdown), этапы/фазы процесса (Greenfield/Exploration/Brownfield). [4]
Инструменты/репозитории. GitHub Spec Kit и Specify CLI. [10]
Шаги внедрения. 1) Поставить Specify CLI и инициализировать проект/репозиторий под спецификации. [11]
2) Ввести правило: «любая существенная фича начинается со спеки (1–3 страницы)». [12]
3) Привязать CI: PR не мерджится без ссылки на spec/раздел спеки. (В первичных источниках конкретная политика CI — не указано.)
4) Научить агентов работать «от спеки»: генерация задач/кода/тестов, затем проверка на соответствие спекам. [12]
Практические лайфхаки с обоснованием.
# Рекомендованный «постоянный» способ установки
uv tool install specify-cli —from git+https://github.com/github/spec-kit.git
# Новый проект
specify init <PROJECT_NAME>
# Инициализация в существующем репозитории (пример с AI-агентом)
specify init . —ai claude
# Самопроверка окружения
specify check
Команды выше даны в README Spec Kit. [11]
Почему это работает: вы снижаете «энтропию входа» (инструмент ставится один раз и стандартизированно), а specify check превращает «у меня не работает агент/окружение» в быстро диагностируемую проблему (меньше скрытых условий — меньше галлюцинаций агента). [11]
Шаблон коммуникации «спека как контракт»: — «Сначала согласуем что (цели/границы/критерии успеха), потом отдаём агенту как. Любые спорные места фиксируем как вопросы/assumptions в спеках».
Почему: Spec Kit прямо ставит intent‑driven и многократное уточнение выше «one‑shot генерации». [4]
Инструкции для coding‑агентов: AGENTS.md и IDE‑правила
Краткое описание. AGENTS.md — открытый формат «README для агентов»: предсказуемое место, где вы задаёте правила работы AI‑агента с репозиторием. Поддерживается как проектом agents.md, так и документацией OpenAI для Codex. [13]
Ключевые принципы. Иерархия инструкций (глобальные → репозиторные → локальные overrides), минималистичные «working agreements», явные команды проверки (lint/test), запреты на опасные действия и правила внесения зависимостей. [14]
Когда применять. Всегда, когда у вас есть AI‑агент в IDE/CLI (особенно в монорепо и в распределённых командах). В противном случае агент будет «переизобретать» правила стиля/структуры и ломать согласованность. [15]
Сильные стороны. Стабилизирует поведение агентов, уменьшает «дрейф» по стилю и архитектуре, ускоряет онбординг. [16]
Слабые стороны. Риск превратить файл в «свалку правил» (тогда агент начнёт игнорировать/обрезать контекст). Предельные размеры/ограничения зависят от инструмента (частично описано в настройках Codex; для других — не указано). [17]
Артефакты/шаблоны. — AGENTS.md в корне репозитория. — AGENTS.override.md в подкаталоге для локальных правил. [17]
— IDE‑правила: например, Cursor хранит project rules в .cursor/rules как Markdown‑файлы с областями действия (globs). [18]
Инструменты/репозитории.
— Спецификация/примеры AGENTS.md: проект agents.md. [19]
— Официальный гайд OpenAI Codex по AGENTS.md. [17]
— Cursor Rules: .cursor/rules (официальные доки Cursor). [18]
Шаги внедрения. 1) Сформировать «минимальные соглашения» (5–15 строк) и положить в AGENTS.md. [20]
2) Добавить команды проверки, которые агент обязан запускать. [17]
3) Для монорепо — сделать overrides рядом со специализированными компонентами (платежи, security‑критичные части). [17]
4) Для IDE‑агентов — перенести «операционные» подсказки (где что лежит, как запускать) в rules‑файлы, scoped по путям. [18]
Практические лайфхаки с обоснованием.
Минимальный скелет (адаптируйте под стек):
# AGENTS.md
## Цели
— Поддерживать читаемость, тестируемость и предсказуемость изменений.
## Обязательные проверки перед PR
— Запусти `make test` (или аналог) после изменения логики.
— Запусти линтер/форматтер: `make lint`.
## Архитектурные ограничения
— Не добавляй новые production-зависимости без явного согласования.
— Не меняй публичные контракты API без обновления OpenAPI/AsyncAPI и контрактных тестов.
Почему: официальное руководство OpenAI рекомендует в репозитории фиксировать «ожидания» (lint, документация, правила сервисов) и поддерживает layered overrides, чтобы агент видел правила именно в контексте директории, где работает. [17]
Конкретные команды из гайда OpenAI (полезно как «референс‑паттерн»):
mkdir -p ~/.codex
# затем создайте ~/.codex/AGENTS.md
codex —ask-for-approval never «Summarize the current instructions.»
codex —cd services/payments —ask-for-approval never «List the instruction sources you loaded.»
Почему: вы проверяете, что агент действительно «подхватил» правила, а не работает «в вакууме». Это снижает риск «невидимых предположений» и, как следствие, неверных правок. [17]
IDE‑правила Cursor как «расширение памяти проекта»: храните короткие, scoped‑правила вида «в этом модуле используем X, тесты запускаются так‑то», потому что Cursor прямо позиционирует rules как version‑controlled знания и workflow‑шаблоны. [18]
Контекст и инструменты: Model Context Protocol (MCP)
Краткое описание. MCP — открытый протокол интеграции LLM‑приложений (IDE/чатов/агентов) с внешними источниками данных и инструментами через стандартизированные сообщения; в спецификации упоминается JSON‑RPC 2.0 и разделение на host/client/server. [21]
Ключевые принципы. Стандартизированный доступ к «контексту» (ресурсы, промпты, инструменты), снижение NxM‑проблемы интеграций, композиция инструментов. [22]
Когда применять. Когда агенту нужно безопасно и предсказуемо работать с репозиториями, документацией, трекерами, API, базами знаний; особенно в enterprise‑условиях, где «быстро дать агенту доступ» без стандарта приводит к зоопарку интеграций. [23]
Сильные стороны. Повторное использование коннекторов/серверов, совместимость «инструменты↔агенты», меньше кастомной обвязки. [23]
Слабые стороны. Требует продуманной модели доверия и прав (в спецификации безопасность как процесс внедрения — не указано). Также возможны риски при неправильной композиции инструментов (общий класс рисков для agentic‑интеграций подтверждают публичные обсуждения MCP‑экосистемы; подробная модель угроз — вне рамок спецификации). [24]
Артефакты/шаблоны.
— Спецификация MCP с нормативными ключевыми словами (MUST/SHOULD и т. п.). [25]
— Схемы/JSON Schema (в репозитории указано, что TypeScript‑schema — источник истины). [26]
Инструменты/репозитории.
— Репозиторий спецификации MCP. [26]
— Официальная статья Anthropic о MCP. [27]
— Официальная спецификация на сайте MCP. [25]
Шаги внедрения. 1) Определить, какие источники «контекста» агенту действительно нужны (код, ADR, спеки, runbooks).
2) Поднять MCP‑сервер(а) для этих источников и ограничить права до «минимально достаточных». (Конкретная RBAC‑схема — не указано.)
3) Встроить MCP в рабочие инструменты команды (IDE/агенты).
4) Добавить «гигиену контекста»: логировать вызовы инструментов и внедрить правило «агент объясняет, какие ресурсы использовал». (В спецификации: требование «объяснять» — не указано.)
Практические лайфхаки с обоснованием. — Лайфхак: в AGENTS.md добавить правило: «перед изменениями в коде агент обязан перечислить ресурсы/файлы, которые он прочитал через MCP, и указать, какие из них определяют контракт».
Почему: MCP стандартизирует подключение контекста/инструментов; если вы требуете прозрачности, вы снижаете риск «скрытой галлюцинации» и улучшаете воспроизводимость ревью. [28]
arc42 как «скелет» архитектурных артефактов
Краткое описание. arc42 — практичный и прагматичный шаблон для коммуникации и документации архитектуры ПО (open source). [29]
Ключевые принципы. Стандартизированная структура (легче читать/обновлять), «управляемое усилие» поддержки документации. [30]
Когда применять. Почти всегда в «средних и больших» проектах, где архитектуру должны понимать разные роли; особенно полезно, когда AI‑агенты пишут код и вам нужен «каркас смысла», к которому можно возвращаться. [31]
Сильные стороны. Единый формат по разделам; удобно хранить в репозитории; хорошо сочетается с ADR (в arc42 даже есть раздел «Architecture Decisions»). [32]
Слабые стороны. Если заполнять «всё и сразу», можно перегрузить команду; требует культуры актуализации (в противном случае становится архивом). (Точная «норма страниц» — не указано.)
Артефакты/шаблоны. Русская версия arc42 включает 12 секций (файлы adoc/01…12). [33]
Канонический список (как в RU‑шаблоне): 1) introduction & goals
2) constraints
3) context & scope
4) solution strategy
5) building block view
6) runtime view
7) deployment view
8) concepts
9) architecture decisions
10) quality requirements
11) technical risks
12) glossary [33]
Инструменты/репозитории. Репозиторий arc42‑template (включая RU). [34]
Шаги внедрения. 1) Взять «plain»‑версию (без подсказок) и положить в /docs/architecture/arc42/. (В самом шаблоне отмечено, что есть версия с подсказками и plain‑версия). [33]
2) Заполнить «минимальный» набор: 1,2,3,4,5,7,10,11 (остальное — по мере надобности).
3) Привязать обновление arc42 к RFC/ADR: любое существенное изменение архитектуры требует обновить 4/5/7/10/11.
4) Встроить в CI проверку «архит‑доки изменены при изменении модулей X/Y» (конкретная реализация — не указано).
Практические лайфхаки с обоснованием. — Лайфхак: используйте AI в режиме «синтеза», но только от первичных артефактов: дайте агенту существующие ADR + диаграммы C4 + требования и попросите заполнить разделы arc42 черновиком.
Почему: arc42 ценен как структура; AI быстрее заполняет «форму», но смысл должен исходить из ваших решений и ограничений, иначе получите «красивый фанфик». Сама идея стандартизированной структуры — ключевое преимущество arc42. [35]
Архитектурные стандарты: ISO/IEC/IEEE 42010 + связка с arc42
Краткое описание. ISO/IEC/IEEE 42010:2022 задаёт требования к структуре и выражению описания архитектуры (architecture description) для различных «entities of interest» (ПО, системы, предприятия и т. д.). [36]
Ключевые принципы. Явные стейкхолдеры и их concerns, views/viewpoints, различение «архитектуры» и «описания архитектуры». [36]
Когда применять. Высокий риск, регуляторика/аудит, гос/энтерпрайз‑контракты, сложные socio‑technical системы. Для «обычных» продуктовых команд можно использовать как «референс‑модель» поверх arc42. [36]
Сильные стороны. Дает язык и «рамку» для сравнимых архитектурных описаний; повышает качество ревью. [37]
Слабые стороны. Может восприниматься как «тяжеловесно» без адаптации; полный текст стандарта часто платный (на странице ISO доступен sample; детали внедрения — не указано). [38]
Артефакты/шаблоны. Формальные architecture descriptions с view/viewpoint; в arc42 многие разделы естественно мапятся на «views» (context/runtime/deployment и т. п.). (Официальный «маппинг arc42↔ISO» — не указано.)
Инструменты. Не привязан к инструментам (стандарт).
Шаги внедрения. 1) Зафиксировать список стейкхолдеров и concerns как часть arc42‑раздела 1/2.
2) Определить набор viewpoints (например: C4‑контекст/контейнеры, deployment, runtime).
3) Включить процедуру редактирования и ревью архитектурного описания вместе с кодом (Docs‑as‑Code).
4) Для критичных систем — добавить формальную архитектурную оценку (см. ATAM ниже). [39]
Лайфхак с обоснованием.
Если у вас «вайб‑кодинг» ускоряет реализацию, ISO 42010/arc42 нужны как «стоп‑кран»: любая новая подсистема обязана ответить на concerns (безопасность, производительность, изменяемость). Почему: стандарт прямо про «структуру и выражение» архитектурного описания для разных сущностей и доменов; он дисциплинирует обсуждение не только «что сделать», но и «какие последствия». [38]
Architecture Decision Records (ADR)
Краткое описание. ADR — короткая запись одного архитектурного решения с контекстом и последствиями. Концепт популяризировал Michael Nygard в статье 2011 года. [40]
Ключевые принципы. Одно ADR = одно решение; фиксируется контекст/forces; хранится в репозитории; имеет статус (proposed/accepted/superseded). [41]
Когда применять. Всегда, когда решение влияет на архитектуру/контракты/техдолг; особенно в распределённых командах и при онбординге. [42]
Сильные стороны. Снижает «потерю памяти», повышает качество ревью, помогает AI‑агентам понимать «почему так». [43]
Слабые стороны. Возможен «ADR‑спам»; нужна дисциплина «суперсидинга» и связей. (Автоматические правила качества ADR — не указано.)
Артефакты/шаблоны. Классическая структура: Title, Status, Context, Decision, Consequences. [44]
Инструменты/репозитории. adr-tools (Nat Pryce) как CLI для ведения ADR‑лога. [45]
Шаги внедрения. 1) Договориться, где лежат ADR (например, docs/adr/). Nygard предлагал хранить в репозитории (пример пути есть в статье). [46]
2) Ввести правило: «PR меняет архитектуру → добавь/обнови ADR».
3) Добавить генерацию TOC/графа решений (если используете adr-tools). [47]
Практические лайфхаки с обоснованием. — Лайфхак: в промпте агенту при сложном изменении добавляйте: «Сначала предложи ADR (Context/Decision/Consequences), затем код».
Почему: ADR заставляет агента артикулировать trade‑off’ы и последствия до генерации кода; это соответствует сути ADR как фиксации «forces» и решения. [46]
Мини‑шаблон ADR (адаптируйте):
# ADR-00NN: <краткое решение>
Status: Proposed | Accepted | Superseded
Date: YYYY-MM-DD
## Context
## Decision
## Consequences
Структура соответствует распространённым ADR‑шаблонам. [48]
C4 Model + Structurizr DSL как «архитектура‑как‑код»
Краткое описание. C4 — «abstraction‑first» способ визуализировать архитектуру на 4 уровнях: System Context, Container, Component, Code. Официальный сайт подчёркивает, что это авторская (Simon Brown) модель для консистентных диаграмм. [49]
Ключевые принципы. Иерархия абстракций, разные «истории» для разных аудиторий, не обязательно использовать все уровни. [50]
Когда применять. Когда нужно быстро согласовать картину системы между командами/стейкхолдерами; идеально как «язык» для AI‑агентов при генерации новых модулей (агенту проще следовать явной декомпозиции). [51]
Сильные стороны. Простота, обучаемость, связь с «моделированием как кодом». [52]
Слабые стороны. Нужна дисциплина именования; «Code level» часто избыточен. (Формальные правила цвет/форма — intentionally гибкие; «обязательные» визуальные стандарты — не указано.) [50]
Артефакты/шаблоны. Набор диаграмм C4 + легенда + ссылки на ADR/arc42.
Инструменты/репозитории. Structurizr DSL — текстовый DSL для описания модели (на базе C4) и генерации видов. [53]
Пример Structurizr DSL из документации:
workspace {
model {
u = person «User»
ss = softwareSystem «Software System»
u -> ss «Uses»
}
views {
systemContext ss {
include *
autolayout lr
}
}
}
Шаги внедрения. 1) Сделать C4 Context + Container «минимальным стандартом» для каждого сервиса/подсистемы. [55]
2) Хранить DSL/диаграммы рядом с кодом, обновлять в PR.
3) Ссылаться из диаграмм на ADR/arc42‑разделы.
4) Для больших систем — «модель одна, видов много» (главная идея моделирования vs рисования). [56]
Практические лайфхаки с обоснованием. — Лайфхак: спрашивайте у агента «на каком уровне C4 ты сейчас работаешь?» и «какой контейнер/компонент меняется?».
Почему: C4 прямо строится на уровнях «zoom», и смешивание абстракций — частая причина путаницы в архитектурных обсуждениях. [57]
RFC/KEP‑процессы для крупных изменений
Краткое описание. RFC‑процесс — способ проводить существенные изменения через формализованное обсуждение и консенсус. Отличный «первичный» пример — репозиторий Rust RFCs: он предназначен для «consistent and controlled path for changes», при этом мелкие изменения идут обычным PR‑потоком. [58]
Похожая практика в Kubernetes — KEP (Kubernetes Enhancement Proposals) для предложения и координации новых инициатив. [59]
Ключевые принципы. Разделение «мелкое = PR» vs «существенное = дизайн‑процесс»; публичное обсуждение; единый шаблон; статус/стадии. [60]
Когда применять. Новые подсистемы, большие рефакторинги, смена контрактов, изменения, затрагивающие несколько команд.
Сильные стороны. Прозрачность и согласование до реализации; идеально сочетается с AI‑агентами, потому что «формализует намерение», уменьшая вероятность неверной генерации. [61]
Слабые стороны. Может замедлять изменения без правильного порога входа; риск «документ вместо результата» (как и любой процесс).
Артефакты/шаблоны. RFC/KEP документ + обсуждение в PR + список alternatives + rollout plan (конкретные поля зависят от проекта; универсальный ISO‑шаблон — не указано).
Инструменты/репозитории. Rust RFCs repo и шаблон 0000-template.md (как пример), Kubernetes enhancements repo (KEPs). [60]
Шаги внедрения. 1) Завести /rfcs или /keps в репозитории и простой порог: «если меняет публичный контракт / 2+ команды / миграция данных — RFC обязателен».
2) Принять жизненный цикл статусов (Draft → Accepted → Implemented → Superseded).
3) Привязывать реализацию в коде к RFC ссылкой в PR/коммитах.
4) «Закрывать петлю»: после внедрения обновить ADR и arc42. (В Rust RFC: связь с реализацией — концептуально есть; конкретная политика — не указано.) [62]
Практические лайфхаки с обоснованием. — Лайфхак: используйте AI как «редактора RFC», но не как «автора решения»: пусть агент предложит раздел Alternatives + риски + вопросы для ревьюеров.
Почему: Rust‑RFC подчёркивает роль стейкхолдеров и уверенности в направлении; AI хорошо генерирует варианты и чек‑листы, но финальное решение требует ответственности команды. [62]
PR/FAQ (Working Backwards) как дизайн‑ориентированная спецификация продукта
Краткое описание. PR/FAQ — артефакт процесса Working Backwards: вы пишете «пресс‑релиз» и FAQ как будто продукт уже запускается, фокусируясь на потребностях клиента и проверяя идею до реализации. [63]
Ключевые принципы. Customer‑centric, «начать с конца», ясность через письменную форму, ранняя проверка ценности/границ. [64]
Когда применять. Новые продукты/крупные инициативы, где риск построить «не то» выше, чем риск «потратить пару дней на документ».
Сильные стороны. Резко уменьшает «разночтения» между бизнесом и инженерией; хорошо подходит для AI‑разработки, потому что формирует «сценарии и критерии» ещё до кода (топливо для SDD/BDD). [65]
Слабые стороны. Может восприниматься как «продуктовая бюрократия»; требует навыка письма и фасилитации обсуждений. (Стандартизированный объём PR/FAQ в источниках часто описывается, но «обязательная длина» — не указано.)
Артефакты/шаблоны. 1) Press Release; 2) FAQ (в т. ч. вопросы внутренних стейкхолдеров). [66]
Инструменты/репозитории. Официальные материалы Working Backwards (сайт/шаблоны от авторов подхода). [67]
Шаги внедрения. 1) Ввести правило: «любая фича > N недель разработки начинается с PR/FAQ».
2) Делать PR/FAQ ревью отдельно до планирования спринтов.
3) Конвертировать FAQ в acceptance criteria (BDD) и в high‑level spec (Spec Kit). [68]
Практические лайфхаки с обоснованием. — Лайфхак: попросите LLM сначала «сжать PR» до 5–7 тезисов (value proposition), затем развернуть FAQ, и только потом разрешайте генерацию архитектуры/кода.
Почему: PR/FAQ целится в ясность ценности; LLM отлично помогает с итеративным редактированием текста, но порядок «ценность → вопросы → реализация» лучше предотвращает промахи в продукте. [69]
Формальные требования и документация: ISO/IEC/IEEE 29148 + ГОСТ 34/19
Краткое описание. ISO/IEC/IEEE 29148:2018 описывает процессы requirements engineering и требования к информационным элементам/содержанию артефактов требований на протяжении жизненного цикла. [70]
В русскоязычном поле для «тяжёлых» проектов часто применяются ГОСТ‑серии, например ГОСТ 34.602‑2020 (ТЗ на создание автоматизированной системы) и серия ГОСТ 19 (ЕСПД, виды программных документов). [71]
Ключевые принципы. Нормативная структура требований/ТЗ, единый формат, возможность аудита и договорной фиксации. [72]
Когда применять. Регуляторика, госзаказ, крупные корпорации, контрактная разработка, safety‑/security‑critical системы. Для стартапов/продуктовых команд — использовать «облегчённые выжимки» (иначе стоимость процесса может превысить пользу).
Сильные стороны. Трассируемость, юридическая определённость, воспроизводимое качество требований. [73]
Слабые стороны. Тяжеловесность; риск «формального соответствия без реального понимания»; требуется опыт аналитиков/системной инженерии (уровень навыков: высокий).
Артефакты/шаблоны.
— SRS/набор требований по ISO 29148 (конкретные поля стандарта — частично в платном тексте; на странице ISO — общая аннотация). [74]
— ТЗ по ГОСТ 34.602‑2020. [75]
— Перечень видов программных документов по ГОСТ 19.101 (актуальная редакция встречается как PDF; детали — по документу). [76]
Инструменты. Документооборот/репозиторий (не указано), статические генераторы (можно Docs‑as‑Code).
Шаги внедрения (практично). 1) Определить «минимально необходимый» набор документов под договор/аудит (вместо «всё по ГОСТ/ISO»).
2) Встроить требования в инженерный поток: требования → спека → тесты → код (иначе документ «умирает»). [77]
3) Принять policy: «изменение требования → изменение тестов/контрактов/доков в том же PR». [78]
Лайфхак с обоснованием.
Автоматизируйте «склейку» требований и реализации через AI, но строго по источнику: LLM помогает конвертировать формализованные требования (ISO/ГОСТ) в user stories, acceptance criteria и скелеты тестов. Почему: ISO 29148 акцентирует процессы и информационные элементы требований; LLM сильна именно в трансформации форматов при сохранении смысла — если вы не даёте ей «домысливать» требования. [79]
API‑first и contract‑first: OpenAPI/AsyncAPI + генерация + Pact
Краткое описание. OpenAPI задаёт стандартное, язык‑агностичное описание HTTP API, позволяющее людям и машинам понять возможности сервиса без доступа к коду. [80]
AsyncAPI — аналогичный стандарт для event‑driven / асинхронных API. [81]
Pact — инструмент контрактного тестирования интеграций (HTTP и message), где контракты проверяются изолированно (consumer/provider), снижая потребность в хрупких интеграционных окружениях. [82]
Ключевые принципы. Контракт — «истина» интерфейса; генерация клиентов/серверов/моков из контракта; проверки контрактов в CI; «не мерджить breaking change без миграции». [83]
Когда применять. Микросервисы, фронт↔бэк, интеграции между командами, публичные API, события/шины данных.
Сильные стороны. Резко снижает ambiguity для AI‑агентов; стабилизирует интеграции; ускоряет параллельную разработку. [84]
Слабые стороны. Контракты нужно поддерживать; возможен «спек‑дрифт», если код меняют без обновления OpenAPI/AsyncAPI. (Авто‑детект дрейфа — не указано.)
Артефакты/шаблоны. openapi.yaml/json, asyncapi.yaml/json, контракты Pact (pact files), политики версионирования.
Инструменты/репозитории.
— OpenAPI спецификация (официальный портал). [85]
— AsyncAPI спецификация (официальный портал). [81]
— OpenAPI Generator CLI. [86]
— Pact docs. [82]
Шаги внедрения. 1) Принять contract‑gate: «PR меняет контроллер/endpoint → меняет OpenAPI + тесты».
2) Включить генерацию SDK/клиента в CI (или как артефакт релиза). [87]
3) Добавить контрактные тесты Pact между потребителем и провайдером. [82]
4) Для событий — описывать каналы/сообщения в AsyncAPI и валидировать схемы. [88]
Практические лайфхаки с обоснованием.
OpenAPI Generator CLI (пример из документации):
# пример установки через npm и запуск через npx
npm install @openapitools/openapi-generator-cli
npx openapi-generator-cli version
# генерация клиента/серверного скелета (пример параметров — зависит от языка)
openapi-generator-cli generate -i docs/openapi.yaml -g typescript-fetch -o generated/
Подход и команды описаны в репозитории/доках генератора. [89]
Почему: генерация превращает контракт в «исполняемую границу». AI‑агенту легче писать код, если типы/эндпойнты и модели данных уже заданы машинно‑читаемо.
Pact как замена части «тяжёлых» интеграционных тестов: Почему: Pact прямо объясняет, что контрактные тесты проверяют «shared understanding» без поднятия всех сервисов вместе, что особенно важно, когда AI‑агенты часто меняют код в нескольких местах. [82]
Docs‑as‑Code как фундамент «живой» документации
Краткое описание. Docs‑as‑Code (Write the Docs) — философия: писать документацию теми же инструментами и процессами, что и код (issue tracker, Git, plaintext markup, code review, automated tests). [90]
Ключевые принципы. Документы в Git; PR‑ревью; автоматические проверки; публикация через CI/CD; документация рядом с изменениями в коде. [91]
Когда применять. Почти всегда, когда документация должна «жить» вместе с продуктом; особенно в распределённых командах.
Сильные стороны. Снижает шанс устаревания; улучшает совместную работу; позволяет превью документации в PR. [92]
Слабые стороны. Порог входа для нерепозиторных ролей; нужно продумать UX публикации (иначе саботаж). (Единый «идеальный» стек — не указано.)
Артефакты/шаблоны. docs/ в репозитории, README, архитектурные разделы, ADR‑лог, «how to run tests», runbooks.
Инструменты/репозитории.
— MkDocs (официальный сайт). [93]
— Docusaurus (официальные docs). [94]
Шаги внедрения. 1) Выбрать генератор (MkDocs для простоты; Docusaurus для больших порталов с версионированием/i18n). [95]
2) Положить docs рядом с кодом (docs/ + конфиг). Для MkDocs дефолтная структура описана в user guide. [96]
3) В CI: сборка docs + link check + публикация превью на PR (детали реализации — не указано).
4) Ввести правило: «изменил поведение — обнови docs в том же PR». [97]
Практические лайфхаки с обоснованием.
MkDocs базовые команды (документированы как стандартный workflow):
mkdocs new .
mkdocs serve
mkdocs build
[98]
Почему: быстрый локальный preview снижает стоимость актуализации, значит documentation перестаёт быть «жертвой дедлайна».
AI‑лайфхак: генерируйте «черновики» документации из PR‑diff + тестов, но заставляйте модель следовать style guide (например, Google style guide для Markdown/документации). Почему: Google публично публикует практики документирования и стиль, а также отдельные рекомендации по использованию LLM в техническом письме (например, задавать цель документа и ограничивать избыточную длину). [99]
BDD и Specification by Example: исполняемые спецификации
Краткое описание. BDD (Dan North) выросла из agile‑практик и фокусируется на поведении системы, помогая командам договориться через примеры и автоматизируемые сценарии. [100]
Gherkin (Cucumber) предоставляет структуру и ключевые слова для «executable specifications». [101]
Specification by Example (Gojko Adzic) — практика спецификации требований и тестов через реалистичные примеры. [102]
Ключевые принципы. Given‑When‑Then; примеры как источник истины; совместное уточнение домена; сценарии = acceptance tests. [103]
Когда применять. Сложная бизнес‑логика, много стейкхолдеров, высокий риск недопонимания, интеграции. Отлично сочетается с AI: агент может генерировать код под готовые сценарии.
Сильные стороны. Улучшает коммуникацию; сценарии можно запускать; снижает двусмысленность требований. [104]
Слабые стороны. Сценарии могут стать хрупкими; нужно уметь писать хорошие примеры; риск «слишком много e2e через BDD». (Оптимальная гранулярность — не указано.)
Артефакты/шаблоны. .feature файлы Gherkin.
Пример (скелет):
Feature: Payments refunds
Scenario: Refund succeeds for captured payment
Given a captured payment of 1000 RUB
When I request a refund of 1000 RUB
Then the refund status should be «Succeeded»
Инструменты/репозитории. Cucumber/Gherkin docs. [101]
Шаги внедрения. 1) Задать правилом: «прежде чем агент пишет код — появляется хотя бы 2–5 сценариев».
2) Связать сценарии с Spec Kit/PRFAQ (FAQ → сценарии). [105]
3) Автоматизировать запуск в CI.
Практические лайфхаки с обоснованием. — Лайфхак: просите AI превращать PR/FAQ‑вопросы в Gherkin‑сценарии, а затем писать код «до зелёного пайплайна».
Почему: BDD исторически создавалась для уменьшения недопонимания и улучшения совместной работы; сценарии как «semi‑structured natural language» — ровно то, с чем LLM работают лучше всего. [106]
TDD и тестовая пирамида как «страховка» от AI‑регрессий
Краткое описание. TDD — цикл Red‑Green‑Refactor; Martin Fowler подчёркивает, что это сердце процесса плюс предварительный список тест‑кейсов. [107]
Test Pyramid (Fowler) — метафора распределения тестов по уровням гранулярности. [108]
Ключевые принципы. Тесты как дизайн‑инструмент; маленькие итерации; большинство тестов — быстрые (unit), меньше — интеграционные, ещё меньше — end‑to‑end. [7]
Когда применять. Всегда, где важна надёжность; особенно при активной работе агентов, которые «быстро меняют много строк».
Сильные стороны. Раннее обнаружение дефектов; упрощает рефакторинг; делает изменения «безопаснее». [7]
Слабые стороны. Требует навыка; иногда замедляет «первый проход», если команда новичков; может давать ложное чувство безопасности при плохом дизайне тестов.
Артефакты/шаблоны. Набор unit/integration/e2e + CI‑pipeline.
Инструменты. Любые тест‑фреймворки; в качестве дополнительной практики — property‑based testing (см. ниже) для крайних случаев.
Шаги внедрения. 1) Ввести «Definition of Done»: «изменение без теста недопустимо» (с исключениями, если явно зафиксировано).
2) Переориентировать AI‑агента: «сначала тест, потом реализация».
3) В CI — быстрый слой тестов как gate на каждый PR; более тяжёлые — по расписанию/на релиз.
Практические лайфхаки с обоснованием. — Лайфхак: промпт для агента «Сгенерируй минимальный failing test, потом код до зелёного, потом refactor без изменения поведения».
Почему: Red‑Green‑Refactor — центральная формула TDD; она структурирует работу агента и снижает риск «случайной логики». [107]
Property‑based testing (Hypothesis) как усилитель качества спецификаций
Краткое описание. Property‑based testing проверяет свойства/инварианты функции на множестве автоматически сгенерированных входов, включая edge cases; Hypothesis определяет это прямо в документации. [109]
Ключевые принципы. Описываем свойства, а не набор примеров; генераторы данных; shrinking контрпримеров (в Hypothesis это стандартное поведение; детальный алгоритм — не указано). [109]
Когда применять. Сложные преобразования данных, парсинг, сериализация, финансы/лимиты, алгоритмы; места, где AI‑код особенно склонен «забыть» крайний случай.
Сильные стороны. Находит неожиданные ошибки; повышает уверенность в инвариантах. [109]
Слабые стороны. Требует умения формулировать свойства; иногда сложнее дебажить.
Артефакты. Набор property‑tests.
Инструменты. Hypothesis. [110]
Шаги внедрения. 1) Выбрать 3–5 критических модулей и описать инварианты.
2) Добавить Hypothesis‑тесты рядом с unit‑тестами.
3) Запускать их в CI (возможно с ограничением по времени).
Лайфхак с обоснованием.
Попросите LLM помочь придумать свойства (не код), например: «какие инварианты должны сохраняться при сериализации/десериализации, сортировке, нормализации?»
Почему: Hypothesis прямо говорит, что вы описываете диапазон входов и свойства, а библиотека подбирает значения, включая edge cases; LLM хорошо работает как генератор гипотез, которые потом проверяются тест‑раннером. [111]
DDD + Event Storming как «антидот» против доменной галлюцинации
Краткое описание. DDD (Eric Evans) — подход к сложным доменам: фокус на core domain, совместное моделирование и ubiquitous language внутри bounded context; эти принципы явно изложены в DDD‑ресурсах Evans. [112]
EventStorming — workshop‑формат, созданный Alberto Brandolini; официальный сайт и материалы привязывают его к collaborative modeling и «learning for complex domains». [113]
Ключевые принципы.
— DDD: bounded contexts, единый язык, модель как центр проектирования. [112]
— EventStorming: моделирование через события и совместное обучение. [114]
Когда применять. Много бизнес‑правил, несколько команд, запутанные процессы, интеграции между контекстами, планирование микросервисов/модульного монолита.
Сильные стороны. Снижает риск «построить неправильные сущности»; формирует словарь, который потом можно положить в AGENTS.md и спеки для агентов. [115]
Слабые стороны. Потребность в фасилитации; можно «утонуть в моделях», если не привязывать к поставке ценности.
Артефакты/шаблоны.
— Ubiquitous language glossary (можно как часть arc42 glossary). [116]
— Карта событий/потоков (результат EventStorming). [117]
— Bounded context map (не указано в источниках выше как «шаблон», но как концепт DDD — да). [118]
Инструменты. Доски (онлайн/offline), любая документация; официальная книга/материалы Brandolini. [119]
Шаги внедрения. 1) Провести EventStorming‑сессию по «сквозному» бизнес‑процессу. [120]
2) Зафиксировать события/термины как glossary и «domain rules» для агентов. [121]
3) Определить bounded contexts и контракты между ними (OpenAPI/AsyncAPI). [122]
4) Превратить ключевые сценарии в BDD. [104]
Лайфхак с обоснованием.
Запишите «словарь домена» отдельным файлом и подключайте в AGENTS.md/rules: переопределяйте запрещённые синонимы (например, «платёж» ≠ «транзакция»).
Почему: DDD делает ubiquitous language центральным механизмом согласования; если агент оперирует неправильными терминами, он почти гарантированно неверно смоделирует сущности/поля/события. [112]
Trunk‑based development + CI/CD как процесс «быстрых, безопасных» итераций
Краткое описание. Trunk‑Based Development — модель ветвления, где разработчики интегрируют маленькие изменения часто в «trunk/main», избегая долгоживущих веток. Официальный сайт даёт определение и детально раскрывает практики. [123]
Ключевые принципы. Маленькие партии изменений, постоянная интеграция, release‑ready trunk, техники вроде feature flags и др. [123]
Когда применять. Высокая скорость изменений, много параллельной работы, сильная опора на CI/CD — типичный «AI‑ускоренный» продукт.
Сильные стороны. Меньше merge hell, быстрее обратная связь, лучше подходит под CI/CD. [124]
Слабые стороны. Требует зрелого CI и дисциплины «не ломать билд»; для очень слабой инфраструктуры может быть болезненно.
Артефакты/шаблоны. Политики PR, feature flags, правила релизных веток (если используются), «release from trunk» практики. [125]
Инструменты. Git, CI, feature flag платформы (экосистема — не указано).
Шаги внедрения. 1) Настроить CI «на каждый PR» как обязательный gate.
2) Ограничить время жизни feature‑ветки (час‑два/день, но не недели). (Точные пороги — не указано.)
3) Ввести feature flags для неполных фич. [126]
4) Согласовать hotfix‑процесс: чинить на trunk и cherry‑pick в release branch (описано как best practice на сайте). [127]
Лайфхак с обоснованием.
Если AI‑агент делает изменения, увеличивающие риск, требуйте «малых PR»: один intent → один PR.
Почему: trunk‑based строится на маленьких, частых интеграциях; это прямо уменьшает конфликты и ускоряет feedback loop. [124]
Архитектурная и security‑оценка рисков: ATAM + threat modeling STRIDE
Краткое описание. ATAM (Architecture Tradeoff Analysis Method) — структурированная техника для понимания trade‑off’ов и оценки архитектуры относительно конкурирующих quality attributes; первичный источник — отчёт SEI (Carnegie Mellon). [128]
Threat modeling в Microsoft SDL использует STRIDE для выявления угроз и планирования mitigations; Microsoft описывает это как core element SDL и даёт guidance/инструмент (Threat Modeling Tool). [129]
Ключевые принципы.
— ATAM: quality attributes → сценарии → trade‑offs → риски/чувствительные точки. [128]
— Threat modeling: построить DFD/диаграмму, идентифицировать угрозы (STRIDE), определить mitigations, валидировать. [130]
Когда применять. High‑risk архитектуры (данные/деньги/персональные данные), новые платформенные решения, критичные интеграции, «перед большим вложением».
Сильные стороны. Раннее обнаружение рисков; дисциплина обсуждения безопасности и качества.
Слабые стороны. Требует времени и фасилитации; может казаться «слишком рано» для маленьких проектов.
Артефакты/шаблоны.
— ATAM отчёт/выводы (формат — не указано в кратком описании).
— DFD + список угроз/митигейшенов (Threat Modeling Tool). [131]
Инструменты.
— SEI материалы по ATAM. [128]
— Microsoft Threat Modeling Tool и docs. [132]
Шаги внедрения. 1) Сформулировать quality attributes (arc42 раздел 10) и техриски (раздел 11). [33]
2) Провести укороченный ATAM‑воркшоп на ключевых сценариях. [128]
3) Сделать threat modeling по STRIDE на DFD и добавить mitigations в backlog. [133]
4) Зафиксировать решения ADR‑ами и обновить архитектурные документы. [134]
AI‑лайфхак с обоснованием.
Пусть LLM помогает составить «каталог вопросов STRIDE» по вашему DFD, но ответы и принятие mitigations оставляйте людям.
Почему: Microsoft прямо использует STRIDE как структуру для идентификации угроз; LLM может ускорить «генерацию вопросов», но безопасность требует ответственности и верификации. [135]
Сравнительная матрица методик
Условные значения:
— Масштаб: S (малый), M (средний), L (большой), XL (очень большой/enterprise).
— Команда: 1–5 / 5–20 / 20+; remote‑friendly: да/частично/нет.
— Документация: light / medium / heavy.
— Скорость изменений: высокая/средняя/низкая.
— Риск: низкий/средний/высокий.
— DevOps/CI fit: высокий/средний/низкий.
— Навыки: базовые/средние/высокие.
| Методика/практика | Масштаб | Команда size/remote | Документация | Скорость изменений | Риск‑профиль | DevOps/CI fit | Требования к навыкам |
| Spec‑Driven Dev (Spec Kit) [4] | M–XL | 5–20+, remote‑friendly: да | medium | высокая | средний→высокий | высокий | средние |
| AGENTS.md + IDE rules [136] | S–XL | 1–20+, remote‑friendly: да | light | высокая | любой | высокий | базовые→средние |
| MCP [22] | M–XL | 5–20+, remote‑friendly: да | medium | высокая | средний→высокий | средний→высокий | высокие |
| arc42 [137] | M–XL | 5–20+, remote‑friendly: да | medium | средняя | средний | средний | средние |
| ISO 42010 [38] | L–XL | 20+, remote‑friendly: частично | heavy | низкая→средняя | высокий | средний | высокие |
| ADR [43] | S–XL | 5–20+, remote‑friendly: да | light | высокая | любой | высокий | базовые |
| C4 + Structurizr [138] | M–XL | 5–20+, remote‑friendly: да | medium | средняя→высокая | средний | средний→высокий | средние |
| RFC/KEP [60] | M–XL | 20+, remote‑friendly: да | medium | средняя | высокий | средний | средние→высокие |
| PR/FAQ [63] | M–XL | 5–20+, remote‑friendly: да | medium | средняя | средний→высокий | средний | средние |
| ISO 29148 + ГОСТ 34/19 [72] | L–XL | 20+, remote‑friendly: частично | heavy | низкая→средняя | высокий | средний | высокие |
| API‑first + Pact [6] | M–XL | 5–20+, remote‑friendly: да | medium | высокая | средний→высокий | высокий | средние |
| Docs‑as‑Code [139] | S–XL | 1–20+, remote‑friendly: да | medium | высокая | любой | высокий | базовые→средние |
| BDD + Spec by Example [140] | M–L | 5–20+, remote‑friendly: да | medium | средняя | средний→высокий | средний | средние |
| TDD + Test Pyramid [7] | S–XL | 1–20+, remote‑friendly: да | light→medium | высокая | любой | высокий | средние |
| Property‑based (Hypothesis) [109] | S–L | 1–10+, remote‑friendly: да | light | средняя | средний | высокий | высокие |
| DDD + Event Storming [115] | M–XL | 5–20+, remote‑friendly: да | medium | средняя | высокий | средний | высокие |
| Trunk‑based development [126] | M–XL | 5–20+, remote‑friendly: да | light | высокая | любой | высокий | средние |
| ATAM + STRIDE [141] | L–XL | 20+, remote‑friendly: частично | heavy | низкая→средняя | высокий | средний | высокие |
Плейбуки внедрения и практические чек‑листы
Ниже — «сборка» из методик в готовые режимы работы. Это полезно, потому что «по одной практике» масштаб редко достигается; устойчивость появляется от связки спеки → архитектура → контракты → тесты → CI. [142]
Lightweight режим для product‑команд с высокой скоростью изменений
Состав: AGENTS.md/IDE rules + ADR + C4 (Context/Container) + OpenAPI + TDD + trunk‑based. [143]
Чек‑лист «готовности фичи к вайб‑реализации агентом»: — Есть 5–15 строк AGENTS.md с командами проверки и запретами на опасные изменения. [17]
— Есть ADR (если меняем архитектуру/контракт/хранилище). [46]
— Обновлён OpenAPI/AsyncAPI (если меняем контракт). [122]
— Есть минимальные тесты (TDD‑петля хотя бы для критичного пути). [107]
— PR небольшой и проходит CI. [144]
Почему этот набор работает: он минимально достаточен, чтобы AI‑генерация не разрушила систему: агент знает правила, решения фиксируются, интерфейсы формализованы, тесты ловят регрессии, trunk‑flow заставляет держать систему «всегда готовой». [145]
Medium режим для платформ/монорепо/нескольких команд
Состав: Spec Kit + RFC + arc42 + ADR + C4/Structurizr + API‑contracts + CI‑policy. [146]
Мини‑шаблон коммуникации «перед тем как звать агента»: 1) «Ссылка на spec/RFC»
2) «Список ограничений (security/compliance/perf)»
3) «Критерии успеха (тесты/метрики)»
4) «Что НЕ делать (out of scope)»
Почему: Spec Kit подчёркивает intent‑first и многошаговое уточнение; RFC‑процессы отделяют «существенное» от «мелкого»; arc42/C4 задают общий язык архитектуры. [147]
Heavyweight режим для high‑risk/regulated
Состав: ISO 29148/ГОСТ + ISO 42010 + ATAM/STRIDE + контрактные тесты + строгий change control. [148]
Правило «anti‑vibe»: агент не имеет права менять: — безопасность/крипто/доступы без threat model и ревью security‑владельца (роль — не указано), — контракты без миграции и контрактных тестов, — данные без плана миграции и rollback.
Почему: STRIDE/threat modeling и ATAM существуют именно для раннего выявления угроз и trade‑off’ов, когда изменения ещё дешёвые. [149]
Визуализации
Decision flow выбора «режима вайб‑кодинга» для инициативы
flowchart TD
A[Новая инициатива/фича] —> B{Риск высокий?\nденьги/PII/регуляторика}
B —>|Да| C[Heavyweight: ISO 29148/ГОСТ + ISO 42010]
C —> D[Threat modeling STRIDE + ATAM]
D —> E[Контракты (OpenAPI/AsyncAPI) + Pact + строгий CI gate]
B —>|Нет| F{Затрагивает 2+ команды\nили публичный контракт?}
F —>|Да| G[Medium: Spec Kit + RFC/KEP]
G —> H[arc42 + ADR + C4/Structurizr]
H —> I[Контракты + тесты + trunk-based]
F —>|Нет| J[Lightweight: AGENTS.md + ADR (по необходимости)]
J —> K[TDD + малые PR + trunk-based]
Основание узлов: ISO 42010/29148 и ГОСТ‑подходы (heavy), STRIDE и ATAM (оценка рисков), Spec Kit как альтернатива «хаотичному vibe coding», RFC/KEP как «существенные изменения через дизайн‑процесс», OpenAPI/AsyncAPI и Pact как контрактная стабилизация, TDD/пирамида тестов и trunk‑based как ускорение обратной связи. [150]
Примерный timeline внедрения практик в команде
gantt
title Timeline внедрения «vibe coding at scale» (пример 6 недель)
dateFormat YYYY-MM-DD
axisFormat %d.%m
section Неделя 1: Базовая управляемость
AGENTS.md + IDE rules :a1, 2026-03-09, 5d
Trunk-based + CI gate :a2, 2026-03-09, 10d
section Неделя 2: Контракты и тесты
OpenAPI/AsyncAPI baseline :b1, 2026-03-16, 7d
TDD + test pyramid policy :b2, 2026-03-16, 7d
section Неделя 3: Архитектура
ADR процесс :c1, 2026-03-23, 5d
C4 Context/Container :c2, 2026-03-23, 5d
section Неделя 4: Спеки и большие изменения
Spec Kit пилот (1 продукт) :d1, 2026-03-30, 7d
RFC/KEP каталог :d2, 2026-03-30, 7d
section Неделя 5–6: Домен и риск
DDD/EventStorming воркшоп :e1, 2026-04-06, 7d
Threat modeling (STRIDE) пилот :e2, 2026-04-13, 7d
Почему такой порядок: сначала фиксируем «память и правила» (AGENTS.md), затем «скорость без хаоса» (CI/trunk), дальше «границы системы» (контракты) и «страховку» (тесты), затем архитектурную коммуникацию (ADR/C4), и только потом масштабируем AI‑разработку через Spec Kit/RFC и доменные/риск‑практики. [151]
Диаграмма распределения «типов выгод» по практикам
Ниже — синтетическая оценка: сколько практик в этом отчёте преимущественно усиливают каждую из выгод (одна практика может усиливать несколько выгод, но мы учитываем «доминирующую»). Это не статистика рынка, а инструмент для приоритизации внедрения.
pie title Доминирующие выгоды (приблизительное распределение по 16 практикам)
«Снижение риска/ошибок» : 5
«Скорость поставки» : 4
«Согласование намерения и коммуникация» : 4
«Онбординг/передача знаний» : 3
Интерпретация: — «Снижение риска» обычно дают контракты, тесты, threat modeling/ATAM, формальные стандарты. [152]
— «Скорость» дают trunk‑based/CI, AGENTS.md/rules, Spec Kit при зрелом процессе. [153]
— «Согласование» дают arc42, C4, RFC/KEP, PR/FAQ. [154]
— «Онбординг» — ADR, Docs‑as‑Code, AGENTS.md. [155]
[1] https://habr.com/ru/news/878868/
[2] https://developer.microsoft.com/blog/spec-driven-development-spec-kit
[3] [8] [10] [11] https://github.com/github/spec-kit
[4] [105] [146] [147] https://github.github.io/spec-kit/
[5] [32] [33] [116] [137] [154] https://github.com/arc42/arc42-template/blob/master/RU/arc42-template.adoc
[6] [80] [83] [122] https://spec.openapis.org/oas/v3.1.2.html
[7] [107] https://martinfowler.com/bliki/TestDrivenDevelopment.html
[9] [12] [142] https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
[13] [16] [19] [20] https://github.com/agentsmd/agents.md
[14] [15] [17] [136] [143] [145] [151] https://developers.openai.com/codex/guides/agents-md
[18] https://cursor.com/docs/context/rules
[21] [22] [24] [25] [28] https://modelcontextprotocol.io/specification/2025-03-26
[23] [27] https://www.anthropic.com/news/model-context-protocol
[26] https://github.com/modelcontextprotocol/modelcontextprotocol
[29] https://arc42.org/
[30] [31] [35] https://arc42.org/documentation/
[34] https://github.com/arc42/arc42-template/tree/master/RU
[36] [38] [39] [150] https://www.iso.org/standard/74393.html
[37] https://quality.arc42.org/standards/iso-42010
[40] [41] [43] [44] [46] [134] https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
[42] https://www.redhat.com/en/blog/architecture-decision-records
[45] https://github.com/npryce/adr-tools
[47] https://deepwiki.com/npryce/adr-tools
[48] https://adr.github.io/adr-templates/
[49] https://c4model.com/
[50] [55] [57] [138] https://c4model.com/diagrams
[51] https://c4model.com/introduction
[52] [56] https://c4model.com/tooling
[53] https://docs.structurizr.com/dsl
[54] https://docs.structurizr.com/dsl/example
[58] [60] [61] [62] https://github.com/rust-lang/rfcs
[59] https://github.com/kubernetes/enhancements/blob/master/keps/README.md
[63] [64] [65] [67] [68] [69] https://workingbackwards.com/concepts/working-backwards-pr-faq-process/
[66] https://ilyabezdelev.com/blog/amazon-prfaq/
[70] [72] [73] [74] [77] [79] [148] https://www.iso.org/standard/72089.html
[71] [75] https://normadocs.ru/gost_34.602-2020
[76] https://files.stroyinf.ru/Data/838/83832.pdf
[78] [90] [91] [92] [139] https://www.writethedocs.org/guide/docs-as-code.html
[81] [88] https://www.asyncapi.com/docs/reference/specification/latest
[82] [152] https://docs.pact.io/
[84] https://swagger.io/specification/v3/
[85] https://spec.openapis.org/oas/
[86] https://openapi-generator.tech/docs/installation/
[87] https://openapi-generator.tech/docs/usage/
[89] https://github.com/OpenAPITools/openapi-generator-cli
[93] [95] [98] https://www.mkdocs.org/
[94] https://docusaurus.io/docs/
[96] https://www.mkdocs.org/user-guide/writing-your-docs/
[97] https://buildwithfern.com/post/docs-as-code
[99] https://google.github.io/styleguide/docguide/best_practices.html
[100] [104] [106] [140] https://dannorth.net/blog/introducing-bdd/
[101] [103] https://cucumber.io/docs/gherkin/reference/
[102] https://gojko.net/books/specification-by-example/
[108] https://martinfowler.com/articles/practical-test-pyramid.html
[109] [110] [111] https://hypothesis.readthedocs.io/
[112] [115] [118] [121] https://www.domainlanguage.com/ddd/
[113] https://www.eventstorming.com/
[114] [117] [119] [120] https://www.eventstorming.com/book/
[123] [126] [144] [153] https://trunkbaseddevelopment.com/
[124] https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development
[125] [127] https://trunkbaseddevelopment.com/branch-for-release/
[128] [141] https://sei.cmu.edu/library/the-architecture-tradeoff-analysis-method/
[129] https://www.microsoft.com/en-us/securityengineering/sdl/threatmodeling
[130] [149] https://microsoft.github.io/code-with-engineering-playbook/security/threat-modelling/
[131] https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-getting-started
[132] https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool
[133] [135] https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats
[155] https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record
