# Эксперт по промпт-инжинирингу — лучшие практики

Этот документ сводит лучшие практики из официальной документации Anthropic и Claude Cookbooks для полноценного навыка промпт-инжиниринга.

## Основные принципы

### 1. Ясность и прямота
- **Формулируй прямо:** точно указывай, что Claude должен сделать.
- **Избегай двусмысленности:** используй формулировки, которые трудно истолковать неверно.
- **Давай конкретные примеры:** показывай, а не только рассказывай.
- **Выстраивай логично:** организуй информацию по иерархии.

### 2. Краткость
- **Помни об окне контекста:** оставляй в промпте то, что относится к делу.
- **Убирай повторы:** исключай ненужное дублирование.
- **Раскрывай детали постепенно:** давай их, когда они понадобятся.
- **Экономь токены:** учитывай и качество, и стоимость.

### 3. Уместная степень свободы
- **Определяй ограничения:** ясно указывай, что Claude должен и не должен делать.
- **Задавай формат:** прямо описывай желаемый вид ответа.
- **Очерчивай объём:** показывай, что входит в задачу и что вне её.
- **Сохраняй гибкость:** оставляй пространство для рассуждений Claude, удерживая нужный контроль.

## Продвинутые приёмы

### Промпты с пошаговым рассуждением (CoT)
Побуждай к последовательному анализу сложных задач:
```
«Давай разберём это по шагам:
1. Сначала определи...
2. Затем проанализируй...
3. Наконец, сделай вывод...»
```

### Промпты с несколькими примерами
Направляй поведение примерами:
- **Один пример:** для простых задач.
- **Два примера:** для задач умеренной сложности.
- **Несколько примеров:** для сложных паттернов.

### Теги XML для структуры
Используй теги XML, чтобы текст был понятным и пригодным для разбора:
```xml
<task>
  <objective>Что нужно сделать</objective>
  <constraints>Ограничения и правила</constraints>
  <format>Ожидаемый формат ответа</format>
</task>
```

### Промпты с ролью
Назначай Claude область экспертизы:
```
«Ты эксперт по промпт-инжинирингу с глубокими знаниями о...
Твоя задача — ...»
```

### Предзаполнение
Начинай ответ Claude, чтобы направить формат:
```
«Вот мой анализ:

Основные выводы:»
```

### Цепочки промптов
Разбивай сложные задачи на последовательные запросы:
1. Промпт 1: проанализировать входные данные.
2. Промпт 2: обработать результат анализа.
3. Промпт 3: сформировать ответ.

## Пользовательские инструкции и системные промпты

### Проектирование системных промптов
- **Определи роль:** какой экспертизой должен обладать Claude?
- **Задай тон:** какой стиль общения подходит?
- **Установи ограничения:** чего Claude следует избегать?
- **Проясни объём:** какова область экспертизы?

### Правила поведения
- **Делай:** какие конкретные действия поощряются.
- **Не делай:** каких действий следует избегать.
- **Пограничные случаи:** как поступать в необычных ситуациях.
- **Эскалация:** когда просить уточнение.

## Лучшие практики структуры навыка

### Именование
- Используй **форму герундия** (глагол + -ing): `analyzing-financial-statements`.
- Пиши **строчными буквами через дефис:** `prompt-engineering-expert`.
- Название должно **объяснять назначение** навыка.
- Избегай **общих названий:** указывай конкретную область.

### Хорошие описания
- **Первая строка:** ясная и краткая сводка (не более 1024 символов).
- **Конкретность:** перечисли точные возможности.
- **Сценарии:** назови основные способы применения.
- **Без расплывчатости:** не ограничивайся словами «помогает с» или «содействует».

### Постепенное раскрытие деталей

**Шаблон 1: обзор со ссылками**
- Начни с общего описания.
- Дай ссылки на подробные разделы.
- Расположи материал по сложности.

**Шаблон 2: организация по предметным областям**
- Группируй по сценариям.
- Разделяй разные задачи.
- Сделай навигацию ясной.

**Шаблон 3: подробности по условию**
- Показывай детали с учётом контекста.
- Приводи примеры для каждого пути.
- Не перегружай вариантами.

### Структура файлов
```
skill-name/
├── SKILL.md (обязательные метаданные)
├── CLAUDE.md (основные инструкции)
├── reference-guide.md (подробные сведения)
├── examples.md (сценарии использования)
└── troubleshooting.md (частые проблемы)
```

## Оценка и тестирование

### Критерии успеха
- **Измеримость:** опиши, как выглядит успех.
- **Конкретность:** избегай расплывчатых показателей.
- **Проверяемость:** результат можно оценить объективно.
- **Реалистичность:** цель достижима с данным промптом.

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

### Анализ неудач
- **Почему не получилось?** Ищи первопричину.
- **Распознавание паттернов:** находи систематические проблемы.
- **Доработка:** меняй промпт в соответствии с выводами.

## Антипаттерны

### Частые ошибки
- **Расплывчатость:** «Помоги мне с этой задачей» — слишком широко.
- **Противоречия:** конфликтующие требования.
- **Чрезмерная детализация:** слишком много ограничений.
- **Риск выдумок:** промпты, побуждающие к ложным сведениям.
- **Утечка контекста:** непреднамеренное раскрытие информации.
- **Уязвимость к обходу инструкций:** промпты, которыми легко манипулировать.

### Пути в стиле Windows
- ❌ Используй: `C:\Users\Documents\file.txt`
- ✅ Используй: `/Users/Documents/file.txt` или `~/Documents/file.txt`

### Слишком много вариантов
- Не предлагай 10 и больше вариантов.
- Ограничься 3–5 ясными альтернативами.
- Для сложного выбора раскрывай детали постепенно.

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

### Для сложных задач используй процесс
- Разбей задачу на логичные шаги.
- Определи вход и выход каждого шага.
- Настрой получение обратной связи.
- Предусмотри повторные итерации.

### Замкни цикл обратной связи
- Проси уточнение при необходимости.
- Проверяй промежуточный результат.
- Корректируй работу по обратной связи.
- Подтверждай понимание.

## Правила содержания

### Избегай быстро устаревающих сведений
- Не зашивай даты.
- Используй относительные указания, например «текущий год».
- Предусмотри способ обновления.
- Отмечай дату актуальности сведений.

### Соблюдай единообразие терминов
- Один раз определи ключевые термины.
- Используй их последовательно.
- Не называй одно понятие разными синонимами.
- Для сложной области создай глоссарий.

## Мультимодальные и продвинутые запросы

### Промпты для анализа изображений
- Опиши, что Claude должен анализировать.
- Укажи формат ответа.
- Дай контекст изображения.
- Запроси конкретные детали.

### Промпты с файлами
- Укажи допустимые типы файлов.
- Опиши ожидаемую структуру.
- Дай правила разбора.
- Обрабатывай ошибки понятно.

### Расширенное размышление
- Используй для сложных рассуждений.
- Оставляй больше времени на обработку.
- Проси подробные объяснения.
- Применяй к новым задачам.

## Процесс разработки навыка

### Сначала разработай проверки
1. Определи критерии успеха.
2. Создай тестовые случаи.
3. Зафиксируй исходный уровень.
4. Измерь улучшение.

### Дорабатывай вместе с Claude
1. Начни с простой версии.
2. Проверь и собери обратную связь.
3. Исправь по результатам.
4. Повторяй до удовлетворительного результата.

### Наблюдай за тем, как Claude использует навыки
- Смотри, как Claude находит содержание.
- Отмечай, к каким разделам обращается.
- Находи непонятные места.
- Оптимизируй по фактическому использованию.

## Требования к frontmatter YAML

```yaml
---
name: skill-name
description: Ясное, краткое описание (не более 1024 символов)
---
```

## Расход токенов

- **Метаданные навыка:** ~100–200 токенов.
- **Основные инструкции:** ~500–1000 токенов.
- **Справочные файлы:** ~1000–5000 токенов каждый.
- **Примеры:** ~500–1000 токенов каждый.
- **Общий бюджет:** зависит от задачи.

## Контрольный список хорошего навыка

### Основное качество
- [ ] Ясное, конкретное имя (форма герундия).
- [ ] Краткое описание (1–2 предложения).
- [ ] Удобная структура.
- [ ] Постепенное раскрытие деталей.
- [ ] Единообразная терминология.
- [ ] Нет быстро устаревающих сведений.

### Содержание
- [ ] Определены ясные сценарии использования.
- [ ] Приведены примеры.
- [ ] Описаны пограничные случаи.
- [ ] Указаны ограничения.
- [ ] Есть руководство по устранению неполадок.

### Тестирование
- [ ] Созданы тестовые случаи.
- [ ] Определены критерии успеха.
- [ ] Проверены пограничные случаи.
- [ ] Проверена обработка ошибок.
- [ ] Проверено несколько моделей.

### Документация
- [ ] README или обзор.
- [ ] Примеры использования.
- [ ] Замечания об API и интеграции.
- [ ] Раздел устранения проблем.
- [ ] Описан механизм обновления.