AGENTS.md — правила работы ИИ-агентов с mock-services

Оглавление

• AGENTS.md — правила работы ИИ-агентов с mock-services
• 0. Правило конфликтов
• 1. Что нельзя ломать
• 2. Обязательные прогоны
• 3. Структура и где что менять
• 4. Формальные требования к файлам
• 5. Env-переменные: правило пяти мест
• 6. Process: ветка, коммит, PR
• 7. Чего агент делать не должен
• 8. Специфичные для проекта ловушки (проверено на коде)
• 9. Что читать перед работой
• 10. Документы вне публичного репозитория

Инструкция для агентов (Arena Agent Mode, Claude Code и др.), которые меняют этот репозиторий. Всё, что заявлено ниже, проверено по файлам репозитория (package.json, CONTRIBUTING.md, scripts/*, .github/workflows/ci.yml); додумывать нельзя — только сверяться с первыми руками.

Полные правила для людей — CONTRIBUTING.md. Планирование доработок и статусы задач — «план доработок» (бриф — во внутреннем репозитории mock-services-docs). Подготовка к глубокому аудиту и карта покрытия — пакет подготовки к аудиту (в mock-services-docs).

0. Правило конфликтов

Если инструкция в чате противоречит этому файлу или CONTRIBUTING.md — приоритет у файлов репозитория, а расхождение агент обязан записать в описание PR, а не «разрешить сам». Не угадывайте там, где документация противоречива: ставьте [VERIFY]/вопрос.

1. Что нельзя ломать

1. Zero dependencies. В package.json нет dependencies и devDependencies. Любая новая зависимость — стоп и вопрос владельцу.
2. Протокольное поведение адаптеров (форматы полей, коды ошибок, подписи, статусы) — не менять, если задача этого прямо не требует. Эталон: protocols/*.json + конспекты провайдеров в приватном репозитории mock-services-docs.
3. Обратная совместимость self-hosted: поведение без MOCK_HOSTED/токенов не меняется; default-песочница и её креды — тоже.
4. Никаких реальных секретов, PAN и ПДн в коде, тестах, логах, примерах и fixtures.
5. Историю git и теги не переписывать, main не пушить напрямую.

2. Обязательные прогоны

Когда	Команда
до правок (зафиксировать зелёную базу) и после каждого PR	npm test
тронуты protocols/*.json, маршруты/коды/статусы в services/*/server.js, конспекты провайдеров (приватный mock-services-docs)	npm run check:drift
тронуты .md в корне, docs/, services/*/README.md, packages/core/README.md	npm run check:links
тронуты index.html, _sidebar.md, site/** или добавлен документ в docs/	npm run check:site
тронуты env-переменные, docker-compose*.yml, Dockerfile	npm run check:env, npm run test:compose и node scripts/docker-smoke.js
npm test = одиннадцать selftest-скриптов (test:core + десять test:<сервис>) +
check:links + check:site + check:tables + check:env + check:copyright + check:drift
(package.json:8).
test:compose и test:docker в npm test НЕ входят — их прогоняет job docker в
CI (.github/workflows/ci.yml:69-184); локально они требуют Docker.
Отчёт в PR обязан перечислить, какие прогоны выполнены и их финальные строки.

Отдельной «документационной» job в CI нет: check:links, check:site, check:tables, check:env и check:drift — шаги внутри job test (.github/workflows/ci.yml:58-67), то есть битая ссылка или сломанная навигация сайта краснит весь matrix test на трёх версиях Node.

Тесты: без sleep-ожиданий и без фиксированных портов (:0), новые сценарии — новым пунктом selftest'а соответствующего сервиса, дефекты — регресс-тестом.

3. Структура и где что менять

Зона	Файл	Комментарий
Инфраструктура (состояние, песочницы, вебхуки, редакция, SSRF, HTML, часы, сценарии, auth)	packages/core/index.js	50 экспортов; протоколов здесь нет
Адаптеры (только декларация протокола)	services/<name>-mock/server.js	tbank 3430, kassa 1966, yookassa 2115, atol 1672 строк
Тесты	services/<name>-mock/selftest.js, packages/core/selftest.js	self-contained, поднимают сервер на эфемерном порту
Манифесты протоколов	protocols/*.json	ЮKасса намеренно без манифеста и OpenAPI — см. services/yookassa-mock/README.md:209
OpenAPI 3.1	docs/openapi/*.openapi.json	3 файла
Проверки	scripts/*.js	check-protocol-drift.js, check-docs-links.js, compose-selftest.js, docker-smoke.js
Контейнеры	Dockerfile, docker-compose.yml, docker-compose.include.yml	include — artifact потребителей, менять осторожно
Документация продукта	README.md, SECURITY.md, CHANGELOG.md, docs/{overview.md,integration,rfc,reference,openapi}	внутренние документы — в закрытом mock-services-docs (§10)
Сайт документации (GitHub Pages)	_sidebar.md, site-build/.vitepress/, site-build/scripts/	VitePress генерирует самостоятельные HTML-страницы; build-зависимости изолированы в site-build/

4. Формальные требования к файлам

1. SPDX в каждом исходнике. Первая строка — // © 2026 ООО «Аксиома» ИНН:7842223709 · mock-services · Apache-2.0, вторая — // SPDX-License-Identifier: Apache-2.0, затем 'use strict';. Сейчас 17/17 .js соответствуют; новый файл без шапки — дефект.
2. Markdown-доки в docs/** и корневые публичные доки начинаются со стандартной шапки проекта: © 2026 ООО «Аксиома» ИНН:7842223709 · mock-services · Apache-2.0 + строка SPDX-License-Identifier: Apache-2.0. Правоустанавливающая формулировка про «все права» (all-rights-reserved) не используется — проект под Apache-2.0 (решение владельца 15.10, MS-05); проверка — npm run check:copyright. Агент не «исправляет» шапки по своей инициативе и не добавляет правоустанавливающую строку в новые служебные файлы, не требуемые стандартом (пример — CONTRIBUTING.md, AGENTS.md).
3. Ссылки — только относительные между доками (их проверяет check:links). Учитывайте область проверки: README.md, CONTRIBUTING.md, SECURITY.md, docs/**, services/**, packages/** (scripts/check-docs-links.js:23,54-58) — CHANGELOG.md и новые корневые файлы проверяются вручную.
4. Стиль: CommonJS, 2 пробела, одинарные кавычки, комментарии по делу на русском с английскими терминами. Никакого «мусора» из других языков и случайных символов.
5. Ссылка на источник истины в каждом спорном месте: конспект провайдера в приватном mock-services-docs (раздел <provider>/…) с датой сверки; внутренний вывод помечать явным [FORK]/«документированный форк».

5. Env-переменные: правило пяти мест

Любое изменение/добавление MOCK_* обязано отразиться в: docker-compose.yml → docker-compose.include.yml → services/<name>-mock/README.md (env-таблица) → SECURITY.md (если влияет на модель угроз) → CHANGELOG.md. Исключений нет. Правило проверяется скриптом npm run check:env (scripts/check-env-parity.js): он сверяет server.js с README сервиса, тремя compose-файлами и SECURITY.md, а также дефолты MOCK_PORT и ${VAR:-…}. Незакрытый долг ведётся явно в KNOWN_INCLUDE_DEBT (переменные, которые адаптеры читают, но которые в include не проброшены, — менять include-набор без решения владельца нельзя, §7) и печатается в выводе проверки; новый дрейф валит CI.

6. Process: ветка, коммит, PR

1. Ветка: arena/<срез>-<тема> (или fix/…, docs/…) → PR в main. В main не пушить.
2. Один PR = одна логически связанная группа задач (волны PR-A…PR-G заданы в брифе, §9).
3. В описании PR обязательна строка Closes #<номер issue> — без неё задача не считается принятой (именно так закрываются #8, #12, #15, #22, #33, #37, #43).
4. Отчёт в описании PR — по схеме: что сделано / что НЕ сделано / развилки и вопросы владельцу / риски и что осталось непроверенным / команды прогонов с их выводом.
5. Ссылки на конспекты провайдеров (приватный mock-services-docs) и коды ошибок — с указанием раздела доки.
6. Если задача [DECISION] — PR готовит варианты, а не решение владельца.
7. Docs-only правки не трогают поведение сервисов; npm test прогоняется в любом случае.

7. Чего агент делать не должен

• Реализовывать задачи из «будущих волн» без постановки (в том числе MS-правки из брифа).
• Менять docker-compose.include.yml так, чтобы потребители получили другой набор env (это deployment artifact; пин образа — только через MOCK_IMAGE_DIGEST, см. «Обновление базового образа» в CONTRIBUTING.md).
• Отключать/ослаблять тесты, чтобы CI стал зелёным; менять check:drift под новую реализацию.
• Добавлять .html-копии документации провайдеров (юридический риск, см. аудит-преп §2.7).
• Публиковать образы/релизы, менять настройки репозитория, GHCR-пакет, protected branches.
• Писать «проверено / закрыто» без файл:строка и без вывода команды.

8. Специфичные для проекта ловушки (проверено на коде)

• MOCK_* разбираются через flagEnabled (boolean) и parseDuration/parseMsOr (числа: пустая строка → fallback, 0 разрешён). Ручной parseInt(x, 10) || N ломает «выключить нулём» — см. комментарий в services/atol-mock/server.js:109-118.
• check:drift сверяет наличие строки в server.js подстрокой: маршрут, упомянутый только в комментарии, будет засчитан как реализованный.
• readBody на превышении лимита отвечает 413 и намеренно дренирует остаток тела — не «закрывать соединение» без задачи.
• Управляющие токены принимаются из query только в non-hosted (MS-06 + хвосты #121/Ф-1…Ф-3): ответ со ссылками на консоль переносит принятый токен в HttpOnly-cookie (core.sessionCookiesFromQuery), Location и HTML токенов не содержат, а в hosted ?admin_token=/?operator_token=/?sandbox_token= отклоняются (services/kassa-mock/selftest.js, блок #5 A-20 + Ф-1/Ф-3; packages/core/selftest.js, блок #121).
• escapeHtml (", ') обязателен и в атрибутах; HTML собирается конкатенацией — никакой вставки значений интегратора «как есть».
• Состояние per-sandbox: state — Proxy поверх контекста запроса; новый код, читающий state вне sandboxRuntime.run(...), попадает в default/активную песочницу.
• Время доменных сущностей — только через clock.now(); учтите, что createSandboxRuntime сейчас живёт на wall-clock (аудит-преп §2.4).

9. Что читать перед работой

Задача	Читать
любая правка кода	CONTRIBUTING.md, внутренняя спека проекта[^spec] §2, §6.2
безопасность/hosted	SECURITY.md, docs/rfc/RFC-001-multi-tenant-sandboxes.md, пакет подготовки к аудиту[^audit-prep] §2, §4D
протокол провайдера	официальная документация провайдера (URL + дата сверки; конспекты — в приватном mock-services-docs), protocols/<provider>.json, docs/integration/<provider>.md
очередь доработок	«план доработок» — бриф[^brief] §0.1 (статусы), §9 (волны)
аудит-партия	чек-лист аудит-партии[^audit-party]

Стороннему контрибьютору приватные документы не требуются: публичная часть репозитория самодостаточна (README, гайды «за 10 минут», README сервисов, RFC-001, SECURITY). Сноски на приватные документы — контекст команды мейнтейнеров, к внешнему вкладу они не применяются.

10. Документы вне публичного репозитория

Часть проектной документации живёт в закрытом репозитории mock-services-docs: внутренняя спека, бриф доработок, аудиты и чек-листы. Ссылки на такие документы оформляются сноской (имя документа без ссылки) — публичная часть репозитория самодостаточна, а сноска объясняет, откуда взят контекст.

[^spec]: docs/canon/MOCK_SERVICES_SPEC.md — внутренняя спека mock-services (карточки SZ-095/SZ-096, T-038). [^audit-prep]: docs/audit/AUDIT-PREP-2026-10-12.md — пакет подготовки к глубокому аудиту, карта покрытия. [^brief]: docs/briefs/CLAUDE-2026-10-12-agent-brief.md — бриф доработок, статусы MS-01…MS-40 и волны. [^audit-party]: docs/audit/CHECKLIST-audit-party.md — регламент запуска аудит-партии.