| name | madspec-generate-agents-md |
| description | Генерирует для репозитория файл AGENTS.md (инструкции для coding-агентов) по лучшим практикам: коротко, детерминированно, с Persona/Architecture/Operations/Code Style/Boundaries & Security. Использовать, когда пользователь просит создать/обновить AGENTS.md, agent instructions, copilot instructions, cursor rules, CLAUDE.md. |
Generate AGENTS.md
Назначение
Сформировать AGENTS.md как операционный контракт для AI‑агента: как собирать проект, где тесты, какие правила код-стайла обязательны, и какие границы/безопасность нельзя нарушать.
Принципы (обязательно)
- Плотность: без «социального шума», только инструкции.
- Детерминизм: формулировки бинарные (делай/не делай), без «старайся/желательно».
- Коротко: цель — примерно 150–200 строк (если проект очень большой — используй иерархию).
- Show, don’t tell: где важно — добавляй 1–3 коротких примера «❌/✅».
- Безопасность: явный раздел Boundaries & Security.
- Устойчивость к ошибкам: проверки предусловий, явные исключения/ошибки, корректный rollback/cleanup.
- SOLID: при описании правил по коду закрепляй принципы (SRP, явные зависимости, тестируемость).
Стратегия размещения (root vs nested)
- Один корневой
AGENTS.md — по умолчанию для малого/среднего репозитория с единым стеком.
- Иерархия
AGENTS.md — если монорепо/несколько стеков/папки apps/, services/, packages/:
/AGENTS.md: общие инварианты (безопасность, git, CI, базовые запреты)./apps/<name>/AGENTS.md или /services/<name>/AGENTS.md: правила и команды конкретного домена.
Сбор фактов о репозитории (перед генерацией)
Собери минимально необходимую информацию, чтобы команды были точными и копируемыми:
- Стек и менеджеры зависимостей:
- Node:
package.json + lock (pnpm-lock.yaml / package-lock.json / yarn.lock)
- Python:
pyproject.toml / requirements.txt
- Go:
go.mod
- Rust:
Cargo.toml
- .NET:
*.sln / *.csproj
- Команды:
Makefile, justfile, scripts/, package.json scripts, CI workflow.
- Тесты/линтер/форматтер: названия команд и как запустить один тест.
- Структура: ключевые папки и их ответственность (не перечисление ради перечисления).
Если факт неизвестен — не выдумывай. Либо найди в репозитории, либо оставь явный TODO‑placeholder.
Правила редактирования файла (безопасное поведение)
- Если
AGENTS.md не существует → создай AGENTS.md.
- Если
AGENTS.md уже существует и пользователь явно не просил перезаписать → не модифицируй его.
- Вместо этого создай
AGENTS.md.draft (или выведи содержимое в чат) и попроси пользователя применить/заменить вручную.
- Никогда не добавляй в
AGENTS.md секреты/ключи/внутренние URL/PII.
Шаблон содержимого (структура)
Используй структуру ниже. Подставь реальные команды и реалии репозитория.
Полный шаблон см. в template.md.
Обязательные разделы:
- Persona / Context
- Architecture / Project Map
- Operations (install/build/test/lint/format + запуск одного теста)
- Code Style (правила + 1–3 примера «❌/✅»)
- Boundaries & Security
- Change policy (как поддерживать файл в актуальном состоянии)
Чеклист качества (перед завершением)
