ProductSpec — скилл
ProductSpec задает формат продуктовой спецификации, а скиллы, CLI и MCP-сервер ведут агента по ней и проверяют итог
- 317 ★ репозитория
- Последний коммит
- MIT
Расширенный доступ
Почему такой уровень
- CLI и MCP-сервер запускаются через `npx` с загрузкой пакета `@productspec/parser@latest` из npm
- Команды `init`, `init-run` и скилл создают и меняют файлы спецификаций и отчетов в репозитории
Установка
- Работает в
В терминале, через SkillFoxx CLI
npx skillfoxx add skills/productspecОпределит агенты на машине, покажет уровень доступа и зафиксирует версию.
Другие способы установки
Доступ и проверки
Как мы проверяемРасширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.
- CLI и MCP-сервер запускаются через `npx` с загрузкой пакета `@productspec/parser@latest` из npm
- Команды `init`, `init-run` и скилл создают и меняют файлы спецификаций и отчетов в репозитории
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
ProductSpec — открытый стандарт для описания продуктовых намерений: что строить, чего не строить, как доказать готовность и когда менять план. Спецификация лежит в репозитории файлом `.product-spec.md` с устойчивыми идентификаторами: `AC-` у критериев приемки, `EVAL-` у проверок поведения модели, `SM-` у метрик успеха. Номер ревизии `spec_revision` показывает, какую версию намерения агент взял в работу. Вместе со стандартом идут два скилла. `productspec-authoring` пишет спецификацию, переводит в нее готовый PRD и проверяет результат. `productspec` ведет реализацию по существующей спецификации: агент ищет файлы `.product-spec.md`, читает объем работ и критерии, держится в границах `scope.in` и перед сдачей сверяет, что спецификация не поменялась. Рядом работают пакет `@productspec/parser` с командой `productspec` (validate, handoff, graph, garden, reconcile, serve, mcp) и MCP-сервер с сессиями вроде `begin_spec_session` и `check_spec_session`. Результат запуска агента записывается в файл Agent Run со ссылками на доказательства по каждому `AC-` и `EVAL-`, а расхождения с замыслом фиксирует Decision Trace. Проверку спецификаций можно повесить на GitHub Actions, а в браузере спецификации пишет бесплатный редактор ProductSpec.io.
Для кого. Продакт-менеджерам и командам, которые поручают реализацию фич Claude Code, Codex или Cursor и хотят сверять результат с письменным намерением.
Подходит, если
- Фичу описывает PRD или тикет, а агенту нужна проверяемая спецификация с критериями приемки
- В CI надо проверять, что файлы `.product-spec.md` валидны, а ссылки на доказательства на месте
- После правок кода агент должен показать доказательство по каждому критерию `AC-` до отчета о готовности
- Реализация упирается в расхождение с замыслом, и решение фиксируют в Decision Trace
- В репозитории копятся спецификации, и по `productspec garden` ищут устаревшие ревизии и пробелы в доказательствах
Не подходит, если
- Задача мелкая и укладывается в одно сообщение агенту: спецификация только добавит бумаги
- Нужен инструмент, который сам оценивает качество продуктового решения: стандарт задает структуру, а не критерии хорошей спецификации
- Команде достаточно записать план реализации для инженеров: ProductSpec описывает намерение, а технический план остается отдельно
- Нет Node.js: CLI и MCP-сервер запускаются через npm
Пример запроса к агенту
Используй скилл productspec-authoring: переведи docs/old-prd.md в docs/product-specs/checkout.product-spec.md и проверь файлОграничения
- Стандарт нейтрален: он задает структуру, идентификаторы разделов и формат заметок, но не определяет, чем хороша спецификация.
- ProductSpec не собирает трассы и не запускает проверки поведения модели. Он дает доказательствам устойчивую цель, ссылки на результаты ведет команда.
- Формат версии 0.1 (`spec_format_version`), то есть ранний: структура может поменяться.
- CLI и MCP-сервер запускаются через `npm exec` или `npx`, нужны Node.js и доступ к реестру npm.
Как отключить. Скиллы убирает `npx skills remove productspec productspec-authoring`. Запись productspec удалите из конфигурации MCP, а файлы `.product-spec.md` остаются в репозитории как обычный Markdown.
Частые вопросы
Как поставить ProductSpec в Claude Code?
Выполните `npx skills add gokulrajaram/ProductSpec --all --full-depth`: так ставятся оба скилла, `productspec-authoring` и `productspec`. Один скилл ставит флаг `--skill <имя>`. Проверить файл можно командой `npm exec --yes --package @productspec/parser -- productspec validate <файл>`.
Как подключить MCP-сервер ProductSpec?
Команда `npx --yes -p @productspec/parser@latest productspec mcp-config claude` печатает готовый блок `mcpServers`, его вставляют в конфигурацию Claude Desktop. Для Cursor вместо `claude` укажите `cursor`. После правки клиент перезапускают.
Чем ProductSpec отличается от PRD?
PRD читают люди, а ProductSpec делит текст на части с идентификаторами `AC-`, `EVAL-` и `SM-`, которые агент и CI проверяют. Готовый PRD скилл `productspec-authoring` переводит в этот формат, сохраняя замысел автора.
Что такое Agent Run?
Это файл-отчет об одном запуске агента против закрепленной ревизии спецификации: проверенные критерии, ссылки на доказательства, статус расхождений и заявление о завершении. Черновик создает `productspec init-run`, проверку делает `validate-run`.
Нужен ли редактор ProductSpec.io?
Нет, стандарт работает без него. Бесплатный редактор в браузере помогает написать и проверить спецификацию до коммита, а затем экспортировать ее в Markdown.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
СкиллыДва скилла для разработки от спецификации: /spec задает вопросы и сохраняет документ в specs/, /spec-impl реализует утвержденную спецификацию по шагам
CLI, MCP-сервер и скилл для разработки по спецификациям: короткие спеки в markdown, доска задач и поиск, понятные агенту.
MCP-сервер для разработки по спецификациям: требования, дизайн и задачи по шагам, с веб-дашбордом и расширением для VS Code
Разработка по спецификациям для кодовых агентов: сначала предложение, требования, дизайн и задачи, потом код
CLI для разработки по спецификациям: агент ведет задачу через файлы в репозитории от плана до проверки и архива
Набор GitHub для разработки от спецификации: CLI specify ставит в проект команды и скиллы для агента, от принципов до реализации
Сравнение с похожими
Карточки с тем же главным запросом: чем они отличаются.
| Инструмент | Официальный | Звезды репозитория | Главное отличие |
|---|---|---|---|
| ProductSpec (эта карточка) | нет | 317 | |
| Spec Kit | нет | 148 171 | набор GitHub для разработки по спецификации с командой specify, а ProductSpec описывает намерение продукта и сверяет с ним отчет агента |
| prd-taskmaster | нет | 608 | превращает цель в PRD и граф задач с исполнением, а ProductSpec задает формат спецификации и проверяет выполнение |
Коротко о README
В README ProductSpec назван стандартом намерения для работы с агентами, рядом перечислены умения агентов с ним и команды обслуживания репозитория. Дальше идут связь намерения с доказательствами, живые спецификации, быстрый старт с демонстрацией, ссылки на гайды для Claude Code, Cursor и Codex и описание установки MCP.
Бейдж для README
Исходный SKILL.md
--- name: productspec description: Use when implementing, reviewing, planning, or changing work governed by a Product Spec. Treat `.product-spec.md` files as the product contract for the work. --- # ProductSpec Agent Skill Product Specs are the product contract for consequential software work. When a repo uses Agent Run files, treat them as the receipt for one agent execution against a pinned Product Spec revision. Before planning, coding, testing, or changing scope, look for relevant `.product-spec.md` files in the repository. Common locations include: - `specs/` - `product-specs/` - `docs/product-specs/` - paths named in the task, issue, pull request, or engineering spec If a relevant Product Spec exists, read it before acting. ## How To Use A Product Spec Read these sections in order: 1. `Problem`: who is hurting and why the work matters. 2. `Hypothesis`: the causal bet behind the product. 3. `Product Summary`: what should exist when the work is done. 4. `Scope`: what is in, out, and deliberately cut. 5. `Acceptance Criteria`: the build contract, including AI evals when present. 6. `Success Metrics`: post-launch outcome checks. 7. `Related Artifacts`: issues, pull requests, eval runs, dashboards, designs, engineering specs, or other Product Specs the work depends on. Acceptance Criteria are the build contract. Plans, tasks, code changes, tests, and pull request summaries should cite the relevant `AC-<number>` IDs. AI evals are pre-launch gates inside Acceptance Criteria, not a separate `## AI Evals` section. Cite `EVAL-<number>` when implementing or changing model behavior. Success Metrics are post-launch outcomes. Do not treat `SM-<number>` items as implementation tasks. ## Planning Rules When creating an implementation plan: - List which Product Spec and `spec_revision` you are implementing. - If ProductSpec MCP is available, call `begin_spec_session` before planning and include the returned `spec_revision` and session id in your plan. - Map each task to the relevant Acceptance Criteria.