MODULE_02 · УРОК 2.1

Описания, которые работают

Пока инструментов три, коротких WHEN TO USE и WHEN NOT TO USE хватает с запасом. Добавьте четвёртый, пятый, потом субагентов - и в один прекрасный день агент полезет в bash там, где хватило бы read, хотя вы вообще ничего не меняли. Просто выбор стал сложнее, а подсказок осталось столько же. Лечится всё тем же местом: описаниями. Только теперь мы превратим их из вольного пересказа в жёсткий контракт, одинаковый у всех инструментов.

ЧТО ПОЛУЧИТСЯ У каждого инструмента будет однотипный «контракт» из пяти блоков. На неоднозначных фразах модель начнёт выбирать между read, grep и bash заметно стабильнее, а вы получите шаблон для всех будущих инструментов.

Слова, которые встретятся

  • Контракт описания - фиксированный шаблон текста, по которому написаны все инструменты. Когда они оформлены одинаково, модели заметно проще их сравнивать между собой.
  • Мягкий запрет (WHEN NOT TO USE) - подсказка в стиле «в этой ситуации возьми лучше вот тот инструмент».
  • Жёсткий запрет (DO NOT USE FOR) - «этим задачу X не решают, вообще никогда». Да, похоже на мягкий запрет, и это не случайность: важное модели приходится говорить дважды.
  • Bash gravity - та самая тяга модели к терминалу, будто это швейцарский нож на все случаи жизни. Отговаривать её мы будем вежливо, но очень настойчиво.

Быстрый путь

  1. Расширьте docstring каждого tool до пяти секций.
  2. Добавьте USAGE (ограничения параметров) и EXAMPLES (конкретные вызовы).
  3. Оставьте оба негатива: WHEN NOT TO USE и DO NOT USE FOR.

Какие файлы трогаем

Файл Что делать
main.py Править. Docstrings у read, grep и bash - полный контракт из пяти секций.
логика tools Не трогать. Меняем только описания, не код внутри функций.

Упражнение 2.1

Приведите описания read, grep и bash к полному контракту.

  • Первая строка - что делает tool и что возвращает.
  • WHEN TO USE - 2-4 сценария словами из реальных промптов.
  • WHEN NOT TO USE - мягко указать другой инструмент по имени.
  • DO NOT USE FOR - жёсткие границы («никогда не для поиска / не для cat»).
  • USAGE - лимиты, дефолты, то, чего не видно из типов аргументов.
  • EXAMPLES - 2-3 конкретных набора аргументов.

Зачем два «не делай так»

Первое, что бросается в глаза: WHEN NOT TO USE и DO NOT USE FOR говорят почти одно и то же. Так и есть, дублирование здесь сознательное. Под нагрузкой, когда промпт размытый а инструментов много, модель прекрасно «забывает» мягкий намёк и опять тянется к bash. Второй запрет работает как ремень безопасности: сказали один раз - может проскочить, сказали дважды - почти всегда держится.

Полный контракт на примере

Начнём с grep: у него больше всего шансов быть перепутанным с остальными. Обратите внимание, что код функции мы не трогаем вообще, меняется только текст в тройных кавычках.

docstring для grep

"""Поиск по содержимому файлов через regex. Строки с путями к файлам.

WHEN TO USE: паттерны по многим файлам, определения функций,
  импорты, TODO, сообщения об ошибках.

WHEN NOT TO USE: чтение уже известного файла (используй read).
  Запуск команд (используй bash).

DO NOT USE FOR: чтение файлов (read), список каталогов (bash),
  правка файлов (edit / write - появятся позже).

USAGE: pattern - строка regex. glob - маска вроде "*.py".
  Результат обрезается на 50 совпадениях.

EXAMPLES:
  - TODO: pattern "TODO" glob "*.py"
  - определения функций: pattern "def \\w+" glob "*.py"
  - импорт пакета: pattern "from pydantic_ai" glob "*.py"
"""

docstring для read

"""Прочитать файл проекта. Возвращает пронумерованные строки.

WHEN TO USE: просмотр содержимого, конфигов, исходников,
  кусок файла через offset/limit.

WHEN NOT TO USE: поиск по многим файлам (используй grep).
  Запуск команд (используй bash).

DO NOT USE FOR: поиск по коду (grep), выполнение в shell (bash),
  изменение файлов (edit / write).

USAGE: path - относительно рабочей директории.
  offset и limit необязательны. Вывод не больше 500 строк.
"""

docstring для bash

"""Выполнить shell-команду в рабочей директории.

WHEN TO USE: сборка, установка пакетов, тесты, git, список файлов.

WHEN NOT TO USE: чтение файла (используй read).
  Поиск по паттерну (используй grep).

DO NOT USE FOR: чтение файлов (read), поиск по коду (grep).

USAGE: command - одна строка shell. Команды вне белого списка
  блокируются и возвращают понятное сообщение.

EXAMPLES:
  - список файлов: command "ls -la"
  - статус git: command "git status"
  - тесты: command "pytest"   # если добавите в белый список
"""
Секция Зачем
Первая строка Что делает и что отдаёт
WHEN TO USE Сценарии и слова из промптов пользователя
WHEN NOT TO USE Мягкий редирект на другой tool
DO NOT USE FOR Жёсткая граница, повтор
USAGE Лимиты и дефолты, которых нет в типах
EXAMPLES Конкретные вызовы «скопируй как образец»

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

Проверьте

По одному промпту на каждый «характер» инструмента:

uv run python main.py . "Найди все TODO-комментарии в проекте"
uv run python main.py . "Прочитай pyproject.toml"
uv run python main.py . "Перечисли файлы в этой директории"

Ждём такого расклада: TODO уходит в grep, файл в read, а список каталога в bash с ls. Отдельная история - смешанные фразы вроде «покажи содержимое pyproject через cat»: они честно могут уйти и в read, и в bash. Это не баг маршрутизации, а размытый промпт, в котором вы сами назвали два разных способа.

Готово, если:

  • У всех трёх tools есть все пять секций описания
  • Поиск TODO уходит в grep
  • Чтение файла уходит в read
  • Список файлов уходит в bash
  • (бонус) Убрали EXAMPLES - и поймали, где маршрутизация впервые ломается
ЭКСПЕРИМЕНТ Сломайте самое любимое описание по секциям: EXAMPLES → DO NOT USE FOR → USAGE. После каждого выреза прогоните три тестовых промпта. Где DeepSeek первым делом свалится в «давайте просто в bash»?