🏠 Главная › user guide › software development writing plans

{/ Эта страница автоматически передается из навыков SKILL.md с помощью сайта/scripts/generate-skill-docs.py. Редактируйте исходный SKILL.md, а не эту страницу. /}

Составление плана

Пишите планы реализации: небольшие задачи, пути, код.

Метаданные навыки
Источник Встроенный (устанавливается по умолчанию)
Путь навыки/разработка программного обеспечения/планы написания
Версия 1.1.0
Автор Агент Гермеса (адаптировано из образа/суперспособностей)
Лицензия Массачусетский технологический институт
Платформы Linux, MacOS, Windows
Теги планирование, проектирование, реализация, рабочий процесс, документация
Связанные навыки разработка-под агентом, test-driven-development, requesting-code-review

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

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

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

Обзор

Пишите комплексные планы реализации, предполагая, что исполнитель не имеет контекста кодовой базы и сомнительного вкуса. Документируйте все, что ему нужно: какие файлы трогать, полный код, команды тестирования, документацию для проверок, как проверить. Давайте ему небольшие задачи. СУХОЙ. ЯГНИ. ТДД. Частные комитеты.

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

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

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

Всегда викорируйте перед: - Реализация многошаговых функций - Разбивка требований - Делегированием подагентам через субагентную разработку

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

Гранулярность мелких задач

Каждая задача = 2-5 минут целенаправленной работы.

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

Слишком большой:

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

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

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

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

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

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

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

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

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

> **Для Hermes:** Используйте навык 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
защита test_special_behavior():
    результат = функция (вход)
    утверждать результат == ожидается
```

**Шаг 2: Запустить тест для проверки падения**

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

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

```python
функция определения (вход):
    ожидается возврат
```

**Шаг 4: Запустить тест для проверки прохождения**

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

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

```bash
git добавить тесты/путь/test.py src/path/file.py
git commit -m "подвиг: добавить конкретную функцию"
```

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

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

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

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

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

# Понять структуру проекта
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

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

mkdir -p docs/plans
# Сохранить план в docs/plans/YYYY-MM-DD-feature-name.md
git add docs/plans/
git commit -m "docs: add implementation plan for [feature]"

Принципы

DRY (Не повторяйся — Не повторяйся)

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

ЯГНИ (Тебе это не понадобится — Вам это не понадобится)

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

# Плохо — нарушение 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. Запустите процедуру проверки.

См. навыки разработки через тестирование для подробностей.

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

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

git add [files]
git commit -m "type: description"

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

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

Плохо: "Добавить аутентификацию" Хорошо: "Создать модель пользователя с полями электронной почты и пароля_хэша"

Неполный код

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

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

Плохо: "Шаг 3: Посмотреть, что работает" Хорошо: "Шаг 3: Запустить pytesttests/test_auth.py -v, помощник: 3 пройдено"

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

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

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

После сохранения плана предлагается подход к завершению:

"План завершён и сохранён. Готов к завершению с использованием субагентной разработки — я отправлю свежего подагента на каждую задачу с двухэтапной проверкой (соответствие характеристик, затем код качества). Продолжить?"

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

Запомните

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

Хороший план создания очевидной.