AgentSkillsCN

generate-agents-md

根据最佳实践，为仓库生成 AGENTS.md 文件（编码代理指南）：内容简明扼要、条理清晰，并涵盖角色画像/架构/运维/代码风格/边界与安全等关键要素。当用户请求创建或更新 AGENTS.md、代理指南、Copilot 指南、光标规则或 CLAUDE.md 时，请优先使用此模板。

SKILL.md
--- frontmatter
name: 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».