On this page Пишите планы реализации: задачи небольшого объёма, пути, код.

Skill metadata¶

|---|---
Source| Встроенный (установлен по умолчанию)
Path| skills/software-development/writing-plans
Version| 1.1.0
Author| Hermes Agent (адаптировано из obra/superpowers)
License| MIT
Tags| planning, design, implementation, workflow, documentation
Related skills| subagent-driven-development, test-driven-development, requesting-code-review

Reference: full SKILL.md¶

info Ниже приведено полное определение навыка, которое Hermes загружает при активации этого навыка. Именно эти инструкции видит агент, когда навык активен.

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

Обзор¶

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

Когда использовать¶

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

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

Размер задач: небольшой объём¶

Каждая задача = 2–5 минут целенаправленной работы. Каждый шаг — одно действие: * «Напишите падающий тест» — шаг * «Запустите его, чтобы убедиться, что он падает» — шаг * «Реализуйте минимальный код, чтобы тест прошёл» — шаг * «Запустите тесты и убедитесь, что они проходят» — шаг * «Закоммитьте» — шаг

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

[/code] Правильный размер: [code] ### Задача 1: Создание модели User с полем email
[10 строк, 1 файл]

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

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

[/code]

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

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

Каждый план ОБЯЗАТЕЛЬНО должен начинаться с: [code] # План реализации [Название функции]

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

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

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

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

---

[/code]

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

Каждая задача следует этому формату: [code] ### Задача 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: добавить конкретную функцию"  
```

[/code]

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

Шаг 1: Поймите требования¶

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

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

Используйте инструменты Hermes для понимания проекта: [code] # Понять структуру проекта
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")

[/code]

Шаг 3: Спроектируйте подход¶

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

Шаг 4: Напишите задачи¶

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

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

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

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

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

Шаг 7: Сохраните план¶

[code] mkdir -p docs/plans
# Сохраните план в docs/plans/YYYY-MM-DD-feature-name.md
git add docs/plans/
git commit -m "docs: добавить план реализации для [функции]"

[/code]

Принципы¶

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

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

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

Плохо: Добавлять «гибкость» для будущих требований Хорошо: Реализовывать только то, что нужно сейчас [code] # Плохо — нарушение 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

[/code]

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

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

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

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

Коммитьте после каждой задачи: [code] git add [files]
git commit -m "type: описание"

[/code]

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

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

Плохо: «Добавить аутентификацию» Хорошо: «Создать модель 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 на каждую задачу с полным контекстом * Проверка соответствия спецификации после каждой задачи * Проверка качества кода после прохождения спецификации * Продолжайте только после одобрения обеих проверок

Запомните¶

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

[/code] Хороший план делает реализацию очевидной. * Skill metadata * Reference: full SKILL.md * Обзор * Когда использовать * Размер задач: небольшой объём * Структура документа плана * Заголовок (обязательно) * Структура задачи * Процесс написания * Шаг 1: Поймите требования * Шаг 2: Исследуйте кодовую базу * Шаг 3: Спроектируйте подход * Шаг 4: Напишите задачи * Шаг 5: Добавьте полные детали * Шаг 6: Проверьте план * Шаг 7: Сохраните план * Принципы * DRY (Don't Repeat Yourself — не повторяйся) * YAGNI (You Aren't Gonna Need It — вам это не понадобится) * TDD (Test-Driven Development — разработка через тестирование) * Частые коммиты * Распространённые ошибки * Расплывчатые задачи * Неполный код * Отсутствие верификации * Отсутствие путей к файлам * Передача на исполнение * Запомните

Skill metadata​¶

Reference: full SKILL.md​¶

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

Обзор​¶

Когда использовать​¶

Размер задач: небольшой объём​¶

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

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

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

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

Шаг 1: Поймите требования​¶

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

Шаг 3: Спроектируйте подход​¶

Шаг 4: Напишите задачи​¶

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

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

Шаг 7: Сохраните план​¶

Принципы​¶

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

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

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

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

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

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

Неполный код​¶

Отсутствие верификации​¶

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

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

Запомните​¶

Skill metadata¶

Reference: full SKILL.md¶

Обзор¶

Когда использовать¶

Размер задач: небольшой объём¶

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

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

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

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

Шаг 1: Поймите требования¶

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

Шаг 3: Спроектируйте подход¶

Шаг 4: Напишите задачи¶

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

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

Шаг 7: Сохраните план¶

Принципы¶

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

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

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

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

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

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

Неполный код¶

Отсутствие верификации¶

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

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

Запомните¶