Разработка на основе спецификаций в Jira
Разработка на основе спецификаций означает, что перед началом работы составляется структурированная спецификация, используя которую, агент создает именно то, что нужно, а не выдает какие-то предположения. В Jira такая спецификация прикрепляется к текущей задаче, когда она обретает реальные очертания: ожидаемые результаты, область, ограничения и критерии приемки. У задачи может быть полная спецификация для одного задания или часть спецификации для более масштабной функции, разделенной на несколько задач.
В этом руководстве рассказывается, как подготовить спецификацию для агента. Вы узнаете, как написать первую спецификацию и почему ее лучше составлять для конкретной задачи. Разработка на основе спецификаций в Jira дает следующие три преимущества.
Есть единый достоверный источник информации, на основе которой работает агент и с которой сверяется проверяющий.
Существуют критерии приемки, по которым определяется, что задача выполнена как для агента, так и для разработчика.
Требуется меньше доработок, так как намерения были четко определены еще до написания агентом первой строки кода.
Что такое разработка на основе спецификаций?
Разработка на основе спецификаций — это подход, при котором составляется структурированная спецификация, определяющая, что именно нужно создать и по каким критериям оценивается успех. ИИ-агент реализует требования спецификации, а не строит догадки на основе коротких запросов.
Спецификация становится достоверным источником информации. В ней определяется план, сборка и проверка результата. В Jira эти три элемента реализуются в рамках одной и той же задачи. Эта идея возникла еще до появления ИИ из практики проектирования API и формальных методов, когда поведение системы определялось до ее создания.
Инструменты развиваются, определение постоянно меняется, поэтому относитесь к этому как к методике, а не строгому формату спецификаций. Неизменным остается главный принцип: определите задачи, прежде чем передать их в разработку агенту.
Устранение неоднозначности — один из ключевых моментов. При использовании вайб-кодинга это происходит после написания кода, а при разработка на основе спецификаций — до.
Вайб-кодинг. Вы управляете работой агента с помощью запросов и принимаете результат его работы, поэтому область, ограничения и крайние случаи, о которых агенту пришлось строить предположения, становятся очевидны только после создания кода.
На основе спецификаций. Сначала вы определяете намерение, ограничения и критерии приемки, чтобы агент создавал решение на основе определения, а не догадок. При проверке выполняется сверка с этим же определением, встроенным в задачу.
Для кода, который должен быть работоспособным в реальной кодовой базе, агент в отсутствие согласованного контекста может решить задачу слишком буквально или упустить важное ограничение. Именно здесь начинается доработка.
Спецификация описывает, что вы создаете, а план — как вы это делаете. В запросах к ИИ часто размывается грань между этими двумя понятиями. При разработке на основе спецификаций сначала определяется, что нужно сделать, а затем исходя из этого — как это будет реализовано. Именно этот шаг инструменты для написания кода на базе ИИ часто пропускают в режиме планирования: они создают план действий прямо на основе запроса, обычно без согласованной спецификации.
Режим планирования может служить в качестве упрощенной спецификации, но в нем план действий («как») составляется на основе текущего запроса, а не на основе согласованной спецификации, которая сохраняется в задаче.
Почему спецификации важны при написании кода с помощью ИИ
Когда стало возможно генерировать код недорого, его написание перестало быть самой сложной задачей. Теперь важнее определить, что нужно разработать. Именно поэтому самым важным создаваемым артефактом является спецификация, а не запрос к ИИ.
Одноразовый запрос не содержит всю информацию, поэтому агент заполняет пробелы на основе предположений и создает код, который выглядит правильно, но решает не ту задачу. Спецификация в первую очередь устраняет эти пробелы, поэтому агент создает решение в соответствии с определением, а не действует наугад. В Jira роль спецификации играет та задача, которую ваша команда уже планирует, назначает и проверяет.
Что должно входить в спецификацию, на основе которой агент создает решение?
Спецификация, пригодная для агента, должна отвечать на вопросы, которые задал бы хороший инженер перед началом работы. В Jira ответы на эти вопросы находятся в описании задачи, связанных требованиях и критериях приемки. Важны шесть следующих элементов.
Ожидаемые результаты. Каково назначение изменения в формулировке, позволяющей проверить, что цель достигнута.
Область. Важно не только то, что входит в объем задачи, но и что не входит.
Ограничения. Архитектурные, эксплуатационные и относящиеся к безопасности ограничения, которые необходимо соблюдать.
Принятые ранее решения. Согласованный контекст, который агент уже не пересматривает.
Декомпозиция задачи. Этапы выполнения задачи, достаточно мелкие для удобства проверки.
Критерии приемки. Тестируемые критерии готовности работы, на которые ориентируется агент и по которым выполняется проверка. В Jira критерии находятся в задаче, и при проверке кода ИИ может сопоставить изменения с ними перед отправкой человеку.
Как задача становится спецификацией в Jira
Правильно составленная задача может служить спецификацией, на основе которой агент разрабатывает и проверяет код. Спецификация также может храниться в прикрепленном документе, как это реализовано во многих инструментах для разработки ПО на основе спецификаций. В Jira просто можно размещать ее там, где уже ведутся задачи. Спецификация, содержащая все шесть указанных выше элементов, соответствует требованиям. А задача, сформулированная одной строкой вида «исправь баг при входе», — нет.
Хранение спецификации в задаче имеет одно структурное преимущество: спецификация находится там же, где и сама работа, поэтому о ней сложнее забыть, чем о файле Markdown в репозитории, который никто повторно не открывает. Это не делает спецификацию самодостаточной. Это значит, что задачи не разойдутся со спецификацией.
Все компоненты — описание, связанные требования в Confluence и критерии приемки — находятся в одном месте, доступном и агенту, и проверяющему.
Файл в репозитории, напротив, хранится отдельно от того места, где команда отслеживает, проверяет и закрывает задачи, поэтому он устаревает, как только план меняется.
Та же самая задача служит площадкой для проверки работы агента, потому что здесь команда согласовывает требования и обсуждает открытые вопросы.
В Jira планы создаются на основе четких требований, задач и оценок.
Создание структурированной спецификации Планировщиком Jira
В предыдущем разделе был рассмотрен основной процесс — самостоятельное создание спецификации на основе задачи. Планировщик Jira предназначен для сложных инициатив, охватывающих несколько команд, когда написание каждой спецификации вручную не позволит масштабировать работу. Все начинается с инициативы, которая разбивается на структурированные задачи, у каждой из которых будет своя спецификация.
Планировщик Jira не выполняет всю работу, а только помогает ускорить разработку спецификации. Метод SDD (разработка на основе спецификации), в основе которого лежит правильно составленная задача с критериями приемки, уже сегодня может применять любая команда. Планировщик Jira ускоряет самую сложную часть этой задачи: превращение сложного запроса, допускающего неоднозначное толкование, в структурированную спецификацию.
Для сложных проектов Планировщик Jira использует Teamwork Graph, включая вашу базу кода, историю Jira и Confluence, а также контекст команды, чтобы определить требования и создать структурированную техническую спецификацию в Confluence, готовую для дальнейшего использования разработчиком или агентом по написанию кода. Он создает один план для разных аудиторий: понятный для человека, полезный для агента.
Что делает этот инструмент.
Предоставляет вам и вашей команде общую рабочую область для сотрудничества, позволяя согласовать все детали до того, как агент приступит к выполнению.
Использует контекст всей работы команды, поэтому спецификация создается на основе имеющихся знаний, а не пустого запроса.
Создает спецификацию, которую легко читает человек и без ошибок разбирает агент: один и тот же артефакт служит и для проверки, и для выполнения.
Хранит спецификацию в Confluence с привязкой к задачам, чтобы намерения и решения были зафиксированы.
Планировщик Jira превращает исходные идеи в структурированные спецификации, готовые для использования агентами.
Планировщик Jira доступен в ознакомительной версии — зарегистрируйтесь в списке ожидания
Как написать свою первую спецификацию для агента в Jira
Возьмите одну задачу и вручную превратите ее в готовую спецификацию для агента, проверяя полноту спецификации по шести элементам контрольного списка.
Начните с задачи. Укажите в описании результат, границы области и ограничения, а не только заголовок.
Превратите намерение в структурированную спецификацию. В этом и состоит важнейший принцип разработки на основе спецификации. Используя предварительный контекст, сформулируйте результаты, область и ограничения задачи — это определение будет передано агенту.
Создайте тестируемые критерии приемки. Это соглашения, на которые ориентируется агент при разработке и проверяющий при проверке. Часто требуется несколько итераций, чтобы сформулировать критерии, которые поддаются тестированию.
Назначьте спецификацию агенту по написанию кода. Задача, снабженная спецификацией, предоставляет агенту достаточно информации для генерации кода и создания запроса pull, связанного с этой задачей.
Проверьте запрос pull на соответствие критериям, а затем доработайте его. Внесите уточняющие дополнения в спецификацию в тех местах, где агент сделал предположение, и повторно используйте этот шаблон для следующей задачи.
Часто задаваемые вопросы о разработке на основе спецификаций
Нужен ли мне Планировщик Jira для разработки на основе спецификаций?
Нет. Основа — это правильно сформулированная задача с критериями приемки, которую любая команда может создать уже сегодня. Планировщик Jira ускоряет выполнение сложных задач, начиная с плана верхнего уровня (инициативы), и разбивая его на структурированные задачи Jira, дополняя каждую заполненной спецификацией, чтобы вам не приходилось создавать их вручную.
В чем разница между спецификацией и критериями приемки?
Спецификация описывает изменение в целом: его результаты, область, ограничения и контекст. Критерии приемки — это одна из ее составляющих, тестируемые признаки готовности, на которые ориентируется агент при разработке и проверяющий при проверке.
Достаточно ли просто хорошего запроса?
Да, зачастую это так для небольших обратимых задач. В сложных или необратимых ситуациях агент вынужден предполагать, что вы упустили в запросе. Спецификация избавляет от догадок.
Как лучше хранить спецификацию? В виде файла в репозитории или в задаче Jira?
Спецификация содержится в задаче, где работа отслеживается, проверяется и закрывается. Это снижает вероятность того, что спецификация устареет, в отличие от файла Markdown в репозитории, который никто не открывает.
Замедляет ли разработка на основе спецификаций работу команд?
Спецификации требуют дополнительных трудозатрат на начальном этапе, но избавляют от переделок в дальнейшем. В случае сложных задач эта практика приносит явную выгоду. В случае обычных исправлений пропустите спецификацию и сразу переходите к составлению запроса.
Когда следует писать спецификацию, а когда можно обойтись без нее?
Спецификация необходима в случае задач сложных, с высокой степенью влияния или с труднообратимыми результатами, а также для задач, имеющих серьезные архитектурные ограничения или ограничения в области безопасности. Пропустите этот шаг, если планируются небольшие обратимые исправления — в этом случае быстрее будет составить краткий запрос.