Модуль 05 — Агентный цикл и права

Время: 4 часа · Формат: теория 90 мин + практика 150 мин

Теория

1. Что такое агент

LLM  →  решает, какой инструмент вызвать
     →  инструмент возвращает результат
     →  результат попадает в контекст
     →  повтор, пока задача не решена

Это цикл tool calling. Модель не «делает» — она просит. Отсюда:

качество агента = качество модели × качество инструментов × качество описаний;
плохой инструмент ломает цикл сильнее, чем слабая модель;
агент может «зациклиться» — нужен предел итераций.

2. Инструменты первого дня

Инструмент	Что делает
`read`	читает файл
`edit` / `write`	правит и создаёт файлы
`glob` / `grep`	ищет файлы и содержимое
`shell`	запускает команды
`webfetch` / `websearch`	достаёт внешнюю информацию

Практика: чем уже инструмент, тем предсказуемее агент. «Запусти мне всё» хуже, чем «запусти pytest tests/test_auth.py».

3. Права: модель угроз

Каждое действие агента потенциально необратимо. Категории риска:

Риск	Пример	Что делать
Необратимое удаление	`rm -rf`, `git reset --hard`	`deny`
Публикация наружу	`git push`, `docker push`, деплой	`ask`
Секреты	чтение `.env`, `~/.ssh`	`deny`
Деньги	вызов платных API пачками	лимиты
Миграции БД	`alembic upgrade` на проде	`ask`/`deny`
Изменение вне проекта	чужие папки	`external_directory`

4. Как устроены правила в OpenCode

Правило = action + resource + effect:

{ "action": "shell",  "resource": "git push *", "effect": "deny" },
{ "action": "shell",  "resource": "git status *", "effect": "allow" },
{ "action": "read",   "resource": "*.env", "effect": "ask" },
{ "action": "external_directory", "resource": "D:/other/*", "effect": "allow" },

Действуют снизу вверх: последнее совпавшее правило побеждает.
По умолчанию — ask (если нет совпадения).
«Always allow» в интерфейсе сохраняет правило на уровне проекта.
deny нельзя обойти кнопкой.

5. Минимальный рабочий набор

{
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "./scripts/check.sh", "effect": "allow" },
    { "action": "shell", "resource": "pytest *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "shell", "resource": "sudo *", "effect": "deny" },
    { "action": "read",  "resource": "*.env*", "effect": "deny" }
  ]
}

Логика: разрешить чтение и проверки, запретить публикацию и необратимое.

6. Изоляция

Ветка — минимум: git checkout -b agent/<задача>.
Worktree — отдельная рабочая копия: агент работает, не мешая вашей.
Контейнер/VM — для рискованных экспериментов.
--auto — авто-одобрение всего, что не запрещено. Только в изолированной среде.

Правило: чем шире права, тем уже должна быть песочница.

7. Субагенты

Отдельная сессия для подзадачи. Зачем:

разведка по большому репо не засоряет основной контекст;
параллельная работа над независимыми частями;
«второе мнение» на ревью.

Цена: субагент не видит вашу историю — ему нужен полный самостоятельный бриф.

8. Когда агент зациклился

Признаки: одни и те же правки, повторяющиеся ошибки, рост числа tool-calls.

Действия:

Остановить.
Сформулировать, что известно точно (файлы, ошибки).
Новая сессия с этим контекстом.
Если повторяется — задача сформулирована неверно.

Чек-лист понимания

Почему «модель делает» — неверная формулировка?
Что произойдёт, если поставить allow на shell: *?
Зачем deny на git push, если есть ревью?
Когда --auto допустим, а когда — нет?
Чем субагент помогает и чем вредит?

Практика

См. practice.md.