Разработка на основе спецификаций: положительные стороны и выводы, сделанные нами за три месяца

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

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

Проблема → Исследование → Спецификация → Проверка → Реализация → Верификация

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

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

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

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

До сих пор существует немало разногласий по поводу того, стоит ли того дополнительная структура SDD. Microsoft и AWS продвигают SDD, в то время как Thoughtworks описывает его как формирующийся и спорный подход, а специалисты-практики сообщают о неоднозначном опыте. Критики предупреждают, что SDD может привести к созданию большего количества Markdown, чем инженеры в состоянии поддерживать, превратить подробную спецификацию в код, написанный прозой, или оставить после себя еще одно описание системы, которое отличается от кода.[1][2][3]

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

Почему мы создали /spec-driven

Некоторые инженеры Asana уже пробовали GitHub Spec Kit и OpenSpec, но ни один из этих инструментов не стал частью их обычного рабочего процесса. Нам нужна была версия, которую мы могли бы адаптировать по мере накопления опыта и интегрировать в процесс разработки Asana.

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

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

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

Рабочий процесс включал в себя несколько команд. Инженеры использовали команду /spec-driven spec, чтобы проработать открытые вопросы и составить спецификацию и план реализации. После ознакомления с планом они использовали команду /spec-driven ship, чтобы реализовать его, проверить результат и подготовить работу к рассмотрению. Конечный автомат отслеживал проект по мере выполнения этих команд, поэтому на последующих сеансах было известно, что произошло и что будет дальше.

С самого начала мы хотели, чтобы /spec-driven был чем-то большим, чем просто способом составления и реализации спецификаций. Мы также хотели, чтобы он управлял рабочими процессами с участием агентов. Он упорядочивает задачи по зависимостям и распределяет пересекающиеся изменения файлов по отдельным этапам выполнения. Она параллельно отправляет независимые задачи нескольким агентам, а затем использует результаты, чтобы решить, что можно выполнять дальше.

Это как GPS для работы: в любой момент понятно, каким будет следующий шаг и где принимаются реальные решения, поэтому трудно зайти в тупик.”

Инженеры Asana использовали /spec-driven как в режиме «спецификация в первую очередь», так и в режиме «спецификация как ориентир». В первом случае они использовали спецификацию, чтобы выбрать направление, а затем перестали её обновлять. При подходе, ориентированном на спецификацию, они поддерживали её актуальность по мере изменения работы. Инженеры также составляли отдельные спецификации для частей более масштабной работы, чтобы один человек мог использовать рабочий процесс, не требуя от всей команды его внедрения.

Когда использование /spec-driven оправдывает дополнительные усилия

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

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

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

Инженеры также использовали /spec-driven для координации больших объёмов работы, выполняемой агентами. В консоли администратора Asana, где ИТ-команды компаний-клиентов управляют настройками безопасности, доступа, интеграций и общего доступа для всей организации, инженеры использовали её для переноса 66 настроек в общие фреймворки. Для переноса этих настроек потребовалось около 150 миграций в нескольких фреймворках консоли администратора. Каждая миграция становилась тикетом Asana для облачного агента, и инженеры выполняли их параллельными партиями, обновляя оставшиеся тикеты на основе предыдущих результатов.

Команда, отвечавшая за эту работу, сообщила, что 91 % переносов не потребовали доработки после проверки и что в целом работа была завершена более чем на месяц раньше первоначального плана.

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

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

Что показали первые результаты

Мы призвали всех хотя бы раз попробовать /spec-driven, но не требовали дальнейшего использования этого подхода. Её опробовала примерно половина инженеров. В последний месяц еженедельно инструментом пользовались от 30 до 50 инженеров. Среди встроенных и разработанных Asana навыков агентов, которыми инженеры пользовались напрямую, /spec-driven занял третье место. Факт постоянного использования инструмента обнадеживал, но не давал нам представления о том, как /spec-driven влиял на результаты работы.

Общеизвестно, что скорость работы инженеров измерить крайне сложно. Заявки на внесение изменений и добавления в рабочий код — несовершенные показатели продуктивности, но мы считаем, что они часто являются полезными ориентирами. Для сравнения скорости работы мы проанализировали данные семи инженеров и 524 объединённых запроса на внесение изменений за четыре месяца. Мы сравнили работу до и после первого явного использования каждым инженером команды /spec-driven и исключили спецификации, планы и другие артефакты рабочего процесса. Для сравнения отмен мы классифицировали заявку на внесение изменений как основанную на спецификациях (/spec-driven), если она изменяла файлы проекта рабочего процесса.

Количество заявок на внесение изменений в неделю увеличилось на 38%, а количество добавлений в рабочий код — в 2,66 раза. На результат по добавлению кода повлиял один короткий период с необычно большим объёмом работы. Даже без учёта этого периода количество добавлений всё равно было на 66 % больше. Показатель явных отмен также был немного ниже: 1,2% для работы, основанной на спецификациях (/spec-driven), по сравнению с 1,66% для других заявок на внесение изменений.

Больший объем кода не обязательно является хорошим результатом. Агент может создать объемную реализацию, когда достаточно было бы менее объемной, поэтому увеличение количества добавлений кода могло отражать неоправданно масштабные решения, а не больший объем завершенной работы. Обычная проверка дала нам возможность выявить этот вид ошибки. Мы полагались на то, что рецензенты будут отмечать реализации, которые были больше или сложнее, чем требовала задача, и эти изменения все равно проходили. Это дало нам определенную уверенность в том, что не все увеличение было обусловлено чрезмерно масштабными реализациями.

Эти сравнения не контролировались, и мы не могли отделить влияние /spec-driven от сочетания проектов или более масштабных улучшений в инструментарии агентов. Даже с учётом этих ограничений результаты нас обнадежили.

Над чем ещё нужно поработать

Проверка документов может стать узким местом

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

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

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

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

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

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

Полезная спецификация меняется вместе с проектом

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

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

Завершенные спецификации поднимают связанный с ними вопрос: что с ними делать? Мы слишком долго ждали, чтобы ответить на него. Если оставить их в монорепозитории, их будет легко найти, но при этом останутся документы, за которые никто не отвечает. Мы перемещаем их в отдельный архив. Нам всё ещё нужна более короткая процедура передачи, которая сохраняет то, что будет важно в будущем. Если документ создавал больше работы, чем экономил, он не приносил пользы.

Внедрение циклов обратной связи в систему

Иногда решением становился не ещё один документ, а изменение системы, в которой работает агент. Одним из примеров была ошибка в том, как /spec-driven считывал Markdown: заголовки и флажки внутри примеров могли быть ошибочно приняты за реальные важные этапы или незавершенные задачи. Зафиксировав ошибку, мы просмотрели остальную часть /spec-driven и обнаружили несколько команд с собственными небольшими парсерами Markdown и той же «слепой зоной». Мы заменили их одним общим парсером, добавили регрессионные тесты и проверку архитектуры, а затем внедрили исправление в среду. OpenAI описывает схожий подход как «инженерную разработку инструментария»: размещать важную информацию там, где агенты могут её найти, обеспечивать возможность применения правил и использовать сбои для улучшения среды вокруг агента.

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

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

Наиболее полезные рекомендации касались изменений в поведении, затронутых пользователей и вариантов, а также связей между API, схемами или парсерами. Оценки охватывали только вопросы и планы. Мы не оценивали, ускорило ли руководство процесс внедрения. Узконаправленные рекомендации также быстрее устаревали и иногда всплывали в несвязанной работе.

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

Как бы мы сейчас подошли к принципу /spec-driven

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

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

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

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

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

Что дальше?

По прошествии трёх месяцев инженеры по-прежнему используют /spec-driven, когда работа продолжается в течение нескольких сессий, передаётся от одного человека к другому или разбивается на множество связанных задач. Они использовали его для поддержания хода многомесячных проектов и организации больших объёмов работы, выполняемой агентами. Это хороший результат для внутреннего эксперимента.

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

У людей сложилось чёткое мнение о SDD и методе Harness Engineering. Мы узнали больше, применив их к реальной работе, чем споря о них. Теперь, прежде чем добавлять новые процессы, мы спрашиваем, чего не хватает агенту в этом проекте. Начинайте с малого, смотрите, где рабочий процесс помогает, а где мешает, а затем вносите коррективы с учётом полученных выводов.

[1] Биргитта Бёкелер, «Понимание разработки на основе спецификаций: Kiro, spec-kit и Tessl», октябрь 2025 г.

[2] Франсуа Занинотто, «Разработка на основе спецификаций: ответный удар Waterfall», ноябрь 2025 г.

[3] Габриэлла Гонсалес, «Достаточно подробная спецификация — это код», март 2026 г.

Об авторе

Уолтер Ли — инженер-программист команды базовой инфраструктуры хранения данных Asana, а Рохан Батра — инженер-программист команды фреймворков серверной части. Оба несколько месяцев работали в команде Agent Success Tiger Team, где руководили разработкой и оценкой описанного в этой публикации рабочего процесса /spec-driven.

Благодарности команде

Особая благодарность Лео Чжану, Каролю Крупе, Горди Левицкому и Митчу Конкеру за помощь в формировании и разработке подхода /spec-driven, а также за то, что они стали одними из первых, кто его внедрил.