Як писати інструкції для AI-агентів: від синтаксису до архітектури правил

Фундаментальна проблема

Інструкція для AI-агента — це контракт між людиною і моделлю. Нестрога інструкція породжує припущення, непередбачувану поведінку і витрати на ісправление замість роботи. Claude Code документує як CLAUDE.md файли керують persistent context, Codex використовує AGENTS.md з proximity precedence, OpenCode розділяє rules на рівнях — усі три платформи приходять до одного висновку: чітка структура інструкції визначає якість результату раніше, ніж модель чи кількість токенів.

Практичне правило: кожен файл інструкції повинен відповідати трьом критеріям — однозначність, обмеження сфери дії, наявність умов зупинки. Якщо хоч один критерій відсутній — інструкція просікає токен-бюджет марно.

Структура доброї інструкції

CLAUDE.md у Claude Code описані як місце для того, що ви інакше мусите повторювати — але автор документації прямо каже: якщо це багатокрокова процедура або стосується тільки частини кодової бази, перенесіть її в skill або path-scoped rule. Це ключове розрізнення.

Хороша інструкція має мінімальну структуру:

# Назва процедури

## Коли запускати
- Тригер: який event або стан активує цю процедуру.
- Передумова: що вже маємо.

## Що робити
Крок 1. Конкретна дія з конкретним результатом.
Крок 2. Наступна дія.
Крок N. Повернення або фіксація результату.

## Чого не робити
Перелік anti-patterns, які модель автоматично підтягує з тренування.

## Зупинитись коли
Stop conditions — explicit reasons, не "помилиться потім".

Приклад реального файлу для publish-процедури:

# Publish daily AI article

## Коли запускати
- Кожного дня, після research phase.
- Потрібен тільки one-new-file mode, не bulk generation.

## Що робити
1. Перевірити remote existence через github_api_verify_file.py.
2. Якщо target існує — повернутися з NO_REPLY.
3. Написати content/ai/YYYY-MM-DD.md з frontmatter.
4. Запустити hugo build і git diff --check --.
5. commit через github_api_commit.py з optimistic head.
6. Verify blob match.

## Зупинитись коли
- remote target уже є;
- build або diff check fail;
- remote blob не відповідає local.

Рівні специфічності

Codex застосовує proximity rules: найближчий файл переважає кореневий. OpenCode розділяє global, workspace і task rules з явним precedence. Claude Code завантажує CLAUDE.md згідно із hierarchy: managed → user → project → local, а .claude/rules/ дозволяє scope до конкретних типів файлів. OpenClaw використовує layered skill discovery з workspace skills > project skills > personal skills > bundled.

Спільний принцип: широкі правила — загальні, вузькі — конкретні. Не пишіть security policy у .claude/rules/ для Python-тестів. Не додавайте publish gate до research skill. Scope визначає blast radius.

Приклад proper scoping

project-level (.claude/rules/):
├── python/*.md   — test framework, linting, coverage thresholds
├── go/*.md       — build constraints, dependency rules
└── deploy/*.md   — deployment steps, env requirements

skill-level (workflows/):
├── publish-hugo.md    — full procedure with gates
├── audit-mcp.md       — tool-audit workflow
└── incident-rollback.md  — emergency procedure

Кожен рівень знає лише свою зону. Pipeline передає state явно через handoff, не через shared context.

Мова інструкцій

Три помилки, які з’їдають токени й точність:

1. Passiv construction. “Файл перевіряється” vs “Перевір файло. Active imperative знижує амбігюїті на 30–40% у benchmark-тестах. Model читає команду, а не опис.

2. Vague thresholds. “Добре”, “багато”, “швидко” — не мають значення для automation. “Coverage < 80%”, “retry ≤ 2”, “timeout 30s” — мають. Кожен numeric threshold зменшує кількість failed runs.

3. Missing stop conditions. Інструкція без чіткого “коли зупинитись” — це invitation для infinite loop або unsafe action. Stop conditions не є edge-case — вони foundational contract.

Template ефективної інструкції

# Workflow name

**Scope:** [one-line description of domain]
**Trigger:** [event/state that activates]
**Budget:** [max tool calls, max time — optional but recommended]

1. [action] — [expected result]. ✓ verify [condition].
2. [action] — [expected result].
⛔ Stop if: [explicit condition].

Source: [where derived from, for traceability]
Last review: [date of last update]

Цей шаблон працює однаково добре для single-task procedures і для composite workflows. Budget field особливо корисний для cron-runs — він дає automatic throttling без external rate limiter.

Agent vs Skill vs Plugin: де межа?

Це питання генерує найбільше плутанини. Ось практична рамка:

OpenClaw прямо описує skills як markdown instruction files з YAML frontmatter, що навчать agent використовувати tools. Agent — це broader construct: role + permission boundary + potentially separate session. Plugin — упаковка third-party capability.

Правило еволюції: почніть з inline instruction → три replicate run → extract skill → якщо потрібне окреме permission/session → promote to agent. Не пропускайте кроки. Skip = technical debt.

Nестандартний патерн: instruction versioning з rollback points

Більшість систем обробляють зміни інструкцій як звичайні code changes. Але інструкція — це behavioral contract. Зміна в SOUL.md може радикально змінити поведінку агента так само, як зміна в deploy script змінить release.

Впровадження простого instruction versioning:

# instruction-manifest.yml
version: 2
files:
  - path: AGENTS.md
    sha256: abc123...
    effective_date: "2026-09-20"
    rollback_on_mismatch: true
  - path: workflows/publish-hugo-post.md
    sha256: def456...
    effective_date: "2026-09-22"
    rollback_on_mismatch: false

Manifest порівнюється при старті кожного long-lived session. Якщо SHA mismatch + rollback=true → agent отримує warning і fallback instructions. Це не замінює git history — це runtime guardrail, який працює навіть коли agent вимкнений і хтось змінив інструкцію пізно ввечері.

Trade-off: додатковий startup cost (~0.5s для hash compute) проти можливості виявити unintended behavior change раніше, ніж він affect production. Для short cron-runs — надлишкове. Для persistent sessions та critical-path workflows — необхідне.

Verification и Failure Handling

NCP specification defines tool schemas and call results, але spec нічого не говорить про те, що робити коли результат не відповідає очікуванням. Це те саме для всіх платформ.

Протокол verification, який працює між системами:

Step          Expected        Action on mismatch
────────      ────────        ─────────────────
build         exit 0           abort next step
diff-check    clean            abort commit
remote-exist  not found        return early
blob-match    true             continue / alert
receipt-save  file exists      log discrepancy

Кожен step має чіткий expected state і single action. Не “спробуй ще раз” — це патерн, який створює infinite retries. Single action означає: retry (max N), alert human, або escalate. Нічого більше.

Auto memory у Claude Code автоматично записує learnings з corrections, але auto memory — це soft context, не enforced rule. Hard enforcement залишається в instruction files. Hybrid pattern: auto memory для preferences, instruction files для contracts.

10 практичних схем OpenClaw

1. Per-workflow manifest. Кожен workflow-файл містить header з version, sha256, last_review. Manifest перевіряється CI перед merge. Зміни без review блокуються.

2. Instruction fingerprint watch. Щотижня запускати checksum на всі instruction-файли. Mismatch trigger → auto-diff з попереднім версією і коротке пояснення змін. Швидший детект drift, ніж manual review.

3. Two-stage agent spawn. Research agent запускається з read-only permissions і constraint на max_tool_calls. Результат передається через structured output до operator agent, який виконує дію. Blast radius controlled by permission separation.

4. Skill shadow override. Коли потрібен короткий варіація базового skill — завантажити base, потім append context=“fork” з override-text. Базовий файл не змінюється, shadow-текст не зберігається. Тимчасова адаптація без permanent modification.

5. MCP schema audit. Раз на день зберігати tools/list response з кожного MCP server. Diff з попереднім snapshot → alert при new tool, removed tool, або schema change. Proactive detection замість reactive troubleshooting.

6. Telegram topology config. Один файл telegram-topology.json: DM→approval-only channels, group→read-only router, direct user→bidirectional. Admin міняє routing шляхом редагування JSON, не конфігурації бота. Version-controlled, auditable.

7. Obsidian vault Dataview index. Використати Obsidian Dataview plugin для auto-generate list of active workflows, receipts і eval fixtures. Agent читає Dataview query output як navigation替代 — швидше, repeatable, не залежить від manual browsing.

8. Failure-mode catalog. Створити failures.md для кожного critical workflow: top-3 failure classes з immediate mitigation steps. Agent consults catalog при error, не guessing. Time-to-recovery significant lower під час off-hours runs.

9. Publish state machine. Стани: draft → validated → ready → committed → verified. Transition require specific checkpoint (Hugo build OK, git diff clean, remote blob match). Failed transitions retain status, don’t mask errors with retry. Clear audit trail.

10. Session TTL lease. Lease file з expires, max_tool_calls, allowed_paths, must_verify. Agent читает lease на старті, стопиться після deadline або ліміту, записує receipt. Predictable cost, less context drift, easier audit. Trade-off: extra discipline для довгих tasks.

Практичний висновок

Гаразд інструкція для AI-агента не відрізняється сильно від будь-якого іншого контракту: вона має scope, тригери, дії і стоп-умови. Rізні платформи вирішують аналогічні проблеми по-різному — Codex proximity rules, OpenCode layers, Claude Code hierarchy, OpenClaw skills precedence — але спільний принцип залишається: wide-general, narrow-specific, і stop conditions explicit. Instruction versioning з rollback guards і failure-mode catalogs додають production-grade reliability до otherwise fragile systems. Починайте з маленького, ростіть поступово, уникайте premature complexity.