Этот репозиторий развивается в режиме agent-first: агент может автономно вносить изменения, но строго соблюдает правила ниже. Наша цель — сделать репозиторий максимально понятным для ИИ и обеспечить быстрый, механически проверяемый цикл: правка → тесты → проверка → PR.
Вместо огромного свода правил, этот файл служит оглавлением (~100–150 строк), чтобы не перегружать контекст агента. Вся детальная информация находится в директории docs/. Если этот файл и docs/ противоречат друг другу — docs/ является источником правды.
- Никаких угадываний: Если агент не знает формат данных или архитектурное решение, он обязан изучить
docs/, посмотреть контракты или спросить человека, а не «галлюцинировать» реализацию. - Механическое соблюдение: Правила архитектуры должны проверяться кодом (линтерами, CI), а не только текстом в этом файле. Если линтер пропускает код, значит он формально валиден.
- Depth-first, а не brute-force: Когда агент буксует на задаче, решение — не «стараться сильнее» и не делать руками. Нужно понять, какой возможности не хватает (инструмент, абстракция, документация, гарантия), и встроить её в репозиторий. Каждая такая доработка — инфраструктура для всех будущих задач.
Знания, которые существуют только в чатах, Google Docs или головах людей, для агента не существуют. Вся правда живет в репозитории как версионируемые артефакты.
| Путь | Назначение |
|---|---|
README.md |
Точка входа: суть проекта, быстрый старт, команды запуска |
AGENTS.md (этот файл) |
Оглавление для агента: ≤150 строк, только указатели |
docs/architecture.md |
Схема слоев, доменных границ, диаграмма зависимостей |
docs/conventions.md |
Нейминг, стиль, принятые паттерны, примеры кода |
docs/golden-principles.md |
Набор неизменных убеждений и архитектурных аксиом проекта |
docs/quality-grades.md |
Оценка качества по доменам и слоям, отслеживание долга |
docs/glossary.md |
Единый словарь предметной области (Ubiquitous Language) |
docs/exec-plans/ |
Планы выполнения: active/ и completed/ |
docs/runbooks/ |
Инструкции по диагностике типовых проблем |
adr/ |
Журнал архитектурных решений (1 файл = 1 решение) |
src/ |
Код приложения, строго разделённый по слоям |
tests/ |
Тесты, зеркалящие структуру src/ |
.linters/ |
Кастомные правила линтеров и структурные тесты |
- Запрещённые зоны: Папки
misc/,old/,tmp/без явного назначения недопустимы. Код без владельца подлежит удалению.
Агент читает контекст послойно, не загружая лишнего:
AGENTS.md→ понимает структуру, находит нужный раздел.docs/<нужный файл>.md→ получает детали конкретной темы.- Код и тесты → видит реализацию и спецификацию поведения.
adr/→ понимает почему сделано именно так (исторический контекст).
Внутри src/ код организован по принципам чистой архитектуры. Зависимости направлены только внутрь (от внешних механизмов к бизнес-логике).
domain ← application ← infrastructure
← interface
domain/(Ядро): Сущности, value objects, бизнес-правила. Не имеет зависимостей от других слоев. Не знает про БД, HTTP, фреймворки.application/(Use-cases): Сценарии использования, оркестрация домена. Зависит только отdomain. Взаимодействует с внешним миром через интерфейсы (порты).infrastructure/(Адаптеры): Реализации интерфейсов изapplication(БД, сторонние API, брокеры сообщений).interface/(Порты ввода): Контроллеры, веб-хендлеры, CLI, которые принимают запросы и вызываютapplication.
- Жёсткое правило: Прямой импорт из
infrastructureвdomainилиapplicationстрого запрещен. - Структурные тесты: В
.linters/находятся скрипты, которые парсят import-графы и ломают CI при нарушении направления зависимостей. - Запрет на циклические зависимости: CI проверяет отсутствие циклов между модулями.
Подробная диаграмма и примеры допустимых/запрещённых импортов — в
docs/architecture.md.
Агенту нужна среда с минимальной неоднозначностью. Код оптимизируется в первую очередь для машинной читаемости.
- Parse, don't guess (Парси, а не угадывай): Данные на границах системы должны строго валидироваться. Использовать жёсткие структуры и схемы (Pydantic, Zod, JSON Schema и т.п.). Никакого YOLO-доступа к полям.
- Локализация контекста: Файлы до ~300 строк. Логика разбивается на небольшие, тестируемые модули. Одна функция — одна ответственность.
- Отсутствие магии: Запрещены скрытые сайд-эффекты, глобальное состояние, сложная рефлексия и динамические импорты, если они не документированы.
- Смысловые комментарии: Комментарии объясняют «почему» принято решение, а не «что» делает код (это должно быть понятно из названий).
- Именование как документация: Имена переменных, функций, модулей должны быть самодокументирующими. Доменный язык из
docs/glossary.mdобязателен. - Единообразие шаблонов: Для типовых операций (CRUD, обработка событий, валидация) используются стандартные шаблоны, описанные в
docs/conventions.md. Агент не изобретает свой подход — он копирует существующий паттерн.
Агент работает автономно только тогда, когда может сам проверить свою работу. Чем богаче обратная связь, тем надёжнее автономия.
- Тесты как спецификация: PR не принимается без зелёного набора тестов.
- TDD для багов: Сначала пишется падающий тест, воспроизводящий баг, затем код, который делает его зелёным.
- Порог покрытия: Покрытие тестами не должно падать. Новый код покрывается не ниже порога, определённого в CI.
- Детерминированность: Тесты не зависят от внешних сервисов, времени, рандома. Используются фикстуры и моки.
Агент должен иметь инструменты для самодиагностики, а не полагаться только на тесты:
- Структурированные логи: Все сообщения — JSON/structured format, доступны агенту для парсинга.
- Локальные метрики: Время ответа, потребление памяти, размер очередей — доступны через эндпоинт или CLI-команду (
just metrics). - Проверяемые утверждения: Нефункциональные требования (например, «startup < 800ms») оформляются как тесты или CI-проверки, а не как пожелания в документации.
- Доступ к UI (если применимо): Если проект имеет фронтенд, агент имеет доступ к инструментам визуальной проверки (headless-браузер, скриншоты, DevTools), чтобы воспроизводить и верифицировать UI-баги.
Репозиторий сам защищает себя от деградации. CI — это не просто проверка, а обучающая система: каждое сообщение об ошибке должно быть достаточно информативным, чтобы агент мог исправить проблему без дополнительного контекста.
В README.md описаны стандартные команды:
| Команда | Назначение |
|---|---|
just test |
Полный набор тестов |
just test-fast |
Быстрые unit-тесты (< 30 сек) |
just lint |
Все линтеры и статический анализ |
just fmt |
Автоформатирование |
just check |
fmt + lint + test — полная проверка перед PR |
just arch-test |
Структурные тесты архитектурных границ |
just metrics |
Локальные метрики наблюдаемости |
- Автоформатирование (diff = 0 после
just fmt). - Статические анализаторы и проверка типов.
- Структурные тесты (направление зависимостей, запрет циклов).
- Полное покрытие тестами (порог не снижается).
- Проверка актуальности документации (cross-links, наличие обязательных секций).
- Размер диффа: PR > 500 строк требует обоснования или разбиения.
Кастомные правила линтеров в .linters/ должны содержать:
- Что нарушено (конкретное правило).
- Почему это важно (контекст для агента).
- Как исправить (пример правильного кода или ссылка на
docs/conventions.md).
Пример:
ERROR: domain/user.py imports from infrastructure/db.py. Domain layer must not depend on infrastructure. See docs/architecture.md#layer-rules. Fix: define an interface in application/ports/ and inject the dependency.
Документация — это продукт. Она версионируется, поддерживается и проверяется наравне с кодом.
| Документ | Содержание | Верификация |
|---|---|---|
docs/architecture.md |
Схема слоев, доменных границ, диаграмма зависимостей | CI: cross-links, наличие секций |
docs/conventions.md |
Нейминг, стиль, шаблоны кода, anti-patterns | Вручную, при ревью |
docs/golden-principles.md |
Неизменные архитектурные аксиомы проекта | Вручную, редко меняется |
docs/quality-grades.md |
Оценка A/B/C/D по доменам и слоям | Обновляется при рефакторинге |
docs/glossary.md |
Ubiquitous Language предметной области | CI: термины из глоссария в коде |
docs/runbooks/ |
Пошаговые инструкции по типовым проблемам | Вручную |
adr/ |
1 файл = 1 решение: Контекст → Решение → Последствия | CI: формат шаблона |
- ADR: Если меняется архитектура, добавляется новый ADR. Старые ADR не редактируются, а помечаются как superseded.
- Автоматическая проверка свежести: CI или фоновая задача проверяет, что документы, ссылающиеся на конкретные модули, обновлены после изменения этих модулей. Устаревшие документы помечаются или создаётся issue/PR на обновление.
- Документация из Slack/чатов: Если в обсуждении принято решение, влияющее на код — оно оформляется как ADR или обновление
docs/до мержа соответствующего PR.
Перед выполнением нетривиальной задачи агент создаёт план — это одновременно контракт с человеком и чеклист для самопроверки.
# <Task ID>: <Краткое описание>
## Контекст
Почему эта задача нужна, ссылки на issue/ADR.
## План изменений
1. [ ] Шаг 1 — что конкретно меняется, в каких файлах
2. [ ] Шаг 2 — ...
3. [ ] Обновить тесты
4. [ ] Обновить docs/ (если нужно)
5. [ ] `just check` проходит
## Риски и открытые вопросы
- Что может пойти не так, что нужно уточнить у человека.
## Верификация
Как проверить, что задача выполнена корректно (конкретные тесты, метрики, UI-проверки).После завершения — план переносится в docs/exec-plans/completed/ с отметками о выполнении.
Прежде чем считать задачу выполненной, агент обязан:
- Создать или обновить план в
docs/exec-plans/. - Написать код минимально возможным диффом.
- Добавить/обновить тесты (покрытие не должно падать).
- Убедиться, что
just checkпроходит без ошибок. - Обновить
docs/, если внесённые изменения делают текущую документацию устаревшей. - Проверить, что нефункциональные требования (если затронуты) по-прежнему выполняются.
- Написать подробный коммит-месседж: Что сделано? Почему? Как это было протестировано?
- Если задача затрагивает публичные контракты (API, схемы, events) — обновить соответствующие спецификации.
Код, генерируемый ИИ, склонен к накоплению технического долга (AI slop). Это не баг процесса, а его свойство — и с ним нужно работать системно.
- Правило бойскаута (касания): Любой затронутый файл должен стать на 10% ближе к текущему архитектурному стандарту.
- Quality Grades:
docs/quality-grades.mdсодержит оценку каждого домена/слоя (A–D). Цель — постоянно двигать оценки вверх. Агент при работе в зоне с низкой оценкой обязан зафиксировать найденные проблемы. - Постоянный рефакторинг: Дублирующийся код и отклонения от
docs/golden-principles.mdвыносятся в отдельные PR. - Миграции: Большие изменения делаются только при наличии полного тестового покрытия старого поведения. Стратегия: expand → migrate → contract.
- Автоматическое обнаружение: CI отслеживает метрики здоровья кода (дублирование, цикломатическая сложность, размер файлов) и предупреждает о деградации.
- Фоновые задачи гигиены: Периодически (или по расписанию) агент запускает сканирование на устаревшие документы, неиспользуемый код, нарушения конвенций — и создаёт PR на исправление.
Без явной команды человека агенту запрещено:
- Менять публичные контракты (API, схемы БД, event-контракты) без обновления документации и спецификаций.
- Делать массовые переименования или менять форматирование всего проекта ради «красоты».
- Трогать файлы с секретами, ключами и production-конфигурациями.
- Обходить линтеры или отключать падающие тесты без создания issue с обоснованием.
- Добавлять новые внешние зависимости (библиотеки, сервисы) без записи в ADR.
- Менять CI-пайплайн или конфигурацию деплоя.
- Удалять или понижать существующее тестовое покрытие.
- Принимать архитектурные решения, не описанные в
docs/golden-principles.md, без создания нового ADR.
Не все задачи решаемы автономно. Агент обязан эскалировать человеку, если:
- Задача требует выбора между двумя валидными архитектурными подходами, не покрытыми
docs/golden-principles.md. - Тесты нестабильны (flaky) и причина неясна после 2 попыток.
- Изменение затрагивает безопасность, персональные данные или compliance.
- Агент не может привести CI к зелёному состоянию после 3 итераций.
- Требуется доступ к внешним системам (production, сторонние API), к которым нет тестового окружения.
Формат эскалации: Issue или комментарий в PR с описанием: что пробовал, почему не получилось, какие варианты видит, какая помощь нужна.
При добавлении нового бизнес-домена или крупной фичи агент обязан:
- Обновить
docs/glossary.mdновыми терминами. - Описать границы нового домена в
docs/architecture.md. - Добавить шаблоны/примеры для типовых операций в
docs/conventions.md(если паттерны отличаются от существующих). - Создать ADR с обоснованием выбранного подхода.
- Добавить новый домен в
docs/quality-grades.mdс начальной оценкой. - Убедиться, что структурные тесты в
.linters/покрывают новые границы.
# 1. Изучи контекст
cat AGENTS.md # Эта карта
cat docs/architecture.md # Слои и границы
cat docs/conventions.md # Как мы пишем код
cat docs/golden-principles.md # Чего никогда не нарушаем
# 2. Проверь, что окружение работает
just check # fmt + lint + test
# 3. Перед задачей — создай план
# docs/exec-plans/active/<task-id>.md
# 4. После изменений — полная проверка
just check
# 5. Коммит с подробным сообщением
git commit -m "feat(domain): add X because Y. Tested by Z"Версия контракта: 2.0 | Последнее обновление: {{DATE}}
При конфликте между этим файлом и docs/ — docs/ является источником правды.