Всем привет! Я Светлана Забирова, лид аналитики в Центре разработки и машинного обучения компании «Инфосистемы Джет». В ИТ работаю уже больше десяти лет, из них половину – в заказной разработке.

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

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

ИИ не будет работать лучше, если аналитики просто «начнут промптить». Задача решается уровнем выше: требования должны стать инженерным артефактом. То есть относиться к требованиям нужно так же, как разработчики относятся к коду:

• хранить их в системе контроля версий;

• проводить ревью изменений;

• фиксировать архитектурные решения;

• связывать требования с API, задачами разработки и тестами.

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

Мы решили проверить подход на одном из пилотных проектов, где было все: аналитика, архитектура, backend/frontend-разработка, тестирование и DevOps.

Как мы перевели аналитику из Confluence/Word в SDD-контур и что из этого получилось, рассказываю под катом.

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

Как работали раньше, и что изменилось

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

И сразу еще немного контекста:

На схемах входы расположены слева, управление — сверху, механизмы — снизу, процессы — в центре.

Было. Аналитик готовил постановку в Confluence, Word и Jira. Разработчик работал в IDE и Git, но входные требования получал из внешнего документа. Архитектурные решения, тест-кейсы и код жили рядом только организационно. Связанной системы артефактов не было.

Красная зона на схеме — знакомая боль многих проектов: ТЗ и код быстро расходятся, потому что меняются в разных средах и по разным правилам.

Стало. Мы собрали SDD-контур (spec-driven development): требования, декомпозиция, пользовательские истории, сценарии приёмки в Gherkin, OpenAPI, ADR, CR-файлы (change request) и инженерные диаграммы ведутся в Git как текстовые файлы.

Код при этом не лежит в том же репозитории. Проект устроен как polyrepo: есть отдельный репозиторий specs, отдельный репозиторий backend и отдельный репозиторий frontend. Но все они находятся в одном Git-проекте и связаны правилами трассировки.

Так мы не пытались «свалить всё в один репозиторий», а сохранили понятные границы владения:

• аналитики ведут требования и связанные спецификации в specs;

• архитектор складывает ADR и архитектурные артефакты в тот же specs;

• разработчики пишут код в backend/frontend-репозиториях;

• агенты получают из specs ровно те артефакты, которые нужны для генерации кода и тест-кейсов по конкретной задаче.

Красная пунктирная линия на схеме «стало» показывает, как мы закрывали обратную связь. Раньше замечание легко уезжало в чат или звучало на созвоне как «потом поправим». В пилоте мы возвращали такие замечания в specs в виде CR и журнала ревью (review log). Так спецификация постепенно становилась пригодной для повторного использования агентами.

В работе аналитика изменились три из четырёх опор процесса:

1. Управление: вместо свободной формы постановки — SDD, шаблоны, контрольные точки ревью и правила трассировки.

2. Среда: вместо Confluence как основного рабочего места — IDE, Markdown и Git.

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

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

Почему подход «дайте аналитику LLM» не сработал

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

Но на общем результате почти не сказывалось, потому что сквозной процесс от этого почти не менялся.

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

Например:

1. Аналитик пишет требования.

2. Архитектор на основе требований проектирует решение.

3. Разработчик пишет код по архитектуре.

4. Тестировщик составляет проверки по коду и требованиям.

Агент в такой схеме получает слишком широкий и неоднозначный контекст, он не понимает:

• какие требования обязательные;

• что просто пожелание;

• какие решения уже приняли;

• какие ограничения нельзя нарушать;

• какие сценарии критические.

Поэтому пилот мы строили не вокруг вопроса «какую модель дать аналитику», а вокруг другого вопроса:

Спойлер: specs-репозиторий.

Как устроили specs-репозиторий

Specs стал местом, где живут текстовые и контрактные артефакты. В нём лежат не исходники приложения, а всё, что нужно для постановки, архитектуры, трассировки и проверки.

Упрощённо структура выглядела так:

specs/
  product/
    source-requirements/        # исходные требования, ЧТЗ-свод, материалы заказчика
  epics/
    EPIC-001_.../
      EPIC-001_....md           # описание эпика
      tasks_features/           # Back_* и Front_* постановки
      user-stories/             # US-*.md
      gherkin/                  # GH-*.feature
      ux/                       # UI-control-register, UI-interaction-map
      cr/                       # CR-файлы с замечаниями и запросами изменений
      review-log*.md          # результаты ревью
  engineering/
    adr/                        # ADR архитектора
    api/                        # OpenAPI / AsyncAPI
    contracts/                  # контракты внешних систем
    schemas/                    # JSON Schema
    examples/                   # примеры CSV/JSON
    diagrams/                   # PlantUML, draw.io, C4, sequence
  security/
    rbac/

Здесь мы отдельно договорились о важной вещи: «спецификация рядом с кодом» не обязательно означает «в той же папке, что и исходники». Для нашего проекта логичнее оказалось разделить код и требования физически, но оставить их в одном инженерном процессе.

Код разнесли так:

• backend — отдельный репозиторий;

• frontend — отдельный репозиторий;

• specs — отдельный репозиторий требований и инженерных спецификаций.

Связь между ними держалась не на памяти участников, а на правилах:

• единое пространство проекта в Git;

• имена эпиков, фич и задач;

• ссылки из Back_* / Front_* на ADR, OpenAPI, Gherkin, CR и смежные задачи;

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

Например, для backend-задачи типа «Хранение» агенту не нужен весь эпик целиком. Ему нужны постановка Back_*, связанный ADR, OpenAPI при наличии, примеры CSV/JSON, Gherkin-сценарии и CR-файлы по этой фиче.

Когда мы начали ограничивать набор входов, стало проще и агенту, и человеку на ревью: меньше шума, меньше шансов упереться в контекстное окно модели.

Как декомпозировали требования под ограниченный контекст модели

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

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

Типовая цепочка выглядела так:

EPIC-001
  FEAT-001-01
    Back_001_01-01  # backend: хранение
    Back_001_01-02  # backend: API Front/Back
    Front_001_01-03 # frontend: форма или блок UI
  FEAT-001-02
    Back_001_02-01  # backend: отдельный endpoint или сценарий интеграции
    Front_001_02-02 # frontend: связанная UI-задача

Для backend выделяли разные типы задач:

• Хранение: БД, миграции, CSV/JSON, начальное наполнение, правила чтения и записи.

• API Front/Back: REST-контракты, ошибки, DTO, валидация, взаимодействие с frontend.

• Адаптер интеграции: требования к обмену с внешней системой, маппинг, polling, статусы, обработка ошибок.

• Эмулятор: если для разработки или CI нужна замена внешней системы.

Для frontend дробили по экранным формам. Если страница была сложной, отдельной задачей становился не весь экран, а конкретный блок или сценарий.

Связи фиксировали в двух местах:

1. В эпике — общая декомпозиция, порядок разработки и трассировка артефактов.

2. В каждой задаче — ссылки на смежные Back_* / Front_*, user story, Gherkin, OpenAPI, ADR и CR.

На основе эпика и вложенных задач аналитики генерировали:

• пользовательские истории (US-*.md);

• сценарии приёмки в Gherkin (GH-*.feature);

• OpenAPI для контрактов Frontend/Backend;

• описание состава полей для справочников и таблиц;

• примеры CSV/JSON для дальнейшей проработки архитектором и разработчиками.

Разберем на примере задачи на backend-хранение

Один из примеров постановки — задача Back_001_01-01: Хранение UI-конфигурации каркаса.

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

Для агента и последующего ревью этого мало.

В новом шаблоне задача фиксировала:

• ID задачи, слой, тип задачи, компонент архитектурной схемы;

• фичу и эпик;

• источники информации;

• требования к структуре данных и хранению;

• порядок интеграции;

• NFR именно этой задачи;

• что находится вне объёма;

• сценарии использования;

• критерии приёмки;

• зависимости и риски.

Фрагмент требования:

3.1.1. Сервис **ms-nsi** должен хранить словари контура
в PostgreSQL. При обработке GET /api/v1/nsi/ui-config
и section-pages должен получать данные только из БД.
Активный контур должен определяться по переменной окружения
PORTAL_CONTOUR_CODE на экземпляре ms-nsi; **UI** не должен
передавать contour_code в запросе.

Формально это всё ещё обычный Markdown. Но для агента это уже не «текст про меню», а нормальный структурированный вход:

• известен компонент (ms-nsi);

• известна операция (GET /api/v1/nsi/ui-config);

• задан источник данных (PostgreSQL);

• указано, чего делать нельзя (UI не передаёт contour_code);

• есть ссылка на смежную API-задачу и OpenAPI;

• есть критерии приёмки и Gherkin-сценарии.

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

Как работал цикл замечаний: CR вместо «поправим потом»

На этом месте быстро всплыл бытовой, но болезненный процессный дефект: замечания терялись в переписке и созвонах. Если архитектор, разработчик или тестировщик находил проблему в спецификации, замечание начали фиксировать в CR-файле внутри эпика.

Например:

specs/epics/EPIC-001_.../cr/CR-001_Specs_Change_Requirements.md

CR использовали, чтобы:

• уточнить границы задачи;

• зафиксировать архитектурные замечания;

• изменить структуры CSV/JSON или OpenAPI;

• перенести технические детали из устного обсуждения в постановку;

• синхронизировать требования после ADR или ревью кода.

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

• эпик и таблица декомпозиции;

• смежные Back_* / Front_*;

• OpenAPI;

• US и Gherkin;

• ADR;

• CR и журнал ревью (review log).

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

Что произошло со SpecKit

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

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

Проблема была не в самой идее SpecKit, а в том, что чужой набор шаблонов не знает:

• нашу декомпозицию эпиков и задач;

• какие репозитории есть в проекте;

• где живёт ADR;

• как связаны backend и frontend;

• какие поля должны быть в OpenAPI;

• какие требования относятся к аналитику, а какие к архитектору или разработчику;

• что считать источником истины при конфликте артефактов.

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

Например, отдельно закрепили правила:

• требования формулируются полными предложениями на русском языке;

• используется модальность «должен / не должен / может»;

• англоязычные термины поясняются при первом употреблении;

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

• строки таблиц и пункты требований имеют разные контуры нумерации;

• в Back_* не дублируется полный контракт внешней системы, а ставится ссылка на канонический контракт;

• в Front_*не дублируются Figma node-id и URL, если они уже зафиксированы в UX-артефактах;

• история изменений ведётся в конце документа, а не длинной строкой в шапке.

Часть этих правил выглядит бюрократически, пока работаешь вручную. Я бы сама раньше спорила с некоторыми из них: зачем так подробно описывать стиль фраз, если «и так понятно»?

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

Как за 6 шагов поменяли жизнь аналитиков (и не только)

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

1. Договорились о методологии и границах

Мы изучили открытые материалы по SDD и чужой опыт, но адаптировали их. Внутри команды договорились: для разработки источником становятся Markdown-артефакты в specs, а не страницы Confluence.

Это не отменило Word полностью. Контрактное ЧТЗ по-прежнему оставалось документом для заказчика. Но для разработки появился отдельный инженерный контур.

2. Пересадили аналитиков в IDE и Git

Аналитики начали работать в VS Code с моделью на сервере компании: не все материалы можно отдавать в публичные облака из-за NDA и внутренних ограничений.

Сами спецификации и проектные материалы мы формировали через on-prem модель qwen3.6-35b-a3b. Для генерации и отладки skills в Cursor использовали платные модели, но без передачи чувствительных данных проекта.

Минимальный Git стал обязательным: клонировать репозиторий, создать ветку, внести изменения, посмотреть diff, отправить изменения на ревью.

Да, страх IDE и Git был. И он не снимается лекцией. Он снимается только реальной задачей.

Аналитик видит свой diff, получает замечание в ревью и постепенно понимает: Markdown и ссылки помогают не потерять смысл требований, а не просто добавляют ещё один инструмент.

3. Собрали каркас specs

Мы описали структуру репозитория, разделили продуктовый слой, эпики, инженерные артефакты, безопасность и служебные проверки.

Отдельно договорились, что ADR архитектора лежат в specs/engineering/adr, OpenAPI — в specs/engineering/api, примеры данных — в specs/engineering/examples.

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

4. Переписали шаблоны под проект

Появились шаблоны:

• эпика;

• user story;

• backend-задачи;

• frontend-задачи;

• правил нумерации;

• правил создания и ревью артефактов.

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

5. Связали скиллы агентов с типами задач

В скиллах агентов прописали, какие артефакты использовать для конкретного действия. Например:

• для задачи на хранение данных в backend — Back_*, ADR, примеры данных, OpenAPI при наличии, Gherkin и CR;

• для frontend-задачи — Front_*, UI map, UX-артефакты, OpenAPI, US и Gherkin;

• для генерации тест-кейсов — US, Gherkin, связанные Back_* / Front_* и критерии приёмки;

• для архитектурного ревью — эпик, задачи, ADR, OpenAPI, CR и диаграммы.

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

6. Отладили ревью по цепочке

Архитектор по первым спецификациям формировал ADR и возвращал замечания к постановке. Разработчики backend и frontend запускали агентов с обновлёнными правилами, смотрели код и снова возвращали замечания к спецификациям.

Тестирование добавляло свои уточнения через Gherkin и критерии приёмки.

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

Человек в процессе все еще главный

Полного автопилота не получилось, хотя никто его и не ждал.

За людьми остались:

• сбор требований на встречах, ВКС и в переписке;

• согласование с заказчиком;

• контрактное ЧТЗ в Word;

• принятие архитектурных решений;

• проверка доменных формулировок;

• ревью постановок, ADR, OpenAPI, кода и тестов;

• ответственность за то, что попало в Git.

Зато модели ускорили подготовительную работу:

• анализ документации и контрактов;

• черновики вопросов к встречам;

• протоколы встреч: транскрибация → черновик → правка аналитиком;

• выжимки из переписки;

• проверку гипотез по внешним API;

• черновую генерацию US и Gherkin;

• приведение текста к проектным правилам.

Владелец требований все еще главный. Если аналитик не понимает домен, агент просто красиво оформит ошибку. Иногда даже слишком уверенно, и ошибку просто будет сложнее заметить.

Но кое-что все-таки изменилось

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

• поддерживать спецификации как версионируемые артефакты;

• работать с ветками, diff и review;

• думать о размере контекста для модели;

• разделять требования по слоям;

• связывать эпики, задачи, US, Gherkin, OpenAPI и ADR;

• фиксировать замечания в CR, а не только в переписке;

• проверять, что после правки одного файла не сломалась трассировка по фиче.

Аналитик стал ближе к инженерному процессу. Его артефакт теперь не просто читают: от него запускаются генерация, ревью и проверка. Это меняет требования к аккуратности сильнее, чем кажется на старте.

Что пока осталось открытым

После пилота у нас остались вопросы, на которые мы найдем ответы со временем тестирования нового подхода:

1. Где баланс между спецификацией для человека и спецификацией для модели?

2. Насколько глубоко нужно стандартизировать мелкие задачи?

3. Когда выгоднее писать лёгкий промпт, а когда полноценный SDD-артефакт?

4. Как формально описать новую зону ответственности аналитика?

5. Как безопасно перегенерировать код при изменении ADR?

6. Как стабилизировать агентные тесты и не получить ложную уверенность от красивого Gherkin?

Если ваши аналитики уже пишут в Git, делитесь опытом, будет интересно сравнить.