Лінтувати специфікації в CI лінтером специфікацій

Лінтер специфікацій — це програма, яка перевіряє специфікацію на структурні помилки і завершується кодом збою, коли їх знаходить. Безперервна інтеграція (CI, continuous integration) — автоматична перевірка кожної запропонованої зміни. Безперервна інтеграція і безперервна доставка (CI/CD, continuous integration and continuous delivery) — це пайплайн, який виконує цю перевірку і зберігає зміну, що пройшла, готовою до випуску. Розробка за специфікаціями (SDD, spec-driven development) — практика писати специфікацію до коду і вважати специфікацію джерелом правди. Документ вимог до продукту (PRD, product requirements document) — проза, яка називає проблему і межі. У SpecScore вимога (REQ) — іменоване правило всередині функції, а критерій приймання (AC, acceptance criterion) — необов’язкова абстрактна умова, яка вказує на одне або кілька таких правил. Перевірка — команда інтерфейсу командного рядка (CLI, command-line interface), specscore spec lint, з CLI в specscore/specscore-cli (Apache-2.0). Easy Approach to Requirements Syntax (EARS) — шаблон речення для вимоги. Цей лінтер перевіряє заголовки, обов’язкові розділи і посилання. Він не оцінює англійську.

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

Що означає лінтувати специфікацію

Лінтувати специфікацію — перевірка того самого роду, що й лінтування коду. Детермінована програма читає файли і повідомляє про порушення правил. Вона не вирішує, чи продукт — добра ідея, і не переписує вимогу кращою прозою. Сторінка валідаторів відокремлює цю структурну перевірку від ручної перевірки ШІ. specscore spec lint — це структурна перевірка.

Опис команди в internal/cli/spec.go на тегу CLI v0.55.1 і на тегу v0.39.1, який встановлює воркфлоу цього репозиторію, каже, що вона перевіряє дерево специфікацій на порушення структурних конвенцій. Чистий запуск друкує 0 violations found і завершується з кодом 0. Запуск, який знаходить порушення, друкує один рядок на кожне зауваження і завершується з кодом 1. Цей код виходу і валить job CI. Неправильні аргументи завершуються з кодом 2. Відсутність specscore.yaml завершується з кодом 3, і повідомлення велить виконати specscore init.

Що перевіряє лінтер специфікацій

Правила належать CLI, а не окремому хмарному сервісу. Згенерований каталог docs/lint-rules.md на тегу v0.55.1 перелічує 183 правила. Воркфлоу цього сайту встановлює v0.39.1, раніший випуск, тож правило, яке є лише в пізнішому тегу, — не те, що виконує цей job. Правила, названі в цьому розділі, є в обох тегах. --severity за замовчуванням — error. Попередження друкується, лише якщо передати --severity warning або info, і команда за замовчуванням через попередження не падає. Каталог позначає dogfood-version-bump як попередження, тому команда за замовчуванням не падає, коли закріплена у воркфлоу версія відстає від бінарника.

Обов’язкові файли і розділи

Правило readme-exists (readme_exists.go) вимагає README.md у кожному каталозі специфікації. Правило oq-section (oq_section.go) вимагає, щоб README функції містив розділ ## Open Questions. Успадкований заголовок ## Outstanding Questions — окреме зауваження, і --fix переписує цей заголовок на місці. Повідомлення в прикладі нижче, «Open Questions section not found», — зауваження з README функції, з якого розділ прибрали.

Рядки індексу і дочірні каталоги

Правило index-entries (index_entries.go) звіряє індекс функцій із дочірніми каталогами на диску. Дочірній каталог, якого немає в списку, — порушення, і рядок, чиє посилання вказує на відсутній дочірній каталог, — теж порушення. --fix може видалити фантомний рядок і вставити той, якого бракує. Це цілісність каталогів і індексу. Це не обхід кожного URL у прозі.

Форма заголовка критеріїв приймання

Правило ac-heading-format (ac_heading.go) застосовується до README функції, файлу, чий заголовок — # Feature:. Рядок, який виглядає як заголовок критерію приймання, має бути точно ### AC: <id> з одним пробілом після двокрапки та id у kebab-case. Заголовок вигляду ### AC: <id> (verifies ...) теж приймається. --fix лагодить лише пробіли. Id з великими літерами або підкресленнями повідомляється і лишається людині. Правило не вимагає рядка **Requirements:**, не оцінює слова на кшталт «graceful» або «fast» і не попереджає, коли проза містить Given, When або Then. Як написати сам критерій — у статті як писати критерії приймання.

Посилання плану на ці ідентифікатори

У плані, який називає функцію-джерело, plan_rules.go читає заголовки ### AC: у README цієї функції. Правило P-002 повідомляє значення **Verifies:** завдання, яке не зводиться до <feature-slug>#ac:<ac-slug> для одного з цих заголовків, порожній рядок **Verifies:**, відсутній або нерозпізнаний рядок джерела, або функцію-джерело, яка не зводиться до README функції. Правило P-001 повідомляє заголовок, який не покриває жодне завдання і який не перелічено під ## Deferred AC Coverage. Плани з джерелом-ідеєю (**Source:** idea:<slug>) і плани з **Source:** none звільнені, і так само звільнений план у термінальному статусі диспозиції. Однорядковий текст каталогу для P-002 каже «valid dependency references»; перевіряючий код у цьому файлі — щойно описана перевірка посилань на AC.

Чим успішний lint не є

Та сама команда не вирішує, чи вимога закриває названу проблему, чи ім’я має сенс і чи дві функції суперечать одна одній за змістом. Сторінка валідаторів відносить це за межі лінтера CLI. Вона також не перевіряє ключові слова кроків сценарію. specscore rehearse виконує файли сценаріїв. Воркфлоу цього репозиторію виконує specscore spec lint і не викликає rehearse. Каталог називає подальші родини — ідеї, рішення, сутності, властивості, уроки, issues і решту правил планів — і кожне правило застосовується до файлів, які йому відповідають. Каталог і є список. Ця сторінка не повторює всі 183 описи.

Запуск specscore spec lint у CI

Команда шукає specscore.yaml вгору від робочого каталогу. Без цього файлу вона завершується з кодом 3 і називає specscore init. Job CI тому потрібен файл конфігурації в checkout. scripts/install.sh читає SPECSCORE_VERSION і, якщо змінну не задано, бере latest. Зафіксуйте тег, якщо хочете ті самі правила на кожному запуску.

Перевірка цього репозиторію — dogfood.yml. Він встановлює CLI з SPECSCORE_VERSION, рівним v0.39.1, і потім виконує specscore spec lint без додаткових флагів, на pull requests і на push до main. GitHub Actions позначає крок як неуспішний, коли процес завершується ненульовим кодом. Уривок нижче зберігає ці кроки встановлення і lint. Файл також задає permissions: contents: read, групу конкурентності і коментар про те, чому закріплення — не latest.

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

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

Звіт про помилку (specscore 0.55.0, та сама форма рядка у v0.39.1)

features/apply-discount/README.md:0 [error] oq-section: Open Questions section not found
features/apply-discount/README.md:0 [error] index-entries: Child directory not listed in index: refunds
features/apply-discount/refunds:0 [error] readme-exists: README.md not found

3 violations found (3 errors)

Чистий звіт

0 violations found

Кожне зауваження — це file:line [severity] rule: message. Підсумок — це N violations found плюс лічба в дужках, наприклад (3 errors). Код виходу — це статус процесу, а не рядок звіту. Три рядки вище знято зі specscore 0.55.0 на функції, з якої прибрали розділ Open Questions і чий індекс пропускав порожній дочірній каталог. Це той самий звіт, який показує сторінка CLI. --format приймає text (типово), json або yaml. --rules і --ignore вибирають правила і не поєднуються. --fix переписує зауваження, у яких є виправник, включно із заголовком Outstanding Questions. Job dogfood не передає --fix.

Інструменти, які не лінтують цей формат у CI

Перевірка якості вимог у цій CLI — це структурна перевірка вище. Це не оцінка прози. Інші інструменти розробки за специфікаціями публікують інші перевірки. Абзаци нижче використовують лише те, що кажуть власні сторінки цих проєктів. Огляд інструментів записує ті самі сторінки як прочитані 30 жовтня 2026 року, крім домашньої сторінки документації Spec Kit, яка друкує 28 вересня 2026 року, і сторінки специфікацій функцій Kiro, яка друкує 4 серпня 2026 року.

GitHub Spec Kit — це воркфлоу агента, який пише артефакти Markdown. Довідник агентного SDD описує /speckit.analyze як звіт про неузгодженості між специфікацією, планом і завданнями, без редагування файлів. Його запускають в агенті. Домашня сторінка документації також називає розширення спільноти, включно з одним на ім’я CI Guard, які додають ворота відповідності. Це не команда, яка лінтує README функції SpecScore.

OpenSpec структурну перевірку таки публікує. openspec validate, описаний у довіднику CLI, перевіряє структуру зміни і специфікації OpenSpec, завершується ненульовим кодом, коли перевірка не минає, і довідник містить фрагмент shell, який може виконати job CI. Ця перевірка — форма OpenSpec, а не заголовки ### AC: і не індекс SpecScore.

Сторінка специфікацій функцій Kiro описує Analyze Requirements як перевірку всередині Kiro, до проєкту, яка шукає неузгодженості, неоднозначність, конфліктні обмеження і прогалини. Це не команда в dogfood.yml. Шаблони речень, які пише Kiro, — у статті синтаксис вимог EARS.

README BMAD Method описує артефакти методу і воркфлоу агентів. Він не документує команду, яка лінтує фіксовану схему специфікації в CI. README Task Master описує розбір PRD на завдання командою task-master parse-prd. Він не описує лінтер для цього PRD. PRD і далі може бути входом функції SpecScore, і specscore spec lint — це те, що потім перевіряє файл функції.

Питання й відповіді

Що таке лінтер специфікацій?

Лінтер специфікацій читає файли специфікації і повідомляє про структурні порушення. specscore spec lint — ця команда для дерева SpecScore. Вона завершується з кодом 0, коли нічого не знаходить на обраній серйозності, і з кодом 1, коли знаходить порушення.

Чи оцінює лінтер якість вимог за формулюванням?

Ні. ac-heading-format перевіряє заголовок ### AC:. Він не оцінює слова на кшталт «graceful» або «fast» і не попереджає, коли критерій містить Given, When або Then. Формулювання — це робота з текстом. Сторінка валідаторів відокремлює цей детермінований lint від ручної перевірки ШІ.

Як лінтувати специфікації в CI?

Встановіть CLI з SPECSCORE_VERSION, закріпленим на тегу випуску, і виконайте specscore spec lint. У checkout потрібен specscore.yaml. dogfood.yml — робочий приклад GitHub Actions. Він закріплює v0.39.1.

Що друкує неуспішний запуск?

Один рядок на зауваження, file:line [severity] rule: message, потім підсумок на кшталт 3 violations found (3 errors). Процес завершується з кодом 1. Чисте дерево друкує 0 violations found і завершується з кодом 0.

Чи перевіряють інші інструменти специфікації в CI/CD?

Команда OpenSpec openspec validate може звалити job CI, і вона перевіряє власну структуру зміни OpenSpec. /speckit.analyze Spec Kit виконується в сесії агента. Analyze Requirements у Kiro виконується всередині Kiro. README BMAD Method і Task Master не документують лінтер формату для CI. Воркфлоу dogfood у SpecScore виконує specscore spec lint по дереву SpecScore.

Джерела

Поведінку CLI перевірено 4 листопада 2026 року за тегами v0.55.1 і v0.39.1 specscore-cli. Сторінки конкурентів — ті, що пов’язані нижче; огляд інструментів записує їх як прочитані 30 жовтня 2026 року, крім сторінок, які друкують власну дату.