madspec-generate-agents-md

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.

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

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».