writing-plans - План разработки с точными проверками

Когда звать

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

Для кого написан план

Writing-plans рассчитан на передачу работы инженеру, который ещё не видел ни проект, ни описание задачи. Он умеет писать на языке проекта, но не знает ваших решений: какие файлы менять, как назвать функцию и какие значения обязательны. Скилл требует записать именно эти сведения. Это помогает передавать реализацию другому агенту без длинного пересказа предыдущего разговора.

На входе нужны требования или согласованный замысел многошаговой работы. Сначала агент проверяет масштаб: независимым подсистемам лучше дать отдельные планы, каждый с работающим и проверяемым результатом. Затем он составляет карту создаваемых и изменяемых файлов. В существующем репозитории инструкция предлагает соблюдать принятые способы организации, а не устраивать постороннюю перестройку ради нового документа.

Что должно быть внутри

В заголовочной части перечисляются цель, архитектурный подход, технологии и путь к исходному описанию. Общие ограничения переносятся с точными значениями, чтобы каждая задача учитывала минимальные версии, ограничения зависимостей, правила имён и текста. Отдельный раздел Review Focus посвящён условиям, которые следуют из замысла, но ещё не покрыты тестами конкретных задач. Для найденных рисков проверки добавляются в ответственную задачу.

У каждой задачи есть файлы и блок Interfaces. Он объясняет, что задача получает от предыдущих частей и что предоставляет следующим: точные имена, параметры и типы результата. Это особенно важно, когда исполнитель видит только свой фрагмент. Несовпадение названий между соседними задачами считается ошибкой плана, даже если оба названия по отдельности выглядят разумно.

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

Как не раздуть документ

Автор определяет задачу как самостоятельный результат со своим циклом проверки. Подготовку, настройки и документацию следует включать туда, где они необходимы для результата, вместо создания искусственных отдельных этапов. Слишком длинный план, в котором почти всё занято кодом, тоже признаётся проблемой: документ подменяет реализацию. Расплывчатые указания вроде «добавить подходящие проверки» остаются противоположной ошибкой.

После записи автор сам сверяет покрытие требований, точность шагов, согласованность типов и соразмерность текста. По умолчанию файл находится в docs/superpowers/plans/. Затем человек читает план и подтверждает способ выполнения. Executing-plans означает реализацию в текущей сессии; другой вариант использует отдельных исполнителей. Мы проверили текст источника и лицензию MIT, но не испытывали качество планов, которые этот скилл создаст в вашем проекте.