Skip to content

Latest commit

 

History

History
457 lines (338 loc) · 35.3 KB

IDLE.md

File metadata and controls

457 lines (338 loc) · 35.3 KB

idle approach

Личные инструкции для агентов, работающих с idle-проектами: правила оформления кода, подходы к работе с ним и с инструменты.

Роль агента

  • Основная специализация — архитектура, безопасность, системная разработка, разработка веб-сервисов.
  • Предпочитаемый стек: Linux, Python, Rust, TypeScript, PostgreSQL, SQLite.
  • Общайся по-русски, кратко и конкретно; не допускай калькирования на русский.
  • Проверяй гипотезы по исходникам, отличай предположения от фактов.

Общие правила

  • После завершения каждого этапа кратко сообщай результат и какой этап планируется следующим. Если работа завершена и следующего этапа нет, явно говори об этом.

Безопасность

  • Безопасность - одно из ключевых требований проекта.
  • Приложение должно гарантировать не только безопасность и стабильность исполнения своего кода, но также и безопасность данных, с которыми оно работает.
  • Не доспускай ошибок, приводящих к компрометации. Об обнаруженных критических ошибках докладывай в том же сеансе, акцентируя внимание на их достоверно возможных последствиях.
  • Не раскрывай конфиденциальные данные через результаты, ошибки и диагностику.

Область применения

  • Общие правила применяются независимо от языка программирования. Раздел «Python» относится к коду на Python; раздел «Rust» — к коду Rust; раздел «Django» — к проектам на Django.
  • Этот документ задает личный стандарт проектов. Явные требования задачи и уточнения в проектном AGENTS.md имеют приоритет над его общими правилами и значениями по умолчанию. При неразрешенном противоречии уточни требование у владельца, а не меняй правила самостоятельно.
  • Применяй правила к новому и затронутому задачей коду. Соседний код приводи к ним только при необходимости для задачи; массовую реорганизацию выполняй только после утверждения владельцем.

Работа с изменениями

  • Соблюдай принятые в проекте соглашения и структуру. Особенности уточняй по его AGENTS.md, README.md, документам из docs/ и существующему коду.
  • Не выходи за рамки задачи; посторонние исправления сначала предлагай.
  • Если замечены опечатки в коде или комментариях, предлагай их исправление.
  • При исправлении ошибки сохраняй остальное наблюдаемое поведение.
  • Всегда явно сообщай об обратно несовместимых изменениях.

Совместимость для проектов, которые ещё не были опубличены - WIP

  • Обязательства по обратной совместимости вступают в силу только после явного объявления владельца проекта. До этого не создавай слои совместимости, версионируемость форматов и структур, а также тесты поддержки прошлых выпусков. После объявления сохранять совместимость в пределах одной мажорной версии приложения; несовместимые изменения требуют смены мажорной версии и проверок на примерах предыдущих поддерживаемых форматов. Версионируемость схем, форматов, интерфейсов вводить после согласования с владельцем проекта.

Архитектура

Модули и повторное использование

  • Примитивы и операции распределяй по логически обособленным модулям: протокол, транспорт, работа с файлами, валидация, журнал, прикладные сценарии. Не собирай всё в точке входа или бесструктурном модуле utils; не дроби ради дробления.
  • Не дублируй код. Общее поведение выноси только при фактическом повторном использовании.

Состояние, ресурсы и ошибки

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

Зависимости и переносимость

  • Не привязывай пакет к расположению репозитория, рабочему каталогу разработчика, конкретному оборудованию, среде исполнения.
  • Сначала используй стандартную библиотеку и уже принятые зависимости. Не добавляй библиотеку или собственную реализацию, дублирующую имеющуюся. Инструменты разработки отделяй от runtime-зависимостей.
  • Не включай в дистрибутивы файлы окружения (.env), кеши, дампы, временные результаты, секреты и другую чувствительную информацию.

CLI

Правила этого подраздела относятся только к пакетам с командным интерфейсом.

  • После добавления команды проверяй её запуск из постороннего каталога.
  • В 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

  • Файл служит для краткого, но ёмкого описания функциональности проекта, с акцентом на то, какую пользу он может принести.
  • Файл не должен содержать избыточных деталей, в том числе технических.
  • При наличии расширенной документации, в файле дожна присутствовать ссылка на неё.
  • В случае отсутствия расширенной документации, допускается добавление в файл примеров использования базовых инструментов, которые предлагает приложение.
  • Не используй относительные ссылки: readme может отображаться там, где нет доступа к исходникам.
  • Не используй абсолютные пути в файловой системе.

Пользовательская документация

  • Хранится в docs/
  • Должна включать
    • минимальные требования зависимостей (например: Python 3.15+).
    • краткую (не более двух-трех строк) информацию по установке.
  • Может включать информацию о том, каким образом можно принять участие в проекте.
  • Отдельным разделом допускается quickstart в минималистичном виде позволяющий решить базовую пользовательскую потребность. Далее его можно развивать по шагам, наращивая сложность.
  • В случае необходимости описания API следует предпочитать автоматизированные средства описания (типа mkdocs-apidescribed-plugin).

INSTALL

  • Файл должен представлять краткое описание процесса установки приложения.

CONTRIBUTING

  • Файл представляет краткое описание процесса возможностей участия в развитии приложения.
  • Важно (в том числе для агентов) указать необходимость следования правилам из IDLE.md.

LICENSE

  • Файл должен включать текст лицензии.
  • Если не указано иное, следует использовать BSD 3-clause.

Тестирование

  • Не повторяй имеющиеся тесты, а также тесты других использующихся библиотек, каркасов, приложений.

Структура и сценарии

  • Для новых самостоятельных пакетов держи тесты в tests/; расположение тестовых файлов должно повторять иерархию модулей пакета (за исключением корневого).
  • Группируй тесты по публичному поведению.
  • Не пиши отдельные тесты приватных методов.
  • Ищи существующие тесты по настройкам тестового инструмента и фактической структуре проекта, не ограничиваясь tests/. Правило размещения новых тестов не ограничивает поиск.
  • Покрывай успешные, ошибочные и граничные сценарии, особенно отказ до записи, частичное выполнение, отмену и освобождение ресурсов.
  • Стремись к небольшому быстрому набору тестов. Не плоди и не дублируй проверки: сходные случаи объединяй там, где это логично и сохраняет понятность. Для этого ознакомься с имеющимися тестами и, когда не противоречит другим правилам, развивай их.
  • Своди к абсолютному минимуму условную логику внутри тестовых функций.
  • Подготовку, действие и проверки разделяй пустыми строками, без обязательных комментариев Arrange/Act/Assert. Имена тестов должны объяснять сценарий, но не быть многословными.
  • Для ошибок проверяй тип и существенный текст.
  • Нельзя писать тесты на тесты, а также тесты на документацию.

Фикстуры, данные и время

  • Изучай и переиспользуй имеющиеся фикстуры; варианты задавать параметризацией. Выбирай минимально необходимый scope и объём данных.
  • Не создавай фикстуры ради использования в единственном месте. Исключения — управление ресурсами, подготовка окружения и гарантированная очистка.
  • Небольшие данные допустимы непосредственно в тесте. Большие должны размещаться рядом в поддиректории datafixtures.
  • Если время или случайность влияют на результат, управляй ими через подмену зависимости. Не используй реальные ожидания для проверки таймеров и длительностей.
  • Не ослабляй production-проверки ради теста.

Изоляция и подмены

  • Общий набор тестов не должен зависеть от порядка, реального оборудования, внешней сети и привилегий.
  • Автотесты не должны требовать административных прав, изменять рабочие системные каталоги, журналы и службы или затрагивать пользовательские сеансы. Внешние взаимодействия, сторонние сервисы, подменяй либо выполняй в изолированной тестовой среде, не затрагивающей рабочую систему и данные пользователя.
  • Широко используй имитации ответов внешних процессов и системных интерфейсов: результатов команд, ошибок доступа и исчезновения внешних объектов. Подменяй внешние взаимодействия, но не проверяемые расчеты, валидацию, сериализацию и прикладные решения.
  • Unit-тесты не должны создавать реальные внешние соединения, в том числе HTTP/TLS: внешние взаимодействия подменяй.
  • Интеграционные тесты проверяют совместную работу реальных проверяемых компонентов в изоляции. Допустимы временные локальные серверы и другие необходимые изолированные компоненты.
  • Проверяй обработку ответов и ошибок.

Границы набора проверок

  • В общем наборе не выделяй отдельный набор тяжёлых тестов.
  • Локально и в CI проверяй одно и то же публичное поведение.
  • Не вводи дополнительную инфраструктуру проверок, в том числе VM-проверки, coverage и Hypothesis, без необходимости для задачи. Сохраняй уже принятую в проекте инфраструктуру проверок.
  • Сквозные (end-to-end) тесты допустимы в отдельном явно запускаемом наборе. Не включай их в общий запуск тестов ни локально, ни в CI.
  • Не добавляй тесты внутреннего механизма стороннего сборщика или установщика.

Файлы

  • Каждый редактируемый текстовый файл должен заканчиваться ровно одним завершающим LF, без дополнительных пустых строк и пробелов в концах строк.

Проверки и отчёт

  • После изменений запускай релевантные проверки и сообщай фактические результаты. Если проверка не выполнена, явно укажи это, не выдавая её за успешную.

Python

Упаковка

Структура и зависимости

  • Новые самостоятельные приложения оформляй как переносимые Python 3.12+ пакеты с src-структурой и pyproject.toml, сборка через hatchling, не setuptools.

Дистрибутивы и служебные файлы

  • В wheel включай пакет с необходимыми для работы ресурсами, метаданные и лицензии. В sdist включай исходники и всё необходимое для сборки: pyproject.toml, используемые при сборке README, лицензии, сборочные скрипты и ресурсы. Тесты и их данные в wheel и sdist не включать.
  • Для библиотек и приложений, устанавливаемых из пакета, uv.lock не включай в VCS. Для веб-сервисов, разворачиваемых из репозитория, храни uv.lock в VCS для воспроизводимого развёртывания. В wheel и sdist uv.lock не включай.

CLI

  • Точка входа — команда из [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

  • Для локальной разработки используй 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-machine 3.x не подменяй монотонные часы: нужный источник монотонного времени подменяй отдельно в тестируемом коде, не глобально.

Границы набора проверок

  • Собственный состав wheel/sdist и установку пакета проверяй, если это относится к задаче, например при изменении ресурсов пакета или точек входа.

Rust

Состояние, ресурсы и ошибки

  • В рабочем коде ожидаемые ошибки возвращай через Result и распространяй через ?. Не используй panic!, unwrap и expect для ошибок входных данных или внешних операций.
  • Ресурсы освобождай через владение и Drop. Если результат завершения операции важен, возвращай его явно; резервная очистка в Drop не заменяет обработку ошибок.

Оформление кода

  • Для путей предпочитай Path и PathBuf, сохраняя низкоуровневые операции там, где нужны гарантии работы с дескриптором.
  • Запрет однобуквенных имён переменных не относится к параметрам типов и временам жизни.
  • Методы доступа к данным могут называться как данные или ресурсы. Сохраняй стандартные имена конструкторов и методов Rust.

Тестирование

  • Не создавай каталог для одного модуля: если достаточно одного файла, использовать его вместо каталога с единственным mod.rs.
  • Для проверок используй cargo test и cargo check из каталога конкретного пакета.

Django

Модели

  • В методах __str__() моделей не обращайся к внешним ключам.

URL и пространства имён

  • В 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