docs: package rules in code style — README, api, Django modules

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

content/code-style.en.md

@@ -113,3 +113,27 @@ I leave code cleaner than I found it. There's no need to rewrite everything at o
 - Commit messages in the conventional commits format: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`.
 - Code that doesn't pass the linter and tests doesn't get into the main branch.
 - Secrets, keys and `.env` never get into the repository.
+
+## 10. Packages
+
+- **Every package has a `README.md`.** It says why the package exists and what problem it solves. You open the folder and understand what's inside without reading the code.
+- **The programming interface lives in an `api` module.** If other code uses the package, everything meant to be called from outside is collected in `api`. The rest of the package's modules are internal: other code doesn't reach into them, and I can change them without worrying about the package's users. If no code calls the package, it doesn't need `api`.
+
+### Django packages
+
+A Django app gets this set of modules:
+
+- **`settings`, always.** The list of every setting the package understands, with defaults and documentation for each. Inside the package, settings are read only from here, not through `django.conf.settings` scattered across the code. To find out how to configure the package, one file is enough.
+- **`urls`, if the package has views.** The package's routes; the project plugs them in with `include()`.
+- **`api`, if other code calls the package.** Following the rule above.
+
+```python
+# reports/settings.py
+from django.conf import settings
+
+# How many days to keep generated reports. After that they are deleted.
+REPORTS_TTL_DAYS = getattr(settings, "REPORTS_TTL_DAYS", 30)
+
+# Address that report emails are sent from.
+REPORTS_FROM_EMAIL = getattr(settings, "REPORTS_FROM_EMAIL", settings.DEFAULT_FROM_EMAIL)
+```

content/code-style.md

@@ -113,3 +113,27 @@ Docstring обязателен для публичных функций и кл
 - Сообщение коммита в формате conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`.
 - В основную ветку не попадает код, который не проходит линтер и тесты.
 - Секреты, ключи и `.env` никогда не попадают в репозиторий.
+
+## 10. Пакеты
+
+- **В каждом пакете есть `README.md`.** В нем написано, зачем пакет существует и какую задачу решает. Открыл папку и сразу понял, что внутри, без чтения кода.
+- **Программный интерфейс живет в модуле `api`.** Если пакетом пользуются из другого кода, все, что можно вызывать снаружи, собрано в `api`. Остальные модули пакета внутренние: другой код в них не лезет, и я могу менять их, не оглядываясь на тех, кто пакетом пользуется. Если пакет никто не вызывает из кода, `api` не нужен.
+
+### Django-пакеты
+
+Для Django-приложения набор модулей такой:
+
+- **`settings`, всегда.** Перечень всех настроек, которые пакет понимает, с умолчаниями и документацией к каждой. Внутри пакета настройки берутся только отсюда, а не через `django.conf.settings` вразброс по коду. Чтобы узнать, как настроить пакет, достаточно открыть один файл.
+- **`urls`, если у пакета есть вьюхи.** Маршруты пакета, проект подключает их через `include()`.
+- **`api`, если к пакету обращаются из кода.** По правилу выше.
+
+```python
+# reports/settings.py
+from django.conf import settings
+
+# Сколько дней хранить сформированные отчеты. После этого срока они удаляются.
+REPORTS_TTL_DAYS = getattr(settings, "REPORTS_TTL_DAYS", 30)
+
+# Адрес, с которого уходят письма с отчетами.
+REPORTS_FROM_EMAIL = getattr(settings, "REPORTS_FROM_EMAIL", settings.DEFAULT_FROM_EMAIL)
+```