Формат
Markdown + YAML. Працює в будь-якому редакторі, що відкриває текст. Жодних нових інструментів, щоб почати писати.
Кожна неоднозначність у специфікації
це токен, який спалює ваш агент.
Потім уточнювальне питання посеред розробки. Потім виправлення після релізу. Потім контекст, який ви пояснюєте знову і знову.
SpecScore — відкритий, лінтовний файловий формат для специфікацій, як JSON для даних. Із CLI, через який ваші агенти запитують і редагують їх — як jq для JSON.
Формат для специфікацій, які ви й так пишете.
SpecScore — це формат на основі Markdown + YAML для фіч, вимог і критеріїв приймання. Він задає структуру, зрозумілу і вашій команді, і вашим ШІ-агентам — і це просто файли у вашому репозиторії.
Проєкт SpecScore складається з трьох типів артефактів в єдиному життєвому циклі: Ідея фіксує напівсформований напрямок; Фіча заморожує узгоджену поведінку;План розкладає фічу на впорядковані завдання, кожне з яких посилається на критерії приймання, які воно задовольняє.
Чому це важливо для вашого агента. Оскільки структура машинозчитувана, ШІ-агенти можуть запитувати специфікацію через CLI, а не читати кожен файл. Запитайте«над чим мені працювати далі?» — і CLI поверне відкриті фічі та невирішені питання. Та сама форма, яку переглядає ваша команда; набагато менше контексту, який агенту треба завантажувати.
Специфікації ієрархічні. І ваше дерево специфікацій — теж.
Плаский список на п'ятдесятьох фічах перетворюється на смітник. SpecScore тримає дерево навігабельним: батьки володіють обсягом, діти — деталями, а форма директорій повторює форму продукту, про яку ваша команда вже міркує.
Відкриті питання спливають угору. Невирішені питання на будь-якій глибині з'являються в індексі кожного батька. Ви бачите, що блокує реліз, з вершини дерева — без потреби розкопувати, щоб їх знайти.
Більшість інструментів для специфікацій виходить із того, що плаский список працює. Працює — поки не перестає. SpecScore зроблений саме для того моменту, коли питання «а де живе ця фіча?» починає мати значення.
specscore-cli/spec/features/cli/spec/features/cli/
├── agent/
│ └── setup/
├── feature/
│ ├── change-status/
│ ├── deps/
│ ├── info/
│ ├── list/
│ ├── new/
│ ├── refs/
│ └── tree/
├── idea/
│ ├── change-status/
│ ├── new/
│ └── relocate/
├── spec/
│ └── lint/
│ ├── issue-rules/ ← під-під-фіча
│ └── plan-rules/
├── task/
│ ├── info/
│ ├── list/
│ └── new/
└── … ще 10 фіч верхнього рівняЩо йде не так без нього.
Специфікації застарівають.
Спека в документі, тред у 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 і їх неможливо забути.
Найпростіший спосіб почати: SpecStudio Skills для ШІ-агентів.
SpecStudio Skills — плагін для Claude Code, який перетворює життєвий цикл SpecScore на чотири slash-команди. Встановіть один раз, потім запускайте їх по порядку — від сирої ідеї до виконуваного плану.
$ /plugin marketplace add specscore/ai-marketplace $ /plugin install specstudio@specscore
Claude Codeавтодоповнення
> /specstudio: /specstudio:ideate Перетворити сиру ідею на SpecScore Idea /specstudio:specify Перетворити схвалену Idea на Feature-специфікацію /specstudio:plan Розкласти Feature на Plan із завдань /specstudio:implement Виконати наступне завдання з Plan
Безкоштовно для публічних та open-source репозиторіїв. Вихідний код плагіна —specscore/specstudio-skills, ліцензія MIT.
Перевірте специфікацію у два проходи.
Швидкий детермінований лінтер, а потім глибша AI-рецензія — запущені на специфікації, яку ви щойно бачили. Два проходи, два види впевненості.
Запустіть лінтер.
детермінований$ specscore lint apply-discount.md ✓ R1 has acceptance criteria ✓ R2 has acceptance criteria ✗ R3 no acceptance criteria ✗ link "Related Feature: discount-tiers" not found ✗ section "Open Questions" missing 3 problems exit 1
Однаковий результат при кожному запуску. Безкоштовно, швидко, працює на кожному коміті.
Рецензія та оцінка від AI.
недетермінований> /score apply-discount.md Grade: B — ready with edits AC-2 vague trigger — name the actor and event AC-3 no error path for an expired code prose reads clean; criteria need tightening
Читає за змістом, як живий рецензент.
Що в комплекті.
Лінтер
CLI на Go. Перевіряє структуру, посилання і повноту. Завершується з ненульовим кодом при помилці — працює в терміналі й у CI.
Жодних обов'язкових інструментів.
SpecScore — це просто файли у вашому репозиторії. Не потрібно реєструватися в SaaS. Не потрібен оркестратор. Використовуйте з Linear, Jira, GitHub Projects, сирими Markdown-файлами в теці — або взагалі без таск-трекера. Формату й лінтеру байдуже, де живуть ваші тікети.
Як SpecScore порівнюється з іншими.
Розробка на основі специфікацій — напрямок із сильною конкуренцією. Ось де SpecScore стоїть на тлі альтернатив — чесно.
Plain MarkdownСтандарт за замовчуванням. SpecScore — це те, до чого доростає ваш Markdown.OpenSpecНадійна відправна точка. SpecScore — це захисні бар'єри.Spec KitSpec Kit — це робочий процес. SpecScore — це артефакт.DatarimDatarim керує конвеєром. SpecScore — це те, що залишається після нього.CodeSpeakCodeSpeak робить ставку на компілятор. SpecScore робить ставку на формат.
Надаєте перевагу CLI?
Не використовуєте ШІ-агентів або потрібна валідація специфікацій у CI-пайплайні? Для цього є CLI. Встановлення за 60 секунд — без акаунта, без телеметрії, працює на будь-якій теці з Markdown-специфікаціями.
$ curl -fsSL https://specscore.md/install/get-cli | sh> irm https://specscore.md/install/get-cli.ps1 | iexЗапустіть лінтер на прикладі специфікації, що йде в комплекті:
$ specscore lint examples/checkout/apply-discount.mdВивід:
examples/checkout/apply-discount.md
✓ R1 has acceptance criteria
✓ R2 has acceptance criteria
✗ R3 no acceptance criteria
✗ link "Related Feature: discount-tiers" not found
✗ section "Open Questions" missing
3 problems exit 1Зроблено на SpecScore.
Codegrapher
Рушій графа коду для швидкого дослідження коду та двостороннього зв’язку між специфікаціями та кодом.
codegrapher.devDALgo
Шар доступу до даних на Go, специфікований за допомогою SpecScore.
dal-go.github.ioinGitDB
Версійна база даних на основі Git, специфікована за допомогою SpecScore.
ingitdb.comRehearse
Шар доказів приймання — насправді проганяє критерії приймання специфікації, з багаторазовими перевірками та без сполучного коду.
rehearse.inkSpecScore Studio
Вебінтерфейс для перегляду та редагування SpecScore-специфікацій.
specscore.studio