Spec Kit

Spec Kit

Назначение

В репозитории spec kit используется как рабочий контур для feature-level спецификаций и планирования реализации. Он не заменяет проектные документы из doc/*.adoc, а дополняет их.

Разделение ролей такое:

  • doc/prd.adoc фиксирует продуктовые и архитектурные решения уровня проекта

  • doc/status.adoc фиксирует фактическое состояние реализации

  • doc/doc.adoc фиксирует актуальный API и интерфейсы

  • spec kit используется для проработки отдельных фич, изменений и delivery workflow

Что уже настроено

В проект уже добавлены:

  • каталог .specify/ с шаблонами и конфигурацией specify

  • интеграция codex, зафиксированная в .specify/integration.json

  • набор базовых skills speckit-* в .agents/skills/

  • отдельный набор skills ml-llm-* для ML/LLM delivery pipeline

  • каталог ML LLM Delivery Pipeline/ с исходными шаблонами документов

Текущая инициализация выполнена для работы specify прямо в этом репозитории, без отдельного sidecar-проекта.

Базовый workflow

Рекомендуемая последовательность работы с фичей:

  1. Зафиксировать feature intent через speckit-specify

  2. Уточнить пробелы через speckit-clarify, если постановка неполная

  3. Подготовить план реализации через speckit-plan

  4. Разбить работу на задачи через speckit-tasks

  5. Перед реализацией проверить согласованность через speckit-analyze

  6. После этого переходить к исполнению через speckit-implement

Если задача меняет проектные инварианты, публичный API или roadmap, изменения должны быть синхронизированы и в doc/*.adoc, а не оставаться только внутри feature-артефактов spec kit.

Структура артефактов

spec kit в этом репозитории отвечает за два слоя.

1. Базовые feature-артефакты

Они создаются и поддерживаются через .specify/templates/:

  • spec-template.md

  • plan-template.md

  • tasks-template.md

  • checklist-template.md

  • constitution-template.md

Эти шаблоны нужны для обычного feature workflow: требования, план, задачи, проверки и проектные принципы.

2. ML / LLM delivery pipeline

Для ML/LLM-направления в репозитории дополнительно заведён отдельный pipeline документов:

  • 01 PRD Template.md

  • 02 System Design Doc Template.md

  • 03 ADR Template.md

  • 04 Service Spec Template.md

  • 05 Evaluation Plan Template.md

  • 06 Delivery Plan Template.md

  • 07 Runbook Template.md

  • 08 Security Note Template.md

  • 09 Prompt Template.md

Оркестрация этого набора описана в skill ml-llm-delivery-pipeline. Документный pipeline должен использоваться поверх существующей документации проекта, а не параллельно ей.

Проектные правила использования

При работе со spec kit в этом репозитории нужно соблюдать следующие правила:

  • не плодить второй набор канонических проектных документов рядом с doc/*.adoc

  • использовать spec kit для feature-level проработки, а не как замену общей документации проекта

  • после принятия решения переносить устойчивые выводы в PRD, status или API reference, если они стали частью проекта

  • использовать ML LLM Delivery Pipeline только там, где действительно нужен полный delivery set, а не для каждой мелкой правки

  • адаптировать шаблоны под терминологию TextFoundry, а не оставлять generic ML/LLM формулировки

Где что лежит

  • .specify/ — конфигурация, шаблоны и integration manifests

  • .agents/skills/speckit-* — базовые skills для feature workflow

  • .agents/skills/ml-llm-* — skills для ML/LLM document pipeline

  • ML LLM Delivery Pipeline/ — исходные шаблоны pipeline-документов

Практический критерий

Если результат нужен как часть долгоживущей проектной документации, он должен оказаться в doc/*.adoc.

Если результат нужен как рабочий артефакт конкретной фичи или delivery-пакета, его можно вести через spec kit и связанные templates.