---
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)

1. **Один корневой `AGENTS.md`** — по умолчанию для малого/среднего репозитория с единым стеком.
2. **Иерархия `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](template.md).

Обязательные разделы:

1. **Persona / Context**
2. **Architecture / Project Map**
3. **Operations** (install/build/test/lint/format + запуск одного теста)
4. **Code Style** (правила + 1–3 примера «❌/✅»)
5. **Boundaries & Security**
6. **Change policy** (как поддерживать файл в актуальном состоянии)

## Чеклист качества (перед завершением)

- [ ] Команды сборки/тестов/линта **копируются и запускаются** (без фантазий).
- [ ] Указан **один** менеджер зависимостей (например, pnpm), чтобы не плодить lock‑файлы.
- [ ] Есть команда запуска **одного теста** (unit) и, если применимо, e2e.
- [ ] Раздел Boundaries & Security содержит запреты на:
  - эксфильтрацию данных,
  - вывод секретов,
  - деструктивные команды без явного подтверждения,
  - удаление файлов без подтверждения.
- [ ] Файл короткий, без длинных эссе и «works cited».