Написание директив
Структура директивы
После идентификаторов процесса и попытки блок новой директивы начинается с однострочного заголовка Step:. Метка текущего узла может содержать переменные процесса. Если подходящего названия или описания нет, в заголовке указывается идентификатор узла. Доступные телепорты перечислены после задания и перед системными напоминаниями.
Ноде agent-directive нужны ID, директива, условие завершения и связь success.
Добавьте inputSchema, если агент должен вернуть данные:
{ "type": "agent-directive", "id": "unique-id", "directive": "Что агент должен сделать", "completionCondition": "Когда задача завершена", "inputSchema": { "type": "object", "properties": { "result": { "type": "string" } }, "required": ["result"] }, "connections": { "success": "next-node" }}Без inputSchema завершайте шаг пустым объектом: произвольные поля будут отклонены.
Написание ясных директив
Будьте конкретны
❌ Плохо:
"Fix the bugs"✅ Хорошо:
"Устраните обнаруженные ошибки TypeScript в src/auth/, сохранив ожидаемое поведение аутентификации. Сообщите команду проверки типов проекта, её фактический результат и оставшиеся ошибки."Включайте контекст
Используйте шаблонные переменные:
"Выполните шаг {{plan.current_step_index}} из {{plan.total_steps}}: {{plan.current_step_name}}\n\nОжидаемый результат: {{plan.expected_outcome}}"Здесь plan — предыдущая нода, проверенный ответ которой содержит эти поля. Локальные результаты
читаются как node-id.field; простое имя доступно только после объявления в variableRegistry.
Не выдумывайте отсутствующие значения: сообщите о недостающей предпосылке или выберите явный путь
восстановления.
Указывайте требования к выводу
"Run tests and report results.\n\nRequired output format:\n- Total tests\n- Passed count\n- Failed count\n- List of failed test names"Условия завершения
Что делает условие хорошим
- Измеримое: можно объективно проверить
- Конкретное: чёткие критерии успеха/провала
- Полное: покрывает все требования
Примеры
❌ Расплывчатое:
"Task is done"✅ Конкретное:
"All tests pass (npm test shows 0 failures)"✅ Множественные критерии:
"Implementation complete:\n- Feature works as specified\n- Tests added and passing\n- No TypeScript errors"Однозначное условие помогает агенту или ревьюеру оценить результат, но не доказывает выполнение работы. Требуйте подходящие свидетельства и предусмотрите честный исход сбоя или блокировки, если критерий невыполним. Схема проверяет форму ответа, а не истинность утверждений. Директива также не выдаёт отсутствующие права доступа или согласие пользователя.
Эффективное использование InputSchema
Требуйте доказательства
{ "inputSchema": { "type": "object", "properties": { "task_completed": { "type": "string", "enum": ["yes", "no"] }, "evidence": { "type": "string", "description": "Concrete proof: command output, test results, etc." } }, "required": ["task_completed", "evidence"] }}Принудительный явный выбор
{ "inputSchema": { "type": "object", "properties": { "quality_check": { "type": "string", "enum": ["pass", "fail"], "description": "Did implementation meet quality standards?" } }, "required": ["quality_check"] }}Маршрутизация по ответу
Ответ-enum обычно и решает, куда пойдёт прогон дальше. Ставьте cases на ту же ноду, чтобы решал
шаг, у которого есть свидетельство. Если для workflow согласован бюджет из трёх ревью, объявите
его счётчик в workflow:
{ "variableRegistry": { "review_round": { "type": "integer", "description": "Количество проверенных по схеме ответов ревью, учтённых в лимите проверок", "minimum": 0, "default": 0 } }}Затем используйте этот фрагмент ноды, определив в графе все цели связей:
{ "id": "review", "type": "agent-directive", "directive": "Review the change against the acceptance criteria.", "completionCondition": "Verdict recorded with the findings that support it", "inputSchema": { "type": "object", "properties": { "verdict": { "type": "string", "enum": ["pass", "repair", "blocked"] }, "findings": { "type": "string", "minLength": 1 } }, "required": ["verdict", "findings"] }, "expressions": ["review_round = review_round + 1"], "cases": [ { "when": { "operator": "eq", "left": { "contextPath": "review.verdict" }, "right": "pass" }, "output": "passed" }, { "when": { "operator": "eq", "left": { "contextPath": "review.verdict" }, "right": "blocked" }, "output": "blocked" }, { "when": { "operator": "gte", "left": { "contextPath": "review_round" }, "right": 3 }, "output": "exhausted" } ], "connections": { "success": "fix-issues", "passed": "merge", "blocked": "escalate", "exhausted": "escalate", "error": "handle-error" }}review.verdict и review.findings — локальные результаты ноды. Только review_round является
объявленной глобальной переменной. Выражения выполняются после проверки ответа и до cases, поэтому
cases видят вычисленные значения. Порядок важен: успешное ревью ведёт в merge, в том числе на
последнем разрешённом круге; блокировка ведёт к эскалации; вердикт repair при исчерпанном бюджете —
тоже. В остальных случаях запасной выход success ведёт в fix-issues. Счётчик ограничивает
попытки, но не доказывает качество.
error и timeout зарезервированы под управление потоком: их не может назвать ни один case, и case
им не нужен.
Используйте inputSchema.globalInputs, только если ответ должен изменить объявленную глобальную
переменную: локальному результату глобальная запись не нужна. directive и completionCondition
обрабатываются как шаблоны, а inputSchema передаётся как схема: строки {{...}} внутри неё
не подставляются.
Сбор структурированных данных
{ "inputSchema": { "type": "object", "properties": { "test_results": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "passed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": ["total", "passed", "failed"] } }, "required": ["test_results"] }}Правила — это исходы, и у каждого своя причина
Там, где директива формулирует правило — каким должен быть план, на чём ревью вправе блокировать, что считается свидетельством, — называйте состояние, которому обязан удовлетворять результат, и причину, по которой обратное плохо.
Исход можно применить к случаю, которого автор не предвидел; процедуру можно только повторить, поэтому она верна ровно там, где совпала картина автора, и молча неверна во всех остальных местах. Причина — это то, что позволяет исполнителю применить правило к непредвиденному случаю, а не угадывать, и то, что позволяет рецензенту спорить с правилом по существу, а не по признаку соблюдения.
Задайте область применимости каждого критерия. Не создавайте артефакты ради посторонних требований, но объясните исключение, если от него зависит приёмка. Неизвестность о применимости правила не доказывает, что оно выполнено.
❌ Процедура:
"ШАГ 1: прочитай план. ШАГ 2: проверь, что у каждого пункта есть проверка. ШАГ 3: сообщи количество."✅ Исход с причиной:
"Каждый пункт называет свидетельство, по которому его примут, в наблюдаемых терминах.\n\nПочему: критерии приёмки, написанные прилагательными — надёжно, чисто, полно, — нельзя ни выполнить, ни отвергнуть, и в итоге их решает тот, кто настойчивее."Повышение голоса этого не заменяет: MANDATORY, NEVER и CRITICAL не добавляют состояния мира, в котором правило выполнено или нарушено. См. Директива как строевая команда.
Паттерны директив
Работа с порядком
Задавайте порядок только там, где он — настоящая зависимость, и говорите, что делает его таковой:
"Перенеси схему до переключения читателя: читатель отвергает строки, которые старая схема ещё производит.\n\nПосле каждого из двух шагов сообщи состояние и команду, которой его получил."Условные инструкции
"{{#if inspection.has_tests}}Запустите подходящий набор: {{inspection.test_command}}{{else}}Сообщите, что набор не настроен, и проверьте результат доступным подходящим способом.{{/if}}"Требования к верификации
"Verify implementation:\n\n- [ ] Feature works as specified\n- [ ] Edge cases handled\n- [ ] Error messages clear\n\nProvide evidence for each checkbox."Типичные ошибки
Слишком много свободы
❌ Проблема:
"Make the code better"✅ Решение:
"Приведите проверку auth к одной существующей границе валидации: допустимые входы сохраняют поведение, недопустимые получают документированный отказ. Выберите реализацию после изучения вызывающего кода и сообщите свидетельства этих свойств."Отсутствие контекста
❌ Проблема:
"Fix the error"✅ Решение:
"Исследуйте сбой в {{diagnosis.file_path}}:\n\nНаблюдаемая ошибка: {{diagnosis.last_error}}\nПодтвердите причину до изменения кода и сообщите, отличает ли выбранная проверка исправленное поведение."Избыточная маршрутизирующая обвязка
Нода condition или expression, единственная работа которой — маршрутизировать или считать то,
что предыдущая директива уже знает, — это избыточная маршрутизирующая обвязка: она добавляет
переход, который читателю приходится проследить, и второе место, где решение расходится со
свидетельством. Сложите её в директиву как cases или запись в expressions — и оставьте отдельную
ноду там, где решение действительно общее, читает состояние, которого не произвела ни одна отдельная
нода, или заслуживает именованного места в маршруте.
❌ Проблема:
[validate] → [route-validation] → [fix] / [next]✅ Решение:
[validate, cases по issues_count] → [fix] / [next]Нет критериев успеха
❌ Проблема:
"completionCondition": "Done"✅ Решение:
"completionCondition": "npm test passes with 0 failures, npm run build completes without errors"Прочитайте свои директивы с точки зрения агента. Будет ли понятно, что именно нужно сделать и когда работа завершена?
Смотрите также
- Input Schema - Структурирование ожидаемых ответов
- Шаблоны - Использование переменных в директивах