Регламент работы агента: MCP, AGENTS.md и типовые сценарии

MCP-сервер: 23 инструмента по stdio #

tools/ragraf-mcp.py запускается агентом как дочерний процесс (JSON-RPC поверх stdio) и отдаёт 23 инструмента ragraf_*: 22 операции фасада + ragraf_list_capabilities (раскрывает режим корпуса и доступные операции). Аргументы инструментов повторяют флаги CLI; ответы — те же конверты.

python tools/ragraf-mcp.py \
  --project config/mycorpus.yaml \
  --agent my-agent --agent-kind external

--agent-kind: autoclaw — среда автора (расширенная атрибуция телеметрии), external — сторонний агент, internal — внутренние сценарии. Телеметрия (usage_call) пишет: кто, какую операцию, сколько фактов/спанов/токенов (оценка) — основа usage_stats и вкладки «Использование» панели.

Известный зазор фильтрации инструментов (описан честно в реестре дефектов, C-02): substring-фильтр имён инструментов может дать ложное срабатывание на похожих префиксах — обход: точные имена в конфигах агента; исправление — в roadmap.

AGENTS.md: регламент вместо свободы #

RAGRAF поставляет регламент для агента — не «вот тебе инструменты, improvisируй», а фиксированный порядок работы:

1. Спроси индекс, а не grep. Любая навигация начинается с ragraf_symbol/ragraf_search, а не с rg. Полное чтение файла — только через ragraf_live_read и только по факту, найденному в индексе.
2. Проверяй конверт, а не только result. stale_warnings не пуст → перечитать затронутое через live_read; capability=degraded → не планировать задачи, требующие slice.
3. Перед записью в БД — write_check. Всегда, без исключений: это 3 мс против рантайм-ошибки SQLSTATE[42S22].
4. impact перед правкой. Глубина 3, --mode hard для плана, all — когда нужен список мест для ручной проверки derived-рёбер.
5. Честное «не найдено» — валидный ответ. Не додумывать; сообщить limits из конверта.

Полный текст регламента живёт в репозитории (AGENTS.md — строка в README описывает его назначение; на момент v0.1.0 файл помечен как не поставляемый в составе — расхождение документировано в реестре дефектов и закроется в релизе).

Сценарий 1 — доработка подсистемы (реальный замер) #

Задача: добавить журналы платежей/договоров/отпусков в раздел /agreements/ пилотного PHP-портала. Итог по журналу телеметрии:

Доминирующий класс пойманного: «работает, но не так» (8 из 16 дефектов пилота) — страница открывается, исключений нет, но отклонённый документ — тупик: маршрут согласования обрывается. Ни компилятор, ни «страница открывается»-тест такое не ловят; ловят policy_trace + routes + проверка под реальной ролью.

Сценарий 2 — правка с оценкой влияния #

1. ragraf_symbol --name PaymentService::markPaid      → определение file:line
2. ragraf_callers --name markPaid --mode hard          → 7 stated-вызовов в 4 файлах
3. ragraf_callers --mode all                           → +2 derived (call_user_func) — открыть live_read
4. ragraf_impact --depth 3                             → транзитивный конус: 12 символов
5. ragraf_write_check --table z_agr_payments --columns … → схема сходится
6. правка → ragraf_reindex → drift_report: что изменилось в знаниях

Сравнение с grep-подходом: rg markPaid даёт 28 совпадений, из которых вызовов — 9, а доказуемо влияющих — неизвестно; агент читает 3–4 файла целиком (~2 800 токенов) и всё равно не видит динамику. Замер навигационных задач пилота: 14 вызовов операций против 28 (реалистично 43) grep-вызовов и 0 против 14 полных чтений файлов.

Сценарий 3 — расследование инцидента #

policy_trace --route /agreements/payments/mark-paid   → маршрут→middleware→проверка роли
schema --table z_agr_payments                          → фактические колонки
table_usage --table z_agr_payments                     → кто читал/писал
search "отметить оплаченным" --with-text               → docblock-контракт функции

Четыре вызова вместо часов grep-археологии; каждый ответ — с path:line и provenance, пригоден для отчёта об инциденте как есть.

Что телеметрия говорит о работе агента #

usage_stats (и вкладка панели «Использование») показывает распределение по операциям: здоровый профиль — доминирование symbol/search/write_check и нулевое live_grep-чтения целых файлов. Аномалия (агент игнорирует индекс и grep-ит) видна сразу — это сигнал править регламент, а не модель.

Смежное: интеграции: AutoClaw, SagaAI, DeepSeek Harness → · панель и эмулятор →