Как писать документ библиотеки
Требования к документам этой библиотеки. Общие правила языка и тона — в правилах письма; здесь — что именно должно быть в документе, чтобы им можно было пользоваться.
4 минутыДокументация
Правила работы
Как писать код и документы: стиль, тесты, история изменений, язык документации.
Правила письма: документация, статьи, тексты
Перечитывать перед написанием любого текста для чтения людьми: документация, README, спека, описание формата/продукта, статья, пост, коммит-описание уровня документа. Цель — текст уровня технической документации и научной статьи, а не маркетинга.
5 минутРабота в кодовой базе
Как вносится отдельное изменение в код: с чем сверяются до, как правят, что проверяют перед сдачей и что делают при расхождении с архитектурой. Правила одинаковы для человека и для ИИ-помощника: у кода два равных пользователя, оба действуют одной логикой и видят одни и те же документы (PRINCIPLES).
10 минутРабота с git и репозиториями
Повседневные правила: что попадает в историю, как выглядит коммит, как ведутся ветки и версии, что делать при ошибке. Границы репозиториев и выделение переиспользуемых единиц — в REUSE; здесь то, что происходит внутри репозитория каждый день.
5 минутСтиль кода бэкенда
Как выглядит код внутри слоя: имена, типизация, исключения, асинхронность, записи в журнал, комментарии, размер единиц. Раскладка по слоям, иерархия маршрутов, конверт ответа, три модели данных, идемпотентность, транзакции и таймауты — в BMBP. Формат записи журнала, уровни и срок хранения — в наблюдении за системой. Хранение самих секретов — в работе с секретами. Здесь только то, что решается при написании модуля.
13 минутСтиль кода фронтенда
Как выглядит код внутри одного файла компонента: структура разметки, вложенность стилей, имена, комментарии, приёмы взаимодействия. Раскладка по слоям, границы импортов и правило «стиль лежит рядом с компонентом» — в BMFP. Роли цвета, типографика, обязательные состояния экрана — в правилах дизайна, единицы и точки перестроения — в адаптивности. Здесь только то, что решается внутри файла.
7 минутТестирование
Что покрывать тестами, какими именно и где они лежат. Документ общий для фронта и бэка: слои разные, принцип один — тест проверяет наблюдаемое поведение через границу, а не внутреннее устройство.
6 минут