Spec-Driven vs Code-First vs Chat-to-Code: Три философии обучения ИИ вашего бизнесу

Существует три способа обучить ИИ-агента вашего бизнесу. Каждый инвертирует того — или то, что является источником истины.

GitHub Spec Kit (122k звёзд) утверждает, что спецификация — это истина: напиши спецификацию, спецификация сгенерирует код. OpenWiki и Mintlify говорят, что код — это истина: читай кодовую базу, пиши документацию, агенты потребляют документацию. QuotyAI утверждает, что предметный эксперт — это истина: опиши бизнес-правила в чате, получи исполняемый код.

Каждый подход работает. Каждый ломается по-своему. И сбои не случайны — они следуют предсказуемым паттернам, связанным с тем, кто создавал знания, когда они были написаны и как они потребляются.

---

Три философии

Spec-Driven: Спецификация — источник истины

GitHub Spec Kit инвертирует традиционную разработку. Спецификации не служат коду — код служит спецификациям. PRD — не руководство по реализации; это источник, генерирующий реализацию. Технические планы — не документы, информирующие о коде; это точные определения, порождающие код.

Рабочий процесс состоит из четырёх команд:

/speckit.specify  →  /speckit.plan  →  /speckit.tasks  →  /speckit.implement

Описание функции превращается в структурированную спецификацию с пользовательскими историями и критериями приёмки. Спецификация становится планом реализации с выбором технологий и обоснованием. План превращается в исполняемый список задач. Список задач становится кодом.

Spec Kit поставляется с конституцией — девятью неизменными статьями (принцип «библиотека в первую очередь», требование «тесты в первую очередь», ворота простоты), которым חייבа следовать каждая сгенерированная реализация. Шаблоны ограничивают вывод LLM чеклистами, обязательными маркерами неопределённости ([NEEDS CLARIFICATION]) и фазовыми воротами, блокирующими прогресс до выполнения архитектурных принципов.

Экосистема вокруг разработки на основе спецификаций обширна:

• Specmatic превращает API-спецификации (OpenAPI, AsyncAPI, gRPC) в исполняемые контракты с виртуализацией сервисов и проверкой обратной совместимости
• Speakeasy переключился с инструментов спецификаций API на пульт управления ИИ для MCP и управления Skills
• Stoplight/Spectral предоставляет линтинг дизайна API с наборами правил управления
• OpenAPI/Swagger генерирует API-клиенты и серверные заготовки из спецификаций на 40+ языках

Ставка: если спецификация достаточно точна, разрыв между намерением и реализацией исчезает.

Code-First: Кодовая база — источник истины

OpenWiki, созданная LangChain AI, читает кодовую базу и пишет markdown-документацию для coding-агентов. GitHub Action запускает openwiki --update ежедневно. Агент сравнивает git, определяет затронутые страницы и перезаписывает только их. Файлы AGENTS.md и CLAUDE.md в корне репозитория направляют coding-агентов к wiki как точке входа.

Но OpenWiki — лишь один инструмент в гораздо более крупной экосистеме:

• Mintlify обеспечивает документацию для Anthropic, Coinbase и Vercel. Инструмент Agent Score тестирует документацию по 29 проверкам на готовность агентов. Контролируемый эксперимент крупной инженерной организации показал, что структурированная документация даёт на 64% более точные ответы, на ~50% меньше токенов и в 1,5 раза быстрее выполнение задач по сравнению с отсутствием документации.
• GitBook предлагает Git Sync (ветки/ревью/слияние документации как кода) и Агента, который проактивно обнаруживает устаревший контент. Их ключевой посыл: «Агенты превращают маленькие ошибки в документации в большие проблемы.»
• ReadMe предлагает обновление документации через PR с помощью AI Writer и MCP-сервера для чтения/записи агентами.
• Swimm использует детерминированный статический анализ плюс GenAI для построения валидированных баз знаний для ИИ-инструментов, соответствует SOC 2, проанализировано 100M+ строк кода.

Экосистема конфигурационных файлов в репозитории тоже обширна:

Инструмент	Конфигурационный файл	Ключевая деталь
Claude Code	CLAUDE.md, .claude/rules/*.md	Рекомендуемый максимум 200 строк; правила с областью видимости по пути загружаются только для совпадающих файлов
Cursor	.cursor/rules/*.mdc	Каталог плагинов сообщества с 4k звёзд
Cline	.clinerules + .cline/skills/	64.7k звёзд на GitHub
Aider	CONVENTIONS.md	Карта репозитория на основе дерева AST через tree-sitter
GitHub Copilot	.github/copilot-instructions.md	Инструкции уровня проекта
Windsurf	.windsurfrules	Кроссплатформенная совместимость с Claude Code

Ставка: если документация достаточно полна, агенты будут понимать кодовую базу так же хорошо, как разработчики, её создавшие.

Chat-to-Code: Предметный эксперт — источник истины

QuotyAI позволяет владельцу спа написать: «наш массаж глубоких тканей стоит 90 за 60 минут, 120 за 90 минут, и мы предлагаем скидку 10% для участников». Платформа генерирует функцию quoteOrder(), которая возвращает $108 за бронирование участника на 90 минут. Каждый раз.

Архитектура: владелец бизнеса общается со конструктором навыков на естественном языке. Конструктор генерирует структурированные документы (JSON-схемы, типы TypeScript, справочные данные) и исполняемый код (функции ценообразования, трансформации расписания, логику валидации). Вывод работает в изолированной виртуальной машине Node.js при каждом входящем сообщении клиента.

Почему существующие продукты не заполняют эту нишу? Пейзаж чат-в-приложение выявляет пробел:

• Vercel v0, bolt.new, Lovable нацелены на нетехнических пользователей, но генерируют UI и фронтенд-приложения. Шаблон «финансовый калькулятор» — это простой калькулятор, а не ценовой движок с поэтапными скидками, условными дополнениями и правилами участия.
• Cursor, GitHub Copilot, Codex мощны, но требуют разработчиков в качестве основного пользователя. Они не понимают вашу бизнес-сферу — ИИ не знает, что confirmed_at — правильная отметка времени для отчёта о доходах, а не created_at.
• Zapier, Make, Bubble автоматизируют простые рабочие процессы, но не могут выразить сложную бизнес-логику. «Если это, то то» слишком примитивно для реального ценообразования и котировок.

Недостающая категория: инструмент, который понимает вашу бизнес-сферу и генерирует конкретный код, реализующий ваши правила, без необходимости писать код или даже думать в категориях кода.

Существуют смежные продукты — DealHub и Salesforce CPQ для корпоративных конфигураторов цены, Clay для ИИ-обогащения продаж, Voiceflow и Botpress для конструкторов чат-ботов — но ни один не позволяет нетехническому предметному эксперту описать сложную логику ценообразования на естественном языке и получить детерминированный, аудируемый код.

Ставка: если разговор достаточно структурирован, знания предметного эксперта могут быть напрямую преобразованы в продакшен-логику.

---

Где каждый подход ломается

Spec-Driven: Проблема размывания контекста

Ставка на спецификации предполагает, что всеобъемлющие спецификации улучшают производительность агентов. Данные говорят обратное.

Размывание контекста — реальность. Исследования Anthropic по контекстной инженерии для ИИ-агентов описывают, как «по мере увеличения количества токенов в контекстном окне способность модели точно вспоминать информацию из этого контекста снижается». Это вытекает из фундаментального ограничения архитектуры трансформера: каждый токен обращается к каждому другому токену, создавая n² парных связей, которые растягиваются по мере роста контекста.

Явление универсально — все модели его проявляют, хотя некоторые деградируют более плавно. Вывод ясен: каждый токен, загруженный в контекст, истощает «бюджет внимания» агента, а спецификации тяжёлы по токенам. Спецификация, достаточно полезная для полезности, может быть слишком большой для эффективности.

Разбухание инструкций агента (ThoughtWorks Technology Radar Vol 34, апрель 2026, рейтинг «Caution»):

«Контекстные файлы, такие как AGENTS.md и CLAUDE.md, имеют тенденцию накапливаться со временем, когда команды добавляют обзоры кодовой базы, объяснения архитектуры, соглашения и правила. Хотя каждое добавление полезно по отдельности, это часто приводит к разбуханию инструкций агента. Инструкции становятся длинными и иногда противоречат друг другу. Модели склонны уделять меньше внимания контенту,埋もれた深い場所にある長い контекстах.»

Исследовательская статья «On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents» (arXiv:2601.20404, январь 2026) показала, что написанные вручную файлы AGENTS.md сокращают медианное время выполнения на 28,64% — но только если они остаются компактными. Громоздкие или плохо написанные спецификации оказывают противоположный эффект.

Цикл усталости от спецификаций следует предсказуемому паттерну:

1. Изначальный энтузиазм: «Давайте напишем всеобъемлющую спецификацию, чтобы ИИ точно знал, что делать»
2. Спецификация растут: появляются крайние случаи, добавляется больше правил и документации
3. Спецификация становится громоздкой: настолько большой, что снижает производительность агента
4. Бремя обслуживания: спецификация теряет актуальность с развивающейся кодовой базой
5. Усталость от спецификаций: команда перестаёт поддерживать спецификацию
6. Мёртвая документация: агенты следуют устаревшим инструкциям с высокой уверенностью

Дрифт архитектуры сохраняется даже при наличии спецификаций. ThoughtWorks Radar отметил «Снижение дрифта архитектуры с LLM» (Assess): «Увеличение использования ИИ coding-агентов может ускорить дрифт от намеченной кодовой базы и архитектурных проектов. Без контроля этот дрифт накапливается, поскольку агенты и люди复制ируют существующие паттерны, включая деградировавшие.»

Code-First: Налог на устаревание

Ставка на код предполагает, что документация, полученная из кода, остаётся точной. Это не так.

Устаревание — проблема номер один. Отчёт GitBook State of Docs 2026 показал, что «поддержание документации в актуальном состоянии с продуктом» — самая большая проблема для документационных команд — почти в два раза больше второй по значимости. README — это «снимки, которые превращаются в ещё один источник устаревшей информации для галлюцинаций агентов.»

В отличие от людей-читателей, которые могут распознать и обойти устаревшую документацию, ИИ-агенты воспринимают устаревшую документацию как ground truth. Агент, следующий шестимесячной давности README, будет уверенно ссылаться на API, пути к файлам и рабочие процессы, которые больше не существуют.

Проблему «зачем» невозможно решить на основе кода. Сооснователь Mintlify Хан Ван:

«Код показывает только что было построено, а не почему. Логика, стоящая за архитектурными решениями, живёт в старых тредах Slack и в головах нескольких человек. Агент, работающий с кодом, не имеет слоя намерения. Даже молоток сложен, если вы не знаете, что им нужно забивать гвозди.»

Агент может прочитать, что функция X вызывает функцию Y, но он не может знать, что Y существует из-за требования соответствия 2023 года или что X использует конкретный алгоритм, потому что того требовал бенчмаркинг производительности.

Налог контекстного окна жесток. Накладные расходы запуска Claude Code — до того, как вы наберёте хоть что-то — потребляют около 8 000–10 000 токенов. Каждый прочитанный файл добавляет 1 000–3 000 токенов. К тому моменту, когда агент прочитает 5–6 исходных файлов, он может превысить 50% контекста. Тяжёлые на документацию процессы ускоряют это истощение.

Исследование Mintlify показало, что структурированная документация сокращает потребление токенов на задачу примерно на 50%. Для компании, тратящей 1 млн/год на токены для кодинга, это экономия 500 тыс. Но документацию нужно поддерживать, чтобы получить эту экономию — а это возвращает вас к проблеме устаревания.

Цена ошибки асимметрична. По данным GitBook: «Агенты превращают маленькие ошибки в документации в большие проблемы.» Разработчик-человек, читающий устаревшую документацию, может заметить несоответствие и обойти его. Агент следует ей слепо, производя сломанный код с высокой уверенностью.

Chat-to-Code: Пробел верификации

Ставка на чат-в-код предполагает, что естественный язык достаточно точен для генерации правильного кода. Часто это не так.

Проблема верификации — самая большая нерешённая задача. Ни один инструмент не спрашивает пользователя: «Вот 5 тестовых случаев. Выглядит ли этот вывод правильно?» Функция ценообразования, которая выглядит правильно, может содержать ошибки на единицу в граничных условиях. Округление может быть незаметным до тех пор, пока не затронуты реальные деньги. Крайние случаи — нулевые количества, отрицательные значения, экстремальные значения — могут не быть протестированы.

Переписывание runtime Bun (июль 2026) решило это с помощью «языконезависимого набора тестов с миллионом утверждений, adversarial-ревью кода и, когда что-то идёт не так, исправления процесса, генерирующего код, вместо ручного исправления кода». Но для этого потребовалась командаexpert-инженеров, создающих наборы тестов соответствия. Владелец спа не может этого сделать.

Доверие хрупко. Владелец бизнеса, доверяющий ценообразованию, сгенерированному ИИ, сталкивается с реальными барьерами: финансовый риск (неправильная цена означает потерю дохода), требования аудита (во многих отраслях требуется объяснимая логика ценообразования), ответственность (если цена, сгенерированная ИИ, является дискриминационной, кто несёт ответственность?) и фундаментальная неспособность прочитать код для проверки корректности.

Инцидент с xAI Grok Build (июль 2026) продемонстрировал, насколько хрупко доверие: запуск CLI в директории загрузил всю директорию — SSH-ключи, базы паролей, документы — в Google Cloud. Одна катастрофа конфиденциальности может разрушить доверие ко всей категории.

Проблема «vibe coding» актуальна. Термин Андрея Карпати для кода, который выглядит правильно, но содержит тонкие ошибки, особенно опасен для бизнес-логики. Расчёт цены с ошибкой в $0,03 за транзакцию кажется тривиальным, пока не умножишь на 10 000 транзакций.

Из опроса Pragmatic Engineer (170+ респондентов): «Copilot может (и делает!) генерировать неверный код. При использовании Copilot нужно предполагать, что он производит ошибки.» Инструменты работают, когда пользователь уже знает, что должен делать код. Для нетехнических пользователей, описывающих бизнес-правила, которые они не полностью понимают в терминах кода, риск гораздо выше.

Предметная специфика ограничивает рынок. Универсальные ИИ-инструменты для кодирования обладают широкими, но поверхностными знаниями в предметной области. Предметно-ориентированные инструменты имеют глубокую экспертизу, но ограниченный охват. Встроить достаточно предметных знаний в инструмент, не сделав его настолько специализированным, что рынка нет — вот основное противоречие.

---

Конвергенция: К чему движется отрасль на самом деле

Интересно то, что все три подхода сходятся к одной базовой модели.

Структурированный markdown побеждает как слой знаний. Формат Agent Skills (agentskills.io) принят более чем 40 продуктами для агентов — Claude Code, Cursor, GitHub Copilot, VS Code, Gemini CLI, Roo Code, Amp, Factory и многими другими. Формат использует файл SKILL.md с YAML-фронтматтером и markdown-инструкциями с прогрессивным раскрытием: агенты загружают только имя и описание, а затем полное содержимое при совпадении задачи.

MCP становится протоколом инструментов. Model Context Protocol — это «USB-C для ИИ» — универсальный коннектор для доступа агентов к инструментам и данным. Сообщество MCP сформировало рабочую группу «Skills Over MCP», активно объединяя оба подхода: MCP-сервер должен предоставлять как свои инструменты, ТАК И инструкции по их совместному использованию.

ThoughtWorks Technology Radar за апрель 2026 определяет направление:

Сигнал	Рейтинг	Значение
Контекстная инженерия	Adopt	Рассматривайте контекстное окно как средство проектирования, а не текстовое поле
Постепенное раскрытие контекста	Trial	Не загружайте всё заранее; позволяйте агенту запрашивать нужное
Разбухание инструкций агента	Caution	Длинные инструкции снижают производительность
Снижение дрифта архитектуры с LLM	Assess	Даже со спецификациями дрифт сохраняется и накапливается

Рекомендуемый подход — постепенное раскрытие контекста: начните с лёгкого индекса доступного, позвольте агенту определить, что актуально, и подтягивайте только необходимое. Это анти-паттерн по отношению к подходу «спецификация в первую очередь» — вместо написания всеобъемлющих спецификаций заранее вы создаёте агентов, которые динамически обнаруживают, что им нужно.

Гибридный поиск превосходит чистый векторный поиск. Слой извлечения знаний сходится к комбинации векторного поиска (семантическое сходство для неструктурированного контента), структурированных запросов (SQL/Cypher для агрегации и рассуждений) и графов знаний (для обхода связей). Паттерн GraphRAG от Neo4j и гибридные запросы Qdrant это иллюстрируют.

Более глубокое понимание: формат менее важен, чем кто его создал, когда он был написан и актуален ли он. Хорошо поддерживаемый файл SKILL.md побеждает устаревшую спецификацию OpenAPI. Живой запрос побеждает статический Markdown-файл. Структурированное интервью с предметным экспертом побеждает промпт, угадывающий бизнес-правила.

---

Когда использовать каждый подход

Spec-Driven: Для технических команд, создающих новый софт

Используйте Spec Kit, когда начинаете новый проект с технической командой, которая может писать и поддерживать спецификации. Конституция, шаблоны и фазовые ворота работают лучше всего, когда у команды есть общий словарь, общий контекст и дисциплина поддерживать спецификации в актуальном состоянии.

Используйте Specmatic или OpenAPI, когда вам нужен дизайн API-контрактов — типизированные интерфейсы между сервисами, где спецификация небольшая, сфокусированная и может быть проверена машинно.

Не используйте подход на основе спецификаций, когда ваш «предметный эксперт» — владелец бизнеса, который мыслит категориями цен и записей на приём, а не пользовательскими историями и критериями приёмки.

Code-First: Для существующих кодовых баз с агентами для разработчиков

Используйте Mintlify, GitBook или OpenWiki, когда у вас есть существующая кодовая база и нужны coding-агенты для её понимания. Подход Mintlify структурированная документация + MCP даёт лучшие измеримые результаты (на 64% точнее, на 50% меньше токенов).

Используйте CLAUDE.md, .cursorrules или .clinerules для проектной конфигурации агентов — но держите их до 200 строк и используйте правила с областью видимости по пути для минимизации накладных расходов контекста.

Не используйте подход на основе кода, когда нужные вам знания не в коде. Бизнес-правила, логика ценообразования и предметная экспертиза живут в головах людей, а не в сигнатурах функций.

Chat-to-Code: Для предметных экспертов, не кодирующих

Используйте QuotyAI, когда нетехнический предметный эксперт нуждается в готовой к продакшену бизнес-логике — функциях ценообразования, правилах валидации, трансформациях расписания — из описаний на естественном языке. Предметно-ориентированный подход работает, потому что он ограничивает задачу: система знает, как должна выглядеть функция ценообразования, и может проверить вывод по типизированным контрактам.

Не используйте подход чат-в-код для универсальной разработки софта. Пробел верификации слишком велик без предметных ограничений.

---

Более глубокий паттерн

Три философии на самом деле не конкурируют. Они отвечают на разные вопросы:

• Spec-Driven отвечает: «Как убедиться, что ИИ построит то, что мы задумали?»
• Code-First отвечает: «Как убедиться, что ИИ поймёт то, что уже существует?»
• Chat-to-Code отвечает: «Как убедиться, что ИИ зафиксирует то, что знает эксперт?»

Настоящий режим отказа — не выбор неправильного подхода. Это применение подхода к неправильной задаче. Разработка на основе спецификаций терпит неудачу, когда предметный эксперт не может написать спецификацию. Документация на основе кода терпит неудачу, когда знания не в коде. Чат-в-код терпит неудачу, когда область слишком широка для ограничения.

Возникающий стек использует все три подхода: спецификации на границах API, вычисляемые знания во время выполнения и структурированные беседы для предметной экспертизы. Общий знаменатель в том, что статические, всеобъемлющие документы, написанные людьми, — неправильная единица. Правильная единица — это то, что остаётся актуальным, компактным и релевантным для текущей задачи.

Постройте детерминированный рантайм под моделью, и проблема знаний решится сама.

---

Часто задаваемые вопросы

В чём разница между подходами spec-driven, code-first и chat-to-code? Разработка на основе спецификаций (GitHub Spec Kit) инвертирует традиционную разработку: спецификации генерируют код, а не направляют его. Документация на основе кода (OpenWiki, Mintlify) читает существующие кодовые базы и пишет markdown для ИИ-агентов. Чат-в-код (QuotyAI) позволяет нетехническим пользователям описывать бизнес-правила на естественном языке и генерирует исполняемый TypeScript. Каждый подход нацелен на разную аудиторию: разработчики, команды разработчиков и предметные эксперты соответственно.

Почему подходы на основе спецификаций терпят неудачу в масштабе? Три задокументированных типа отказов: (1) Размывание контекста — исследования Anthropic показывают снижение производительности модели по мере заполнения контекстного окна из-за ограничений архитектуры трансформера, растягивающих внимание на большее число токенов. (2) Разбухание инструкций агента — ThoughtWorks Technology Radar отметил накопление и конфликт файлов AGENTS.md, снижающих производительность агента. (3) Цикл усталости от спецификаций — спецификации растут, становятся громоздкими, теряют актуальность и команды перестают их поддерживать.

Почему v0, bolt.new или Lovable не решают проблему чат-в-код для бизнес-логики? Эти инструменты нацелены на нетехнических пользователей, но генерируют UI и фронтенд-приложения, а не сложную бизнес-логику. Ценовой движок с поэтапными скидками, условными дополнениями и правилами участия требует предметного понимания, которого не хватает универсальным конструкторам из чата. Ни один крупный продукт пока не позволяет владельцу бизнеса описать ценообразование на естественном языке и получить готовый к продакшену детерминированный код.

К чему движется отрасль в области знаний ИИ-агентов? Формат Agent Skills (agentskills.io) принят более чем 40 продуктами для агентов. MCP становится стандартным протоколом инструментов. ThoughtWorks Technology Radar за апрель 2026 рекомендует «контекстную инженерию» (Adopt) и «постепенное раскрытие контекста» (Trial) — рассматривать контекстное окно как средство проектирования и позволять агентам запрашивать только необходимое, а не загружать все спецификации заранее.

---

Дополнительное чтение

• Open Knowledge Format (OKF) vs Agent Skills — почему детерминированное исполнение побеждает статические файлы знаний
• OpenWiki vs QuotyAI — два проекта LangChain DeepAgents, две архитектуры
• Determinism as Infrastructure — почему ИИ-платформам нужно детерминированное исполнение
• Why I Picked Bun and Hono — исходный разбор решения для стека QuotyAI

---

Tags: spec-driven-development openwiki mintlify quotyai ai-agents agent-architecture context-engineering deterministic-ai spec-kit agent-skills MCP