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 — автоматично |
| Виявлення неоднозначності | Немає — нечіткі дієслова проходять непомітно | Нечіткі дієслова, відсутні критерії приймання, висячі посилання позначаються |
| Ідентифікатори вимог / критеріїв приймання | Немає | Машинно-адресовані ідентифікатори (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
Хибне тлумачення перестає накопичуватися
Один агент неправильно зрозумів вимогу, другий побудував на ній, третій залежить від обох — а ви помічаєте це три агенти потому. Структуровані критерії приймання дають кожному агенту однакові умови pass/fail, тож інтерпретація не дрейфує між ними.
Код простежується назад до специфікації
Звичайні документи не мають зв'язку з кодом, що їх реалізує. 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 з іншим інструментом? запросіть його.