Управління специфікаціями: зберігати, версіонувати й рецензувати специфікації як код
Управління специфікаціями — це те, як команда зберігає специфікацію програмного забезпечення, записує кожну зміну, рецензує цю зміну і тримає специфікацію актуальною. Управління специфікацією — та сама робота: специфікація є документом, який каже, що мусить робити програмне забезпечення, а керувати нею — це те, як документ лишається таким, що його можна знайти, і гідним довіри. Вести специфікації як код означає, що ці документи є файлами в системі контролю версій, тож зміна специфікації — це commit, який рецензент може порівняти. Версіонування специфікацій — це історія цих commit разом зі статусом, записаним у кожному документі. Тримати специфікації синхронними з кодом означає, що запропонована зміна, яка ламає структуру специфікації, провалює ту саму автоматичну перевірку, крізь яку проходить зміна коду. Розробка за специфікаціями (SDD, spec-driven development) — практика писати специфікацію до коду і вважати специфікацію джерелом правди. Безперервна інтеграція (CI, continuous integration) — автоматична перевірка кожної запропонованої зміни. Документ вимог до продукту (PRD, product requirements document) — проза, яка формулює проблему і межі; шаблон PRD у Markdown — це один файл функції SpecScore такої форми. Easy Approach to Requirements Syntax (EARS) — шаблон речення для вимоги. У SpecScore вимога (REQ) — іменоване правило всередині функції, а критерій приймання (AC, acceptance criterion) — необов’язкова абстрактна умова, яка вказує на одне або кілька таких правил. Перевірка — це команда інтерфейсу командного рядка (CLI, command-line interface), specscore spec lint, описана в лінтувати специфікації в CI. Формат живе в публічному репозиторії specscore/specscore (CC BY 4.0). CLI живе в specscore/specscore-cli (Apache-2.0).
Оновлено: 9 листопада 2026
Де зберігається специфікація
Управління специфікаціями починається з місця, де можуть жити файли. У цьому репозиторії специфікація — це Markdown під spec/. README специфікації перелічує каталоги: функції, плани, ідеї, рішення й уроки. Функція — це один каталог із README.md. Специфікація функції є контрактом цього файла, а шаблон PRD — заповнений приклад, який прийняв лінтер.
specscore spec lint не вгадує, яке дерево читати. internal/cli/spec.go на тегу v0.55.1, і та сама функція на тегу v0.39.1, іде вгору від робочого каталогу, доки не знайде specscore.yaml. Коментар тієї функції каже, що команда вимагає цей файл, повертає код виходу 3, коли його немає, і каже виконати specscore init. Воркфлоу dogfood цього репозиторію встановлює CLI v0.39.1, а потім виконує specscore spec lint, тож checkout, який він лінтує, має цей файл конфігурації.
Поруч із файлами функцій стоїть індекс. Правило feature-index-row-sync є помилкою в каталозі lint v0.39.1 і v0.55.1. Рядок каталогу каже, що воно вимагає, щоб кожен рядок індексу функцій збігався зі своїм файлом функції. Це індекс, узгоджений із документом, на який він вказує. Це не порівняння формулювання вимоги з файлом вихідного коду.
Версіонування специфікацій
Версіонування специфікацій, для файлів, які закомічено в git, — це історія commit цих файлів. SpecScore не додає другий номер версії до функції. Ревізія, на яку дивиться рецензент, — це commit на гілці. Рядок статусу в документі каже, де ця функція перебуває у своєму життєвому циклі, а це інший факт, ніж хеш git.
Сама специфікація функції в репозиторії має **Status:** Stable. Вона вимагає рядок **Status:** одразу після заголовка, і значення мусить бути одним із Draft, In Review, Approved, Implementing, Stable, Amending, Rejected або Deprecated. Правило status-mirror, в обох названих вище каталогах, вимагає, щоб status: у frontmatter артефакту зі статусом збігався з тим рядком тіла, і забороняє status: на типі, який не має статусу. Зіставити дві копії — не те саме, що відхилити слово поза вісьмома значеннями. Жоден із двох рядків каталогу не описує правила, яке відхиляє статус функції поза цим набором, тож ця сторінка не стверджує, що таке правило є.
Плани використовують інший набір. Правило P-006, в обох каталогах, вимагає, щоб **Status:** у тілі плану з одного файла було одним із Draft, In Review, Approved, Executing, Blocked, Implemented, Failed, Rejected, Withdrawn, Superseded або Deprecated. Правило idea-status-values відхиляє статус ідеї поза набором, який дозволяє це правило. Каталог і є список. Ця сторінка не повторює слова ідей.
Ця специфікація плану також описує необов’язкову таблицю ## Snapshots зі стовпцями Date, Git Hash, Action і Comment. Вона каже, що кожен знімок посилається на хеш git commit стану плану в той момент. Два каталоги lint, перевірені для цієї сторінки, не називають правила, яке розв’язує цей хеш, тож ця сторінка не стверджує, що лінтер перевіряє, чи існує commit. Хеш — це вказівник, за яким людина може піти в git. Опублікована специфікація плану є сторінкою формату цього документа.
Рецензування специфікації
Рецензія специфікації в Markdown — це pull request, який її змінює. dogfood.yml виконується на pull_request і на push до main. Job робить checkout репозиторію, встановлює CLI з SPECSCORE_VERSION, рівним v0.39.1, і виконує specscore spec lint без додаткових флагів. GitHub Actions провалює крок, коли цей процес завершується ненульовим кодом. Дозволи воркфлоу — contents: read.
Статус функції In Review означає, що функцію подано на рецензію. Записати це слово — це редагування файла Markdown. Pull request — місце, де людина читає diff. status-mirror перевіряє, що frontmatter і тіло називають той самий статус. Він не фіксує, що рецензент погодився з прозою. Сторінка валідаторів відділяє цю структурну перевірку від читання, яке людина все ще мусить зробити. Пояснення правило за правилом того, про що повідомляє specscore spec lint, є в лінтувати специфікації в CI.
Тримати специфікації синхронними з кодом
Тримати специфікації синхронними з кодом, на цьому сайті, означає, що специфікація є в репозиторії разом із проєктом, і CI провалює pull request, коли дерево специфікації порушує формат. Pull request може змінити файл функції і код у тому самому diff. Правило feature-index-row-sync тримає рядок індексу узгодженим із файлом функції, який він називає. Воно не читає вихідний файл і не вирішує, чи код реалізує вимогу.
Уривок нижче — кроки встановлення і lint із dogfood.yml. Файл воркфлоу також задає дозволи, групу конкурентності і коментар про те, чому закріплення — не latest. Ці рядки тут опущено. Команди — ті, які виконує цей файл.
name: Dogfood lint
on:
push:
branches: [main]
pull_request:
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
- name: Install specscore CLI (pinned)
env:
SPECSCORE_VERSION: v0.39.1
run: |
curl -fsSL https://specscore.md/install/get-cli | \
SPECSCORE_INSTALL_DIR="$HOME/.local/bin" sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
specscore --version
- name: Lint spec tree
run: specscore spec lint
Коментар у тому файлі каже, що плаваюче закріплення latest змінює ворота під репозиторієм: pull request і гілка main, на яку він націлений, можуть бачити різні правила. Закріплення — v0.39.1. Job не передає --fix. Чистий запуск і запуск зі збоєм, включно з рядком file:line [severity] rule: message, показано в лінтувати специфікації в CI.
Речення специфікації, яке вже не описує код, не є одним із тих зауважень. specscore spec lint перевіряє структуру: обов’язкові файли й розділи, рядки індексу, форму заголовка і посилання, які називають правила. Він не оцінює, чи реалізація збігається з вимогою. Ця межа — сенс сторінки валідаторів. Тримати прозу правдивою й далі означає рецензію diff.
Як інші інструменти розробки за специфікаціями перевіряють специфікацію
Абзаци нижче використовують сторінки, отримані 9 листопада 2026 року. Вони описують власні перевірки тих інструментів. Вони не кажуть, скільки продуктів існує, і не ранжують ринок. Огляд інструментів — довше порівняння.
Цей довідник агентного SDD GitHub Spec Kit описує /speckit.analyze як перевірку лише для читання по spec.md, plan.md і tasks.md. Він повідомляє про конфлікти, прогалини й неоднозначності, ніколи не редагує файли, і його запускають в агенті до реалізації. Список команд тієї самої сторінки не описує job CI, який виконує specscore spec lint проти дерева SpecScore.
OpenSpec зберігає зміну як каталог безпосередньо під openspec/changes/. openspec validate перевіряє зміни і специфікації на структурні проблеми. Довідник каже, що код виходу 0 означає, що кожен перевірений елемент пройшов, а код виходу 1 означає, що елемент не пройшов, запит звіту недійсний, конфігурацію не можна прочитати або запуск не вдався. Ця перевірка — форма OpenSpec, включно з його блоками вимоги і сценарію, а не заголовок SpecScore ### AC:. В іншій команді, openspec status, той самий довідник каже, що пакет, який не може завантажити одну зміну, усе одно завершується кодом 1, “so CI doesn’t accept an incomplete report as successful.” Це речення — про openspec status, а не про openspec validate.
Питання й відповіді
Що таке управління специфікаціями?
Управління специфікаціями — це зберігання специфікації програмного забезпечення, запис кожної зміни, рецензія цієї зміни і те, що специфікацію тримають актуальною. У SpecScore файли — це Markdown у репозиторії git, а specscore spec lint — структурна перевірка, яку job CI може провалити.
Що таке управління специфікацією?
Управління специфікацією — та сама практика. Специфікація — документ, який каже, що мусить робити програмне забезпечення. Керувати нею означає, що документ має відоме місце, історію, рецензію і перевірку того, що його структура й далі збігається з форматом.
Як працює ведення специфікацій як коду?
Специфікація — це дерево файлів Markdown під spec/, плюс specscore.yaml у корені репозиторію. Зміна — це commit. Pull request рецензує diff. dogfood.yml виконує specscore spec lint на цьому pull request.
Як працює версіонування специфікацій?
Історія git — це історія версій файлів. Функція також несе **Status:** з одним із восьми значень, яких вимагає специфікація функції. План може записати рядок ## Snapshots, чий Git Hash є commit стану плану. Каталоги лінтера, цитовані тут, не описують правила, яке розв’язує цей хеш.
Як тримати специфікації синхронними з кодом?
Покладіть специфікацію в репозиторій і проваліть pull request, коли specscore spec lint повідомляє про структурне порушення, зокрема про рядок індексу, який не збігається зі своїм файлом функції. Команда не вирішує, чи код реалізує вимогу. Речення, яке відійшло від коду, і далі потребує, щоб людина прочитала diff.
Джерела
Файли CLI і каталоги lint прочитано 9 листопада 2026 року на тегах v0.39.1 specscore-cli (версія, яку встановлює dogfood.yml) і v0.55.1. Вимоги до функції і до плану — це файли, пов’язані нижче, у specscore/specscore. Сторінки конкурентів отримано того самого дня.
- specscore/specscore — spec/README.md
- specscore/specscore — значення статусу функції
- specscore/specscore — знімки плану
- specscore/specscore
- specscore/specscore — ліцензія CC BY 4.0
- specscore/specscore-cli
- specscore-cli — ліцензія Apache-2.0
- specscore-cli v0.39.1 — internal/cli/spec.go
- specscore-cli v0.55.1 — internal/cli/spec.go
- specscore-cli v0.39.1 — каталог правил lint
- specscore-cli v0.55.1 — каталог правил lint
- specscore/specscore — dogfood.yml (CLI v0.39.1)
- Що перевіряє SpecScore
- Лінтувати специфікації в CI лінтером специфікацій
- Синтаксис вимог EARS з поясненням і прикладами
- Як писати критерії приймання, які перевірить ШІ-агент
- Шаблон PRD у Markdown для програмування зі ШІ
- Специфікація функції
- Специфікація плану
- GitHub Spec Kit — довідник агентного SDD (/speckit.analyze)
- Довідник CLI OpenSpec — openspec validate і openspec status
- Fission-AI/OpenSpec
- Інструменти розробки за специфікаціями
Пов’язане
- Лінтувати специфікації в CI лінтером специфікацій
- Шаблон PRD у Markdown для програмування зі ШІ
- Як писати критерії приймання, які перевірить ШІ-агент
- Синтаксис вимог EARS з поясненням і прикладами
- Розробка за специфікаціями
- Інструменти розробки за специфікаціями
- Специфікація функції
- Специфікація плану
- CLI
- Що перевіряє SpecScore