Skip to content

migration-guide.md

Latest commit

 

History

History
113 lines (77 loc) · 11.5 KB

migration-guide.md

File metadata and controls

113 lines (77 loc) · 11.5 KB

Руководство по миграции cc-sdd

📖 English version: Migration Guide

cc-sdd 1.x (особенно 1.1.5) и 2.0.0 разделяют одну философию AI-DLC и список команд, но артефакты дизайна, шаблоны и структура steering были перестроены с нуля. Используйте это руководство, чтобы выбрать один из двух чётких путей — либо продолжить использовать 1.1.5 как есть, либо принять изменения и перейти на 2.0.0, где шаблоны/правила делают настройку мгновенной.

TL;DR – выберите свой путь

Цель Рекомендуемое действие
Сохранить legacy 1.x рабочий процесс без изменений Запускайте npx cc-sdd@1.1.5 при установке/обновлении файлов. Продолжайте редактировать папки промптов для агентов (только оригинальные 8 команд spec/steering).
Принять унифицированные шаблоны, разделение research/design и единообразное поведение для всех 7 поддерживаемых агентов Переустановите с npx cc-sdd@latest (=2.0.0) и настраивайте только .kiro/settings/templates/* плюс .kiro/settings/rules/ (полный набор из 11 команд, включая validate-*).

⚠️ Смешивание схем 1.x и 2.x в одном дереве .kiro не поддерживается. Выберите один путь для каждого репозитория/ветки.

Что переносится без изменений

  • Директории .kiro/specs/<функция>/, которые вы уже создали, остаются валидными входными данными; просто перегенерируйте новые шаблоны, когда будете готовы.
  • .kiro/steering/ (или один файл steering.md) можно использовать как есть — содержимое по-прежнему потребляется дословно как память проекта.
  • 11 команд AI-DLC (spec-*, validate-*, steering*) и высокоуровневый поток spec→design→tasks→impl остаются идентичными; только внутренняя часть шаблонов переместилась в just-in-time, агентный стиль.

1. Остаёмся на cc-sdd 1.1.5 (резервный вариант)

1.1.5 больше не на @latest, но вы можете зафиксировать его явно:

npx cc-sdd@1.1.5 --claude-code   # legacy имя флага (используйте --cursor / --gemini / и т.д. для других)
npx cc-sdd@1.1.5 --lang ja       # legacy i18n флаги всё ещё работают
  • Вы можете продолжать редактировать .claude/commands/*, .cursor/prompts/*, .codex/prompts/* и другие папки для агентов напрямую.
  • Схемы директорий для агентов остаются точно такими же, как в v1.
  • Новые функции здесь не появятся — будущая работа нацелена только на @latest.
  • Команды validate (/kiro:validate-gap, -design, -impl) не существуют в 1.1.5. Если вы полагаетесь на эти контрольные точки, мигрируйте на v2.

2. Почему стоит перейти на 2.0.0

Рабочий процесс AI-DLC (spec-init → design → tasks → impl, с контрольными точками валидации) и 11 входных точек команд не изменились. Изменилось где вы настраиваете и сколько структуры предоставляют результирующие документы.

  • Настройка через шаблоны и правила – перестаньте патчить команды; редактируйте .kiro/settings/templates/ и .kiro/settings/rules/ один раз, и каждый агент подхватит это.
  • Качество спецификаций – Research.md фиксирует журналы исследований, а Design.md становится удобным для проверки с таблицами сводки, покрытием требований, справочными ссылками и облегчёнными блоками компонентов/интерфейсов.
  • Steering = Память проекта – размещайте структурированные знания в файлах .kiro/steering/*.md, и каждая команда потребляет их.
  • Защита для brownfield – /kiro:validate-gap, validate-design, validate-impl плюс разделение research/design делают анализ пробелов и обновление существующих систем намного безопаснее.
  • Унифицированное покрытие – все 7 поддерживаемых агентов (Claude Code, Claude Subagents, Cursor, Codex CLI, Gemini CLI, GitHub Copilot, Qwen Code, Windsurf) запускают один и тот же рабочий процесс из 11 команд, поэтому смешивание агентов (например, Cursor + Claude) не требует переписывания спецификаций.

3. Рекомендуемые шаги миграции

  1. Резервное копирование

    cp -r .kiro .kiro.backup
cp -r .claude .claude.backup   # повторите для .cursor, .codex, …

  2. Чистая установка v2 (используйте интерактивный выбор)

    npx cc-sdd@latest                 # по умолчанию (Claude Code)
npx cc-sdd@latest --cursor        # другие агенты
npx cc-sdd@latest --claude-agent  # режим субагентов
    • Установщик теперь спрашивает по каждой группе файлов (перезаписать / добавить / сохранить). Вы можете выбрать "append" для steering/specs для объединения существующих документов, или "keep" для пропуска нетронутых ресурсов.

  3. Перегенерируйте + объедините шаблоны/правила

    • Новая схема: .kiro/settings/templates/ (централизованно) + .kiro/settings/rules/.
    • Сравните новые шаблоны с любой пользовательской логикой, которую вы ранее хранили в папках промптов агентов, и переместите переиспользуемые части в templates/rules.

  4. Переместите пользовательские правила

    • Размещайте Markdown-файлы в .kiro/settings/rules/. Каждая команда spec/design/tasks читает их.
    • Всё, что вы ранее жёстко прописывали в промптах, становится записью правила ("DO/DO NOT …").

  5. Перестройте steering (опционально)

    • Разделите память проекта на файлы типа project-context.md, architecture.md, domain-knowledge.md.
    • Шаблоны research/design ссылаются на эту папку, поэтому мигрируйте существующие заметки сюда.

  6. Обновите автоматизацию

    • Направьте все скрипты/документы на npx cc-sdd@latest; отмените использование @next.
    • Сопоставьте старые ручные вызовы команд с 11 поддерживаемыми (spec-*, validate-*, steering*).

4. Сопоставление legacy-правок с v2

Legacy точка касания Замена в v2 Примечания
.claude/commands/spec-design.prompt.md и т.п. файлы команд для агентов .kiro/settings/templates/specs/design.md Шаблоны теперь живут в .kiro/settings/templates/ и автоматически генерируют Summary/Supporting References.
.claude/commands/<cmd>.prompt, .cursor/prompts/* .kiro/settings/rules/*.md Замените редактирование промптов на общие правила, чтобы каждый агент получал идентичные инструкции.
.kiro/steering/ (один файл или нет) .kiro/steering/*.md с более чёткими принципами/гайдами Тот же путь к папке; v2 просто поощряет разбиение содержимого на сфокусированные гайды памяти проекта.
Заметки исследований, вплетённые в design.md .kiro/specs/<функция>/research.md + секция Supporting References Design остаётся удобным для проверки; research хранит сырые находки без загромождения основного тела.

5. FAQ / устранение неполадок

Могу ли я переиспользовать старые шаблоны внутри v2? – Технически да, но вы теряете покрытие требований и справочные ссылки, поэтому качество генерации падает. Предпочтительнее перенести содержимое в новые templates/rules.

Могу ли я переключаться между 1.1.5 и 2.0.0 в одном репозитории? – Только если вы изолируете .kiro для каждой ветки или автоматизируете обмен директориями; схемы конфликтуют.

После редактирования шаблонов, какие команды запускать? – Как минимум: /kiro:steering, /kiro:spec-init, /kiro:spec-design для перегенерации Research/Design/Tasks в новом формате.

6. Выводы

  • Оставайтесь на 1.1.5, если вам просто нужен legacy рабочий процесс — зафиксируйте версию и продолжайте как раньше.
  • Переходите на 2.0.0, если хотите унифицированные шаблоны, справочные ссылки, разделение research/design и минимальное обслуживание через правила.
  • Будущие функции и исправления нацелены на v2+, поэтому обновление открывает полный опыт разработки на основе спецификаций.