FAQ

Чем spec отличается от inspect?

spec создает или обновляет спецификацию фичи.

inspect проверяет эту спецификацию и связанные артефакты на полноту, согласованность и соответствие конституции. Это опциональный quality gate, а не authoring phase.

Когда нужно создавать research.md?

research.md нужен только тогда, когда есть реальная неопределенность, которую стоит сохранить:

• нужно изучить внешний протокол или интеграцию
• сравниваются несколько архитектурных вариантов
• проектное решение требует подтверждающего исследования

Не стоит создавать его по умолчанию для каждой фичи.

Когда нужно архивировать фичу?

Фичу стоит архивировать, когда она больше не находится в active workflow, например если она:

• завершена
• вытеснена новой версией
• отклонена
• abandoned
• deferred

Архив сохраняет историю, не раздувая активное рабочее пространство.

Чем remove-agent отличается от cleanup-agents?

remove-agent обновляет .speckeep/speckeep.yaml и удаляет generated files для выбранных включенных targets.

cleanup-agents удаляет leftover orphaned files, которые больше не соответствуют набору включенных targets в config.

После любой из этих команд удобно запускать doctor, чтобы проверить здоровье workspace.

Как обновить промты, скрипты и agent files в уже существующем проекте?

Используй speckeep refresh [path].

refresh обновляет только SpecKeep-managed generated artifacts, например .speckeep/templates/, .speckeep/scripts/, .speckeep/speckeep.yaml, project-local agent files и managed SpecKeep block внутри AGENTS.md.

При этом команда не изменяет содержимое authored feature state (constitution.md, specs/active/, specs/archived/), но может безопасно перенести директории спецификаций/архива при использовании --specs-dir / --archive-dir.

Почему SpecKeep оставляет Given / When / Then на английском даже в русской документации?

Эти маркеры намеренно сделаны каноническими. Агентам так проще распознавать их стабильно, а правилам валидации проще их проверять.

Остальной текст документа при этом может быть на русском.

Нужно ли implement всегда читать весь feature package?

Нет. implement должен стартовать от tasks.md и подтягивать более глубокие артефакты только тогда, когда этого требует активная задача.

Типичный минимальный порядок чтения:

• tasks.md
• .speckeep/constitution.summary.md, если нужен policy-контекст
• затем CONSTITUTION.md только если summary отсутствует или недостаточен
• затем spec.md, plan.md, data-model.md, contracts/ или research.md только при необходимости

Может ли plan работать без spec?

Нет. Предполагаемая цепочка строгая:

constitution -> spec -> [inspect, опционально] -> plan -> tasks -> implement -> verify -> archive

plan зависит от уже существующей spec.

Зачем нужны стабильные идентификаторы критериев?

Идентификаторы вроде AC-001 делают traceability дешевле и понятнее между spec, tasks, inspect-отчетами и будущей фазой verification.

Для чего нужен verify?

verify — это легкая подтверждающая фаза после implement. Она помогает ответить, достаточно ли фича согласована с tasks, spec, plan artifacts и правилами проекта, чтобы двигаться к архивированию или заявлению о завершенности.