Каждая неоднозначность в спецификации
это токен, который сжигает ваш агент.

Что идёт не так без него.

• 🌀 Спецификации устаревают.

  Спека в документе, тред в Slack и код в PR молча расходятся неделями. Никто не может найти, какая версия разговора каноническая.

  Решение

  Одна каноническая спека в репозитории, версионируется вместе с кодом. specscore lint запускается в CI на каждый push; git-история — это аудит-трейл. Спека, тред и PR не могут молча разойтись — это один и тот же файл под ревью.

• 🌫️ Критерии расплываются.

  "Обрабатывает ошибки корректно" должно было означать "показать тост и откатить." Или"логировать и повторить?" Агенту приходится гадать.

  Решение

  Линтер ловит размытые критерии до того, как написана хоть строчка кода. Глагол не проходит линт, потому что у него нет конкретного объекта и условия. Чтобы убрать предупреждение, приходится сформулировать, что значит"обрабатывает".

• 🤖 Агенты делают не то.

  Люди интерполируют, уточняют, спрашивают. ИИ-агенты — нет. Они реализуют тот паттерн, который чаще всего встречался в их обучающих данных. Код проходит ревью, потому что делаетчто-то разумное. Просто не то, что вы имели в виду.

  Решение

  Структурированный вход. ИИ-агенты парсят REQ-ID, AC-ID и сценарииGIVEN / WHEN / THENдетерминированно — интерполировать нечего. Каждая задача Plan обязана сослаться на AC-ID, которые она удовлетворяет: сделанное всегда сверяемо со специфицированным.

• 🔁 За расплывчатую спецификацию вы платите дважды.

  Агент что-то собирает по нечёткому заданию, вы видите, что это не то, и переформулируете запрос — четырьмя разными способами. Каждая недоделанная функция и каждая повторная попытка оплачиваются токенами. Чем расплывчатее спецификация, тем больше кругов до результата.

  Решение

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

• 💸 Агенты платят за повторное чтение спецификаций.

  ИИ-агент, отвечающий на вопрос "что зависит от этой фичи?", читает весь README фичи. Потом каждый родительский индекс. Потом соседние фичи на всякий случай. Каждый запрос — новый парсинг. Токены сгорают; латентность растёт; счёт растёт вместе с ними.

  Решение

  Структурированные запросы вместо чтения файлов.specscore feature tree возвращает иерархию как YAML; feature deps обходит транзитивные зависимости; feature info показывает статус, владельца и открытые вопросы — каждая команда за один вызов. Агент навигирует по графу, а не по прозе.

• 🔗 Код забывает свою спецификацию.

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

  Решение

  Аннотации в исходниках. Комментарии вида// specscore: features/checkout/apply-discount/R1.AC-2делают связь машиночитаемой и переживают любой рефакторинг.specscore code deps отвечает на вопрос"какую спеку реализует этот файл?" за один вызов; линтер помечает ссылки на удалённые спецификации.

• 🏷️ Изменения статуса утекают.

  Ты переводишь фичу из Draft в Approvedв её README, но родительский features-index всё ещё показывает её как Draft. Через три недели агент, читающий индекс, думает, что фича всё ещё в работе. Статус живёт в двух местах, и они расходятся.

  Решение

  specscore feature change-status переписывает поле Status фичи и пересинхронизирует строку в features-index одной атомарной операцией — при сбое линта изменение откатывается. Статус существует в одном каноническом месте; индекс — это его сгенерированное представление.

• 📋 Спецификации забывают то, чего не знают.

  Спека читается как готовая — пока ты не вспоминаешь, что вопрос "а что с часовыми поясами?" потерялся в треде Slack два месяца назад и так и не попал в документ. Теперь вы в реализации, и никто не может сказать, каким был ответ.

  Решение

  У каждой SpecScore-фичи обязательная секцияOutstanding Questions. Линтер отвергает фичи, в которых её нет — пусто можно ("None at this time."), но отсутствие — нельзя. Нерешённые вопросы видны в документе, доступны из CLI и их невозможно забыть.