Сейчас очень сложно найти человека, который не использует агентов для разработки, – а агенты для разработки это круто. Задача написания низкоуровневого кода фактически уже решена. Если взять отдельный метод в вакууме, то написанный агентом он почти наверняка будет лучше, чем написал бы человек: и эффективнее, и понятнее. Разумеется, если мы говорим про современные, действительно сильные модели.

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

Раньше всё это разработчик держал в голове. Если мы натыкались на код, который в моменте не понимали, то, как правило, смотрели либо в git blame, либо бежали к коллеге: «Вася, слушай, объясни, пожалуйста, что здесь за херня — я никак не пойму, почему сделано именно так». И Вася, эксперт этой подсистемы, с удовольствием отвечал: «Тут стоит проверка на null, потому что такой-то API при таком-то условии возвращает не совсем то, что нужно, — какой-то такой бред». Знания жили в головах разработчиков, и, когда ты пишешь одну и ту же подсистему пять лет подряд, это в целом не проблема.

Но вот пришли агенты — и пишут код просто невероятно быстро. Отдельные индивидуумы заявляют, что делают по 100 коммитов в день. Охотно верим. Но возникает вопрос: кто потом будет во всём этом коде разбираться? Вот здесь человек и становится узким местом. Причём узких мест сразу два:

• Проверить, что написанный код — действительно тот код, который мы хотели.

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

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

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

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

В лучшем случае были какие-то низкоуровневые генераторы, которые скаффолдили базовый код. Сейчас это не так — и возникают вопросы:

• Как не потеряться в сгенерированном коде?

• Как писать этот код эффективно и при этом так, чтобы он не ломал то, что было написано раньше?

Есть тесты, безусловно. Но проблема тестов в том, что они точно так же могут фиксировать очень неправильное поведение (вот научная статья). Дальше — всё тот же вопрос правильного контекста, и так далее. Со всеми этими проблемами индустрия потихоньку приходит к формату spec-driven development.

Я хочу разобрать две крупные методологии — OpenSpec и Spec Kit, — а в следующей статье, возможно, расскажу и про другие, которые тоже помогают вести разработку от спецификаций.

Обе методологии по сути представляют собой набор скиллов для любого AI-агента — но у каждой свои особенности. Я не ставлю себе цели сделать исчерпывающие обзоры этих инструментов, тем более они продолжают развиваться, но хочу в общем виде дать понимание каждого из них.

OpenSpec

Начнём с OpenSpec. Его разрабатывает команда Fission AI — участник Y Combinator, стартап продуктом которого и является OpenSpec.

Установка

Базовый CLI ставится через npm: npm install -g @fission-ai/openspec@latest. Через него дальше настраивается проект и агент — командой openspec init. Она установит в вашего агента систему скиллов или /-команд с префиксом opsx и проинициализирует структуру проекта. По большому счёту, у вас появится единственная директория openspec с файлом config.yaml внутри — но о нём поговорим ниже. А пока мы уже можем начинать писать спецификации. С самим CLI вы, скорее всего, работать практически не будете, но к нему будут обращаться скиллы OpenSpec.

OpenSpec propose

Первая команда, с которой начинается стандартный workflow, — это /opsx:propose. Мы пишем её в промпте своему агенту с описанием задачи, которую хотим выполнить. После этого OpenSpec создаст новую change-спецификацию.

Поддержка OpenSpec есть в OpenIDE Pro. Лично я ненавижу печатать в терминале. OpenIDE предоставляет удобный редактор, в котором мы можем описать изначальный запрос. Чем этот запрос подробнее описан, тем лучше, но для простоты, опишем нашу задачу поверхностно:

После генерации будет создана директория openspec/changes/<имя-change> и набор артефактов: proposal, технический дизайн, требования в Gherkin-виде (GIVEN/WHEN/THEN).

Здесь стоит сказать, что в OpenSpec спецификации бывают двух видов — change и main. Main-спецификации описывают текущее поведение проекта: что и как работает прямо сейчас. А change-спецификация описывает создание новой функциональности или изменение текущей — то, с чем мы работаем в данный момент.

Конечно, если change-спека создана, это совсем не значит, что она готова. Агент мог нагенерировать какой-нибудь ерунды, неправильно понять наши требования, оставить противоречия и т.д. Подразумевается, что после создания proposal мы с ним ещё как-то работаем, доводя его до идеала. Я, в частности, использую для этого OpenIDE и его механизм ревью. Обидно получить неправильный результат просто потому, что «взял и применил» спеку, доверившись первому (второму, десятому) суждению агента.

В OpenIDE можно провести полноценное ревью результатов и запустить доработку, либо через специальное действие в Spec Cockpit, либо попросив в чате.

OpenSpec apply

Дальше мы вызываем команду /opsx:apply. OpenSpec должен полностью выполнить все задачи из tasks.md, вынося изменения в наш код. И вот тут OpenSpec оставляет разработчика наедине с агентом. Задачи как-то должны быть выполнены. А что после? Что делать, если задача по какой-то причине выполниться не может или получается не совсем то, что хочется? OpenSpec на это не отвечает. Да, наверное, и не должен.

Тут я хочу сослаться на статью Anthropic "Как найти свои неизвестные". Карта — это всё ещё не местность, и пока мы по местности не прошли, точную карту мы не получим. Поэтому применение спеки — это всегда риск. Риск того, что она окажется неприменимой, как ни странно. Или что применится она не так, как мы рассчитывали.

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

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

OpenSpec sync и archive

Когда мы применили спеку, поведение проекта, очевидно, изменилось — и нужно поменять вышеупомянутые main-спеки. В OpenSpec для этого есть команды /opsx:sync и /opsx:archive. Разница между ними такая: sync можно вызвать в любой момент, чтобы частично применить текущую change-спеку к main-спекам. Например, если фича большая и мы не хотим, чтобы состояние двух спек слишком сильно расходилось. archive же вызывается в конце: change-спека с датой уезжает в openspec/archive/, а её дельты вливаются в main. Так main-спеки всегда описывают систему как она есть сейчас, а история — как мы к этому пришли — сохраняется отдельно и не мешается под ногами.

По сути archive — это тот же sync, плюс перемещение change’а в архив и его закрытие. Отдельный sync нужен ровно для длинных изменений, где хочется держать main-спеки актуальными ещё до закрытия change’а.

OpenSpec explore

Ещё в OpenSpec есть незамысловатый скилл explore. Он не создаёт никаких артефактов, а помогает изучить проект и принять решения о том, куда его расширять дальше. Это подготовительный шаг перед /opsx:propose. Сам скилл можно посмотреть вот тут.

OpenSpec: расширяемость

config.yaml

Вот теперь можно вернуться к config.yaml. В этом файле описываются важные вещи о том, как OpenSpec стоит работать именно с вашим workflow: какие данные всегда подгружать в контекст, какие действия выполнять на той или иной фазе. Например, можно указать, что после выполнения всех задач обязательно нужно прогонять тесты (хотя это и так достаточно очевидно).

По сути в config.yaml живут два по-настоящему полезных поля:

• context — текст, который автоматически вклеивается в каждый промпт агента. Стек, конвенции, инварианты проекта. Пишешь один раз — и агент перестаёт каждый раз заново гадать, на чём ты пишешь и можно ли ломать публичный API. Похоже на AGENTS.md, только для OpenSpec.

• rules — правила для каждого типа артефакта. Например: «спеки всегда в Gherkin», «у каждого proposal — план отката», «у каждой задачи — критерий приёмки». Правило приклеивается только к своему артефакту, и его не нужно повторять в каждом промпте. Об артефактах — чуть ниже.

Всё это — обычный YAML в git: версионируется вместе с кодом, шарится на всю команду одним коммитом, правится руками за минуту. Дёшево и полезно.

Кстати, не путайте config.yaml с ещё одним файлом — .openspec.yaml, который лежит внутри папки каждого change’а. Вот с ним вы руками почти никогда не работаете: его ведёт сама CLI. Там машинные метаданные — какая у change’а схема и когда он создан.

schema.yaml

Выше пару раз мелькнули «артефакты». Так вот, артефакты — это части каждой спецификации: proposal.md, specs/, design.md, tasks.md. И это не единственный возможный и жёстко зафиксированный формат — OpenSpec позволяет описать свою собственную структуру спецификации. Она называется схемой (schema), и это просто граф артефактов: что генерится, в каком порядке и что от чего зависит. Дефолтная схема лежит здесь.

Своя схема — это папка openspec/schemas/<имя>/ с файлом schema.yaml и подпапкой templates/ для шаблонов артефактов. Проще всего форкнуть дефолтную (openspec schema fork spec-driven my-schema) и подпилить. Допустим, мы хотим добавить отдельный артефакт testing-strategy между дизайном и задачами:

# Some of fields are missing for the sake of simplicity
name: my-schema
version: 1
description: стандартный flow openspec + отдельная стратегия тестирования
artifacts:
  - id: proposal
    generates: proposal.md
    template: proposal.md
    requires: []
  - id: specs
    generates: specs/**/*.md
    template: specs/spec.md
    requires: [proposal]
  - id: design
    generates: design.md
    template: design.md
    requires: [specs]
  - id: testing-strategy          # ← наш новый артефакт
    generates: testing-strategy.md
    template: testing-strategy.md
    requires: [design]
  - id: tasks
    generates: tasks.md
    template: tasks.md
    requires: [design, testing-strategy]
apply:
  requires: [tasks]
  tracks: tasks.md

Порядок задаётся не позицией в списке, а полем requires — это и есть граф зависимостей. Активируется схема строчкой schema: my-schema в config.yaml (или флагом --schema на конкретный change). Проверить, откуда резолвится схема, — openspec schema which.

Кстати, если вам понравился работа со спеками в OpenIDE, то для полноценной работы с ним пока (!) желательно не выкидывать из схемы артефакт tasks.md: без него большая часть функциональности окажется недоступна.

OpenSpec: итоги

OpenSpec — достаточно легковесный инструмент для работы от спецификаций. Простая система команд, понятный workflow. За нас уже решили, где живут спеки, при этом дали возможность менять их формат. Мне очень нравится, что спеки живут рядом с кодом и что теперь вместо похода к Васе я могу прямо в коммите найти change-спеку, которая привела к конкретным изменениям.

При этом у меня сложилось ощущение, что в большинстве случаев OpenSpec во время apply относится к спеке как к чему-то решённому. С моей точки зрения, даже change-спека — это живой документ, и инструменты вроде OpenIDE позволяют модифицировать спеку прямо в процессе выполнения.

Spec Kit

Вторая методология — GitHub Spec Kit. Если судить о популярности по звёздам на GitHub, то это примерно вдвое более популярный инструмент.

Установка

Ставится тоже как CLI-тула: uv tool install specify-cli, после чего идёт инициализация проекта — specify init <проект>, — которая установит набор /-команд с префиксом speckit. Во время инициализации в директории .specify нагенерируется куча всего: markdown-шаблоны разных документов и несколько sh-скриптов. Содержимое этой директории можно изучить детальнее, если захотите вносить коррективы в свой стандартный workflow — фактически он целиком настраивается через неё. К самому CLI мы дальше тоже обращаться почти не будем: сразу уходим в своего агента.

Пара слов про эти скрипты, чтобы не пугали: они детерминированные и делают механическую работу, которую нельзя доверять «на глаз» агенту. create-new-feature заводит фичу (ветку, папку specs/<NNN-feature>/, начальный spec.md), setup-plan и setup-tasks готовят каркасы плана и задач, check-prerequisites проверяет, что предыдущий артефакт на месте (план требует спеку, задачи — план), common — общие хелперы. Идут в трёх вариантах (bash / PowerShell / Python) ради кроссплатформенности. /-команды дёргают их сами.

Конституция

Работа начинается с определения конституции. /speckit.constitution запустит небольшой опрос: что за проект, каким принципам нужно следовать, какой у вас стек. На выходе — достаточно объёмный документ .specify/memory/constitution.md. О нём тоже можно думать как о своего рода AGENTS.md — контексте который SpecKit будет использовать в каждой следующей фазе работы.

Spec Kit specify

Следующая команда — /speckit.specify. В целом она похожа на OpenSpec propose: мы также описываем задачу, которую хотим выполнить. Но в стандартном workflow Spec Kit структура спеки немного другая. У нас появляется файл spec.md и директория checklists/, в которой сразу создаются, как ни странно, чек-листы — и они проверяют вашу спеку на соответствие некоторым требованиям к самой спецификации. Понимаю, что звучит сложно, извините. ИИ именно проверяет саму спеку и пишет документ по результатам проверки. Такой подход даёт дополнительный уровень гарантий, что спека получится такой, какой её задумали создатели этого workflow. Про чек-листы подробнее — позже.

Внутри spec.md мы увидим несколько секций: User Scenarios & Testing (сценарии в Gherkin-формате), Requirements, Success Criteria и, возможно, Assumptions (если используем стандартный workflow).

Поддержка OpenIDE для Spec Kit пока слабее, чем для OpenSpec: нужные команды придётся дёргать самим через агента. Что в целом не страшно. А вот механизм ревью вам доступен. Спеки генерируются в папке specs/ с порядковым номером фичи. Вы можете привычным механизмом код-ревью оставить замечания прямо по спецификации и попросить агента поправить их в свободной форме — он подтянет ваши комментарии и внесет изменения.

Конечно, создание спеки агентом совсем не гарантирует, что она корректна. У Spec Kit есть специальный скилл /speckit.clarify, чтобы эту спеку почелленджить: он настроен искать места, которые спека не покрывает. Что ж, это всяко дешевле, чем ставить агента на ночь генерировать код, — так что не пренебрегаем.

Spec Kit plan

После того как спеку отревьюили и уверены, что она полностью отражает наше намерение, наступает этап планирования. /speckit.plan работает в две фазы и создает сразу несколько артефактов. Первая фаза — ресерч: создаётся research.md, где агент старается закрыть оставшиеся открытые вопросы. Вторая фаза — техническая проектная документация: доменная модель, контракты интерфейсов (отдельной папкой contracts/) и даже quickstart.md для проверки фичи.

Но ещё раз обращу внимание: всё в ваших силах настроить под себя. Поведение команды описано в .specify/templates/plan-template.md:

specs/[###-feature]/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command — NOT created by /speckit.plan)

Не премину упомянуть, что OpenIDE отлично подойдёт для ревью всех этих документов и отправки их на доработку.

Конечно, главный файл во всём этом ворохе — plan.md. Но нет, он содержит не совсем то, что вы подумали. Это не список задач, а скорее верхнеуровневое описание реализации со ссылками на остальные документы. Я бы его вообще назвал не plan, а design. Если вы внимательно посмотрели на приведённый выше сниппет, то заметили там tasks.md, который эта команда не порождает. Идём дальше.

Spec Kit tasks

/speckit.tasks бьёт план на упорядоченный список конкретных задач. Будет создан тот самый tasks.md, и разбивка получится довольно подробная: несколько фаз, в каждой свои подзадачи, ссылки на User Story, пометки для задач, которые можно выполнять параллельно.

Мне тут добавить нечего, кроме напоминания про метафору карты и местность.

Spec Kit implement

Ну наконец мы доходим до написания кода. /speckit.implement запускает выполнение задач. Но перед этим прогоняются чек-листы, которым я до сих пор уделил не очень много объяснений. Давайте ещё раз, медленно: перед написанием кода выполняются чек-листы. Когда я впервые читал про эту функциональность, я думал, что это чек-листы, которые проверяют реализацию. Но нет — это чек-листы, которые проверяют спеку. Мы долго работали, сгенерировали ворох файлов, и теперь нужно убедиться, что то, что мы нагенерировали, — не bullshit.

Как это устроено под капотом. implement сканирует всю папку checklists/, по каждому файлу считает отмеченные и неотмеченные пункты и строит табличку PASS/FAIL. Если хоть один чек-лист неполный — команда останавливается и спрашивает: «продолжать всё равно? (yes/no)». По сути это единственная человеческая точка контроля перед тем, как агент уйдёт молотить весь tasks.md.

Чек-листы можно сгенерировать заранее командой /speckit.checklist, указав, что именно мы хотим проверифицировать: ux, security, api — что угодно. Идея у них у всех одна — это «unit-тесты для английского». То есть каждый пункт проверяет не код, а качество самих требований: заданы ли они полностью, однозначны ли, измеримы ли, нет ли противоречий. Например, не «проверь, что кнопка кликается», а «а в спеке вообще задано, что происходит, если картинка логотипа не загрузилась?».

Отдельно про тот checklists/requirements.md, что появляется сам ещё на шаге specify. Тут есть подвох: галочки в нём проставляет сам агент — он грейдит собственную спеку. Так что читать этот файл всё-таки стоит, но не как справку «всё хорошо», а как отчёт агента о самопроверке: смотреть в первую очередь на незакрытые пункты и на то, какие неясности он закрыл, сам за вас что-то додумав.

Конечно, мы в OpenIDE собираемся сделать пошаговое выполнение и для Spec Kit — но пока не сделали. Ревьюить придётся уже полный diff.

И последний вопрос: куда девается спека в Spec Kit после того, как мы её реализовали? Никуда. Она остаётся там же, где была, — в specs/<фича>/. Механизма архивирования не предусмотрено, аналога main-спек из OpenSpec тоже нет. То есть через полгода в specs/ у вас будет лежать пачка папок-снимков по фичам, а единого документа «как система устроена сейчас» из них одним взглядом не собрать.

Spec Kit: итоги

Что ж, как по мне, стандартный workflow довольно сложный и местами контринтуитивный. Вот эти самые чек-листы, которые оказываются unit-тестами для спеки. Или plan, который делает не совсем plan (я бы его скорее назвал design). Мне кажется, такие вещи не играют Spec Kit на руку. При этом у Spec Kit заметно больше возможностей для кастомизации. Но нужны ли они нам?

Что в итоге выбрать?

Обе методологии достаточно похожи и имеют много общего — и это неудивительно. Базовая идея одна: сначала распланируй, потом выполни. Обе в базовом workflow описывают требования в Gherkin и так далее. У обеих есть возможности расширения. При этом OpenSpec, при всей внешней простоте, имеет полезные шаги синхронизации и архивирования, которые позволяют хранить спецификацию, описывающую поведение системы на текущий момент. Похожий механизм можно, конечно, реализовать в Spec Kit самостоятельно — но вопрос: захотим ли мы это делать? Каких усилий это потребует, если достаточно просто взять OpenSpec?

Лично мне OpenSpec нравится больше: с одной стороны, его workflow кажется мне более полным, с другой — более простым. Именно поэтому мы поддержали его раньше, чем GitHub Spec Kit, — несмотря на то, что у второго больше звёздочек на GitHub.

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

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

OpenIDE Pro позволяет разрабатывать проекты на Java, Spring, Python, Go, PHP, JavaScript и TypeScript! А полноценный DB‑клиент, поддержка Docker и 300+ плагинов доступны абсолютно бесплатно в маркетплейсе. Пробуйте российскую IDE в деле и подписывайтесь на нас в Telegram или Max, чтобы не пропустить свежие обновления и полезные материалы.