Перейти к содержимому

Написание директив

Структура директивы

После идентификаторов процесса и попытки блок новой директивы начинается с однострочного заголовка 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 - Структурирование ожидаемых ответов
  • Шаблоны - Использование переменных в директивах