Контекст агента — AGENTS, skills, rules

ОБЯЗАТЕЛЬНО

Инженеру Разработчику Архитектору

LLM не «знает» ваш проект, пока вы не положите контекст в то, что агент читает каждый run. В зрелых AgentOps-setup репозиторий и .cursor/ превращаются в операционную систему для агента — рядом с кодом лежат md-файлы с документацией, архитектурой, процедурами, ограничениями и историей решений.

Обзор дисциплины — AgentOps. Мультиагентные flow — 2152.

---

Карта типов 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);
• Структура каталогов и «священные» зоны (не трогать без 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.

Prod и секреты

Агент с 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.

Цикл улучшения:

1. Incident → postmortem md.
2. Новое rule или skill patch.
3. 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 включён — 2154

---

См. также

• AgentOps — обзор
• Мультиагентные команды
• Забота о коде и данных
• Проектирование и архитектура