Личные инструкции для агентов, работающих с idle-проектами: правила оформления кода, подходы к работе с ним и с инструменты.
- Основная специализация — архитектура, безопасность, системная разработка, разработка веб-сервисов.
- Предпочитаемый стек: Linux, Python, Rust, TypeScript, PostgreSQL, SQLite.
- Общайся по-русски, кратко и конкретно; не допускай калькирования на русский.
- Проверяй гипотезы по исходникам, отличай предположения от фактов.
- После завершения каждого этапа кратко сообщай результат и какой этап планируется следующим. Если работа завершена и следующего этапа нет, явно говори об этом.
- Безопасность - одно из ключевых требований проекта.
- Приложение должно гарантировать не только безопасность и стабильность исполнения своего кода, но также и безопасность данных, с которыми оно работает.
- Не доспускай ошибок, приводящих к компрометации. Об обнаруженных критических ошибках докладывай в том же сеансе, акцентируя внимание на их достоверно возможных последствиях.
- Не раскрывай конфиденциальные данные через результаты, ошибки и диагностику.
- Общие правила применяются независимо от языка программирования. Раздел «Python» относится к коду на Python; раздел «Rust» — к коду Rust; раздел «Django» — к проектам на Django.
- Этот документ задает личный стандарт проектов. Явные требования задачи и уточнения
в проектном
AGENTS.mdимеют приоритет над его общими правилами и значениями по умолчанию. При неразрешенном противоречии уточни требование у владельца, а не меняй правила самостоятельно. - Применяй правила к новому и затронутому задачей коду. Соседний код приводи к ним только при необходимости для задачи; массовую реорганизацию выполняй только после утверждения владельцем.
- Соблюдай принятые в проекте соглашения и структуру. Особенности уточняй по его
AGENTS.md,README.md, документам изdocs/и существующему коду. - Не выходи за рамки задачи; посторонние исправления сначала предлагай.
- Если замечены опечатки в коде или комментариях, предлагай их исправление.
- При исправлении ошибки сохраняй остальное наблюдаемое поведение.
- Всегда явно сообщай об обратно несовместимых изменениях.
- Обязательства по обратной совместимости вступают в силу только после явного объявления владельца проекта. До этого не создавай слои совместимости, версионируемость форматов и структур, а также тесты поддержки прошлых выпусков. После объявления сохранять совместимость в пределах одной мажорной версии приложения; несовместимые изменения требуют смены мажорной версии и проверок на примерах предыдущих поддерживаемых форматов. Версионируемость схем, форматов, интерфейсов вводить после согласования с владельцем проекта.
- Примитивы и операции распределяй по логически обособленным модулям:
протокол, транспорт, работа с файлами, валидация, журнал, прикладные сценарии.
Не собирай всё в точке входа или бесструктурном модуле
utils; не дроби ради дробления. - Не дублируй код. Общее поведение выноси только при фактическом повторном использовании.
- Объединяй связанное состояние, ресурсы и операции в классы или структуры, когда это логично. Допускаются классы или структуры как пространства имён, когда они объединяют связанные данные и методы.
- Импорт модуля и создание объекта не должны неожиданно обращаться к сети, запускать процессы, изменять файлы или начинать фоновую работу. Инициализация состояния и проверка аргументов допустимы; внешние действия выполнять явно.
- Освобождай ресурсы при штатном завершении, ошибке и отмене операции.
- Проверяй входные данные на границе системы. Ошибки не замалчивай; ожидаемые ошибки отделяй от ошибок программирования. Обрабатывай ошибки там, где можно корректно завершить операцию, сохранить её состояние и сообщить результат. Не добавляй неявные повторы опасных действий.
- Изменения ради производительности обосновывай измерениями; сохраняй надёжность и функциональность.
- Не привязывай пакет к расположению репозитория, рабочему каталогу разработчика, конкретному оборудованию, среде исполнения.
- Сначала используй стандартную библиотеку и уже принятые зависимости. Не добавляй библиотеку или собственную реализацию, дублирующую имеющуюся. Инструменты разработки отделяй от runtime-зависимостей.
- Не включай в дистрибутивы файлы окружения (
.env), кеши, дампы, временные результаты, секреты и другую чувствительную информацию.
Правила этого подраздела относятся только к пакетам с командным интерфейсом.
- После добавления команды проверяй её запуск из постороннего каталога.
- В CLI оставляй только аргументы, выбор команды, взаимодействие с пользователем, представление результата и коды завершения.
- Нижние слои не должны зависеть от CLI.
- Диагностику CLI направляй в stderr, данные для обработки программами (например, JSON) — в stdout без примеси логов. Справка и запрос подтверждения остаются интерфейсом CLI.
- Уровни выбирай по смыслу:
DEBUG,INFO,WARNING,ERROR. - Прикладные уведомления о прогрессе отделяй от диагностики. Для GUI и веб-интерфейса допустимы структурированные события или callback прогресса; нельзя получать их разбором логов.
- Обработчики и формат логов настраивай в точке входа. Библиотечный код не может перенастраивать глобальную конфигурацию логов.
- Сообщения CLI и журналов — на английском. Не логируй секреты и полные данные, включая бинарные.
- Если проект требует обязательного журнала или аудита, полнота этих данных не должна зависеть от уровня или обработчиков диагностического журналирования.
- Для строковых литералов используй двойные кавычки.
- Используй осмысленные имена. Никогда и нигде не используй имена переменных
из одной буквы. Примеры:
s→source,i→idx,p→path,u1→user_1,r2→response_2. - Имена функций и методов начинай с глагола и формулируй как действие:
filter_known_fields,read_database,create_empty_entry. Для предикатов использоватьis_,has_,can_илиshould_, напримерis_valid_image_path.
- Импорты обычно размещаются в начале модуля. Исключение - циклические импорты, если они оправданы.
- Внутри функций и методов разделяй смысловые части одной пустой строкой (LF).
- Не допускай в коде две и более последовательных пустых строк.
- Комментриуй и документируй на понятном литературном языке, сводя сленг к минимуму.
- Комментарии объясняют неочевидные ограничения и причины, а не повторяют код.
- Убирай неактуальные комментарии.
- Публичные методы следует документировать простыми словами.
- Не используй устаревшие инструменты, когда есть подходящие новые.
- Линтеры и форматтеры запускай только по прямой просьбе владельца, включая режимы проверки без изменений.
- Не переформатируй незатронутый тобой код.
- Описания следует давать простым, доступным широкому кругу языком.
- Файл служит для краткого, но ёмкого описания функциональности проекта, с акцентом на то, какую пользу он может принести.
- Файл не должен содержать избыточных деталей, в том числе технических.
- При наличии расширенной документации, в файле дожна присутствовать ссылка на неё.
- В случае отсутствия расширенной документации, допускается добавление в файл примеров использования базовых инструментов, которые предлагает приложение.
- Не используй относительные ссылки: readme может отображаться там, где нет доступа к исходникам.
- Не используй абсолютные пути в файловой системе.
- Хранится в docs/
- Должна включать
- минимальные требования зависимостей (например: Python 3.15+).
- краткую (не более двух-трех строк) информацию по установке.
- Может включать информацию о том, каким образом можно принять участие в проекте.
- Отдельным разделом допускается quickstart в минималистичном виде позволяющий решить базовую пользовательскую потребность. Далее его можно развивать по шагам, наращивая сложность.
- В случае необходимости описания API следует предпочитать автоматизированные средства описания (типа
mkdocs-apidescribed-plugin).
- Файл должен представлять краткое описание процесса установки приложения.
- Файл представляет краткое описание процесса возможностей участия в развитии приложения.
- Важно (в том числе для агентов) указать необходимость следования правилам из IDLE.md.
- Файл должен включать текст лицензии.
- Если не указано иное, следует использовать BSD 3-clause.
- Не повторяй имеющиеся тесты, а также тесты других использующихся библиотек, каркасов, приложений.
- Для новых самостоятельных пакетов держи тесты в
tests/; расположение тестовых файлов должно повторять иерархию модулей пакета (за исключением корневого). - Группируй тесты по публичному поведению.
- Не пиши отдельные тесты приватных методов.
- Ищи существующие тесты по настройкам тестового инструмента и фактической структуре
проекта, не ограничиваясь
tests/. Правило размещения новых тестов не ограничивает поиск. - Покрывай успешные, ошибочные и граничные сценарии, особенно отказ до записи, частичное выполнение, отмену и освобождение ресурсов.
- Стремись к небольшому быстрому набору тестов. Не плоди и не дублируй проверки: сходные случаи объединяй там, где это логично и сохраняет понятность. Для этого ознакомься с имеющимися тестами и, когда не противоречит другим правилам, развивай их.
- Своди к абсолютному минимуму условную логику внутри тестовых функций.
- Подготовку, действие и проверки разделяй пустыми строками, без обязательных комментариев Arrange/Act/Assert. Имена тестов должны объяснять сценарий, но не быть многословными.
- Для ошибок проверяй тип и существенный текст.
- Нельзя писать тесты на тесты, а также тесты на документацию.
- Изучай и переиспользуй имеющиеся фикстуры; варианты задавать параметризацией. Выбирай минимально необходимый scope и объём данных.
- Не создавай фикстуры ради использования в единственном месте. Исключения — управление ресурсами, подготовка окружения и гарантированная очистка.
- Небольшие данные допустимы непосредственно в тесте. Большие должны размещаться рядом в поддиректории datafixtures.
- Если время или случайность влияют на результат, управляй ими через подмену зависимости. Не используй реальные ожидания для проверки таймеров и длительностей.
- Не ослабляй production-проверки ради теста.
- Общий набор тестов не должен зависеть от порядка, реального оборудования, внешней сети и привилегий.
- Автотесты не должны требовать административных прав, изменять рабочие системные каталоги, журналы и службы или затрагивать пользовательские сеансы. Внешние взаимодействия, сторонние сервисы, подменяй либо выполняй в изолированной тестовой среде, не затрагивающей рабочую систему и данные пользователя.
- Широко используй имитации ответов внешних процессов и системных интерфейсов: результатов команд, ошибок доступа и исчезновения внешних объектов. Подменяй внешние взаимодействия, но не проверяемые расчеты, валидацию, сериализацию и прикладные решения.
- Unit-тесты не должны создавать реальные внешние соединения, в том числе HTTP/TLS: внешние взаимодействия подменяй.
- Интеграционные тесты проверяют совместную работу реальных проверяемых компонентов в изоляции. Допустимы временные локальные серверы и другие необходимые изолированные компоненты.
- Проверяй обработку ответов и ошибок.
- В общем наборе не выделяй отдельный набор тяжёлых тестов.
- Локально и в CI проверяй одно и то же публичное поведение.
- Не вводи дополнительную инфраструктуру проверок, в том числе VM-проверки, coverage и Hypothesis, без необходимости для задачи. Сохраняй уже принятую в проекте инфраструктуру проверок.
- Сквозные (end-to-end) тесты допустимы в отдельном явно запускаемом наборе. Не включай их в общий запуск тестов ни локально, ни в CI.
- Не добавляй тесты внутреннего механизма стороннего сборщика или установщика.
- Каждый редактируемый текстовый файл должен заканчиваться ровно одним завершающим LF, без дополнительных пустых строк и пробелов в концах строк.
- После изменений запускай релевантные проверки и сообщай фактические результаты. Если проверка не выполнена, явно укажи это, не выдавая её за успешную.
- Новые самостоятельные приложения оформляй как переносимые Python 3.12+ пакеты
с
src-структурой иpyproject.toml, сборка черезhatchling, не setuptools.
- В wheel включай пакет с необходимыми для работы ресурсами, метаданные и лицензии.
В sdist включай исходники и всё необходимое для сборки:
pyproject.toml, используемые при сборке README, лицензии, сборочные скрипты и ресурсы. Тесты и их данные в wheel и sdist не включать. - Для библиотек и приложений, устанавливаемых из пакета,
uv.lockне включай в VCS. Для веб-сервисов, разворачиваемых из репозитория, храниuv.lockв VCS для воспроизводимого развёртывания. В wheel и sdistuv.lockне включай.
- Точка входа — команда из
[project.scripts], например<package>.cli:main. Не создавайmain.pyи__main__.py; функцияmain()вcli.pyдопустима. - Нижние слои не должны зависеть от
argparse.Namespace,inputилиprint.
- Для диагностических сообщений используй стандартный
loggingи модульные логгерыlogging.getLogger(__name__), а неprintили собственный callback. - В logging используй отложенное форматирование:
logger.info("Read %d bytes", size); f-строки — для обычного построения строк.
- Свойства (
@property) и pytest-фикстуры называй как данные или ресурсы. - Аннотируй аргументы и возвращаемые значения функций и методов, включая непубличные. Keyword-only параметры используй, когда это предотвращает путаницу.
from __future__ import annotationsдобавляйь только при необходимости отложенных аннотаций, например для ссылок на ещё не определённые типы или импортов подTYPE_CHECKING. Не добавляй его во все модули по привычке.
- Внешние импорты — абсолютные, все импорты внутри приложения — относительные;
import *запрещён. - Ленивый импорт допустим по конкретной причине, например, чтобы справка и импорт библиотеки не требовали необязательного backend.
- Для путей предпочитать
pathlib.Path, сохраняя низкоуровневыйosтам, где нужны гарантии работы с дескриптором. - При повторном чтении одного и того же атрибуйта (илилих цепочки), или неизменившегося значения словаря, сохраняй его в переменной, если это улучшает читаемость. Если словарь мог измениться, повторно читать актуальное значение.
- Используй оператор
:=(walrus), когда он устраняет повторное вычисление и улучшает читаемость, не только в циклах, но и в компоновках (comprehensions). Например:names = {name_ for name in names_all if (name_ := name.strip())}.
- Перед блоками
with,for,while,if, а также передelifиelseоставляй ровно одну пустую строку. Это относится и к первому блоку сразу после объявления функции, и к вложенным блокам. - Перед
exceptоставляй ровно одну пустую строку. После блоков иraiseоставляй одну пустую строку, если далее в функции есть код. В конце файла дополнительную пустую строку не добавляй: действует правило единственного завершающего LF.
- Для обычного преобразования значений в строки и форматирования используй
f-строки, а не
str(),format()или оператор%. Исключение — обязательное отложенное форматирование сообщенийlogging, указанное выше.
- Не оставляй
.pyфайлы, содержащие только комментарии; исключение —__init__.py.
- Для локальной разработки используй makeapp:
ma toolsиma testsиз каталога конкретного пакета. В CI makeapp не используй: тесты запускай через pytest. - Для локальной работы и разработки CLI устанавливай из каталога пакета:
ma up --tool. Запускай напрямую по имени команды. В пользовательских инструкциях не описывай альтернативные способы установки и ручное управление окружениями.
- При прямо запрошенном форматировании Python используй Ruff с настройками пакета. Длина строки — не более 129 символов, либо более строгий лимит форматтера пакета.
- База тестирования — pytest. Для данных из файлов используй
pytest-datafixtures, для имитации HTTP-ответов внешних систем при использованииrequests—pytest-responsemockи его фикстуруresponse_mock, для Django-приложений —pytest-djangoapp, для управления календарным временем —time-machine(импорт и pytest-фикстураtime_machine). Все это зависимости разработки, отдельно от зависимостей времени выполнения приложений.
- Например,
src/pkg/model/config.pyсоответствуетtests/pkg/model/test_config.py. - Docstring добавляй к тестам только в неочевидных случаях.
- Для проверки исключений используй
pytest.raises(..., match=...).
- Общие фикстуры размещай в
conftest.py. Когда вариантам нужны имена, используйpytest.param(..., id="name"). - Получай фикстуры через параметры тестов, а не через импорт функций-фикстур.
- Создавай callable-фикстуры, если требуется гибкость в передаче параметров: такие фикстуры должны возвращать вызываемый объект.
- Объёмные сохранённые образцы храни в
tests/datafixtures/и читай черезpytest-datafixtures. - Используй
tmp_pathдля файлов,caplogдля логов. time-machine3.x не подменяй монотонные часы: нужный источник монотонного времени подменяй отдельно в тестируемом коде, не глобально.
- Собственный состав wheel/sdist и установку пакета проверяй, если это относится к задаче, например при изменении ресурсов пакета или точек входа.
- В рабочем коде ожидаемые ошибки возвращай через
Resultи распространяй через?. Не используйpanic!,unwrapиexpectдля ошибок входных данных или внешних операций. - Ресурсы освобождай через владение и
Drop. Если результат завершения операции важен, возвращай его явно; резервная очистка вDropне заменяет обработку ошибок.
- Для путей предпочитай
PathиPathBuf, сохраняя низкоуровневые операции там, где нужны гарантии работы с дескриптором. - Запрет однобуквенных имён переменных не относится к параметрам типов и временам жизни.
- Методы доступа к данным могут называться как данные или ресурсы. Сохраняй стандартные имена конструкторов и методов Rust.
- Не создавай каталог для одного модуля: если достаточно одного файла,
использовать его вместо каталога с единственным
mod.rs. - Для проверок используй
cargo testиcargo checkиз каталога конкретного пакета.
- В методах
__str__()моделей не обращайся к внешним ключам.
- В
urls.pyзадавайapp_nameдля создания пространства имён. - Иерархические URL записывай прямо в
urlpatternsвложенным деревомpath("prefix/", include([path(...), ...])): дочерниеpathразмещай внутриinclude, а не в плоском списке или промежуточных переменных вродеlimits_patterns.
- Миграции изменений схемы создавай и перегенерируй командами Django.
- Для авторских миграций данных и специальных операций
RunPythonилиRunSQLсоздавай пустую миграцию черезmakemigrations --empty, затем записывай необходимые операции и код преобразования. - Уже применённые миграции не переписывай без утверждения владельца, если проект явно не допускает перегенерацию первоначальных миграций на этапе разработки.
- Для миграций используй встроенные средства Django, не строй отдельный набор автотестов механизма миграций. Собственную логику преобразования данных проверяй.
- Не используй
django.test.TestCaseдля Django-тестов. Используй машинерию pytest. - В Django-тестах не задавай внутренние URL вручную — получай их через
reverse(). Не вызывай reverse() каждый раз — создавай url_* фикстуры и используй их. - При использовании фикстур, считающих обращения к БД, следи за актуальностью ожидаемого количества запросов: проверяй фактические значения, не выдумывай числа.
Источник и актуальная версия: https://gist.github.com/idlesign/206cad37df9a9cfbe1a366ff6dc1bd06