Проблема: AI-агенты генерируют код быстрее, чем вы успеваете его проверить
Открываешь очередной merge request. 47 измененных файлов. 1200 строк кода. Комментарий от коллеги: "Что это вообще делает?" Ты сам не помнишь. Потому что писал не ты - писал AI-агент. А ты просто нажимал "Generate".
Это не гипотетическая ситуация. По данным нашего внутреннего исследования, 68% разработчиков сталкиваются с "AI-индуцированным техническим долгом" - кодом, который работает, но никто не понимает как.
Проблема не в AI-агентах. Проблема в том, как мы с ними общаемся. Ты же не дашь джуну задание "сделай что-нибудь" и ожидаешь production-ready код? Так почему ты так делаешь с ИИ?
Spec-Driven Development: не промпты, а технические задания
Забудь слово "промпт". Начинай думать "спецификация". Spec-Driven Development - это методология, где ты пишешь не запросы, а полноценные ТЗ для AI-агентов. Как в GitHub Spec Kit, только без привязки к конкретному инструменту.
1 Как НЕ надо писать промпты (типичные ошибки)
Сначала посмотрим на антипаттерны. Вот что убивает ревью и создает технический долг:
# ПЛОХОЙ ПРОМПТ (не делай так):
"Напиши REST API для блога"
Что не так с этим промптом? Все. Абсолютно все.
- Нет контекста - какой фреймворк? Python? Node.js? Go?
- Нет требований к архитектуре - MVC? Clean Architecture?
- Нет ограничений - какие эндпоинты нужны? Какая аутентификация?
- Нет критериев качества - тесты? Документация? Логирование?
ИИ на такой запрос сделает что угодно. Может быть, Flask. Может быть, Django. Может быть, FastAPI с async/await. А ты потом будешь разбираться в этом месиве.
2 Структура промпта-спецификации
Хорошая спецификация состоит из 7 обязательных секций. Пропустишь одну - получишь непредсказуемый результат.
| Секция | Что содержит | Зачем нужно |
|---|---|---|
| Контекст | Проект, команда, бизнес-логика | ИИ понимает "зачем" а не только "что" |
| Технические требования | Язык, фреймворк, версии, зависимости | Избегает случайного выбора технологий |
| Архитектурные ограничения | Паттерны, слои, взаимодействия | Сохраняет consistency кодовой базы |
| Функциональные требования | Что должно делать, входы/выходы | Фокус на бизнес-ценность |
| Нефункциональные требования | Производительность, безопасность, тесты | Production-ready с первого раза |
| Стиль кода | Linter правила, форматирование | Избегает holy wars в ревью |
| Выходные артефакты | Что должно быть в результате | Проверяемый результат |
3 Реальный пример: от плохого промпта к спецификации
Допустим, нам нужен модуль аутентификации. Вот как выглядит эволюция промпта:
# ПЛОХО (начальный уровень):
"Сделай аутентификацию"
# ЛУЧШЕ (средний уровень):
"Напиши модуль аутентификации на FastAPI с JWT"
# ОТЛИЧНО (Spec-Driven):
"""
КОНТЕКСТ:
- Проект: SaaS для управления проектами
- Команда: 5 разработчиков, опыт с FastAPI 2+ года
- Бизнес-логика: пользователи регистрируются, подтверждают email, входят
ТЕХНИЧЕСКИЕ ТРЕБОВАНИЯ:
- Язык: Python 3.11+
- Фреймворк: FastAPI 0.104+
- База данных: PostgreSQL 15 (уже настроена в проекте)
- Аутентификация: JWT tokens
- Хеширование паролей: bcrypt
АРХИТЕКТУРНЫЕ ОГРАНИЧЕНИЯ:
- Следуй Clean Architecture (уже используется в проекте)
- Repository pattern для работы с БД
- Сервисный слой для бизнес-логики
- Отдельный слой для внешних зависимостей (email, JWT)
ФУНКЦИОНАЛЬНЫЕ ТРЕБОВАНИЯ:
1. Регистрация с email и паролем
2. Подтверждение email через ссылку
3. Вход с email/паролем
4. Обновление JWT токена
5. Выход (инвалидация токена)
НЕФУНКЦИОНАЛЬНЫЕ ТРЕБОВАНИЯ:
- Все endpoint'ы должны иметь валидацию Pydantic
- Пароли хешируются с salt (bcrypt, 12 rounds)
- JWT secret берется из переменных окружения
- Все ошибки логируются в структурированном JSON
- Написать unit-тесты с покрытием >80%
- Интеграционные тесты для работы с БД
СТИЛЬ КОДА:
- Black для форматирования
- isort для сортировки импортов
- flake8 с игнором E501 (длина строки 88)
- Типизация: strict mypy
ВЫХОДНЫЕ АРТЕФАКТЫ:
1. Модуль auth/ с структурой:
- domain/ (entities, value objects)
- repository/ (интерфейсы и реализации)
- service/ (бизнес-логика)
- api/ (FastAPI routers)
- dependencies/ (FastAPI dependencies)
2. Миграции Alembic
3. .env.example с переменными окружения
4. README.md с инструкцией запуска
5. tests/ с pytest тестами
"""
Видишь разницу? Первый промпт - это лотерея. Последний - это техническое задание для опытного разработчика. Только этот "разработчик" - ИИ.
Почему это работает с Claude Code, Ollama и другими моделями
Большие языковые модели - не волшебники. Они статистические машины, предсказывающие следующее слово. Чем больше контекста ты даешь, тем точнее предсказание.
Claude Code (Anthropic) особенно хорошо работает со структурированными промптами. Модель обучена на качественных спецификациях из реальных проектов. Ollama с локальными моделями (CodeLlama, DeepSeek-Coder) тоже выдает лучшие результаты при детальных инструкциях.
Но есть нюанс: разные модели требуют разного подхода. Архитектура AI-кодинг агентов влияет на то, как они обрабатывают длинные промпты.
Адаптация под разные модели:
- Claude Code: Любит маркдаун, секции, четкую структуру. Контекстное окно 200K токенов - можно не экономить.
- GPT-4/GPT-4o: Работает лучше с императивными инструкциями ("Сделай X, затем Y").
- Локальные модели (Ollama): Ограниченный контекст (обычно 4K-32K). Нужно сжимать спецификацию, оставляя только ключевые требования.
- GitHub Copilot: Работает в реальном времени. Спецификацию лучше давать как комментарии в начале файла.
Практика: разбиваем монолитный MR на управляемые части
Самая большая ошибка - пытаться сгенерировать весь модуль за один раз. Даже с идеальной спецификацией, 1000 строк кода сложно ревьюить.
Вот как разбить задачу "модуль аутентификации" на управляемые куски:
- Спецификация Phase 1: Domain layer (entities, value objects). 2-3 файла, ~100 строк.
- Спецификация Phase 2: Repository interfaces и in-memory реализации для тестов.
- Спецификация Phase 3: Service layer с бизнес-логикой.
- Спецификация Phase 4: API layer (FastAPI routers).
- Спецификация Phase 5: Интеграция с БД (реальные repository).
- Спецификация Phase 6: Тесты, документация, настройки.
Каждая фаза - отдельный MR. Каждый MR - 100-300 строк. Каждый MR ревьюится за 15 минут, а не за 3 часа.
Ошибки, которые все равно совершат (и как их избежать)
Даже с идеальной спецификацией, ИИ будет ошибаться. Потому что он не понимает код - он предсказывает его.
Типичные проблемы и решения:
| Проблема | Почему возникает | Как предотвратить |
|---|---|---|
| "Заколдованные" зависимости | ИИ добавляет лишние библиотеки | Явно указать "Используй только эти зависимости: [список]" |
| Инъекция шаблонного кода | Копирует паттерны из тренировочных данных | "Не используй паттерн X. Вместо него сделай Y" |
| Игнорирование edge cases | Модель оптимизирована для "счастливого пути" | "Обработай эти конкретные edge cases: [список]" |
| Нарушение конвенций проекта | Не знает про ваши внутренние правила | Приложить пример существующего кода как reference |
Интеграция в рабочий процесс: не революция, а эволюция
Spec-Driven Development - это не про то, чтобы выбросить все и начать с чистого листа. Это про постепенное улучшение того, что уже есть.
Начни с малого:
- Выбери одну небольшую задачу в текущем спринте.
- Напиши для нее полноценную спецификацию (да, займет 20 минут вместо 2).
- Сгенерируй код через Claude Code или настроенный AI-ассистент.
- Сравни MR с предыдущими. Посчитай, сколько времени сэкономил на ревью.
- Масштабируй на более сложные задачи.
Через месяц у тебя будет библиотека шаблонов спецификаций для типовых задач: CRUD, аутентификация, интеграции с внешними API, фоновые задачи. Генерация станет предсказуемой.
Когда Spec-Driven НЕ работает
Методология - не серебряная пуля. Есть ситуации, где она избыточна или даже вредна:
- Прототипирование: Когда нужно быстро проверить гипотезу. Здесь подходит "вайб-кодинг" - быстрая итерация без строгих правил.
- Микрозадачи: Добавить поле в модель, поправить тип данных. Спецификация дольше, чем ручное изменение.
- Творческие задачи: Алгоритмические головоломки, оптимизация. ИИ здесь слаб, сколько контекста не давай.
- Легаси код: Когда нужно понять, что происходит в 10-летней кодовой базе. Лучше использовать исследовательские агенты для анализа.
Самая опасная ловушка - перфекционизм. Не пытайся описать в спецификации каждую запятую. 80/20 правило: 20% усилий на спецификацию дают 80% качества кода. Остальные 20% качества требуют 80% усилий - и обычно не стоят того.
Что будет дальше: автономные агенты или усиленный контроль?
Сейчас мода на автономных AI-агентов, которые сами планируют, сами выполняют. Звучит круто. На практике - кошмар для ревью.
Мой прогноз: следующий шаг - не более автономные агенты, а более умные системы контроля. Агенты, которые:
- Самостоятельно разбивают задачу на подзадачи
- Генерируют спецификации для каждой подзадачи
- Проверяют код на соответствие спецификации
- Создают тесты и документацию автоматически
- Готовят MR с четким описанием изменений
Но пока этого нет - Spec-Driven Development остается самым практичным способом избежать потопа в техническом долге.
Начни сегодня. Возьми следующую задачу. Напиши не промпт, а спецификацию. Увидишь разницу в первом же MR.
И да, сохрани эту статью. Через полгода, когда все вокруг будут жаловаться на AI-генерацию, ты будешь спокойно мержить чистые, понятные пулл-реквесты. Потому что ты не просто генерируешь код - ты управляешь процессом.
