Структурированная разработка на основе промптов

Как сделать изменения, вносимые с помощью LLM, управляемыми, проверяемыми и воспроизводимыми.

Программные ассистенты LLM продемонстрировали значительную ценность, но в основном для отдельных разработчиков. Внутренняя ИТ-организация Thoughtworks использует их для своих команд и разработала метод и рабочий процесс, называемый структурированной разработкой на основе промптов (Structured Prompt-Driven Development, SPDD). В одноименной статье Вэй Чжан и Джесси Цзе Ся, опубликованной на сайте Мартина Фаулера, описывается простой пример этого рабочего процесса с подробностями на GitHub. Этот рабочий процесс рассматривает промпты как артефакт первого класса, хранящийся вместе с кодом в системе контроля версий и используемый для согласования разработки с потребностями бизнеса. Мы обнаружили, что разработчикам для эффективной работы необходимы три ключевых навыка: согласованность, подход «сначала абстракция» и итеративный анализ.

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

• Неоднозначные требования быстро превращаются в код, и вместе с ними растут и недопонимания.

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

• Возникает всё больше проблем с интеграцией и тестированием, потому что «сгенерировано» не означает «согласовано».

• Оценить производственные риски становится сложнее, когда объем изменений возрастает.

Да, локальная скорость повышается. Но это не приводит к автоматическому увеличению пропускной способности на системном уровне. Это как купить Ferrari и ездить на нем по грязным дорогам: двигатель мощный, но время прибытия определяется состоянием дороги и трафиком. По нашему опыту, настоящий вопрос не в том, «Как сгенерировать больше кода?», а в том, как сделать изменения, сгенерированные ИИ, управляемыми, проверяемыми и воспроизводимыми, чтобы команды работали быстрее и безопаснее.

Это подтолкнуло наши внутренние ИТ-команды Thoughtworks (Global IT Services) к разработке метода и рабочего процесса, который мы теперь называем структурированной разработкой на основе промптов (Structured Prompt-Driven Development, SPDD). Цель SPDD – превратить использование ИИ из инструмента повышения личной эффективности в возможность уровня организации, которую можно масштабировать без ущерба для качества.

Что такое SPDD?

Структурированная разработка на основе промптов (Structured Prompt-Driven Development, SPDD) – это инженерный метод, который рассматривает промпты как артефакты доставки первого класса.

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

SPDD состоит из двух основных компонентов.

REASONS Canvas

REASONS Canvas – это структура для генерации промптов. Она способствует ясности в отношении требований, доменной модели, подхода к решению, структуры системы, декомпозиции задач, переиспользуемых норм и мер безопасности. Таким образом, LLM руководствуется намерениями, а не догадками.

REASONS Canvas – это структура из семи частей, которая направляет промпт: намерение → проектирование → реализация → управление.

Абстрактные части (намерение и дизайн)

• R (Requirements) – Требования: Какую проблему мы решаем и что в качестве DoD?

• E (Entities) – Сущности: Сущности предметной области и отношения.

• А (Approach) – Подход: Стратегия выполнения требований.

• S (Structure) – Структура: Место изменений в системе; компоненты и зависимости.

Конкретные части (исполнение)

• О (Operations) – Операции: Разбейте абстрактную стратегию на конкретные, проверяемые этапы реализации.    

Общие стандарты (управление)

• N (Norms) – Нормы: Сквозные инженерные нормы (именование, наблюдаемость, защитное кодирование и т.д.).

• S (Safeguards) – Меры безопасности: Не подлежащие обсуждению границы (инварианты, пределы производительности, правила безопасности и т.д.).

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

Рабочий процесс SPDD

Рабочий процесс определяет порядок работы с промптами, как и с кодом: история коммитов, проверка и контроль качества. Он также обеспечивает соблюдение простого, но эффективного правила:

Если реальность изменилась, сначала исправьте промпт, а затем обновите код.

Со временем это меняет подход, согласно которому работают команды. Ревью смещается от «обнаружения ошибки» к «проверке намерений». Переделки становятся более контролируемыми. А успешные шаблоны естественным образом накапливаются в библиотеку переиспользуемых промптов, поддерживающую подход AI-First Software Delivery (AIFSD).

Если вы знакомы с разработкой на основе спецификаций (Spec-Driven Development), вы узнаете ту же отправную точку: сначала четко сформулируйте спецификацию, а затем позвольте модели ее реализовать. SPDD использует другой подход. Структурированные промпты рассматриваются как управляемые, переиспользуемые, версионированные ресурсы команды (REASONS + рабочий процесс), которые развиваются вместе с кодом – подход, который Биргитта Бёкелер классифицирует как подход с привязкой к спецификации.

Что SPDD добавляет к разработке на основе спецификаций?

SDD и SPDD имеют общую отправную точку: сначала генерируется спецификация, а затем код. SPDD добавляет метод для описания процесса создания, проверки и синхронизации этой спецификации с кодом.

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

• От требований к технической спецификации. REASONS Canvas выходит за рамки того, что система должна делать. Она отражает выбранный подход, структуру системы, инженерные нормы и меры безопасности, предоставляя LLM не просто цель, а границы реализации.

• Синхронизация, а не передача управления. Промпт и код остаются синхронизированными. Изменения с обеих сторон отражаются обратно, поэтому намерение и реализация не расходятся.

• Повторяемый контроль со стороны команд. Суть не в «более подробных спецификациях», а в том, чтобы у команд был единый подход к управлению результатами работы ИИ и переносу принятых решений между итерациями. Анализ компромиссов, лежащих в основе этих решений, проводится на этапе анализа; а в Canvas фиксируются результаты.

Цель рабочего процесса SPDD – превратить последовательность «ввод бизнес-данных → абстракция → выполнение → проверка → выпуск» в «замкнутый цикл» – и обеспечить, чтобы промпты и код развивались вместе, а не по отдельности.

Цель этого рабочего процесса – закрепить сотрудничество над промптами, чтобы разработчики и владельцы продукта могли избежать повторяющихся циклов согласования. Промпт устанавливает четкие границы для генерации кода, уменьшая случайность недетерминированности LLM и упрощая управление этим процессом. Рассматривая структурированные промпты как артефакты первого класса в системе контроля версий, мы превращаем успешные практики в переиспользуемые ресурсы, повышая согласованность и сокращая необходимость повторной разработки.

На практике эти шаги выполняются с помощью команд, предоставляемых openspdd, инструментом командной строки, реализующим рабочий процесс SPDD. В таблице ниже приведено описание каждой команды.

Улучшение биллинговой системы с помощью SPDD

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

Вы можете следовать этому примеру, установив openspdd в своей среде.

Текущая система

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

Полная кодовая база этой исходной версии доступна на GitHub. Репозиторий содержит историю исходных требований и все артефакты SPDD, использованные для ее генерации. Для краткости мы не будем описывать здесь эту первоначальную генерацию, но она следует практически тем же шагам, что и для улучшения. Мы сосредоточимся на описании улучшения, поскольку большая часть работы над системой заключается именно в нем.

Улучшение

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

• Улучшение API: обновить существующий эндпоинт POST /api/usage, чтобы он принимал новый обязательный параметр modelId (например, «fast-model», «reasoning-model»).

• Ценообразование с учетом модели: перейти от единой глобальной ставки к динамическому ценообразованию, при котором стоимость варьируется в зависимости от конкретной используемой модели ИИ.

• Логика биллинга для нескольких тарифных планов: внедрить различные сценарии биллинга в зависимости от уровня подписки клиента:

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

  – Премиум-план (новый): работает без ограничения по квоте. Вводит раздельный биллинг, при котором токены запроса и токены генерации оплачиваются отдельно по разным тарифам в зависимости от используемой модели.

• Архитектурная масштабируемость: применить расширяемый шаблон проектирования (например, «Стратегия» или «Фабрика»), чтобы четко разграничить формулы расчета для разных планов, обеспечивая возможность легкой адаптации системы к будущим моделям ценообразования.

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

Шаг 1: Создать первоначальные требования

Чтобы быстро запустить процесс, мы можем использовать команду /spdd-story для генерации пользовательской истории непосредственно на основе улучшения (поскольку это опциональная команда, то если она недоступна в вашей локальной среде, вы можете сгенерировать её, выполнив команду openspdd generate spdd-story). Как правило, пользовательские истории предоставляются владельцем продукта или бизнес-аналитиком. Однако в нашем рабочем процессе мы можем преобразовывать истории любого вида в согласованный формат и измерение. При условии согласованности окончательных критериев приемки этот шаг может быть выполнен владельцем продукта, бизнес-аналитиком или разработчиком, в зависимости от гибкого разделения труда в команде.

Как работает spdd-story

Эта команда разбивает большое требование на независимые, выполнимые пользовательские истории в соответствии с принципом INVEST (1–5 дней работы над каждой). Каждая история включает критерии приемки, сформулированные на языке бизнеса, готовые служить в качестве входных данных для /spdd-analysis.

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

Инструкция:

/spdd-story @idea-of-the-enhancement.md

ИИ проанализировал описание улучшения и разделил его на две пользовательские истории:

• История 1-1 (Стандартный план и ценообразование с учетом модели)

• История 1-2 (Премиум-план для раздельной оплаты)

Автоматически сгенерированные истории достаточно подробны, чтобы служить основой для формального проекта. Для этого пошагового руководства мы объединили их в одну упрощенную историю, чтобы пример оставался самодостаточным.

Инструкция:

Объединить следующие две пользовательские истории в одну упрощенную:
@[User-story-1-1-initial]Multi-Plan-Billing-Foundation-&-Standard-Plan-Model-Aware-Pricing.md
@[User-story-1-2-initial]Premium-Plan-Split-Rate-Billing.md
Требования:
1.  Объединить оба плана (Стандартный и Премиум) в одну связную историю.
2.  Оставить только разделы: Предыстория, Бизнес-ценность, Объем работ, За рамками и Критерии приемки.
3.  Убрать детали уровня реализации — сосредоточиться на том, что должна делать система, а не на том, как.
4.  Критерии приемки должны быть в формате «Дано/Когда/Тогда» (Given/When/Then) с конкретными числовыми примерами.
5.  Результат должен быть кратким — не более одной страницы.
6.  Оставить только три высокоуровневых критерия приемки.

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

Объединенная пользовательская история (упрощенная)

Предыстория

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

Ценность для бизнеса

1. Гибкая монетизация: Поддержать различные стратегии биллинга (стандартная, премиум) для охвата разных сегментов рынка.

2. Ценообразование с учетом модели: Установить разные тарифы в зависимости от используемой модели ИИ.

3. Масштабируемость архитектуры: Реализовать расширяемый дизайн (например, паттерн «Стратегия») для изоляции логики вычислений и легкого добавления будущих моделей ценообразования.

Объем работ

• Улучшить существующий эндпоинт POST /api/usage.

• Новое поле запроса: добавить modelId (обязательно, строка, например, “fast-model”, “reasoning-model”).

• Реализовать механизм маршрутизации (паттерны Стратегия/Фабрика) для обработки различных формул расчета.

• Реализовать два начальных типа планов:

  1. Стандартный план (рефактор легаси): Имеет ежемесячную глобальную квоту. Тарифы за превышение лимита теперь зависят от modelId.

  2. Премиум-план (новый): Без квоты. Токены запроса и токены генерации оплачиваются отдельно, тарифы различаются в зависимости от modelId.

За рамками

• Сложная многоуровневая, зависящая от объема логика скидок (отложена до этапа 2).

• Создание планов подписки и назначение CRUD.

• Формирование счетов-фактур.

Критерии приемки (КП)

1. Базовые проверки (регрессионные и новые)

   Дан недопустимый запрос (например, отсутствует modelId, отрицательные токены)

   Когда бэкэнд проверяет запрос

   Тогда возвращается HTTP 400 с соответствующими сообщениями об ошибке.

2. Стандартный план с превышением с учетом модели.

   Дан клиент с тарифом «Стандартный», с ежемесячной квотой в 100 000 токенов, уже использовано 90 000. Превышение лимита для «быстрой модели» составляет $0.01/1K.

   Когда отправка 30 000 токенов для «быстрой модели»

   Тогда в счете отображается: 10 000 по квоте, 20 000 превышения, плата $0.2.

3. Премиум-план с раздельными тарифами

   Дан клиент с тарифом «Премиум». Для «модели с рассуждением» стоимость токенов запроса – $0.03/1K, токенов генерации – $0.06/1K.

   Когда отправка 10 000 токенов запроса и 20 000 токенов генерации для «модели с рассуждением»

   Тогда в счете отображается: 0 по квоте, плата за запросы $0.30, плата за генерацию $1.20, итого $1.50.

Шаг 2: Прояснить детали анализа

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

Основная логика

В API появилось новое обязательное поле: modelId. Теперь клиент сообщает нам, какую модель ИИ он использовал – это ключ к определению правильной цены.

• Стандартный план: У клиента есть ежемесячная квота токенов. Использование в пределах квоты бесплатно. За превышение лимита взимается плата по тарифу, зависящему от модели (например, для быстрой модели $0,01/1000, для модели с рассуждением $0,03/1000). Существующая логика квоты сохраняется; изменяется только поиск тарифа.

• Премиум-план: Без квот. Оплата за каждый токен, начиная с первого. Токены запроса и токены генерации оплачиваются отдельно, по тарифу, соответствующему каждой модели. Счет = плата за запрос + плата за генерацию. Этот план совершенно новый.

• Маршрутизация: Система определяет тарифный план клиента и направляет запрос в соответствующую формулу биллинга. Дизайн должен быть простым для расширения – в будущем появятся Корпоративные тарифные планы (История 2).

Границы области применения

Мы рассчитываем только текущий счет. Мы НЕ создаем CRUD-операции с клиентами, НЕ запрашиваем данные из истории счетов, НЕ управляем подписками и НЕ добавляем/удаляем модели.

Определение завершенности

В следующих сценариях критерии приемки истории переформулированы с учетом деталей реализации, которые команде необходимо проверить. Четвертый пункт (формат ответа) не является новым бизнес-критерием приемки – он отражает нефункциональный контракт, который разработчик добавляет, чтобы сделать критерии пригодными для сквозного тестирования.

• Проверка: Отсутствует modelId → HTTP 400. Неизвестный клиент → HTTP 404. Отрицательные токены → HTTP 400. Все существующие проверки остаются в силе.

• Выставление счетов по стандартному плану: Клиент с квотой в 100K токенов и уже использованными 90K токенами отправляет 30K токенов для быстрой модели ($0,01/1K). Ожидаемый результат: 10K токенов покрыто квотой, 20K – превышение, плата – $0,20. Тот же запрос с использованием модели с рассуждением ($0,03 /1K) дает $0,60 – та же логика квоты, другой тариф.

• Выставление счетов по премиум-плану: Клиент отправляет 10K токенов запроса + 20K токенов генерации для модели с рассуждением (запрос $0,03/1K, генерация $0,06/1K). Ожидаемый результат: $0,30 + $1,20 = $1,50. Нет квоты, нет превышения – запросы и генерация оплачиваются отдельно.

• Формат ответа: HTTP 201, возвращающий ID счета, ID клиента, количество токенов, метку времени, modelId и разбивку платежа в соответствии с тарифным планом.

Если все эти сценарии сработают, мы победим в этой истории.

Шаг 3: Сгенерировать контекст анализа

После уточнения требований и области применения мы используем команду /spdd-analysis. Передавая ей бизнес-требования, мы даем указание ИИ сгенерировать всесторонний контекст анализа.

Как работает spdd-analysis

Эта команда извлекает ключевые слова предметной области из бизнес-требований (например, «биллинг», «квота», «план») и использует их для сканирования только релевантных частей кодовой базы, а не всей её. Она выявляет существующие понятия, новые понятия, ключевые бизнес-правила и технические риски.

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

Инструкция:

/spdd-analysis @[User-story-1]Multi-Plan-Billing-Foundation-&-Model-Aware-Pricing.md

 Сгенерированный артефакт: начальный документ с контекстом анализа.

Эта команда проводит анализ стратегического уровня, основанный на исследовании актуальной кодовой базы. Результат анализа полностью фокусируется на вопросах «что» и «зачем», намеренно избегая детальной проработки реализации на этом этапе. Обычно он охватывает:

• Понятия предметной области: существующие и новые, взаимосвязи, бизнес-правила.

• Стратегический подход: направление решения, проектные решения, компромиссы.

• Риски и расхождения: двусмысленности, краевые случаи, технические риски, соответствие критериям приемки.

Проверьте и уточните контекст анализа

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

В данном конкретном случае проверка сосредоточена на нескольких важных областях:

• Правильно ли был рассмотрен паттерн Стратегия.

• Соблюдение принципов ООП, установленных в существующей системе, в частности, принципов ISP и SRP.

• Достоверность предложенной стратегии для добавления новых полей.

• Выявление ранее не предусмотренных краевых случаев.

• Выявление потенциальных технических рисков.

После завершении проверки, анализ, проведенный ИИ, в значительной степени соответствует нашим архитектурным замыслам; более того, в некоторых областях его выводы оказались даже более всесторонними, чем наши.

Говоря откровенно, на данном этапе у нас есть лишь общее концептуальное представление. Хотя мы можем быстро представить себе реализацию в тех областях, где у нас есть опыт, мы не можем сейчас полностью проработать все технические детали для незнакомых нам частей.

Однако это совершенно нормально. Общее направление согласовано. Мы можем перейти к следующему шагу: наблюдению за тем, как ИИ «моделирует» конкретные детали реализации в рамках нашего установленного фреймворка и контекста. Как только у нас появятся эти конкретные детали, мы сможем выявить более глубокие, скрытые проблемы и принять обоснованные компромиссы на основе реального сценария, – применяя подходы, в которых преимущества перевешивают недостатки, и отбрасывая остальные.

Решение: принять анализ в том виде, в каком он есть, и продолжить.

Шаг 4: Сгенерировать структурный промпт

Как работает spdd-reasons-canvas

Эта команда считывает бизнес-контекст (результат выполнения команды /spdd-analysis или непосредственное описание требований) и объединяет его с текущим состоянием кодовой базы. Затем она генерирует спецификацию проекта по всем семи параметрам REASONS – от «зачем мы это делаем» до «чего мы делать не должны».

На выходе получается исполняемый проект. Раздел «Операции» содержит точную информацию вплоть до сигнатур методов, типов параметров и шагов выполнения.

Инструкция:

/spdd-reasons-canvas @GGQPA-001-202603191100-[Analysis]-multi-plan-billing-model-aware-pricing.md

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

К этому моменту мы уже проработали высокоуровневую стратегию на этапе анализа – поэтому при проверке структурированного промпта мы не начинаем с нуля. Вместо этого мы изучаем, как ИИ преобразовал наше общее понимание в структуру REASONS Canvas: от стратегии к абстракции и конкретным деталям.

Рассматривайте это как последовательность: этап анализа дал нам стратегическую ясность; теперь мы проверяем, насколько эта ясность была точно отражена в архитектурных абстракциях и особенностях реализации. Это согласование намерений на более глубоком уровне – гарантия того, что до генерации любого кода ИИ фактически «смоделировал» все решение в рамках определенного нами фреймворка. Мы можем проводить анализ с глобальной точки зрения, а не теряться в деталях с самого начала.

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

На данный момент мы достигли прочного консенсуса на уровне намерений, прояснив как основную проблему, так и путь ее решения. Хотя в деталях могут быть небольшие неточности, это не вызывает опасений; согласование общего подхода с ИИ делает локальные оптимизации легко контролируемыми. Теперь переходим к этапу генерации кода.

Что делать, если структурированный промпт требует доработки?

Мы никогда не редактируем файл структурированного промпта вручную. Вместо этого мы поддерживаем итеративный диалог SPDD:

1. Определите расхождение: выявите недостающие элементы (например, отсутствие принципов ООП или неправильное понимание бизнес-правил).

2. Введите новый промпт: через диалоговый интерфейс укажите недостающее намерение непосредственно ИИ.

3. ИИ обновляет файл: он обрабатывает новое намерение и уточняет только те разделы структурированного промпта, которые требуют изменений.

Позже мы рассмотрим конкретный пошаговый пример такого рабочего процесса «сначала обновление промпта», где мы изменим промпт, чтобы исправить несоответствие бизнес-логики, прежде чем трогать какой-либо код.

Шаг 5: Сгенерировать код

Этот этап более сложный, поскольку мы генерируем код продукта, тесты, и наши проверки имеют два альтернативных результата.

Сгенерировать код продукта

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

Как работает spdd-generate

Эта команда считывает REASONS Canvas и генерирует код от задачи к задаче, следуя порядку, определенному в разделе «Операции». Она строго придерживается стандартов кодирования, описанных в разделе «Нормы», и ограничений, описанных в разделе «Меры безопасности» – никакой импровизации, никаких функций, кроме тех, что указаны в спецификации.

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

Инструкция:

/spdd-generate @GGQPA-001-202603191105-[Feat]-multi-plan-billing-model-aware-pricing.md

 Сгенерированный артефакт: код, сгенерированный на основе структурированного промпта.

Благодаря многократным циклам логической дедукции, которые мы провели ранее, используя структурированные промпты, мы подходим к проверке кода с четкой целью и набором приоритетов:

1. Архитектура: строго ли следует код ожидаемой нами трехуровневой архитектуре?

2. Бизнес-логика: полностью ли соответствует реализация сервисного уровня нашим первоначальным замыслам?

3. Объем изменений: строго ли изменения ограничиваются границами, определенными в структурированном промпте, избегая несвязанных изменений или расширения объема работ?

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

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

Проверка функциональности

При проверке функциональности рабочий процесс SPDD предоставляет команду /spdd-api-test для генерации скриптов функционального тестирования (поскольку это опциональная команда, то если она недоступна в вашей локальной среде, вы можете сгенерировать её, выполнив команду openspdd generate spdd-api-test).

Как работает spdd-api-test

Эта команда извлекает информацию об эндпоинтах API из реализации кода или критериев приемки и генерирует тестовый скрипт на основе cURL. Скрипт включает в себя структурированную таблицу тест-кейсов, охватывающих нормальные сценарии, граничные условия и сценарии с ошибками. При выполнении он выводит результаты сравнения ожидаемых и фактических значений.

Инструкция:

/spdd-api-test

Созданный артефакт: скрипт тестирования API.

Руководствуясь правилами, заданными в команде, ИИ генерирует скрипт, который с помощью команд curl формулирует необходимые тестовые сценарии. Мы можем проверить эти сгенерированные ИИ сценарии в разделе «ОБЗОР ТЕСТ-КЕЙСОВ» (TEST CASE OVERVIEW) скрипта.

Выполнение: после генерации скрипта запустите его:

sh scripts/test-api.sh

Результат: все функциональные тесты пройдены успешно.

Проверка кода и финальные корректировки

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

Для обеспечения точности в наших инженерных практиках мы классифицируем эти окончательные корректировки на два отдельных типа – в зависимости от того, изменяют ли они наблюдаемое поведение системы – и обрабатываем их с использованием различных стратегий в рамках рабочего процесса SPDD:

Коррекция логики (изменение поведения)

Стратегия: сначала обновите промпт, а затем сгенерируйте код. В случае проблем, связанных с бизнес-правилами или несоответствиями логики (которые по своей сути меняют наблюдаемое поведение программного обеспечения), всегда обновляйте структурированный промпт, чтобы зафиксировать правильное намерение, прежде чем вносить изменения в код. Это обновление или исправление ошибки, а не рефакторинг.

Например, при сохранении modelId в счете, мы в настоящее время допускаем значение NULL для этого поля. Основная причина заключается в необходимости обеспечения обратной совместимости с историческими данными, что делает это обходное решение разумным архитектурным решением.

Однако есть альтернатива. Если стейкхолдеры со стороны бизнеса смогут подтвердить, каким должно быть значение modelId до внесения этого изменения, мы сможем унифицировать поведение системы и устранить этот потенциальный технический долг. Предположим, что после подтверждения со стороны бизнеса значение modelId для всех исторических счетов должно быть установлено как fast-model.

С этим четким намерением мы взаимодействуем с ИИ.

Как работает spdd-prompt-update

Эта команда инкрементально обновляет существующий Canvas. Она изменяет только те разделы, которые затронуты изменением, и сохраняет все остальное. В зависимости от типа изменения – новое требование, архитектурная корректировка или изменение ограничений – она автоматически определяет, какие измерения REASONS нуждаются в обновлении.

Это отличается от /spdd-sync: sync действует от кода к спецификации, когда код был изменен; prompt-update же действует от требований к спецификации, когда требования были изменены.

Инструкция:

/spdd-prompt-update @GGQPA-001-202603191105-[Feat]-multi-plan-billing-model-aware-pricing.md
model_id – обязательное поле, и его значение по умолчанию – fast-model. На основании этого решения, обнови соответствующие части структурированного промпта.

На основе этой инструкции ИИ обновляет структурированный промпт.

Обновленный артефакт: обновленный структурированный промпт.

После подтверждения используйте команду /spdd-generate для обновления соответствующего кода в соответствии с обновленным структурированным промптом:

/spdd-generate @GGQPA-001-202603191105-[Feat]-multi-plan-billing-model-aware-pricing.md

ИИ, руководствуясь правилами, определенными в команде /spdd-generate, понимает необходимые изменения и выполняет целевые обновления исключительно в затронутом коде.

Обновленный артефакт: обновленный код.

Важно отметить, что мы не перегенерируем всю кодовую базу. Мы продолжаем использовать существующий структурированный промпт, а ИИ обрабатывает целевые изменения:

1. Определите несоответствия: обратите внимание, что поведение modelId во время сохранения данных не соответствует новому бизнес-требованию (оно должно быть обязательным со значением по умолчанию).

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

3. Обновите промпт: вставьте извлеченный фрагмент в чат вместе с измененным бизнес-правилом, дав указание ИИ сначала обновить структурированный промпт.

4. Сгенерируйте целевые обновления кода: как только промпт отразит новые данные, запустите команду /spdd-generate, указав на обновленный файл. ИИ автоматически выполнит целевые изменения исключительно в затронутом коде, а не будет перегенерировать все с нуля.

Рефакторинг (чистый код и стиль)

«Изменение внутренней структуры программного обеспечения, призванное упростить ее понимание и удешевить модификацию без изменения наблюдаемого поведения».

— Мартин Фаулер

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

Например, сгенерированный ИИ класс BillingServiceImpl содержит несколько жестко закодированных «магических чисел», которые необходимо перенести в осмысленные константы.

private int calculateRemainingQuota(String customerId, PricingPlan plan) {        if (plan.getMonthlyQuota() == null || plan.getMonthlyQuota() == 0) {            return 0;        }        LocalDate currentDate = LocalDate.now(ZoneOffset.UTC);        LocalDateTime monthStart = currentDate.withDayOfMonth(1).atStartOfDay();        LocalDateTime monthEnd = currentDate.plusMonths(1).withDayOfMonth(1).atStartOfDay();        Integer currentMonthUsage = billRepository.sumIncludedTokensUsedForMonth(customerId, monthStart, monthEnd);        return plan.getMonthlyQuota() - currentMonthUsa;    }

Инструкция 1:

@BillingServiceImpl.java В методе calculateRemainingQuota есть несколько магических чисел, которые нужно обрабатывать как константы

ИИ выполняет рефакторинг кода на основе этой инструкции (помните золотое правило: всегда проводите рефакторинг небольшими, поэтапными шагами). Если результат соответствует нашим ожиданиям, мы используем команду /spdd-sync для синхронизации этих обновленных деталей кода с соответствующими им местами в структурированном промпте.

Как работает spdd-sync

Эта команда сравнивает текущий код со спецификацией Canvas, а затем синхронизирует изменения в коде (рефакторинг, исправления ошибок, новые компоненты) обратно с Canvas.

Цель состоит в том, чтобы сохранить Canvas в качестве точного проектного документа для текущего кода, а не устаревшей исторической записи.

Инструкция 2:

/spdd-sync

ИИ обобщает изменения на основе правил, заданных в команде /spdd-sync. Затем, следуя структурным требованиям REASONS Canvas, он записывает детальные обновления описания кода обратно в соответствующие разделы структурированного промпта.

После выполнения обеих команд все изменения в промптах и коде можно увидеть здесь .

Для более глубоких или скрытых проблем в коде просто повторите эти шаги. Золотое правило – всегда синхронизировать структурированный промпт с последней версией вашей кодовой базы.

Регрессионный тест

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

Результат: все пройдено.

Шаг 6: Сгенерировать модульные тесты

Одного лишь функционального тестирования недостаточно для надежной валидации; оно выступает в основном в качестве вспомогательной проверки и не учитывается в метриках покрытия кода. Для окончательной проверки основной логики требуются всесторонние модульные тесты. В настоящее время в рабочем процессе SPDD не доработаны специальные команды для тестирования (они будут представлены в будущих итерациях). В качестве временного решения мы используем подход, основанный на шаблонах, для генерации структурированных промптов для модульного тестирования.

Сгенерируйте начальный тестовый промпт

Начнем с того, что объединим детали реализации с нашим стандартизированным шаблоном тестирования, чтобы сгенерировать базовый тестовый промпт.

Инструкция:

На основе промпта с деталями реализации @GGQPA-001-202603191105-[Feat]-multi-plan-billing-model-aware-pricing.md и шаблона @TEST-SCENARIOS-TEMPLATE.md, пожалуйста, сгенерируй файл с тестовыми промптами.

 Удалите дубликаты и уточните сценарии

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

Инструкция:

@GGQPA-001-202603191105-[Test]-multi-plan-billing-model-aware-pricing.md Есть тесты, дублирующие уже существующие; сравни соответствующие тесты с существующими, а затем добавь только тесты для новых сценариев

Обновленный артефакт: структурированный тестовый промпт.

Сгенерируйте код модульного теста

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

Инструкция:

На основе сгенерированного тестового промпта @GGQPA-001-202603191105-[Test]-multi-plan-billing-model-aware-pricing.md, пожалуйста, сгенерируй соответствующий код модульного теста.

Результат: все тесты пройдены. Коммит для тестов.

Что показал этот пример

На этом полный рабочий процесс SPDD завершается. Благодаря этому стандартизированному процессу мы успешно достигли следующих ключевых результатов:

1. Реализация бизнес-логики с исключительно высоким уровнем соответствия замыслу (~99%).

2. Полная прозрачность в техническом плане, включая четкое понимание пути реализации, технических решений и допущенных компромиссов.

3. Структурированные промпты, тесно синхронизированные с текущей кодовой базой, закладывают прочную основу для будущих итераций.

4. Объединение человеческой экспертизы, содействие непрерывному накоплению опыта разработчиков и формированию ментальных моделей в процессе совместной работы с ИИ.

Полный список изменений в коде для этого улучшения можно посмотреть на GitHub.

Мы также подготовили дополнительную функцию – многоуровневую систему биллинга в зависимости от объема для корпоративных тарифных планов. Если вы хотите получить практический опыт, мы настоятельно рекомендуем вам реализовать её, используя описанный выше рабочий процесс SPDD.

Три основных навыка

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

Сначала абстракция

Сперва спроектируйте, затем сгенерируйте

Прежде чем генерировать код, необходимо четко понимать, какие объекты существуют, как они взаимодействуют и где проходят границы. Без этого ИИ часто спешит с деталями реализации, в то время как структура разваливается. Неясные обязанности, дублирующаяся логика, несогласованные интерфейсы – цена этого проявляется позже, в проверке и доработке (читать далее…)

Соответствие

Зафиксируйте намерение перед написанием кода

Перед началом реализации необходимо четко определить, «что мы будем делать / чего мы не будем делать», и заранее согласовать стандарты и жесткие ограничения. В противном случае вы получите быстрый результат и медленную доработку (читать далее…)

Итеративная проверка

Превратите вывод в управляемый цикл

Вам нужно, чтобы поддержка ИИ работала как инженерный процесс, а не как разовый черновик. Без четкого цикла проверок и итераций команды либо постоянно заставляют модель исправлять ошибки до тех пор, пока решение не изменится, либо постоянно перезапускают ее и теряют контроль над затратами и временем (читать далее…)

Где подходит SPDD

Оценка приспособленности

SPDD – это инженерная инвестиция. В таблице ниже приведена оценка окупаемости в зависимости от сценария, от очень рекомендуемого (5 звезд) до неподходящего (1 звезда).

Компромиссы, которые следует учитывать

Окупаемость инвестиций

Первоначальные инвестиции

Продолжение следует: преодоление барьера «только для экспертов»

При нынешних компромиссах SPDD может показаться методом, предназначенным только для опытных архитекторов, поскольку он предъявляет высокие требования к абстракции и моделированию. Но это не является нашей конечной целью.

Мы работаем над снижением этого барьера. Для решения проблемы масштабируемости мы изучаем способы переиспользования существующих ресурсов SPDD и делаем сложные бизнес-правила и проектные ограничения более машиночитаемыми и «интеллектуальными», чтобы их можно было применять единообразно, не полагаясь на индивидуальную интуицию.

Наше направление ясно: SPDD должен меньше зависеть от личного мастерства и больше от зрелой системы управления ресурсами на уровне организации. Независимо от того, являетесь ли вы опытным экспертом или только начинаете, вы должны иметь возможность получать высококачественные, стандартизированные результаты, затрачивая гораздо меньше «экспертного времени».

В разработке находятся новые подходы, призванные упростить внедрение SPDD.

Заключение

Используя REASONS Canvas, уточняя намерения, устанавливая правильные абстракции, разбивая работу на конкретные задачи и определяя границы, мы предоставляем ИИ четко определенное пространство для работы. В рамках этого пространства SPDD, возможно, не является кратчайшим путем к «быстрой генерации кода», но это один из самых надежных способов уверенно внедрять необходимые изменения.

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

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

В эпоху искусственного интеллекта разработка программного обеспечения – это не соревнование IQ моделей. Это соревнование в когнитивных возможностях инженеров – насколько четко мы можем мыслить, формулировать проблемы и принимать решения.

В заключение приведем цитату, которая отражает дух SPDD:

«В науке, если вы знаете, что делаете, вам не следует этого делать. В инженерии, если вы не знаете, что делаете, вам не следует этого делать».

— Ричард В. Хэмминг