writing-plans

name	writing-plans
description	Используй когда есть спек или требования для многошагового задания, до того как трогать код или конфиги

Написание планов реализации

Обзор

Пиши исчерпывающие планы реализации, предполагая что исполнитель не имеет контекста кодовой базы. Документируй всё необходимое: какие файлы трогать в каждой задаче, код/конфиги, шаги тестирования, как верифицировать. Давай весь план мелкими задачами. DRY. YAGNI. TDD.

Предполагай квалифицированного разработчика, который почти ничего не знает о нашем стеке и предметной области.

Объяви в начале: «Использую скилл writing-plans для создания плана реализации.»

Сохраняй планы в: docs/plans/YYYY-MM-DD-<название-фичи>.md

• Создай директорию docs/plans/, если её нет
• (Предпочтения пользователя по расположению переопределяют дефолт)

Проверка масштаба

Если спек охватывает несколько независимых подсистем, его нужно было разбить на под-спеки ещё на этапе брейнсторминга. Если этого не сделано — предложи разбить на отдельные планы, по одному на подсистему. Каждый план должен производить работающее, тестируемое программное обеспечение самостоятельно.

Файловая структура

До определения задач составь карту файлов которые будут созданы или изменены и за что каждый отвечает.

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

Эта структура информирует декомпозицию задач. Каждая задача должна производить самостоятельные изменения, понятные независимо от других.

Гранулярность задач

Каждый шаг — одно действие (2-5 минут):

• «Написать падающий тест» — шаг
• «Запустить тест и убедиться что он падает» — шаг
• «Реализовать минимальный код/конфиг для прохождения теста» — шаг
• «Запустить верификацию и подтвердить что проходит» — шаг

Шаблоны плана и задачи

Шаблоны заголовка документа и структуры задачи (TDD-шаги) — references/plan-templates.md

Запрет на плейсхолдеры

Каждый шаг должен содержать реальное содержимое необходимое исполнителю. Это провалы плана — никогда не пиши:

• «TBD», «TODO», «реализовать позже», «заполнить детали»
• «Добавить соответствующую обработку ошибок» / «добавить валидацию» / «обработать граничные случаи»
• «Написать тесты для вышеуказанного» (без реального кода теста)
• «Аналогично задаче N» (повтори код — исполнитель может читать задачи не по порядку)
• Шаги описывающие что делать без показа как (блоки кода обязательны для шагов с кодом)

Помни

• Точные пути к файлам всегда
• Полный код/конфиг в каждом шаге — если шаг меняет код, покажи код
• Точные команды с ожидаемым выводом
• DRY, YAGNI, TDD

Само-ревью

После написания полного плана посмотри на спек свежим взглядом.

1. Покрытие спека: Просмотри каждый раздел/требование спека. Можешь указать на задачу которая его реализует? Перечисли пробелы.

2. Проверка плейсхолдеров: Поищи красные флаги — паттерны из раздела «Запрет на плейсхолдеры». Исправь их.

3. Согласованность имён: Совпадают ли имена, сигнатуры методов и ключи конфигов в поздних задачах с тем что определено в ранних?

Находи проблемы — исправляй на месте. Если найдёшь требование спека без задачи — добавь задачу.

Финальные задачи плана (опционально)

После само-ревью, до передачи на исполнение, спроси пользователя:

«Добавить в конец плана финальные задачи?

1. Запуск проверок качества кода — если в проекте есть линтеры/тайпчекеры/форматтеры/тесты (определю по CLAUDE.md, package.json, pyproject.toml, Makefile, justfile и т.п.).
2. Код-ревью изменений — вызов скилла code-review по итоговому диффу.

Да / нет / только одну из них?»

Если пользователь согласился:

1. Для проверок качества — определи реальные команды из конфигов проекта (например, npm run lint, ruff check, mypy, just lint, make lint). Не выдумывай команды, которых нет в проекте. Если ничего не нашёл — сообщи пользователю и пропусти этот пункт.
2. Допиши соответствующие задачи в конец файла плана, соблюдая ту же гранулярность и формат (точная команда, ожидаемый вывод, что делать при провале).
3. Задача код-ревью:
   • Сначала проверь, есть ли в проекте субагент для код-ревью (например, code-reviewer или похожий — смотри .claude/agents/ в проекте и ~/.claude/agents/, а также список доступных субагентов).
   • Если субагент есть — задача должна явно содержать: «Запусти субагент <имя-субагента> через tool Agent для ревью изменений, внесённых этим планом. Передай ему диф и контекст плана.»
   • Если субагента нет — задача должна явно содержать: «Вызови скилл code-review по изменениям, внесённым этим планом.»
   • В обоих случаях: «Исправления не делай, обсуди их сначала с пользователем.»

Если отказался: ничего не добавляй и переходи к передаче на исполнение.

Передача на исполнение

После сохранения плана спроси пользователя, как продолжить:

«План сохранён в docs/plans/<имя-файла>.md. Как продолжим?

1. executing-plans сейчас — начну выполнение в текущем контекстном окне.
2. next-stage-prompt — сгенерирую готовый промпт со ссылкой на план, чтобы ты вставил его в новый чистый контекст.»

Жди ответа и вызови выбранный скилл:

• Вариант 1 → вызови executing-plans
• Вариант 2 → вызови next-stage-prompt

НЕ вызывай никакой другой скилл и не выбирай за пользователя.