SpecScore vs Plain Markdown
У большинства команд уже есть «спецификации» — в виде разрозненного Markdown в папке с документацией, страниц Notion или тикетов Jira. Это бесплатно, это уже на месте и это работает. SpecScore — это тот же Markdown, плюс структура, которую ИИ-агент может линтовать, запрашивать и прослеживать обратно к коду.
Что у них общего.
В чём силён вариант по умолчанию.
Plain Markdown, Notion и Jira — это настоящий вариант по умолчанию. И не зря.
Нулевой порог входа
Нет схемы, нет обязательных полей, нет CLI в цепочке. Откройте файл и начните печатать. Для разовой заметки или крошечного проекта это именно то, что нужно — структура, которая вам не нужна, — это просто трение.
Уже установлено
Ваша команда уже в Notion, Confluence или папке docs/. Нечего внедрять, нечего мигрировать. Вариант с наименьшим трением — тот, которым вы уже пользуетесь.
Универсально переносим
Plain Markdown открывается где угодно и переживёт любой инструмент. SpecScore построен именно на этом свойстве — поэтому SpecScore тоже Markdown, а не база данных.
Сравнение возможностей.
Разница не в файле — а в том, что агент может с ним сделать.
| Возможность | Plain Markdown / Notion | SpecScore |
|---|---|---|
| Формат | Свободный Markdown / документация | Markdown + YAML frontmatter (структурированный) |
| Где живут требования | Jira, Notion, Slack, в чьей-то голове | В репозитории, рядом с кодом |
| «Полна ли эта спецификация?» | Человек читает и решает | specscore lint — автоматически |
| Выявление неоднозначности | Нет — расплывчатые глаголы проходят молча | Расплывчатые глаголы, отсутствующие критерии приёмки, висячие ссылки помечаются |
| ID требований / критериев приёмки | Нет | Машинно-адресуемые ID (REQ: slug) |
| Статус жизненного цикла | Неявный, если вообще отслеживается | Контролируемый — Draft → Approved → Implementing → Stable |
| Трассируемость кода к спецификациям | Нет | specscore: аннотации + Verifies: трейлеры |
| Навигация для агента | Читать каждый файл, чтобы что-то найти | Запрос к графу спецификаций из CLI |
| Гейт качества в CI | Нет | specscore lint завершается с ненулевым кодом, как линтер |
| Порог входа | Нулевой | Формат, который надо изучить (постепенно) |
| Стоимость / лицензия | Бесплатно | Бесплатно, открытый код |
В чём SpecScore идёт дальше.
Неоднозначность ловится, а не интерпретируется
При свободных спецификациях каждое взаимодействие с агентом начинается с интерпретации — «логин должен работать» — это подброс монетки между «верно» и «правдоподобно, но неверно». lint в SpecScore помечает расплывчатый глагол и отсутствующий критерий приёмки до того, как агент начнёт действовать.
$ specscore lint auth/login.md ✗ R1 "should work" — unmeasurable ✗ R1 no acceptance criteria
Неверная интерпретация перестаёт накапливаться
Один агент неправильно прочитал требование, второй строит на нём, третий зависит от обоих — и вы замечаете это тремя агентами позже. Структурированные критерии приёмки дают каждому агенту одинаковые условия прохождения/непрохождения, так что интерпретация не дрейфует между ними.
Код прослеживается до спецификации
У обычной документации нет связи с кодом, который её реализует. SpecScore добавляет аннотации specscore: в исходниках и трейлерыVerifies: в коммитах — specscore code refs отвечает на вопрос «какой код реализует это требование?» детерминированно.
Одна спецификация вместо сорока тикетов
Новый коллега (или свежий агент) читает одну спецификацию функции со всем контекстом, вместо того чтобы реконструировать намерение из сорока тикетов Jira и треда в Slack.
Агенты запрашивают, а не перечитывают
В папке с документацией поиск «что в работе?» означает открытие файлов. В SpecScore это specscore feature list — граф спецификаций отвечает из CLI, так что агенты не сжигают контекст на перечитывание репозитория.
Качество контролируется в CI
У свободных спецификаций нет гейта — недописанная сливается так же легко, как и полная. specscore lint завершается с ненулевым кодом при проблемах, так же как ESLint или go vet охраняют код.
Когда что использовать.
Plain Markdown подходит, когда…
- Это разовая заметка, эксперимент или проект, слишком маленький, чтобы нуждаться в структуре.
- Ни один ИИ-агент не будет строить по документу — человек читает его и просто понимает.
- Вы фиксируете грубую идею, а не требование, которое кто-то будет реализовывать.
Берите SpecScore, когда…
- ИИ-агент строит по спецификации — неоднозначность превращается в неверный код.
- Несколько агентов или людей зависят от одних и тех же требований.
- Вам нужно знать, какой код реализует какое требование.
- На вопрос «готова ли эта спецификация?» должен отвечать инструмент, а не совещание.
- Проект достаточно велик, чтобы перечитывание всего не масштабировалось.
Дорастите спецификации, которые у вас уже есть.
Вы не конвертируете свой бэклог и не меняете инструменты. Выберите следующую функцию, напишите для неё спецификацию SpecScore и запуститеspecscore lint — посмотрите, поймает ли он то, что упустил ваш тикет. Добавьте аннотации specscore:, когда будете реализовывать. Расширяйтесь на следующий спринт только если это помогло.
Plain Markdown — это въезд на эстакаду. SpecScore — это то, во что он вырастает.
Обратная связь
Это сравнение основано на публично доступной документации и исходном коде. Что-то неверно или устарело? откройте issue с исправлением. Хотите, чтобы мы сравнили SpecScore с другим инструментом? запросите его.