# Управління специфікаціями: зберігати, версіонувати й рецензувати специфікації як код

Canonical: https://specscore.md/uk/articles/spec-management/

Оновлено: 9 листопада 2026

Управління специфікаціями — це те, як команда зберігає специфікацію програмного забезпечення, записує кожну зміну, рецензує цю зміну і тримає специфікацію актуальною. Управління специфікацією — та сама робота: специфікація є документом, який каже, що мусить робити програмне забезпечення, а керувати нею — це те, як документ лишається таким, що його можна знайти, і гідним довіри. Вести специфікації як код означає, що ці документи є файлами в системі контролю версій, тож зміна специфікації — це commit, який рецензент може порівняти. Версіонування специфікацій — це історія цих commit разом зі статусом, записаним у кожному документі. Тримати специфікації синхронними з кодом означає, що запропонована зміна, яка ламає структуру специфікації, провалює ту саму автоматичну перевірку, крізь яку проходить зміна коду. [Розробка за специфікаціями](https://specscore.md/uk/spec-driven-development/) (SDD, spec-driven development) — практика писати специфікацію до коду і вважати специфікацію джерелом правди. [Безперервна інтеграція](https://specscore.md/uk/validators/) (CI, continuous integration) — автоматична перевірка кожної запропонованої зміни. Документ вимог до продукту (PRD, product requirements document) — проза, яка формулює проблему і межі; [шаблон PRD у Markdown](https://specscore.md/uk/articles/feature-spec-template/) — це один файл функції SpecScore такої форми. [Easy Approach to Requirements Syntax](https://specscore.md/uk/articles/ears-requirements/) (EARS) — шаблон речення для вимоги. У [SpecScore](https://specscore.md/) вимога (REQ) — іменоване правило всередині функції, а [критерій приймання](https://specscore.md/uk/articles/acceptance-criteria/) (AC, acceptance criterion) — необов’язкова абстрактна умова, яка вказує на одне або кілька таких правил. Перевірка — це команда [інтерфейсу командного рядка](https://specscore.md/uk/cli/) (CLI, command-line interface), `specscore spec lint`, описана в [лінтувати специфікації в CI](https://specscore.md/uk/articles/lint-specs-in-ci/). Формат живе в публічному репозиторії [specscore/specscore](https://github.com/specscore/specscore) ([CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE)). CLI живе в [specscore/specscore-cli](https://github.com/specscore/specscore-cli) ([Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE)).

## Де зберігається специфікація

Управління специфікаціями починається з місця, де можуть жити файли. У цьому репозиторії специфікація — це Markdown під `spec/`. [README специфікації](https://github.com/specscore/specscore/blob/main/spec/README.md) перелічує каталоги: функції, плани, ідеї, рішення й уроки. Функція — це один каталог із `README.md`. [Специфікація функції](https://specscore.md/feature-specification) є контрактом цього файла, а [шаблон PRD](https://specscore.md/uk/articles/feature-spec-template/) — заповнений приклад, який прийняв лінтер.

`specscore spec lint` не вгадує, яке дерево читати. [internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/internal/cli/spec.go) на тегу v0.55.1, і та сама функція на [тегу v0.39.1](https://github.com/specscore/specscore-cli/blob/v0.39.1/internal/cli/spec.go), іде вгору від робочого каталогу, доки не знайде `specscore.yaml`. Коментар тієї функції каже, що команда вимагає цей файл, повертає код виходу 3, коли його немає, і каже виконати `specscore init`. [Воркфлоу dogfood](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) цього репозиторію встановлює CLI v0.39.1, а потім виконує `specscore spec lint`, тож checkout, який він лінтує, має цей файл конфігурації.

Поруч із файлами функцій стоїть індекс. Правило `feature-index-row-sync` є помилкою в каталозі lint [v0.39.1](https://github.com/specscore/specscore-cli/blob/v0.39.1/docs/lint-rules.md) і [v0.55.1](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md). Рядок каталогу каже, що воно вимагає, щоб кожен рядок індексу функцій збігався зі своїм файлом функції. Це індекс, узгоджений із документом, на який він вказує. Це не порівняння формулювання вимоги з файлом вихідного коду.

## Версіонування специфікацій

Версіонування специфікацій, для файлів, які закомічено в git, — це історія commit цих файлів. SpecScore не додає другий номер версії до функції. Ревізія, на яку дивиться рецензент, — це commit на гілці. Рядок статусу в документі каже, де ця функція перебуває у своєму життєвому циклі, а це інший факт, ніж хеш git.

Сама [специфікація функції в репозиторії](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md) має `**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` відхиляє статус ідеї поза набором, який дозволяє це правило. Каталог і є список. Ця сторінка не повторює слова ідей.

Ця [специфікація плану](https://github.com/specscore/specscore/blob/main/spec/features/plan/README.md) також описує необов’язкову таблицю `## Snapshots` зі стовпцями Date, Git Hash, Action і Comment. Вона каже, що кожен знімок посилається на хеш git commit стану плану в той момент. Два каталоги lint, перевірені для цієї сторінки, не називають правила, яке розв’язує цей хеш, тож ця сторінка не стверджує, що лінтер перевіряє, чи існує commit. Хеш — це вказівник, за яким людина може піти в git. Опублікована [специфікація плану](https://specscore.md/plan-specification) є сторінкою формату цього документа.

## Рецензування специфікації

Рецензія специфікації в Markdown — це pull request, який її змінює. [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/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 і тіло називають той самий статус. Він не фіксує, що рецензент погодився з прозою. [Сторінка валідаторів](https://specscore.md/uk/validators/) відділяє цю структурну перевірку від читання, яке людина все ще мусить зробити. Пояснення правило за правилом того, про що повідомляє `specscore spec lint`, є в [лінтувати специфікації в CI](https://specscore.md/uk/articles/lint-specs-in-ci/).

## Тримати специфікації синхронними з кодом

Тримати специфікації синхронними з кодом, на цьому сайті, означає, що специфікація є в репозиторії разом із проєктом, і CI провалює pull request, коли дерево специфікації порушує формат. Pull request може змінити файл функції і код у тому самому diff. Правило `feature-index-row-sync` тримає рядок індексу узгодженим із файлом функції, який він називає. Воно не читає вихідний файл і не вирішує, чи код реалізує вимогу.

Уривок нижче — кроки встановлення і lint із [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml). Файл воркфлоу також задає дозволи, групу конкурентності і коментар про те, чому закріплення — не `latest`. Ці рядки тут опущено. Команди — ті, які виконує цей файл.

### Кроки встановлення і lint з dogfood.yml

```yaml
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](https://specscore.md/uk/articles/lint-specs-in-ci/).

Речення специфікації, яке вже не описує код, не є одним із тих зауважень. `specscore spec lint` перевіряє структуру: обов’язкові файли й розділи, рядки індексу, форму заголовка і посилання, які називають правила. Він не оцінює, чи реалізація збігається з вимогою. Ця межа — сенс [сторінки валідаторів](https://specscore.md/uk/validators/). Тримати прозу правдивою й далі означає рецензію diff.

## Як інші інструменти розробки за специфікаціями перевіряють специфікацію

Абзаци нижче використовують сторінки, отримані 9 листопада 2026 року. Вони описують власні перевірки тих інструментів. Вони не кажуть, скільки продуктів існує, і не ранжують ринок. [Огляд інструментів](https://specscore.md/uk/spec-driven-development/tools/) — довше порівняння.

Цей [довідник агентного SDD GitHub Spec Kit](https://github.github.io/spec-kit/reference/agentic-sdd.html) описує `/speckit.analyze` як перевірку лише для читання по `spec.md`, `plan.md` і `tasks.md`. Він повідомляє про конфлікти, прогалини й неоднозначності, ніколи не редагує файли, і його запускають в агенті до реалізації. Список команд тієї самої сторінки не описує job CI, який виконує `specscore spec lint` проти дерева SpecScore.

[OpenSpec](https://github.com/Fission-AI/OpenSpec) зберігає зміну як каталог безпосередньо під `openspec/changes/`. [openspec validate](https://openspec.dev/docs/cli) перевіряє зміни і специфікації на структурні проблеми. Довідник каже, що код виходу 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](https://github.com/specscore/specscore/blob/main/.github/workflows/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](https://github.com/specscore/specscore/blob/main/spec/README.md)
- [specscore/specscore — значення статусу функції](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md)
- [specscore/specscore — знімки плану](https://github.com/specscore/specscore/blob/main/spec/features/plan/README.md)
- [specscore/specscore](https://github.com/specscore/specscore)
- [specscore/specscore — ліцензія CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE)
- [specscore/specscore-cli](https://github.com/specscore/specscore-cli)
- [specscore-cli — ліцензія Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE)
- [specscore-cli v0.39.1 — internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.39.1/internal/cli/spec.go)
- [specscore-cli v0.55.1 — internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/internal/cli/spec.go)
- [specscore-cli v0.39.1 — каталог правил lint](https://github.com/specscore/specscore-cli/blob/v0.39.1/docs/lint-rules.md)
- [specscore-cli v0.55.1 — каталог правил lint](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md)
- [specscore/specscore — dogfood.yml (CLI v0.39.1)](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml)
- [Що перевіряє SpecScore](https://specscore.md/uk/validators/)
- [Лінтувати специфікації в CI лінтером специфікацій](https://specscore.md/uk/articles/lint-specs-in-ci/)
- [Синтаксис вимог EARS з поясненням і прикладами](https://specscore.md/uk/articles/ears-requirements/)
- [Як писати критерії приймання, які перевірить ШІ-агент](https://specscore.md/uk/articles/acceptance-criteria/)
- [Шаблон PRD у Markdown для програмування зі ШІ](https://specscore.md/uk/articles/feature-spec-template/)
- [Специфікація функції](https://specscore.md/feature-specification)
- [Специфікація плану](https://specscore.md/plan-specification)
- [GitHub Spec Kit — довідник агентного SDD (/speckit.analyze)](https://github.github.io/spec-kit/reference/agentic-sdd.html)
- [Довідник CLI OpenSpec — openspec validate і openspec status](https://openspec.dev/docs/cli)
- [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- [Інструменти розробки за специфікаціями](https://specscore.md/uk/spec-driven-development/tools/)

## Пов’язане

- [Лінтувати специфікації в CI лінтером специфікацій](https://specscore.md/uk/articles/lint-specs-in-ci/)
- [Шаблон PRD у Markdown для програмування зі ШІ](https://specscore.md/uk/articles/feature-spec-template/)
- [Як писати критерії приймання, які перевірить ШІ-агент](https://specscore.md/uk/articles/acceptance-criteria/)
- [Синтаксис вимог EARS з поясненням і прикладами](https://specscore.md/uk/articles/ears-requirements/)
- [Розробка за специфікаціями](https://specscore.md/uk/spec-driven-development/)
- [Інструменти розробки за специфікаціями](https://specscore.md/uk/spec-driven-development/tools/)
- [Специфікація функції](https://specscore.md/feature-specification)
- [Специфікація плану](https://specscore.md/plan-specification)
- [CLI](https://specscore.md/uk/cli/)
- [Що перевіряє SpecScore](https://specscore.md/uk/validators/)
