Урок 2.6. SDD Toolkits и API Specification Tools

Зачем это нужно

В предыдущих уроках мы разобрали, как превращать идею в specification: выделять requirements, constraints, acceptance criteria, edge cases и open questions. Но в реальной разработке быстро появляется следующий вопрос:

Как удерживать этот process повторяемым,
если с кодом работает AI agent?

Можно писать spec.md, design.md и tasks.md вручную. Это хороший старт. Но по мере роста проекта появляются типичные проблемы:

• разные features описываются в разных форматах;
• agent прыгает от идеи сразу к code changes;
• specifications остаются в chat history и теряются;
• design decisions не попадают в repository;
• tasks становятся слишком крупными;
• API contracts расходятся с implementation;
• после изменения endpoint ломается frontend или external client;
• review не может понять, что именно agent должен был сделать.

Именно здесь появляются два класса инструментов:

• SDD toolkits, которые управляют движением от идеи к specification, plan, tasks и implementation;
• API specification tools, которые формально описывают machine-readable contracts: HTTP API, events, schemas и generated types.

Главная мысль урока:

SDD toolkit управляет смыслом изменения.
API specification tool управляет формой интерфейса.
В agent development нужны оба слоя.

Основная идея

Specification в AI-разработке существует минимум на двух уровнях.

Первый уровень - human-readable specification. Она нужна людям и агентам, чтобы понимать intent:

Goal
Non-goals
Actors
Requirements
Acceptance criteria
Constraints
Edge cases
Open questions
Verification

Она отвечает на вопрос:

Что должно измениться в поведении продукта и почему?

Второй уровень - machine-readable contract. Он нужен tooling, tests, CI, generated clients и runtime validators:

OpenAPI
AsyncAPI
JSON Schema
TypeScript types
Protocol schema
Event schema
Contract tests

Он отвечает на вопрос:

Какую точную форму должен соблюдать interface?

Если есть только human-readable spec, agent может понять intent, но ошибиться в interface shape.

Если есть только OpenAPI, agent знает endpoint и schema, но не знает product constraints, non-goals, security assumptions и edge cases.

Предсказуемая AI-разработка соединяет оба слоя.

Ключевые термины

Два слоя specification

В этой схеме SDD toolkits отвечают за верхний поток: idea, spec, clarification, design, tasks, implementation.

API specification tools отвечают за нижний поток: contract, schemas, generated artifacts, contract tests.

Оба потока сходятся в evidence. Задача готова не тогда, когда agent написал "done", а когда есть проверяемое доказательство:

• spec согласован;
• tasks выполнены;
• tests прошли;
• API contract валиден;
• implementation соответствует contract;
• diff не содержит лишних изменений.

Метод отбора инструментов

Для этого урока используется snapshot на 2026-08-08.

Основной источник для SDD-инструментов - GitHub topic:

https://github.com/topics/spec-driven-development

Фильтр:

• сортировка Most stars;
• только англоязычные материалы;
• китайские локализации и китайские README не рассматриваем;
• очевидные false positives исключаем;
• обязательные инструменты из плана курса включаем отдельно.

Почему нельзя просто взять верхние 20 репозиториев по stars?

Потому что GitHub topic содержит шум. Например, zeromicro/go-zero может быть отмечен topic spec-driven-development, но это Go microservices framework, а не SDD toolkit для AI-agent workflow. Его нельзя честно ставить в один ряд с Spec Kit, OpenSpec или Superpowers.

Также важно не путать:

• open-source repository;
• product feature;
• methodology;
• plugin;
• API contract tool.

Kiro Specs, например, важен для курса, но это workflow внутри Kiro IDE/Web/CLI, а не отдельный GitHub OSS repository. Поэтому он входит в обзор, но не участвует в рейтинге GitHub repositories by stars.

Top-20 инструментов для урока 2.6

Эта таблица не является "топом качества". Это учебная карта инструментов: какие подходы студент должен уметь различать после урока.

Краткая матрица выбора ТОП-3

В контексте SDD и agent workflows выбор инструмента сильно зависит от типа проекта.

Greenfield - проект с нуля: нет старого кода и ограничений.
Brownfield - существующий код: живая система, interfaces и technical debt.

Классификация по типу проекта:

• Greenfield: нужны инструменты "жестких рельсов", которые заставляют agent сначала декомпозировать задачи и следовать неизменяемой constitution. Подходят Superpowers (skills, TDD, review), GitHub Spec Kit (constitution → specify → clarify → plan → tasks → implement), BMAD Method (полная agile-методология) и GSD (lightweight SDD с context engineering).
• Brownfield: нужна изоляция изменений от текущего состояния. OpenSpec прямо создан для этого: openspec/specs/ хранит то, что есть, openspec/changes/ - то, что меняем, с циклом propose → apply → archive. Как плагинный слой поверх существующего workflow подходят cc-sdd, Conductor и gsd-2.

Резюме по ТОП-3:

• Superpowers (~295k★) - не инструмент, а методология: engineering-процесс декомпозирован в composable skills (brainstorming, design, worktrees, TDD, review). Брать, когда нужен дисциплинированный workflow, особенно для новых проектов.
• GitHub Spec Kit (~140k★) - официальный SDD-harness от GitHub с фиксированным pipeline и этапом clarify, который снимает неоднозначности до старта кода. Самый зрелый baseline для проектов с нуля.
• OpenSpec (~71k★) - единственный в списке инструмент с явной архитектурой под изменения, а не с нуля. Каждое изменение атомарно и отслеживаемо - лучший выбор для brownfield.

Как читать popularity

Stars полезны как сигнал, но в AI-agent tooling они особенно легко вводят в заблуждение.

Один repository может быть:

• полноценным framework;
• collection of prompts;
• plugin для одного agent harness;
• UI dashboard;
• fork с активным community;
• временным экспериментом;
• списком ссылок;
• локализацией другого проекта.

Поэтому при выборе инструмента нужно смотреть не только на stars:

Для курса особенно ценны инструменты, которые оставляют понятные Markdown/YAML/JSON artifacts в repository. Чем меньше workflow спрятан внутри непрозрачного UI, тем проще студенту понять механику.

Как обновлять обзор GitHub topic

GitHub topic - это хороший discovery feed, но плохой источник истины. Topic может поставить автор, форк, экспериментальный проект или репозиторий, который использует слово specification в другом смысле.

Перед тем как включать инструмент в учебный обзор или выбирать его для проекта, полезно пройти короткий фильтр:

Если инструмент не проходит фильтр, его можно упомянуть как сигнал рынка, но не стоит строить на нем курс или production workflow.

Практическое правило:

Stars помогают найти кандидатов.
SDD artifacts, gates и verification показывают, можно ли кандидату доверять.

Выбор toolkit по ситуации

Выбор SDD toolkit лучше начинать не с рейтинга, а с формы работы.

Практическая интерпретация:

Иногда инструменты комбинируются. Например, Spec Kit может быть удобен для durable spec artifacts, а skill-first workflow - для implementation loop, TDD и review. Главное, чтобы source of truth и gates были ясны:

Кто создает spec?
Кто утверждает plan?
Где живут tasks?
Как implementation доказывает соответствие spec?

Greenfield, brownfield и legacy

SDD выглядит по-разному в новом и существующем коде.

Для brownfield и legacy не начинайте с фразы:

Сделай систему по этой новой спецификации.

Лучше:

Сначала исследуй текущий код и опиши current behavior.
Затем сформируй delta spec: что меняется, что не меняется,
какие existing constraints нужно сохранить.
Не реализуй до approval.

Это снижает риск "археологии наугад": агент не должен сам выводить весь intent из кода, но он обязан проверить, как текущая система действительно работает.

Что будет разобрано отдельно

Урок 2.6 остается обзорной картой. В следующих уроках модуль углубится в top-10 SDD/agent workflow инструментов по популярности среди англоязычных repositories и обязательных инструментов курса.

SDD toolkits: что они делают

SDD toolkit нужен не для того, чтобы "магически сделать проект правильно". Он нужен, чтобы agent не работал в пустоте.

Типовой SDD workflow:

idea
-> clarification
-> requirements
-> design
-> plan
-> tasks
-> implementation
-> verification
-> archive / knowledge update

Главная ценность toolkit - сделать этот workflow повторяемым.

GitHub Spec Kit

GitHub Spec Kit полезен как canonical baseline для курса. Его удобно объяснять через pipeline:

constitution
-> specify
-> clarify
-> plan
-> tasks
-> analyze
-> implement

Что важно:

• project constitution задает принципы, которым должны подчиняться specs и plans;
• /speckit.specify описывает what and why;
• /speckit.clarify помогает убрать ambiguity до plan;
• /speckit.plan фиксирует technical approach;
• /speckit.tasks превращает plan в executable task breakdown;
• /speckit.analyze ищет inconsistencies across artifacts;
• /speckit.implement выполняет tasks.

Spec Kit хорош для обучения, потому что явно показывает:

coding agent не должен начинать с кода.

Сначала agent должен создать artifacts, которые можно прочитать, исправить и закоммитить.

OpenSpec

OpenSpec строится вокруг идеи changes и deltas.

Типовая структура:

openspec/
  project.md
  specs/
    auth/
      spec.md
  changes/
    add-2fa/
      proposal.md
      design.md
      tasks.md
      specs/
        auth/
          spec.md

Смысл:

• openspec/specs/ хранит current source of truth;
• openspec/changes/ хранит proposed changes;
• после реализации change архивируется;
• living specs обновляются постепенно.

Это особенно удобно для brownfield development. Агенту не нужно переписывать весь продукт. Он работает с одним change:

Что меняем?
Почему?
Какие requirements добавляем или меняем?
Какие tasks выполняем?
Как доказываем готовность?

OpenSpec хорошо подходит для курса как пример delta-first thinking.

Kiro Specs

Kiro Specs показывает product-native SDD workflow внутри agentic IDE/Web/CLI.

Базовые артефакты:

.kiro/specs/<feature-name>/
  requirements.md
  design.md
  tasks.md

Типовой workflow:

requirements
-> design
-> tasks
-> task execution

Сильная сторона Kiro - visibility and gates. Студент видит, что implementation начинается не с просьбы "напиши код", а после подготовки и review artifacts.

Ограничение: Kiro Specs сильнее привязан к конкретной среде. Поэтому для курса важно сохранять portable artifacts в repository, чтобы workflow не исчезал при смене инструмента.

BMAD Method

BMAD Method - это уже не просто SDD toolkit. Это full lifecycle methodology для AI-driven development.

Типовой mental model:

Analysis
-> Planning
-> Solutioning
-> Implementation

Артефакты могут включать:

• product brief;
• PRD;
• architecture;
• epics;
• stories;
• sprint status;
• implementation readiness checks;
• code review artifacts.

BMAD полезен, когда проект достаточно большой, чтобы оправдать additional ceremony:

• несколько ролей;
• несколько этапов планирования;
• сложная architecture;
• необходимость project memory;
• работа story by story;
• team-level process.

Для маленькой feature BMAD может быть слишком тяжелым. В курсе это важный пример:

Инструмент должен соответствовать масштабу задачи.

Superpowers

Superpowers важен для курса как пример skill-first SDLC.

Его идея:

Engineering process можно оформить как reusable skills,
которые agent обязан применять в нужный момент.

Типовой workflow:

brainstorming
-> design
-> git worktree
-> writing plans
-> TDD
-> implementation
-> code review
-> finish branch

Это связывает сразу несколько тем курса:

• skills;
• git worktrees;
• TDD;
• subagent development;
• review before completion;
• evidence over claims.

Superpowers полезен, когда команда хочет не просто "лучшие промпты", а repeatable engineering behavior.

Agent-OS / Ouroboros

Agent-OS / Ouroboros показывает более системный подход: agent работает не просто по prompt, а внутри operating model.

Важные идеи:

• seed spec фиксирует intent;
• ledger делает действия replayable and auditable;
• runtime adapters подключают разные agent harnesses;
• evaluation gates проверяют результат;
• ooo commands ведут workflow через interview, seed, run, evaluate.

Типовой flow:

interview
-> seed
-> run
-> evaluate
-> evolve / resume

Для курса это пример следующего уровня зрелости. Вместо "agent session" появляется управляемый execution environment, где есть specs, history, boundaries и verification.

GSD, Conductor, cc-sdd и другие lightweight harnesses

Не все команды хотят full methodology. Иногда нужен тонкий слой, который делает простую вещь:

Не давай агенту кодить без spec.
Не давай агенту продолжать без plan.
Не объявляй done без tests.

Такие tools важны, потому что они ближе к реальной ежедневной практике.

Примеры:

• GSD systems добавляют context engineering и rails для agent workflow;
• Conductor показывает plugin-first SDD;
• cc-sdd показывает minimal adaptable harness;
• Pilot Shell показывает shell-like process вокруг Codex/Claude;
• Spec Kitty добавляет dashboard и worktree workflow;
• AGTX показывает shared blackboard для multi-session coordination.

В курсе эти инструменты полезны не только сами по себе. Они показывают разные формы одного принципа:

Agent workflow должен быть явным, проверяемым и повторяемым.

API specification tools: что они делают

API specification tools решают другую проблему. Они не объясняют product intent. Они фиксируют interface.

Пример human-readable requirement:

User can create a project inside a team.
Project name is required.
Duplicate project names inside one team are forbidden.

Пример machine-readable contract:

POST /api/projects
Request:
  teamId: string
  name: string
Response 201:
  id: string
  teamId: string
  name: string
Error 409:
  code: PROJECT_NAME_TAKEN

Агенту нужны оба артефакта. Без requirement он не поймет business rule. Без contract он может вернуть неправильный status code или field name.

OpenAPI Generator

OpenAPI Generator нужен, когда OpenAPI contract должен порождать clients, servers, SDKs или types.

В agent workflow это выглядит так:

agent updates openapi.yaml
-> runs generator
-> reviews generated diff
-> runs typecheck/tests

Важно: generated code лучше выносить в отдельную task или отдельный diff. Иначе review тонет в механических изменениях.

Swagger OSS Tools

Swagger ecosystem - классический набор open-source tools вокруг OpenAPI:

• читать API documentation;
• редактировать OpenAPI specs;
• тестировать endpoints;
• генерировать code stubs.

Для AI agent Swagger важен как human-readable surface для machine-readable contract. Человек и agent могут смотреть на один и тот же API description.

AsyncAPI

OpenAPI хорошо описывает HTTP APIs. Но многие системы работают не только через HTTP.

AsyncAPI нужен для:

• events;
• queues;
• message brokers;
• pub/sub;
• producers and consumers;
• event payload schemas.

Если agent меняет event-driven system, specification должна отвечать не только на вопрос "какой endpoint", но и:

• кто публикует event;
• кто его потребляет;
• какая schema payload;
• какие compatibility constraints;
• какие retries and failure modes.

Stoplight Spectral / Elements

Spectral - это linter для API specs. Он проверяет rules:

• naming conventions;
• required descriptions;
• response shape;
• error format;
• pagination conventions;
• internal style guide.

Elements - это documentation surface, который делает API spec readable для людей.

В agent workflow Spectral важен как автоматическая проверка:

agent changed OpenAPI
-> spectral lint
-> lint found missing error schema
-> agent fixes contract before implementation is accepted

Redocly CLI

Redocly CLI полезен для linting, bundling и documentation build.

Пример verification:

redocly lint api/openapi.yaml
redocly bundle api/openapi.yaml

Для курса важна не конкретная команда, а принцип:

API docs build должен быть частью definition of done.

Если agent обновил endpoint, но documentation build падает, task не готова.

Specmatic

Specmatic нужен для contract testing. Он проверяет, что service действительно соответствует declared API contract.

Пример:

OpenAPI says:
POST /api/projects returns 409 PROJECT_NAME_TAKEN for duplicate name.

Implementation returns:
400 DUPLICATE_PROJECT.

Contract test fails.

Это хороший тип failure для AI-разработки. Agent может написать working code, но wrong contract. Contract test ловит mismatch до production.

Как SDD и API contracts соединяются

Надежный workflow для AI agent выглядит так:

spec.md
-> design.md
-> tasks.md
-> api/openapi.yaml
-> failing tests / contract tests
-> implementation
-> verification
-> review

Это не waterfall ради waterfall. Это способ удержать agent от guesswork.

Пример task для SaaS Task Manager

Задача:

Добавить создание project через API.

Плохой prompt:

Добавь endpoint для создания проекта.

Лучше:

TASK PROJ-12

Goal:
Add POST /api/projects for creating a project inside a team.

Inputs:
- specs/projects/spec.md
- specs/projects/design.md
- api/openapi.yaml

Allowed scope:
- src/projects/*
- tests/projects/*
- api/openapi.yaml

Acceptance criteria:
- Authenticated user can create project in a team they belong to.
- name is required and cannot be blank.
- Duplicate project name inside the same team returns PROJECT_NAME_TAKEN.
- Response matches ProjectResponse schema.

Contract:
- Update POST /api/projects in api/openapi.yaml.
- Preserve existing ErrorResponse shape.

Verification:
- pytest tests/projects/test_create_project.py
- npm run openapi:lint
- npm run typecheck

Теперь agent не должен "угадать" endpoint. Он должен привести requirements, implementation, tests и contract в согласованное состояние.

Traceability

Traceability показывает, как requirement проходит путь до проверки.

Для AI agent traceability особенно важна. Агент может:

• добавить тест, но не на тот behavior;
• обновить OpenAPI, но забыть implementation;
• реализовать endpoint, но не тот error code;
• сделать happy path и пропустить edge case;
• случайно поменять consumer-facing contract.

Traceability делает такие разрывы видимыми.

Decision matrix

Выбор инструмента начинается не с вопроса "что популярнее", а с вопроса "какая проблема болит".

Выбор под тип проекта

Маленький учебный проект

Начните без тяжелого toolkit:

specs/
  feature-name/
    spec.md
    design.md
    tasks.md
api/
  openapi.yaml
scripts/
  verify

Добавьте:

• один шаблон spec;
• один шаблон task;
• одну команду verification;
• правило "no code before spec".

Tooling можно добавить позже.

Brownfield продукт

Главная проблема brownfield - existing behavior. Агент не должен переписать систему под красивый новый plan.

Подходящие инструменты:

• OpenSpec для delta specs;
• Spec Kit с аккуратным clarify/analyze;
• cc-sdd как minimal harness;
• API contract tools для interfaces.

Важно:

Для brownfield changes spec должен описывать не только что меняем,
но и что обязано остаться неизменным.

API-heavy backend

Если проект живет вокруг API, SDD без contract validation будет слабым.

Минимальный stack:

spec.md
design.md
tasks.md
openapi.yaml
openapi lint
contract tests
generated types

Возможные инструменты:

• OpenAPI Generator;
• Swagger OSS tools;
• Redocly CLI;
• Spectral;
• Specmatic.

Multi-agent workflow

Если несколько agents работают параллельно, риск drift резко растет.

Нужны:

• shared source of truth;
• role boundaries;
• task ownership;
• independent review;
• artifact-level coordination;
• logs and evidence.

Инструменты для изучения:

• Superpowers;
• BMAD Method;
• Agent-OS / Ouroboros;
• AGTX;
• Spec Kitty.

Prompt patterns

Инструмент не отменяет prompts. Он делает prompts более дисциплинированными.

Prompt для SDD toolkit

Use the repository SDD workflow.

Do not implement yet.

First:
1. Read the project rules.
2. Create or update the feature spec.
3. Ask clarification questions for ambiguous requirements.
4. Produce design and tasks.
5. Stop for review before code changes.

Prompt для API contract change

Update the API contract before implementation.

Required:
- update api/openapi.yaml
- preserve existing error response format
- add or update contract tests
- run API linting
- then implement the endpoint
- stop if contract and implementation disagree

Prompt для review

Review this change against:
- approved spec
- design document
- tasks.md
- OpenAPI contract
- tests and verification output

Report only behavioral gaps, contract mismatches, missing tests,
scope creep, and risks.

Типичные ошибки

Ошибка 1. Выбирать инструмент по stars

Stars показывают visibility, а не fit.

Для production-выбора важнее:

• artifact format;
• local execution;
• CI integration;
• reviewability;
• security posture;
• compatibility with your agent harness;
• cost of adoption.

Ошибка 2. Считать OpenAPI полноценным product spec

OpenAPI может сказать:

POST /api/projects returns 201.

Но он не объяснит:

• зачем пользователю project;
• кто имеет право его создать;
• какие business constraints существуют;
• какие non-goals у feature;
• какие edge cases важны.

OpenAPI фиксирует форму. Product spec фиксирует смысл.

Ошибка 3. Писать spec, но не делать его проверяемым

Плохое requirement:

API должен быть удобным.

Лучше:

REQ-PROJ-004:
POST /api/projects returns 400 VALIDATION_ERROR
when name is missing or contains only whitespace.

Ошибка 4. Давать agent contract без verification command

Плохой prompt:

Обнови OpenAPI.

Лучше:

Обнови api/openapi.yaml и запусти:
- npm run openapi:lint
- npm run typecheck
- pytest tests/projects/test_create_project.py

Ошибка 5. Смешивать generated code и hand-written code

Generated clients могут создать большой diff. Для review это опасно:

• сложно отделить механические изменения от логики;
• легко пропустить breaking change;
• agent может исправить generated file вручную;
• CI может пройти, но consumer contract изменится незаметно.

Правило:

Contract change, generator run и hand-written implementation
лучше разделять на явные steps.

Ошибка 6. Считать toolkit заменой engineering judgment

Spec Kit, OpenSpec, BMAD или Superpowers не гарантируют качество требований. Они дают process. Качество все еще зависит от:

• ясности intent;
• review;
• tests;
• constraints;
• domain knowledge;
• verification.

Toolkit усиливает дисциплину, но не заменяет инженера.

Минимальный вариант без тяжелого tooling

Если команда еще не готова выбирать toolkit, можно начать с простого repository convention:

specs/
  <feature>/
    spec.md
    design.md
    tasks.md
    evidence.md

api/
  openapi.yaml

scripts/
  verify
  lint-api

Минимальные правила:

1. Каждая feature начинается с spec.md.
2. Каждая implementation task ссылается на accepted requirement.
3. Agent получает allowed scope.
4. Code changes не принимаются без tests.
5. API changes не принимаются без contract update.
6. Verification commands записываются в task и выполняются перед завершением.
7. Evidence сохраняется в summary, PR description или evidence.md.

Такой lightweight setup хорошо подходит для курса. Студент видит механику без магии.

Практика

Практика 1. Выберите слой

Для каждого сценария определите, нужен SDD toolkit, API contract tool или оба слоя.

Практика 2. Напишите task с contract check

Шаблон:

TASK API-XX

Goal:

Inputs:

Allowed scope:

Contract:

Acceptance criteria:

Verification:

Минимальное требование: в Verification должна быть хотя бы одна проверка contract, а не только unit tests.

Практика 3. Найдите missing source of truth

Если agent run завершился фразой:

I updated the endpoint and adjusted the docs.

Проверьте:

• где requirement id;
• где acceptance criterion;
• где OpenAPI schema;
• где test;
• где command output;
• где diff review;
• где evidence, что implementation соответствует contract.

Если хотя бы один пункт отсутствует, task не полностью доказана.

Checklist выбора инструмента

Перед внедрением toolkit ответьте:

• Какой artifact будет source of truth?
• Где этот artifact лежит в repository?
• Как agent поймет, что нельзя начинать implementation?
• Какие approval gates есть между phases?
• Какое минимальное изменение можно выполнить через этот workflow?
• Как workflow работает в brownfield codebase?
• Можно ли запустить проверки в CI?
• Что произойдет, если toolkit исчезнет?
• Можно ли прочитать specs обычным Markdown viewer?
• Где будут храниться completed specs, archives или decisions?
• Как workflow отличается для greenfield и brownfield?
• Что является output каждого phase: spec, plan, tasks, tests, run log?
• Можно ли разделить durable artifacts и agent-only working notes?

Перед внедрением API specification tool ответьте:

• Какой contract считается главным?
• Кто обновляет contract: backend, API platform team, agent?
• Есть ли lint rules?
• Есть ли generated clients или types?
• Есть ли contract tests?
• Что считается breaking change?
• Как agent узнает, что contract нельзя менять без approval?

Критерии готовности

После урока студент должен уметь:

• объяснить отличие SDD toolkit от API specification tool;
• объяснить, почему human-readable spec и machine-readable contract не заменяют друг друга;
• назвать роль GitHub Spec Kit, OpenSpec, Kiro Specs, BMAD Method, Superpowers и Agent-OS;
• читать GitHub popularity signals критически;
• выбрать lightweight или full-lifecycle toolkit под задачу;
• встроить OpenAPI/AsyncAPI/JSON Schema/TypeScript types в agent workflow;
• написать task, где есть allowed scope, acceptance criteria и verification commands;
• объяснить, почему API contract должен проверяться автоматически;
• построить traceability от requirement до test.

Краткое резюме

SDD toolkits помогают управлять intent: что строим, зачем, где границы, какие tasks и как проверить результат.

API specification tools помогают управлять interface: какие endpoints, schemas, events, errors и generated artifacts должны совпасть.

В AI Agent Development эти слои работают вместе. Human-readable spec снижает риск неправильного поведения. Machine-readable contract снижает риск неправильной формы. Tests, linters, contract checks и review дают evidence.

Правильный вопрос звучит не так:

Какой инструмент самый популярный?

Лучше спрашивать:

Какой самый маленький workflow удержит agent от guesswork
и даст проверяемый результат для моей задачи?

Вопросы для самопроверки

1. Почему OpenAPI не заменяет spec.md?
2. В чем отличие Delta Spec от полной feature specification?
3. Когда лучше использовать lightweight SDD harness, а когда full-lifecycle methodology?
4. Какие проверки стоит добавить, если agent меняет API endpoint?
5. Почему generated clients лучше обновлять отдельным step?
6. Почему Kiro Specs нельзя честно ранжировать как GitHub OSS repository?

Источники для актуализации

• GitHub topic spec-driven-development: https://github.com/topics/spec-driven-development
• GitHub Spec Kit: https://github.com/github/spec-kit
• OpenSpec: https://github.com/Fission-AI/OpenSpec
• Kiro Specs: https://kiro.dev/docs/specs/
• BMAD Method: https://github.com/bmad-code-org/BMAD-METHOD
• Superpowers: https://github.com/obra/superpowers
• Agent-OS / Ouroboros: https://github.com/Q00/ouroboros
• GSD (public archive): https://github.com/gsd-build/get-shit-done
• Conductor: https://github.com/gemini-cli-extensions/conductor
• cc-sdd: https://github.com/gotalab/cc-sdd
• OpenAPI Generator: https://github.com/OpenAPITools/openapi-generator
• Swagger OSS: https://github.com/swagger-api
• AsyncAPI: https://github.com/asyncapi
• Stoplight Spectral: https://github.com/stoplightio/spectral
• Redocly CLI: https://github.com/Redocly/redocly-cli
• Specmatic: https://github.com/specmatic/specmatic

Что дальше

Дальше логично перейти к отдельным лекциям 2.7-2.16. В них мы уже не просто сравним инструменты, а разберем каждый top SDD toolkit как рабочий process: что он создает в repository, как им пользоваться, какие prompts давать agent, где verification gates и когда инструмент не стоит брать.