План

Режим планирования: написать план в Markdown, без выполнения.

Метаданные навыка

Источник	Встроенный (установлен по умолчанию)
Путь	skills/software-development/plan
Версия	2.1.0
Автор	VibeOS (writing-craft адаптирован из obra/superpowers)
Лицензия	MIT
Платформы	linux, macos, windows
Теги	planning, plan-mode, implementation, workflow, design, documentation
Связанные навыки	subagent-driven-development, test-driven-development, requesting-code-review

Справочник: полный SKILL.md

к сведению

Ниже приведено полное описание навыка, которое VibeOS загружает при его активации. Это те инструкции, которые видит агент, когда навык активен.

Режим планирования

Используйте этот навык, когда пользователь хочет получить план, а не выполнение.

Основное поведение

В этот раз вы занимаетесь только планированием.

• Не реализуйте код.
• Не редактируйте файлы проекта, кроме файла плана в Markdown.
• Не выполняйте изменяющие терминальные команды, не делайте коммиты, не отправляйте изменения и не совершайте внешних действий.
• При необходимости вы можете просматривать репозиторий или другой контекст с помощью команд/инструментов только для чтения.
• Ваш результат — это план в Markdown, сохранённый внутри активного рабочего пространства в папке .vibeos/plans/ (создайте папку, если нужно). Устаревшая папка .vibeos/plans/ допустима только в том случае, если рабочее пространство уже её использует.

Требования к выводу

Напишите план в Markdown, который будет конкретным и выполнимым.

Включите, если уместно:

• Цель
• Текущий контекст / допущения
• Предлагаемый подход
• Пошаговый план
• Файлы, которые, вероятно, изменятся
• Тесты / проверка
• Риски, компромиссы и открытые вопросы

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

Место сохранения

Сохраните план с помощью write_file по пути:

• .vibeos/plans/YYYY-MM-DD_HHMMSS-<slug>.md

Считайте этот путь относительным к активному рабочему каталогу / рабочему пространству бэкенда. Инструменты для работы с файлами учитывают бэкенд, поэтому этот относительный путь остаётся в рабочем пространстве на локальном, docker, ssh, modal и daytona бэкендах.

Если среда выполнения предоставляет конкретный целевой путь, используйте его. Если нет, создайте самостоятельно осмысленное имя файла с меткой времени в папке .vibeos/plans/.

Стиль взаимодействия

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

---

Как хорошо написать план

Остальная часть этого навыка — это искусство составления хорошего плана реализации — того содержимого, которое помещается в файл Markdown выше.

Обзор

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

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

Основной принцип: Хороший план делает реализацию очевидной. Если кто-то должен догадываться, план неполный.

Когда нужен полный план реализации

Всегда используйте перед:

• Реализацией многошаговых функций
• Разбивкой сложных требований
• Делегированием под-агентам через subagent-driven-development

Не пропускайте, когда:

• Функция кажется простой (допущения приводят к ошибкам)
• Вы планируете реализовать её сами (будущий вы нуждается в руководстве)
• Работаете в одиночку (документация важна)

Размер небольших задач

Каждая задача = 2–5 минут сосредоточенной работы.

Каждый шаг — это одно действие:

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

Слишком крупно:

### Задача 1: Создать систему аутентификации
[50 строк кода в 5 файлах]

Правильный размер:

### Задача 1: Создать модель User с полем email
[10 строк, 1 файл]

### Задача 2: Добавить поле хеша пароля в модель User
[8 строк, 1 файл]

### Задача 3: Создать утилиту для хеширования паролей
[15 строк, 1 файл]

Структура документа плана

Заголовок (обязательно)

Каждый план ДОЛЖЕН начинаться с:

# План реализации [Название функции]

> **Для VibeOS:** Используйте навык subagent-driven-development для реализации этого плана задача за задачей.

**Цель:** [Одно предложение, описывающее, что создаётся]

**Архитектура:** [2–3 предложения о подходе]

**Технологический стек:** [Ключевые технологии/библиотеки]

---

Структура задачи

Каждая задача следует этому формату:

### Задача N: [Описательное название]

**Цель:** Что эта задача выполняет (одно предложение)

**Файлы:**
- Создать: `exact/path/to/new_file.py`
- Изменить: `exact/path/to/existing.py:45-67` (номера строк, если известны)
- Тест: `tests/path/to/test_file.py`

**Шаг 1: Написать падающий тест**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

**Шаг 2: Запустить тест, чтобы убедиться в падении**

Запустить: `pytest tests/path/test.py::test_specific_behavior -v`
Ожидается: FAIL — «function not defined»

**Шаг 3: Написать минимальную реализацию**

```python
def function(input):
    return expected
```

**Шаг 4: Запустить тест, чтобы убедиться в прохождении**

Запустить: `pytest tests/path/test.py::test_specific_behavior -v`
Ожидается: PASS

**Шаг 5: Закоммитить**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

Процесс написания

Шаг 1: Понять требования

Прочитайте и поймите:

• Требования к функции
• Дизайн-документы или описание пользователя
• Критерии приёмки
• Ограничения

Шаг 2: Исследовать кодовую базу

Используйте инструменты VibeOS для понимания проекта:

# Понять структуру проекта
search_files("*.py", target="files", path="src/")

# Посмотреть на похожие функции
search_files("similar_pattern", path="src/", file_glob="*.py")

# Проверить существующие тесты
search_files("*.py", target="files", path="tests/")

# Прочитать ключевые файлы
read_file("src/app.py")

Шаг 3: Спроектировать подход

Решите:

• Архитектурный паттерн
• Организацию файлов
• Необходимые зависимости
• Стратегию тестирования

Шаг 4: Написать задачи

Создайте задачи по порядку:

1. Настройка/инфраструктура
2. Основная функциональность (TDD для каждой)
3. Крайние случаи
4. Интеграция
5. Очистка/документация

Шаг 5: Добавить полные детали

Для каждой задачи включите:

• Точные пути к файлам (не «файл конфигурации», а src/config/settings.py)
• Полные примеры кода (не «добавить валидацию», а сам код)
• Точные команды с ожидаемым выводом
• Шаги проверки, которые доказывают, что задача работает

Шаг 6: Проверить план

Убедитесь:

• Задачи последовательны и логичны
• Каждая задача небольшая (2–5 мин)
• Пути к файлам точны
• Примеры кода полны (можно скопировать и вставить)
• Команды точны с ожидаемым выводом
• Нет недостающего контекста
• Применены принципы DRY, YAGNI, TDD

Принципы

DRY (Don't Repeat Yourself — Не повторяйся)

Плохо: Копировать валидацию в 3 местах Хорошо: Вынести функцию валидации, использовать везде

YAGNI (You Aren't Gonna Need It — Вам это не понадобится)

Плохо: Добавлять «гибкость» для будущих требований Хорошо: Реализовать только то, что нужно сейчас

# Плохо — нарушение YAGNI
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email
        self.preferences = {}  # Пока не нужно!
        self.metadata = {}     # Пока не нужно!

# Хорошо — YAGNI
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email

TDD (Test-Driven Development — Разработка через тестирование)

Каждая задача, которая создаёт код, должна включать полный цикл TDD:

1. Написать падающий тест
2. Запустить, чтобы убедиться в падении
3. Написать минимальный код
4. Запустить, чтобы убедиться в прохождении

Подробнее см. в навыке test-driven-development.

Частые коммиты

Делайте коммит после каждой задачи:

git add [файлы]
git commit -m "type: description"

Распространённые ошибки

Расплывчатые задачи

Плохо: «Добавить аутентификацию» Хорошо: «Создать модель User с полями email и password_hash»

Неполный код

Плохо: «Шаг 1: Добавить функцию валидации» Хорошо: «Шаг 1: Добавить функцию валидации» с последующим полным кодом функции

Отсутствие проверки

Плохо: «Шаг 3: Проверить, что работает» Хорошо: «Шаг 3: Запустить pytest tests/test_auth.py -v, ожидается: 3 passed»

Отсутствие путей к файлам

Плохо: «Создать файл модели» Хорошо: «Создать: src/models/user.py»

Передача на выполнение

После сохранения плана предложите подход к выполнению:

«План завершён и сохранён. Готов выполнить с помощью subagent-driven-development — я отправлю свежего под-агента на каждую задачу с двухэтапной проверкой (соответствие спецификации, затем качество кода). Продолжить?»

При выполнении используйте навык subagent-driven-development:

• Свежий delegate_task на каждую задачу с полным контекстом
• Проверка соответствия спецификации после каждой задачи
• Проверка качества кода после прохождения спецификации
• Продолжать только после одобрения обеих проверок

Запомните

Небольшие задачи (2–5 мин каждая)
Точные пути к файлам
Полный код (можно скопировать и вставить)
Точные команды с ожидаемым выводом
Шаги проверки
DRY, YAGNI, TDD
Частые коммиты

Хороший план делает реализацию очевидной.