Спецификации были мертвы. Да здравствуют спецификации!

Я ненавидел писать спецификации — код и есть лучшая спецификация. Ну, я так думал.

Я всегда был ленивым разработчиком — всегда очень много работал чтобы работать меньше. Я вообще считаю что хороший разработчик — это ленивый разработчик. Готовый потратить неделю чтобы автоматизировать день монотонной работы.

Написание спецификаций это ведь просто переписывание того что я и так уже знаю — код или уже написан или существует у меня в голове. Кому хочется писать одно и то же дважды? В конце концов — вот же есть код — тут английским, можно сказать, языком, чёрным по белому, написано что мы делаем. Да ещё и с подсветкой синтаксиса. А если повезло даже есть комментарии почему именно так делаем. Чего ещё надо то?

А потом ещё этот геморрой с тем где их хранить и почти невыполнимая задача поддерживать их в актуальном состоянии.

Потом пришёл Agile. Наверное не я один выдохнул с облегчением когда менеджеры все как один заявили «к чёрту спецификации, живём от спринта до спринта!».

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

Так я жил довольно долго. Пока не подсел на AI-assisted development. Первый раз попробовал в начале 2025 года — ерунда какая-то, подумал я. Интересная концепция, но пока что не то на что я готов тратить время и деньги. Потом вышел Клод с Opus/Sonnet 4.5 + много хайпа в Ютубе - решил попробовать ещё раз. И моя жизнь изменилась.

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

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

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

Хотя цена AI ничтожна по сравнению со стоимостью человеческого труда — она не нулевая. И для таких одиночек как я может быстро стать неподъёмной. Мы пока живём в золотой эре субсидированных токенов по подписке, но если вам случалось исчерпывать подписочные квоты, а задача горит и вы, по глупости, решались на «ок, заплачу за API usage» — вы знаете как это может быть больно/дорого.

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

Экономика интерпретации

Примерно через 2 недели использования AI-агентов я заметил что перестал открывать IDE. Это открытие меня немного удивило. Я достаточно хардкорный разработчик, и у меня даже есть полная подписка на все инструменты JetBrains за которую я плачу из своего кармана. И вот приходит AI, я плачу за IDE и при этом почти не открываю их - большую часть времени я теперь провожу в терминале.

И у меня возник вопрос — Я всё ещё разработчик или кто?

С момента появления индустрии программного обеспечения скорость написания кода и его качество были узким местом. У нас больше нет этого ограничения — мы можем генерировать много кода, и делать это быстро. При должном умении и дисциплине он даже будет лучше (гораздо) чем в среднем по больнице. Надо «всего лишь» сказать/объяснить чего мы хотим и, возможно, как это должно быть сделано.

Бутылочное горлышко переползает вверх:

• Как держать AI загруженным? Как успевать ставить задачи?
• Как задавать условия проверки и проверять результат от AI?

Я называю это экономикой интерпретации. Дефицитный ресурс — больше не код. AI-агенты генерируют его быстро и дёшево. Дефицитный ресурс — ясно выраженное намерение.

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

Когда-то test-driven development изменил то как мы пишем ПО. Теперь мы наблюдаем следующий сдвиг — Intent-Driven Development (разработка на основе намерений). Это не вайб кодинг — слишком неструктурированно, нет повторяемости. И не водопадные 40-страничные PRD — слишком негибко, устаревают до конца спринта. Это точное выражение намерения в форме которую AI-агенты могут надёжно потреблять и превращать в работающий код.

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

В контексте работы с AI постановка задачи состоит из двух частей:

1. Описание новой проблемы (и, опционально, пути решения)
2. Предоставление контекста существующей системы для новой проблемы.

Если ограничиться только №1 то получишь тот самый вайб кодинг который мы все так любим и ненавидим - идеально для красивых демок и быстрых прототипов.

Знакомо? Мне — очень.

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

Казалось бы в чём проблема? У нас же есть код и, допустим, документация на проект. Ведь AI всегда может посмотреть то что у нас есть, понять и добавить/поправить как мы просим. Так?

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

Принципы хорошо организованного кода и хорошо структурированной документации универсальны и помогают работать и людям и AI-агентам. Они просты и хорошо известны:

• Декомпозиция на модули и компоненты
• Единая ответственность (single responsibility)
• Иерархичная структура (директории, наследование, композиция)
• Чёткие интерфейсы и контракты между компонентами
• Именование, отражающее назначение (self-documenting code)

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

В документации ситуация немного другая — более разнообразная. Кто-то использует Wiki, кто-то Confluence, кто то Word-документы на SharePoint.

Это лучше чем ничего, но у всех этих подходов есть проблемы. Такие как:

• Рассинхронизация с кодовой базой
• Необходимость поддерживать инфраструктуру
• Проблемы версионирования
• Нет связи между документацией и конкретным кодом
• Сложность для AI-агентов получить доступ (за пределами репозитория)

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

У такого подхода следующие достоинства:

• Синхронизирован с кодом — документация версионируется вместе с кодом
• Код может надёжно ссылаться на документацию, и наоборот
• Может использовать PR для процесса review & approve
• AI-агенты имеют прямой доступ без дополнительных интеграций
• Работает оффлайн, не зависит от внешних сервисов

Но это ответ на вопрос «где стоит хранить требования и документацию?» А ведь ещё есть и вопрос «Как её хранить?»

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

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

Дом построим — будем жить!

После 30 лет карьеры разработчика + месяца с AI-агентами я довольно точно знал чего я хочу.

На высоком уровне у меня было всего одно желание:

• Чтобы формат и инструменты помогали и мне и AI-агентам восстанавливать контекст быстро и эффективно. То есть чтобы:
  • Я мог вспомнить/понять что же я тут напридумывал 2-3 месяца назад.
  • Чтобы агент меньше жрал токенов и работал быстрее.

Вот что мне для этого было нужно:

• Главные принципы:
  • Необходимость и достаточность — как в математике.
  • Прогрессивная загрузка — каждый уровень (директория) должен иметь суммарный README.md
• Строгий формат который можно прогнать через линтер:
  • Какие секции должны быть обязательными, какие опциональными, какие заголовки, что выносить во frontmatter.
  • Как документы ссылаются друг на друга.
  • Какие статусы разрешены и как они изменяются.
• Понятная система ссылок между документами и кодом — как внутри репозитория так и на внешние ресурсы.
• Иерархичность — модули и фичи верхнего уровня разбиваются на подмодули и подфичи.
• Возможность запрашивать данные как из базы данных (наложить фильтр; узнать статус; дерево вверх/вниз/соседи; и т.п.)

Я попытался найти что-то готовое и самое близкое что я нашёл был OpenSpec — A lightweight spec-driven framework. Хороший проект с правильной идеей: простой, лёгкий в установке, с поддержкой AI-агентов из коробки. Но для моих запросов он оказался слишком «лайтовым»:

• Нет линтинга содержимого спецификаций — валидация проверяет только наличие файлов и структуру папок, но не качество самих спеков. Нечёткие формулировки, пропущенные критерии приёмки, битые ссылки — всё это проходит мимо.
• Нет метаданных на спецификациях — ни статуса, ни жизненного цикла, ни владельца, ни зависимостей. Нет frontmatter вообще.
• Нет идентификаторов у требований — всё ссылается по заголовкам, что ломается при переименовании.
• Нет связи код↔спецификация — невозможно спросить «какой код реализует это требование?»
• Нет иерархии — спецификации плоские по доменам, без подфич и зависимостей между спеками.

Изначально я просто начал писать AI-скил и спецификацию для формата «фич». Но каюсь — увлёкся. И вот получился SpecScore, а я пишу эту статью на Хабр.

Что такое SpecScore

SpecScore.md — это открытый стандарт markdown и YAML документов для описания систем и управления изменениями. MIT-лицензия, git-native, никакого SaaS. Ваши спецификации живут в вашем репозитории рядом с кодом (или в специально выделенном репозитории).

Формат определяет типизированные документы с чётким жизненным циклом:

• Идеи (Ideas) — пре-спек одностраничники: Draft → Under Review → Approved → Specifying → Specified → Implementing → Implemented
• Фичи (Features) — полноценные спецификации с требованиями и критериями приёмки: Draft → Under Review → Approved → Implementing → Stable → Deprecated
  • Требования
  • Критерии приёмки
  • Открытые вопросы
• Планы (Plans) — мост от спецификации к реализации: задачи привязанные к конкретным критериям приёмки
• Сущности (Entities) — типизированные определения бизнес-объектов (User, Order, Money) с валидируемыми свойствами. Фичи ссылаются на сущности — а не описывают данные в свободной форме
• Решения (Decisions) — ADR: какой выбор сделан, почему, какие альтернативы отвергнуты, какие последствия наблюдаем. Неизменяемы после принятия — отменить можно только новым решением
• Сценарии (Scenarios) — Given/When/Then поведенческие тесты

Каждый документ имеет frontmatter (статус, владелец, зависимости), именованные требования (REQ: slug), и обязательные секции проверяемые линтером.

specscore CLI

Поверх стандарта — CLI написанный на Go. Линтит, запрашивает и навигирует спек-дерево прямо из терминала.

Бесплатный и open source: github.com/specscore/specscore-cli.

$ specscore feature tree
cli
	code
		deps
	event
		emit
	feature
		change-status
		deps
		info
		list
		...
	idea
		change-status
		new
		relocate
	spec
		lint
			issue-rules
			plan-rules
	task
		info
		list
		new

$ specscore spec lint
spec/features/checkout/README.md:
  WARN  missing-ac: requirement REQ:validate-cart has no acceptance criteria
  ERR   vague-verb: "handle errors appropriately" — use a specific verb
spec/features/payments/README.md:
  ERR   broken-ref: depends-on "checkout" references unknown feature

3 violations found (2 errors, 1 warning)

Почему Go? Потому что CLI нужен быстрый, нативный, и без зависимостей:

• Быстрая компиляция — короткий цикл обратной связи при разработке.
• Горутины — линтинг это чтение, парсинг и анализ множества файлов параллельно. Go для этого создан.
• Изолированные пакеты — отлично ложатся на тестирование (кстати, у specscore CLI 100% покрытие тестами).
• Кросс-платформенная компиляция в один бинарник — без JVM, без Node.js.
• Дружелюбен к open source сообществу.

Ну не руками же их писать

Кроме стандарта и CLI существуют 2 набора скилов для specification-driven development:

1. ai-plugin-specscore — тонкая обёртка вокруг команд CLI. Детерминированные, предсказуемые. Для тех кто хочет интегрировать SpecScore в свой собственный рабочий процесс.
2. SpecStudio Skills — полноценный цикл разработки: ideate → specify → plan → implement → verify → recap. Опинионированный рабочий процесс поверх SpecScore для тех кто хочет получить готовое решение «из коробки».

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

✅ Feature "user-notifications" specified and lint-clean.

   4 requirements, 11 acceptance criteria, 0 open questions.
   Artifact: spec/features/user-notifications/README.md

The feature is ready for planning. What would you like to do?

 1. /plan — break into tasks with AC traceability
 2. Review the spec — I'll walk you through each requirement
 3. Edit — tell me what to change
 4. Something else

SpecStudio Skills — не конкурент Superpowers, agent-skills или GitHub Spec Kit, а коллега. Скилы описывают как агент работает. Спеки описывают что он должен построить. Разные слои — и SpecStudio может использовать Superpowers и agent-skills внутри, а сам внедряться как расширение в Spec Kit. Можно (и нужно) использовать SpecStudio Skills и сами по себе — они заточены под SpecScore.

Проверено на себе

SpecScore специфицирован в SpecScore — спек-дерево описывает само себя и specscore-cli. Я также использую SpecScore для своих других открытых проектов — inGitDB, DALgo, и других.

CLI имеет 100% покрытие тестами. Не потому что я такой дисциплинированный — а потому что со структурированными спеками и AI-агентами у вас просто нет оправданий этого не делать. Это реально экономит время и повышает качество.

Попробовать

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

Проект на ранней стадии. Я пока один. Строю публично. Бенчмарков по экономии токенов пока нет — я хочу реальные данные от пользователей, а не придуманные цифры. Стандарт будет эволюционировать.

Если вы работаете с Claude Code — самый простой и продуктивный способ попробовать spec-driven development — установить SpecStudio Skills:

/plugin marketplace add specscore/ai-marketplace
/plugin install specstudio@specscore

Два шага — и у вас полный цикл spec-driven development: ideate → specify → plan → implement → verify. CLI ставится автоматически. Если вы не используете Claude Code — есть и другие способы установки.

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

Я строю это потому что мне самому это нужно. Если вам тоже — буду рад.

P.S.

Кстати, если кто-то думает что с AI станет проще то это, на мой взгляд, не так.

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

Хорошие спецификации сделают вашу жизнь немного легче.