Контекст агента — AGENTS, skills, rules
LLM не "знает" ваш проект, пока вы не положите контекст в то, что агент читает каждый run. В зрелых AgentOps-setup репозиторий и .cursor/ превращаются в операционную систему для агента — рядом с кодом лежат md-файлы с документацией, архитектурой, процедурами, ограничениями и историей решений.
Обзор дисциплины — AgentOps. Мультиагентные flow — Мультиагентные команды и DevOps-pipeline.
Карта типов md-контекста
| Файл / каталог | Назначение | Кто обновляет |
|---|---|---|
docs/ | Пользовательская и техническая документация | Команда + агент (с review) |
docs/architecture/ · ADR | Решения, диагrams, границы сервисов | Architect, agent по шаблону |
AGENTS.md | Инструкции для агента: цели репо, команды, границы | Tech lead |
.cursor/rules/ | Постоянные правила (стиль, git safety, frontmatter) | DevOps / platform |
Skills (SKILL.md) | Процедуры "как сделать X" — PR, deploy, triage CI | SRE, senior dev |
decisions/ · ADR | Почему выбрали PostgreSQL, а не Mongo | Архитектор |
info/ · runbooks | Карта машин, IP, роли серверов, "память" инфры | Ops |
CHANGELOG · release notes | Что уже выкатили — чтобы агент не откатывал фичи | Release manager |
Агент не держит долгую память между сессиями. Всё, что должно пережить restart — в файлах, которые подмешиваются в контекст (rules, @-mentions, MCP resources, index).
AGENTS.md — манифест репозитория для агента
Файл в корне (или docs/AGENTS.md) — контракт между командой и любым агентом (Cursor, Codex, Claude Code, CI bot).
Что включать
- Как собрать и запустить проект (
npm run,docker compose— шаблоны стека в Docker Compose — готовые стеки); - Структура каталогов и "священные" зоны (не трогать без approve);
- Политика коммитов и веток;
- Куда смотреть архитектуру и ADR;
- Список MCP servers и зачем они;
- Escalation — когда остановиться и спросить человека.
Пример фрагмента:
## Git
- Коммиты только по явной просьбе пользователя.
- Никогда `push --force` на main/master.
- Перед PR: lint + tests из package.json.
## Опасные зоны
- `infra/prod/` — только read; apply через CI job deploy-prod.
- Секреты — не коммитить; см. docs/security/secrets.md.
Cursor читает AGENTS.md нативно; другие IDE копируют содержимое в project instructions.
Rules — неизменяемые ограничения
.cursor/rules/*.mdc — правила с glob-привязкой (docs/**/*.md, **/*.ts). Подгружаются автоматически при работе с matching files.
Типичные rules в AgentOps-репо:
- frontmatter и MDX-safe markup для docs;
- git safety protocol (как в user rules Cursor);
- запрет destructive shell без approve;
- стиль энциклопедии (утвердительные формулировки, callouts).
Rules короче skills: "что нельзя" и "как форматировать", а не пошаговый runbook.
Skills — процедуры через markdown
Skill — файл SKILL.md с пошаговым workflow — "создать PR", "починить упавший CI", "сгенерировать toc". Агент читает skill при релевантной задаче (явный @skill или auto-discovery из .cursor/skills/).
Skills превращают tribal knowledge в повторяемые процедуры:
| Skill | Содержание |
|---|---|
create-hook | Как добавить Cursor hook |
babysit | Цикл triage PR comments → fix CI |
split-to-prs | Разбить большой diff |
ci-investigator | Root cause одного failed check |
Без skills каждый run переизобретает gh pr create и флаги вашего монорепо.
Documentation и architecture
docs/ — источник правды для людей и RAG/MCP. Агент с @docs или doc-search index находит статьи быстрее, чем grep по 500 файлам.
Architecture md — C4, sequence diagrams, границы bounded context. Агент-coder сверяет diff с diagram: "новый сервис должен жить в services/billing/".
ADR (Architecture Decision Records) — формат "контекст → решение → последствия". Агент перед спорным refactor читает ADR-007 "почему event-driven" и не предлагает sync REST "для простоты".
Карта машин и "память" серверов
Ops-команды ведут inventory в git (Ansible inventory, Terraform, или info/servers.md):
| Host | Role | Env | SSH jump | Notes |
|------|------|-----|----------|-------|
| db-01 | PostgreSQL primary | prod | bastion | Patroni, no direct agent shell |
| worker-03 | CI runner pool | ci | — | Agent sandbox, 2h TTL |
Агент с доступом к этому файлу не галлюцинирует hostname. MCP server "infra" может отдавать live status; md — baseline, когда API недоступен.
Server memory — не magic: это
- актуальный inventory в git;
- последние incident postmortems в
docs/postmortems/; - metrics/traces links в runbook.
Полномочия агента — сколько давать
Современные агенты могут получить очень широкие права — shell, git write, network, MCP к prod DB, browser automation. AgentOps требует явной модели доверия.
| Уровень | Permissions | Когда |
|---|---|---|
| Read-only | Read files, search, ask | Exploration, onboarding |
| Dev sandbox | Shell в container, git branch local | Feature work |
| Git write | Commit, push branch, open PR | Trusted repo, CI обязателен |
| CI trigger | Webhook, workflow_dispatch | После review |
| Deploy staging | CD to non-prod | Auto после green CI |
| Prod | IaC apply, kubectl, payments | Только human approve |
В Cursor это required_permissions — git_write, full_network, all (disable sandbox). Каждый запрос — audit event.
Агент с all + prod credentials может за минуты удалить bucket, rotate keys, force-push. Минимизируйте scope — отдельный service account, time-limited tokens, deny list команд из Опасных скриптов.
Human-in-the-loop — любое действие, меняющее billing, PII, prod state — approval dialog, second reviewer, или break-glass role.
История решений и agent transcripts
agent-transcripts/ (или ссылки в PR) — UUID сессии для расследования "почему агент так сделал". Не коммитьте секреты из чатов.
Decision log — merge ADR + postmortem + "agent mistake of the week" для обучения rules.
Цикл улучшения:
- Incident → postmortem md.
- Новое rule или skill patch.
- Eval case в CI "на этом промпте агент не должен вызывать rm -rf".
Чек-лист настройки среды
-
AGENTS.mdв корне с build/test/git policy - Rules на docs, git, security
- Skills для частых ops-процедур
- ADR для спорных архитектурных выборов
- Inventory / architecture md актуален
- MCP servers документированы в AGENTS.md
- Permission tiers согласованы с security
- Tracing включён — Инструменты AgentOps