AGENTS.md

Поведенческие гайдлайны для LLM-агента, чтобы сократить типовые ошибки в коде.

Компромисс: эти правила смещают баланс в сторону осторожности, а не скорости. Для тривиальных задач — действуй по здравому смыслу.

Проектные правила: см. _docs/instructions.md и _board/process.md (они приоритетнее при конфликтах).

1. Сначала думай, потом кодь

Не додумывай. Не прячь сомнения. Озвучивай развилки.

Перед реализацией:

• Явно сформулируй свои допущения. Если не уверен — спроси.
• Если возможно несколько интерпретаций задачи — назови их, не выбирай молча.
• Если есть более простой способ — скажи об этом. Возражай, когда это оправдано.
• Если что-то непонятно — остановись, назови, что именно непонятно, и задай вопрос.

2. Минимализм

Минимум кода, решающего задачу. Никаких спекуляций.

• Никаких фич, которых не просили.
• Никаких абстракций ради одного использования.
• Никакой «гибкости» и «конфигурируемости», которых не просили.
• Никакой обработки невозможных сценариев.
• Если получилось 200 строк, а хватило бы 50 — перепиши.

Спроси себя: «Сеньор сказал бы, что это переусложнено?» Если да — упрости.

3. Хирургические правки

Трогай только то, что необходимо. Прибирай только за собой.

При правке существующего кода:

• Не «улучшай» соседний код, комментарии или форматирование.
• Не рефактори то, что не сломано.
• Сохраняй существующий стиль кода, даже если ты бы написал иначе.
• Заметил мёртвый код, не относящийся к задаче, — упомяни в коммите/обсуждении, не удаляй.

Когда твои правки создают «осиротевший» код:

• Удали импорты/переменные/функции, которые стали не нужны из-за твоих изменений.
• Не удаляй ранее существовавший мёртвый код, если об этом не просили.

Проверка: каждая изменённая строка должна напрямую соответствовать запросу пользователя.

4. Выполнение от цели

Определяй критерий успеха. Итеративно проверяй, пока не достигнешь его.

Превращай задачу в проверяемую цель:

• «Добавь валидацию» → «Напиши тесты на невалидный ввод, потом сделай их зелёными».
• «Почини баг» → «Напиши тест, воспроизводящий баг, потом сделай его зелёным».
• «Зарефактори X» → «Тесты зелёные до и после».

Для многошаговых задач сформулируй короткий план:

1. [Шаг] → проверка: [как убедиться]
2. [Шаг] → проверка: [как убедиться]
3. [Шаг] → проверка: [как убедиться]

Сильный критерий успеха позволяет работать независимо. Слабый («чтобы заработало») приводит к постоянным уточнениям.

5. Автоматизируй без ИИ

Детерминированное и повторяемое — автоматизируй инструментом, а не ИИ и не глазами.

• Рутинную проверку или операцию, выразимую кодом (линт, синхронизация конфига/доски, валидность ссылок, прогон тестов), оформляй скриптом или CI-гейтом — он дешевле, быстрее и надёжнее ИИ.
• Повтор — сигнал к инструменту: делаешь одну и ту же сверку руками или просишь ИИ дважды → напиши скрипт (scripts/, гейт в CI).
• ИИ оставляй для суждений (дизайн, рассуждения, неоднозначность), а не для механики, которую решает grep/скрипт/тест.
• Зелёный гейт — источник истины: не дублируй его ИИ-проверкой, красный — чини, а не маскируй.

Примеры в репозитории: flake8, pytest + порог покрытия, scripts/check_env_sync.py, scripts/check_sprint_sync.py, scripts/check_doc_links.py, гейт на артефакты из .gitignore — всё сразу через preflight.sh. Автоматизируются не только проверки, но и операции: ритуал перехода статуса задачи делает python3 -m scripts.task start|done <NN>.<stage>.<task> (_docs/instructions.md §13, скилл automation-discipline).

Признаки того, что эти гайдлайны работают: меньше лишних изменений в diff'ах, меньше переписываний из-за переусложнения, уточняющие вопросы появляются до реализации, а не после ошибок.

Навигация для агента

AGENTS.md — единая точка входа и источник истины для всех AI-агентов проекта. Файлы CLAUDE.md, GEMINI.md, QWEN.md, .github/copilot-instructions.md — относительные symlink'и на этот файл; правила Cursor (.cursor/rules/) и Devin/Windsurf (.devin/rules/) на него ссылаются. Меняй правила здесь — изменения подхватят все агенты. Подробно про зеркалирование и добавление нового агента — .agents/README.md.

• Правила разработки (git, стиль, async, ошибки, тесты, документация) — _docs/instructions.md.
• Процесс задач (спринты, ритуал коммитов, DoD) — _board/process.md; весь цикл задачи на одном экране — §0 «Шпаргалка (TL;DR)», остальные разделы — по ссылке из шага.
• Работа вне спринта (хотфикс, правка по итогам аудита, когда активного спринта нет) — _board/process.md §12 и журнал _board/maintenance.md. «Безымянных» коммитов в обход доски быть не должно.
• Архитектура — _docs/architecture.md.
• Целевая система (бюджет ресурсов для решений/дефолтов) — RTX 5090, 24 ГБ VRAM, Core Ultra 9 275HX, Kingston FURY Renegade G5 4 ТБ (PCIe 5.0 x4); подробности и тюнинг под слабые системы — README.md § «Целевая система и тюнинг под неё».

Skills

Скиллы-дисциплины для разработки живут один раз в .agents/skills/<name>/SKILL.md (не путать с runtime-скиллами бота в app/skills/ — _docs/skills.md). Если тема задачи совпадает со скиллом — прочитай его до правок.

• .agents/skills/architecture-discipline/SKILL.md — границы слоёв, JSON-цикл, local-first; загружай первым для широкой задачи.
• .agents/skills/async-discipline/SKILL.md — весь I/O через await, синхронные либы через asyncio.to_thread.
• .agents/skills/testing-discipline/SKILL.md — pytest + asyncio, моки внешних систем, тест на новое поведение.
• .agents/skills/error-handling-discipline/SKILL.md — иерархии исключений, нет необработанных, человеческие сообщения.
• .agents/skills/prompt-injection-defense/SKILL.md — InputSanitizer / ResponseSanitizer / FileIdMapper, allowlist опасных tools.
• .agents/skills/documentation-discipline/SKILL.md — относительные пути, синхронизация ссылок, doc-before-code.
• .agents/skills/git-discipline/SKILL.md — Conventional Commits, ритуал задачи, зелёные pytest + flake8 до коммита.
• .agents/skills/pull-request-discipline/SKILL.md — подготовка PR/MR: ветка, тело, зелёные проверки, merge только пользователем.
• .agents/skills/pr-review-discipline/SKILL.md — ревью PR/MR: чек-лист, исходы approve/reject, запрет апрува при красном CI.
• .agents/skills/automation-discipline/SKILL.md — детерминированное автоматизируй скриптом/CI-гейтом, а не ИИ; ИИ — для суждений.
• .agents/skills/debugging-discipline/SKILL.md — дисциплина отладки: стоп-линия, воспроизводящий тест, первопричина, минимальный фикс.
• .agents/skills/skill-authoring/SKILL.md — как добавлять скиллы/промпты ассистента: формат, скрипты, зеркала, проверка check_agents_sync.py.

Рекомендуемый порядок загрузки

• Широкая или неочевидная задача: architecture-discipline → профильный скилл.
• Код в app/: architecture-discipline → async-discipline → testing-discipline → error-handling-discipline.
• Новая точка входа пользовательского текста или tool с ФС/сетью: prompt-injection-defense.
• Задача про документацию: documentation-discipline. Задача про коммит/ветку: git-discipline. Задача про PR/MR: pull-request-discipline → pr-review-discipline.
• Задача про повторяющиеся проверки, скрипты или CI-гейты: automation-discipline.
• Отладка сбоя / баг-репорт: debugging-discipline → testing-discipline. Правка самих скиллов/промптов ассистента: skill-authoring.