Правила работы над проектом

Для проектов, созданных из этого шаблона: если в репозитории присутствует agent_docs/setup-checklist.md — пройти его и удалить. В 2030ai-project-template этот файл хранится как часть шаблона.

Описание проекта

• Проект: 2030ai-project-template — шаблон репозитория для проектов, где регулярно работают AI-агенты.
• Цели пользователя/команды: быстро создавать переносимые проекты с едиными правилами для Codex, Claude Code, Cursor и проектной документации.
• Как используется: как GitHub template или исходный набор файлов; в новом проекте проходят agent_docs/setup-checklist.md, заменяют описание проекта и удаляют одноразовый checklist.
• Контекст и ограничения: это docs-first шаблон без прикладного runtime; все коммитимые инструкции и конфиги должны оставаться переносимыми и не содержать локальные абсолютные пути.

В проектах, созданных из шаблона, заменить этот блок на описание конкретного проекта. Если блок не заполнен — запросить у пользователя краткое описание перед началом работы.

Принципы работы агента

Эти принципы смещают баланс в сторону точности и минимализма за счёт скорости. Для тривиальных задач — здравый смысл.

1. Понять до начала действий

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

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

Формат вопросов: коротко и по делу. Контекст вопроса прикладывать отдельно (списком ссылок/цитат), чтобы пользователь мог ознакомиться при необходимости.

2. Минимум необходимого

Минимальный объём решения, ничего спекулятивного.

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

Тест: сказал бы опытный коллега, что это переусложнено? Если да — упрости.

3. Точечные изменения

Касайся только того, что нужно. Убирай за собой только своё.

• Не «улучшай» соседний материал, форматирование, формулировки.
• Не пересобирай то, что не сломано.
• Подстраивайся под существующий стиль, даже если сделал бы иначе.
• Если заметил несвязанное «мёртвое» — упомяни, не удаляй.
• Удаляй только то, что ТВОИ правки сделали ненужным. Чужое «мёртвое» не трогать.

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

4. Работа от проверяемой цели

Сформулируй критерий успеха. Доводи до проверки.

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

• «Добавить раздел» → «Описать, что должно появиться; убедиться, что оно есть и связано с остальным».
• «Починить баг» → «Воспроизвести шагами; убедиться, что воспроизведение перестаёт работать».
• «Привести в порядок» → «Зафиксировать состояние до; убедиться, что критерий после выполнен».

Многошаговые задачи — короткий план с проверками:

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

Сильные критерии успеха позволяют работать автономно.

Автономность

• Работать самостоятельно и доводить задачу до конца.
• Не запрашивать согласование на рутинные решения. Согласование — только перед необратимыми действиями или действиями, влияющими на shared систему.
• При нехватке контекста — сначала вывести из имеющихся артефактов; если действительно не хватает — задать 1–2 коротких вопроса с приложенным контекстом отдельно.

Назначение AGENTS.md и границы

• AGENTS.md содержит только универсальные правила, применимые ко всем задачам в проекте.
• Специфические инструкции — в agent_docs/; не раздувать AGENTS.md.
• Все проектные документы — в agent_docs/, кроме README.md, AGENTS.md, CLAUDE.md.
• Событийные документы вести атомарно: одна итерация, решение, проверка или отчёт — один файл по правилам agent_docs/guides/atomic-documents.md.

Project-Local Skills

• Если проекту нужны локальные skills, источник истины: .agents/skills/<name>/SKILL.md.
• Platform mirrors: .claude/skills/<name>, .codex/skills/<name>, .cursor/skills/<name> должны быть symlink на ../../.agents/skills/<name>.
• Не создавать новые slash-command файлы; полезные workflows оформлять как skills.
• Manifest всегда называется SKILL.md.

При начале работы

• Свериться с разделом «Описание проекта» выше — это основной контекст.
• Открыть agent_docs/development-history/README.md и самостоятельно определить релевантную глубину просмотра записей по риску задачи, затронутым файлам и необходимости восстановить контекст.
• По карте agent_docs/index.md открыть только релевантные файлы.
• При проектной терминологии — свериться с agent_docs/glossary.md.

Универсальные правила

• Следовать существующим паттернам и соглашениям проекта.
• Не использовать AGENTS.md как стайлгайд или справочник команд; для стиля — линтеры, форматтеры и существующие артефакты.
• Документы держать краткими; вместо копирования больших фрагментов — ссылаться на файлы и разделы.
• Обновлять затронутую документацию.

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

• Требования выполнены, результат соответствует ожидаемому поведению.
• Каждое изменение прослеживается к исходному запросу (нет «попутных улучшений»).
• Документация обновлена; для нетривиальных изменений — отдельная запись в agent_docs/development-history/YYYY-MM-DD-HHMM-title.md.
• Если принято важное решение — добавлена отдельная запись в agent_docs/adr/YYYY-MM-DD-HHMM-title.md (шаблон: agent_docs/templates/adr.md).
• Сверено с agent_docs/guides/dod.md, критерии DoD выполнены или зафиксированы причины отклонений.
• Если тесты применимы и не запускались/не добавлены — указано почему.

Признаки того, что правила работают

• Меньше лишних правок в diff'ах и материалах.
• Меньше переделок из-за переусложнения.
• Уточняющие вопросы — до начала, а не после ошибок.