Проектирование многошагового рабочего процесса Skills

Простые задачи требуют только одного шага, но реальные рабочие процессы часто включают несколько этапов.

В этой статье рассказывается, как разбить сложные задачи на понятные шаги и организовать их в надёжный рабочий процесс выполнения в SKILL.md.


Почему стоит явно определять шаги

Claude очень умён, но без явного пошагового руководства он может пропустить некоторые этапы или выполнить их в непоследовательном порядке.

Преимущества явных шагов:

Во-первых, это делает поведение Claude предсказуемым; во-вторых, помогает пользователям понимать, что происходит; в-третьих, при возникновении ошибок легко определить, на каком шаге что-то пошло не так.


Основные принципы проектирования шагов

Принцип Описание
Каждый шаг выполняет только одно действие Избегайте того, чтобы один шаг выполнял несколько несвязанных операций одновременно
Чёткие входы и выходы между шагами Выход предыдущего шага является входом следующего шага, без опоры на неявное состояние
Предоставляйте обратную связь после выполнения каждого шага Сообщайте пользователю, что завершил этот шаг и каким будет следующий шаг
Разрешайте прерывание на полпути Пользователи могут приостанавливать или изменять параметры на любом шаге

Определение многошаговых рабочих процессов в SKILL.md

Пример

---
name: excel-report-generator
описание: >
Создайте форматированный отчёт Excel на основе необработанных данных, загруженных пользователем, включая очистку данных,
создание диаграмм и сводную статистику. Запускайте, когда пользователю нужен отчёт по данным, вывод в Excel,
или автоматизированная статистика.
---

# Генератор отчётов Excel

## Рабочий процесс выполнения

### Шаг 1: Чтение и проверка данных

1. Проверьте, существует ли файл и имеет ли он формат .csv или .xlsx
2. Прочитайте файл и выведите основную информацию:
- Всего строк, всего столбцов
- Тип данных каждого столбца
- Количество пропущенных значений
3. Если обнаружены серьёзные проблемы (например, файл пуст или формат не поддерживается), остановитесь и сообщите пользователю

**Вывод**: Базовый отчёт с информацией о данных (отображается в диалоге)

---

### Шаг 2: Очистка данных

Запустите`scripts/clean_data.py`, который выполняет:
- Удалить полностью дублирующиеся строки
- Заполнить пропущенные значения в числовых столбцах с помощью0
- Удалить начальные и конечные пробелы в строках

Выведите очищенные данные в`/home/claude/cleaned_data.csv`

**Вывод**: Отчёт об очистке (сколько строк было удалено, сколько значений было изменено)

---

### Шаг 3: Создание статистической сводки

Запустите`scripts/calc_stats.py`, который вычисляет:
- Среднее, медиана и стандартное отклонение для каждого числового столбца
- Данные тренда, сгруппированные по столбцу времени (если столбец времени существует)

Вывод в`/home/claude/stats.json`

---

### Шаг 4: Создание отчёта Excel

Запустите`scripts/gen_excel.py`, чтобы создать файл Excel, содержащий следующее:
- Sheet1: очищенные исходные данные
- Sheet2: таблица статистической сводки
- Sheet3: линейный график (если есть данные временных рядов)

Сохраните итоговый файл в`/mnt/user-data/outputs/report_YYYYMMDD.xlsx`

**Вывод**: Вызовите present_files, чтобы отобразить файл и предоставить ссылку для скачивания

---

### Обработка ошибок

Когда какой-либо шаг завершается неудачно:
1. Показать полное сообщение об ошибке
2. Объяснить возможные причины
3. Спросить пользователя, хочет ли он пропустить текущий шаг или повторить попытку после изменения параметров

Как организовать скрипты шагов

Каждый шаг многошагового рабочего процесса может соответствовать отдельному файлу скрипта или быть объединён в один основной скрипт.

Вариант 1: Один скрипт на шаг (рекомендуется для сложных рабочих процессов)

excel-report-generator/
├── SKILL.md
└── scripts/
    ├── clean_data.py      # 第二步:数据清洗
    ├── calc_stats.py      # 第三步:统计计算
    └── gen_excel.py       # 第四步:生成报告

Вариант 2: Единый основной скрипт (подходит для простых рабочих процессов)

Пример

# Путь к файлу: scripts/pipeline.py
# Единый основной скрипт; используйте параметр --step, чтобы управлять тем, какой шаг выполняется

import argparse
import sys

def step_clean(input_file: str, output_file: str) -> dict:
    """Шаг 2: Очистка данных"""
    print(f"Очистка данных: {input_file}")
    # Фактическая логика очистки...
    return {"status": "success", "removed_rows": 3, "fixed_values": 12}

def step_stats(input_file: str, output_file: str) -> dict:
    """Шаг 3: Статистический расчет"""
    print(f"Вычисление статистики: {input_file}")
    # Фактическая логика статистики...
    return {"status": "success", "columns_analyzed": 5}

def step_excel(data_file: str, stats_file: str, output_file: str) -> dict:
    """Шаг 4: Генерация Excel"""
    print(f"Генерация отчета Excel: {output_file}")
    # Фактическая логика генерации...
    return {"status": "success", "output": output_file}

STEPS = {
    "clean": step_clean,
    "stats": step_stats,
    "excel": step_excel,
}

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--step",   required=True, choices=STEPS.keys(),
                        help="Шаг для запуска: clean / stats / excel")
    parser.add_argument("--input",  required=True, help="Путь к входному файлу")
    parser.add_argument("--output", required=True, help="Путь к выходному файлу")
    args = parser.parse_args()

    import json
    result = STEPS[args.step](args.input, args.output)
    print(json.dumps(result, ensure_ascii=False, indent=2))

Вызов этого скрипта в SKILL.md:

Пример

# Шаг 2: Очистка данных
python scripts/pipeline.py \
  --step clean \
  --input /mnt/user-data/uploads/example_sales.csv \
  --output /home/claude/cleaned_data.csv

# Шаг 3: Статистический расчёт
python scripts/pipeline.py \
  --step stats \
  --input /home/claude/cleaned_data.csv \
  --output /home/claude/stats.json

Проверки зависимостей между шагами

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

Пример

# Путь к файлу: scripts/check_deps.py
import os
import sys

def check_step_deps(step_name: str, required_files: list) -> bool:
    """
Проверить, были ли сгенерированы необходимые файлы шага

Параметры:
step_name: Имя текущего шага (используется для сообщений об ошибках)
required_files: Список путей к файлам, которые должны существовать

Возвращает:
True означает, что все зависимости готовы, False означает, что некоторые файлы отсутствуют
    """

    missing = [f for f in required_files if not os.path.exists(f)]

    if missing:
        print(f"Ошибка: {step_name} — отсутствуют необходимые файлы:")
        for f in missing:
            print(f"  - {f}")
        print("Пожалуйста, сначала выполните предварительные шаги.")
        return False

    return True

# Пример использования: проверка предварительных файлов перед созданием Excel на шаге 4
if __name__ == "__main__":
    deps = [
        "/home/claude/cleaned_data.csv",
        "/home/claude/stats.json"
    ]
    if not check_step_deps("Создать отчет Excel", deps):
        sys.exit(1)
    print("Все предварительные файлы готовы, начинаю создание отчета...")
错误:生成 Excel 报告 缺少前置文件:
  - /home/claude/stats.json
请先完成前置步骤。

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

Другие расширения