# Управление спецификациями: хранить, версионировать и рецензировать спецификации как код

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

Последнее обновление: 9 ноября 2026

Управление спецификациями — это то, как команда хранит спецификацию программного обеспечения, записывает каждое изменение, рассматривает это изменение и поддерживает спецификацию актуальной. Управление спецификацией — та же работа: спецификация — документ, который говорит, что должно делать программное обеспечение, а управление ею — то, как документ остаётся легко находимым и заслуживающим доверия. Управление спецификациями как кодом означает, что эти документы — файлы в системе контроля версий, поэтому изменение спецификации — это коммит, который рецензент может сравнить в diff. Версионирование спецификаций — это история этих коммитов вместе со статусом, записанным в каждом документе. Поддержание спецификаций в синхронизации с кодом означает, что предлагаемое изменение, которое ломает структуру спецификации, не проходит ту же автоматическую проверку, через которую проходит изменение кода. [Разработка по спецификациям](https://specscore.md/ru/spec-driven-development/) (SDD, spec-driven development) — практика писать спецификацию до кода и считать спецификацию источником правды. [Непрерывная интеграция](https://specscore.md/ru/validators/) (CI, continuous integration) — автоматическая проверка каждого предлагаемого изменения. Документ требований к продукту (PRD, product requirements document) — проза, которая называет проблему и рамки; [шаблон PRD в Markdown](https://specscore.md/ru/articles/feature-spec-template/) — это один файл функции SpecScore в этой форме. [Easy Approach to Requirements Syntax](https://specscore.md/ru/articles/ears-requirements/) (EARS) — шаблон предложения для требования. В [SpecScore](https://specscore.md/) требование (REQ) — именованное правило внутри функции, а [критерий приёмки](https://specscore.md/ru/articles/acceptance-criteria/) (AC, acceptance criterion) — необязательное абстрактное условие, которое указывает на одно или несколько таких правил. Проверка — команда [интерфейса командной строки](https://specscore.md/ru/cli/) (CLI, command-line interface), `specscore spec lint`, описанная в [Линтовать спецификации в CI линтером спецификаций](https://specscore.md/ru/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 spec](https://github.com/specscore/specscore/blob/main/spec/README.md) перечисляет каталоги: features, plans, ideas, decisions и lessons. Функция — это один каталог с `README.md`. [Спецификация функции](https://specscore.md/feature-specification) — контракт этого файла, а [шаблон PRD](https://specscore.md/ru/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, — это история коммитов этих файлов. SpecScore не добавляет второй номер версии к функции. Ревизия, на которую смотрит рецензент, — это коммит на ветке. Строка статуса в документе говорит, на каком этапе жизненного цикла находится эта функция, и это другой факт, чем хеш 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 состояния плана в тот момент. Два каталога lint, проверенные для этой страницы, не называют правило, которое находит коммит по этому хешу, поэтому эта страница не утверждает, что линтер проверяет, что коммит существует. Хеш — это указатель, по которому человек может пройти в 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/ru/validators/) отделяет эту структурную проверку от чтения, которое человеку всё ещё предстоит сделать. Разбор правило за правилом того, о чём сообщает `specscore spec lint`, — в [Линтовать спецификации в CI линтером спецификаций](https://specscore.md/ru/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/ru/articles/lint-specs-in-ci/).

Предложение в спецификации, которое больше не описывает код, не является одним из этих замечаний. `specscore spec lint` проверяет структуру: обязательные файлы и разделы, строки индекса, форму заголовков и ссылки, которые правила называют. Он не оценивает, совпадает ли реализация с требованием. Этот предел — смысл [страницы валидаторов](https://specscore.md/ru/validators/). Сохранять истинность прозы по-прежнему значит рецензировать diff.

## Как другие инструменты разработки по спецификациям проверяют спецификацию

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

[GitHub Spec Kit — справочник агентного SDD (/speckit.analyze)](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` в корне репозитория. Изменение — это коммит. 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 — коммит состояния плана. Каталоги линтера, цитируемые здесь, не описывают правило, которое находит коммит по этому хешу.

### Как поддерживать спецификации в синхронизации с кодом?

Положите спецификацию в репозиторий и роняйте pull request, когда `specscore spec lint` сообщает о структурном нарушении, включая строку индекса, которая не совпадает со своим файлом функции. Команда не решает, реализует ли код требование. Предложение, которое разошлось с кодом, всё ещё требует, чтобы человек прочитал diff.

## Источники

Файлы CLI и каталоги lint прочитаны 9 ноября 2026 года на тегах specscore-cli v0.39.1 (версия, которую устанавливает 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/ru/validators/)
- [Линтовать спецификации в CI линтером спецификаций](https://specscore.md/ru/articles/lint-specs-in-ci/)
- [Синтаксис требований EARS с объяснением и примерами](https://specscore.md/ru/articles/ears-requirements/)
- [Как писать критерии приёмки, которые проверит ИИ-агент](https://specscore.md/ru/articles/acceptance-criteria/)
- [Шаблон PRD в Markdown для программирования с ИИ](https://specscore.md/ru/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/ru/spec-driven-development/tools/)

## Связанное

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