Модуль 3
Обучить агента проекту
AGENTS.md, opencode.jsonc и permissions учат агента командам и границам проекта; своя команда /review запускает ревью диффа одним словом.
Чему научишься
- написать AGENTS.md: команды, структура, конвенции, способ проверки
- настроить opencode.jsonc: модель проекта и permissions
- закрыть git push и *.env правилами deny и ask
- создать свою команду /review в .opencode/commands
AGENTS.md: инструкция для агента
AGENTS.md это README для агентов. Файл лежит в корне проекта и описывает команды сборки и тестов, структуру, конвенции и способ проверки работы. Это открытый стандарт (agents.md, Linux Foundation), его читают OpenCode, Codex, Claude Code, Cursor, Cline и Gemini CLI. Файл коммитят в репозиторий: он одинаков для всей команды и для всех агентов.
Вложенные AGENTS.md подтягиваются по мере чтения файлов: свой файл в src/services опишет конвенции слоя. Личные глобальные правила живут в ~/.config/opencode/AGENTS.md. Порядок сборки промпта: системный промпт, затем инструменты и MCP, затем AGENTS.md с инструкциями, в конце дата и окружение.
Черновик AGENTS.md уже сгенерирован /init в модуле 1. Теперь вычитай его и допиши то, чего сканер не знал: конвенции, способ проверки, границы проекта.
Пиши в AGENTS.md четыре раздела: команды (установка, запуск, тесты, типы), структура каталогов, конвенции (форматы ошибок, статусы, единицы) и способ проверки изменений. Чем конкретнее раздел проверки, тем реже агент угадывает. Ниже готовый AGENTS.md для orders-api: подставь его, затем адаптируй под свой проект.
# orders-api
REST-сервис заказов кофейни: Express + TypeScript, база в `data/db.json`, порт 3000.
## Команды
- установка: `npm install`
- дев-сервер: `npm run dev`
- тесты: `npm test`
- типы: `npm run typecheck`
## Структура
- `src/index.ts` — точка входа, монтирует роутеры
- `src/routes/` — HTTP-слой: menu, orders, stats, legacy
- `src/services/` — бизнес-логика: pricing
- `src/db.ts` — чтение и запись `data/db.json`
- `tests/` — тесты, пока только pricing
## Конвенции
- статусы заказа: new → confirmed → done
- ошибки API: JSON `{"error": "текст"}`, коды 400 и 404
- цены и суммы: целые числа в рублях
## Как проверять изменения
После правок запускать `npm run typecheck`, затем `npm test`. Ручная проверка: `curl http://localhost:3000/health`, затем изменённый эндпоинт.opencode.jsonc: настройки проекта
Настройки проекта живут в opencode.jsonc в корне (или в .opencode/opencode.jsonc). Формат это JSON с комментариями, схема https://opencode.ai/config.json. Уровней два: глобальный ~/.config/opencode/opencode.jsonc и проектный; проектный важнее. В строках работает подстановка {env:ИМЯ}.
Тема, хоткеи и табы терминального клиента настраиваются отдельно в ~/.config/opencode/cli.json со схемой https://opencode.ai/v2/cli.json.
{
// схема подсказывает ключи в редакторе
"$schema": "https://opencode.ai/config.json",
// модель по умолчанию для этого проекта;
// точный id скопируй из /models
"model": "opencode/beam"
}Permissions: границы для агента
Правила задаются массивом permissions; каждое правило это действие, ресурс и эффект из набора allow, ask, deny. Побеждает последнее совпавшее правило, поведение по умолчанию это разрешить с вопросом. Действия: read, edit, shell, subagent, skill, webfetch, websearch, external_directory и MCP-инструменты вида <server>_<tool>. В ресурсах работают маски * и ?.
Рабочий набор правил: разрешить безопасное (git status), запретить опасное (git push) и отправить секреты на ручное подтверждение (*.env).
"permissions": [
// git status без вопросов
{ "action": "shell", "resource": "git status *", "effect": "allow" },
// push из проекта запрещён всегда
{ "action": "shell", "resource": "git push *", "effect": "deny" },
// секреты только с явного согласия
{ "action": "read", "resource": "*.env", "effect": "ask" },
{ "action": "read", "resource": "*.env.*", "effect": "ask" },
{ "action": "read", "resource": "*.env.example", "effect": "allow" }
]Когда правило требует согласия, OpenCode показывает запрос с вариантами once, always и reject: один раз, всегда для этого ресурса или отказать. Агент plan файлы проекта не правит в принципе, поэтому обсуждение планов безопасно даже без правил. Отвечая always, перечитай дифф: решение переживёт текущую сессию.
Своя команда /review
Команда это markdown-файл в .opencode/commands: имя файла становится именем команды, review.md превращается в /review. Глобальные команды живут в ~/.config/opencode/commands/. В frontmatter задаются description, agent, model и subagent; тело файла это промпт команды.
В теле работают плейсхолдеры $ARGUMENTS и $1, а также shell-подстановка: запись вида ` !git diff ` выполнится при вызове и подставит вывод в промпт. Команда ниже запускает ревью текущего диффа агентом plan.
---
description: Ревью текущих изменений в рабочей копии
agent: plan
---
Проведи ревью изменений. Дифф: !`git diff`
1. Прочитай дифф целиком, затем открой изменённые файлы вокруг правок.
2. Проверь обработку ошибок и граничные случаи.
3. Сверь правки с конвенциями из AGENTS.md.
4. Отметь, что может сломать существующее поведение.
Ответ: список замечаний по файлам с пометками «блокирует», «стоит поправить», «на усмотрение». Если задан $ARGUMENTS — сфокусируйся на нём./review
Читаю git diff и AGENTS.md. Изменён src/routes/orders.ts: в POST / добавлена проверка items (quantity целое и не меньше 1, menuId из меню), при нарушении 400 с {"error"}. Формат ошибки соответствует конвенции из AGENTS.md. Замечания: 1) «стоит поправить»: на отрицательное количество нет регрессионного теста, tests/ покрывает только pricing; 2) «на усмотрение»: текст ошибки стоит держать рядом с остальными сообщениями роута. Блокирующих проблем нет.
Тест добавим позже. Запусти проверку из AGENTS.md.
npm run typecheck и npm test прошли без ошибок. Ревью завершено: правка готова к коммиту.
Сделай сам
# orders-api REST-сервис заказов кофейни: Express + TypeScript, база в `data/db.json`, порт 3000. ## Команды - установка: `npm install` - дев-сервер: `npm run dev` - тесты: `npm test` - типы: `npm run typecheck` ## Структура - `src/index.ts` — точка входа, монтирует роутеры - `src/routes/` — HTTP-слой: menu, orders, stats, legacy - `src/services/` — бизнес-логика: pricing - `src/db.ts` — чтение и запись `data/db.json` - `tests/` — тесты, пока только pricing ## Конвенции - статусы заказа: new → confirmed → done - ошибки API: JSON `{"error": "текст"}`, коды 400 и 404 - цены и суммы: целые числа в рублях ## Как проверять изменения После правок запускать `npm run typecheck`, затем `npm test`. Ручная проверка: `curl http://localhost:3000/health`, затем изменённый эндпоинт.npm run typecheck npm test{ "$schema": "https://opencode.ai/config.json", "model": "opencode/beam", "permissions": [ { "action": "shell", "resource": "git status *", "effect": "allow" }, { "action": "shell", "resource": "git push *", "effect": "deny" }, { "action": "read", "resource": "*.env", "effect": "ask" }, { "action": "read", "resource": "*.env.*", "effect": "ask" }, { "action": "read", "resource": "*.env.example", "effect": "allow" } ] }--- description: Ревью текущих изменений в рабочей копии agent: plan --- Проведи ревью изменений. Дифф: !`git diff` 1. Прочитай дифф целиком, затем открой изменённые файлы вокруг правок. 2. Проверь обработку ошибок и граничные случаи. 3. Сверь правки с конвенциями из AGENTS.md. 4. Отметь, что может сломать существующее поведение. Ответ: список замечаний по файлам с пометками «блокирует», «стоит поправить», «на усмотрение». Если задан $ARGUMENTS — сфокусируйся на нём./reviewgit add AGENTS.md opencode.jsonc .opencode git commit -m "Настройка агента: AGENTS.md, permissions, /review"
Отмечено 0 из 8
Проверь себя
Вопрос 1 из 5
Шпаргалка модуля
AGENTS.md
- корень проекта
- команды, структура, конвенции, проверка; коммитить в репозиторий
- /init
- черновик AGENTS.md по кодовой базе
- ~/.config/opencode/AGENTS.md
- глобальные личные инструкции
Конфиг
- opencode.jsonc
- JSONC в корне или в .opencode/; проектный важнее глобального
- {env:ИМЯ}
- подстановка переменных окружения в строках конфига
- cli.json
- отдельные настройки терминального клиента: тема, хоткеи, табы
Permissions
- allow / ask / deny
- эффекты правил; побеждает последнее совпавшее
- *.env — ask
- секреты читаются только с явного согласия
- git push * — deny
- опасные команды блокируются до shell
Команды
- .opencode/commands/*.md
- имя файла равно имени команды
- frontmatter
- description, agent, model, subagent
- $ARGUMENTS, !
команда - плейсхолдеры и shell-подстановка в теле команды