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

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

Каждый узел agent-directive должен содержать:

{
  "type": "agent-directive",
  "id": "unique-id",
  "directive": "Что агент должен сделать",
  "completionCondition": "Когда задача завершена",
  "inputSchema": {
    /* ожидаемая структура ответа */
  },
  "connections": { "success": "next-node" }
}

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

Будьте конкретны

❌ Плохо:

"Fix the bugs"

✅ Хорошо:

"Fix TypeScript compilation errors in src/auth/.\n\nSteps:\n1. Run tsc --noEmit\n2. Fix each error\n3. Verify compilation succeeds"

Включайте контекст

Используйте шаблонные переменные:

"Implement step {{current_step_index}} of {{total_steps}}: {{current_step_name}}\n\nExpected outcome: {{expected_outcome}}"

Указывайте требования к выводу

"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": {
    "properties": {
      "task_completed": { "type": "string", "enum": ["yes", "no"] },
      "evidence": {
        "type": "string",
        "description": "Concrete proof: command output, test results, etc."
      }
    },
    "required": ["task_completed", "evidence"]
  }
}

Принудительный явный выбор

{
  "inputSchema": {
    "properties": {
      "quality_check": {
        "type": "string",
        "enum": ["pass", "fail"],
        "description": "Did implementation meet quality standards?"
      }
    },
    "required": ["quality_check"]
  }
}

Сбор структурированных данных

{
  "inputSchema": {
    "properties": {
      "test_results": {
        "type": "object",
        "properties": {
          "total": { "type": "number" },
          "passed": { "type": "number" },
          "failed": { "type": "number" }
        },
        "required": ["total", "passed", "failed"]
      }
    },
    "required": ["test_results"]
  }
}

Паттерны директив

Пошаговые инструкции

"Complete the following steps in order:\n\n1. [First action]\n2. [Second action]\n3. [Third action]\n\nReport which steps completed successfully."

Условные инструкции

"{{#if has_tests}}Run test suite: {{test_command}}{{else}}No tests configured, skip testing{{/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"

✅ Решение:

"Refactor auth module:\n- Extract validation logic to separate function\n- Add error handling for null inputs\n- Add JSDoc comments"

Отсутствие контекста

❌ Проблема:

"Fix the error"

✅ Решение:

"Fix error in {{file_path}}:\n\nError message: {{last_error}}\nIteration: {{current_iteration}}"

Нет критериев успеха

❌ Проблема:

"completionCondition": "Done"

✅ Решение:

"completionCondition": "npm test passes with 0 failures, npm run build completes without errors"

Смотрите также

Input Schema - Структурирование ожидаемых ответов
Шаблоны - Использование переменных в директивах