sab.code.lab
1c85091186
Прежняя git-история утрачена при переносе проекта на машину владельца (снапшот без .git). Хэши коммитов в docs/reports/* относятся к утраченной истории. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
759 lines
86 KiB
Markdown
759 lines
86 KiB
Markdown
# Литания перед стартом нового проекта
|
||
|
||
> **Как применять:** положи этот файл в корень нового проекта и дай Claude Code вместе
|
||
> с первой задачей: «Прочитай prestart-litany.md, определи профиль проекта, разверни
|
||
> описанную систему триажем под этот проект, затем приступай к задаче: …».
|
||
>
|
||
> **Источники:** BAZA.CRM (ERP, 22 модуля, Django+React+Celery, боевой прод), EventPlan
|
||
> (геометрический SaaS, FastAPI+React), АПЕКС-М (IoT: FastAPI+React+ESP32, боевой VPS) —
|
||
> плюс аудит всех 17 проектов рабочей папки от 2026-07-26 (Ad-Tycoon, REC dimmer,
|
||
> мониторинг, HS+auth, лендинги и др. — см. litany-audit-2026-07-26.md). Каждая грабля
|
||
> в разделе VI оплачена реальным инцидентом — источник указан в скобках.
|
||
>
|
||
> **Устройство:** ядро сформулировано стек-нейтрально; конкретика стека — в примерах
|
||
> *курсивом* и тегах `[Docker]` `[React]` `[Windows]` `[железо]`… Неприменимое к твоему
|
||
> профилю и стеку отсекается триажем (раздел 0), а не игнорируется молча.
|
||
>
|
||
> **Ссылки на литанию — только слагом** (`` `gotcha-…` `` у граблей, названием пункта у
|
||
> правил), никогда номером: перенумерация родительского документа тихо ломает все
|
||
> производные правила *(EventPlan: ссылки «V.15», «VI.10» из rules/ и ADR-0004 били в
|
||
> пустоту уже через 2 часа после финальной правки литании)*.
|
||
|
||
---
|
||
|
||
## 0. Развёртывание (порядок строгий)
|
||
|
||
### 0.1. Профиль проекта — первый вопрос, до триажа
|
||
|
||
| Профиль | Признаки | Примеры |
|
||
|---|---|---|
|
||
| **D — документ** | Артефакт = один документ, кода нет | инструкция, руководство |
|
||
| **S — статика** | Один экран/лендинг, нет БД и пользователей; правит не-программист | лендинг, брендбук |
|
||
| **A — одиночный артефакт** | Скетч, скрипт, утилита; один файл-проект | генератор, трей-клиент |
|
||
| **M — продукт без своего прода** | Код, тесты, релизы — но нет своего сервера/БД/денег | игра, расширение, десктоп |
|
||
| **XL — полное ядро** | Прод, БД, деньги, пользователи, контейнеры, железо в поле | ERP, SaaS, IoT-платформа |
|
||
|
||
Без профилей мелкие проекты выпадают из процесса целиком, а не частично: 6 из 17
|
||
проектов папки жили вообще без git, один версионировался зипами `(4)…(8).zip`.
|
||
|
||
### 0.2. Минимальное ядро — действует ВСЕГДА, даже для D и S
|
||
|
||
1. **git с первого файла** + `.gitattributes` (`* text=auto eol=lf`) и `.gitignore` —
|
||
ДО первого `git add`. Никаких копий-папок и зипов как версий.
|
||
2. **Секрет-гигиена** — включая документацию, примеры команд и **рабочий каталог**:
|
||
секреты вне git всё равно попадают в бэкапы диска, скриншоты и контекст агента,
|
||
получившего доступ к папке *(recovery-коды открытым текстом в корне папки проектов)*.
|
||
3. **Опасные действия письменно**; на боевом — только команды, выполняет человек.
|
||
4. **Бэкап перед перезаписью боевого файла** (ротация N копий).
|
||
5. **Версия и дата на артефакте**: подвал сайта, штамп «версии на момент составления»
|
||
в доке, `v1.0 · дата` в README.
|
||
6. **Плейсхолдеры помечены** (`?`, TODO владельцу) и сверяются перед выкладкой.
|
||
7. **Мини-ритуал закрытия**: обновить дату, строка «что сделали», всё отложенное —
|
||
письменно в момент откладывания.
|
||
8. **Развилки — через AskUserQuestion**, очевидные дефолты — принять и озвучить.
|
||
9. **Один ADR** даже в S — на 5 строк, но с обязательным «Компромиссом».
|
||
|
||
### 0.3. Профильные добавки (сверх ядра)
|
||
|
||
- **D:** SoT — исходник (HTML/markdown), PDF — производный артефакт, пересобирается
|
||
вместе с ним; раздел «версии ПО на момент составления»; нумерация до третьего уровня
|
||
(чтобы ссылаться на шаг в переписке); визуальные классы опасности (danger/warn/ok)
|
||
вместо прозы; владелец и дата пересмотра.
|
||
- **S:** контент отделён от кода **одним файлом** («правишь это, остальное не трогай»);
|
||
индексация закрыта по умолчанию (`Disallow: /` + noindex), открытие — сознательный
|
||
акт по чеклисту (robots, аналитика, schema.org, PageSpeed, Вебмастер/Search Console,
|
||
privacy-policy не заглушка); deny-list «что не выкладывать на прод» (локальный
|
||
редактор, дизайн-канвас); бюджет веса страницы и картинок; документ передачи
|
||
не-разработчику (варианты правки по возрастанию сложности, лимиты хостинга).
|
||
- **A:** один README-витрина: что это · пины/константы **одной таблицей** · как
|
||
собрать · troubleshooting «симптом → причина»; все физические/средовые константы
|
||
в одном месте файла; способ проверить **без** железа/боевого стека + одна строка
|
||
«чего он не проверяет».
|
||
- **M:** + чистое ядро и детерминизм (II), версионирование локального состояния (I),
|
||
адаптер платформы (I), CI-матрица ОС (II), профиль публичного релиза (V), роли (IV).
|
||
- **XL:** литания целиком.
|
||
|
||
### 0.4. Триаж
|
||
|
||
Для D/S/A — «профиль + список отклонений» ≤10 строк в README. Для M/XL — полный,
|
||
каждый пункт → **IN / DEFERRED / OUT** с причиной, итог — одним ADR. Формат вердиктов
|
||
(проверен дважды: EventPlan ADR-0004, АПЕКС ADR-024):
|
||
|
||
| Пункт | Вердикт | Причина / условие |
|
||
|---|---|---|
|
||
| … | IN / DEFERRED / OUT | … |
|
||
|
||
+ обязательный раздел «Компромиссы — что осознанно потеряли». DEFERRED — только
|
||
с условием активации («появятся формы → схемная валидация»), не «потом». Осознанный
|
||
legacy-путь получает зеркальное — **условие снятия** («удалить, когда ни одного
|
||
устройства с plaintext-токеном»), иначе он вечен. Мёртвое правило убивает доверие
|
||
ко всем правилам.
|
||
|
||
### 0.5. Стартовый бриф и вопросы
|
||
|
||
**Вопросы одним заходом** (AskUserQuestion): стек и версии тулчейна, число артефактов
|
||
версии, есть ли фронтенд / воркеры / прод / железо, ОС разработчика. Бриф проекта
|
||
пишется по шаблону, проверенному дважды *(HS+auth PROJECT_BRIEF, REC dimmer bootstrap)*:
|
||
принципы-обязательства → **«Чего НЕ делать»** (явные запреты) → этапы с подтверждением
|
||
человека → «что нужно на выходе» → финал **«ничего не пиши в файлы, пока не согласуем;
|
||
вопросы без ответа в документах — задай списком, не делай допущений»**. Полезный
|
||
парный документ — памятка человеку «как ставить задачу»: шаблон [ЗОНА][ДЕЙСТВИЕ],
|
||
формат баг-репорта, «чего НЕ указывать — уже в CLAUDE.md» *(АПЕКС how_to_ask.md)*.
|
||
|
||
### 0.6. Каркас и финал развёртывания
|
||
|
||
Развернуть каркас из разделов I–V по итогам триажа. Финал: показать пользователю
|
||
Module Map и список созданных правил на ревью → отдельный коммит каркаса → только
|
||
затем первая боевая задача.
|
||
|
||
### 0.7. Обратный поток граблей
|
||
|
||
Копия литании в проекте — read-only архив, её не редактируют. Новые грабли проекта
|
||
пишутся в живой раздел `docs/architecture.md#Грабли проекта` с источником; раз в
|
||
несколько сессий обобщаемое мигрирует в мастер-литанию *(Самолётики: финал «дописывай
|
||
в VI» оказался невыполним — копия заморожена, дописывать было некуда)*.
|
||
|
||
Раздел VI — постоянный чеклист на всю жизнь проекта, не одноразовое чтение.
|
||
|
||
Всё общение и документация — на русском. Идентификаторы кода, пути API, хэши и версии
|
||
не переводить — по ним ищут в коде; жаргон — с оригиналом в скобках при первом
|
||
упоминании *(BAZA d64605c)*.
|
||
|
||
## I. Архитектура — принципы, проверенные боем
|
||
|
||
1. **Модульность:** один модуль/приложение = одна бизнес-область. Cross-module общение —
|
||
только события или явные сервис-вызовы через абстракции; прямой импорт внутренностей
|
||
чужого домена запрещён. Каждый новый модуль в момент создания попадает в Module Map (III.1).
|
||
2. **Сервисный слой:** контроллер/view/handler = parse → call service → respond, ноль
|
||
логики. Модель = структура данных. Вся бизнес-логика в сервисах; при росте делить на
|
||
подмодули СРАЗУ (реэкспорт сохраняет внешний контракт), не ждать god-файла.
|
||
3. **Статусы = конечный автомат:** защищённое поле + именованные переходы с
|
||
source/target/permission + side-effects внутри перехода. Прямое присваивание статуса
|
||
запрещено — это обход прав, аудита и эффектов.
|
||
4. **Аудит-след обязателен:** каждая транзакция создаёт запись в журнале через **единую
|
||
точку применения эффекта**. Мутация в обход журнала — критическая ошибка. Контракт
|
||
логирования — таблицей «событие → что логировать» с именованным логгером, иначе
|
||
«аудит обязателен» выполняется на глаз *(BAZA CLAUDE.md)*.
|
||
5. **Soft delete** для доменов с документами/деньгами, двухуровневый: документы/деньги =
|
||
`is_active + deleted_at`; справочники = только `is_active`. Физический delete запрещён;
|
||
связи на audit-модели — PROTECT.
|
||
6. **Деньги = Decimal** (12,2) или целые минорные единицы. Float рядом с money-полями —
|
||
блокирующая ошибка. Общий принцип: **число без объявленной единицы — баг, ждущий
|
||
повода**; единицы измерения и система координат — часть контракта, объявляются
|
||
письменно один раз *(EventPlan: «единицы — миллиметры», СК от самой длинной стены)*.
|
||
Есть стандартный формат обмена для домена (GeoJSON, iCal, ISO-коды) — брать его,
|
||
не изобретать: бесплатные валидаторы и общий язык со всеми слоями.
|
||
7. **Миграции схемы append-only:** существующие не редактировать; каждая data-миграция
|
||
обратима; большие таблицы — expand → backfill → contract. Механика раннера (glob vs
|
||
реестр, порядок применения, идемпотентность) — в README рядом с миграциями, иначе
|
||
каждая сессия изобретает своё *(АПЕКС)*. У грабли «дрейф миграций» записан не только
|
||
запрет, но и рецепт восстановления *(BAZA: 5 шагов через MigrationLoader)*.
|
||
8. **Внешние вызовы:** только асинхронно (очередь), идемпотентные ключи, retry с backoff,
|
||
верификация вебхуков, audit-лог каждого вызова. Внешняя платформа/SDK (маркетплейс,
|
||
магазин, игровая площадка, платёжка) — за адаптером с **двумя реализациями: боевой и
|
||
Local-заглушкой**; вход в приложение — в try/catch с фолбэком; требования модерации —
|
||
чеклистом ДО релиза *(Ad-Tycoon: PlatformAdapter, «вечный чёрный экран» без фолбэка)*.
|
||
Недоступные из твоей инфраструктуры внешние сервисы — письменно списком, иначе агент
|
||
раз за разом предлагает нерабочее *(АПЕКС: Telegram на RU-VPS, protomaps)*.
|
||
9. **Парные операции симметричны с рождения:** если есть create-эффект — в том же
|
||
коммите пишется cancel-эффект и ТЕСТ на пару (`gotcha-pair-asymmetry`).
|
||
10. **Без хардкода — в меру.** Значение, которое может измениться, повториться или
|
||
зависеть от окружения/клиента — в константу/конфиг/env/данные. Самоочевидные
|
||
единичные значения не выносить. **Доменные параметры** — редактируемые данные
|
||
(сид + переопределение на сущность), не константы; вычислительное ядро принимает их
|
||
параметром и остаётся чистым *(EventPlan ADR-0003)*. То же — **матрица прав и
|
||
фиче-флаги**: данные в БД, редактируемые без релиза *(BAZA)*. Параметры, зависящие
|
||
от экземпляра (калибровки, коэффициенты per-device/per-tenant) — хранятся при
|
||
экземпляре, не в коде `[железо]` *(АПЕКС: NVS, калибровка минимум в 3 точках)*.
|
||
Настроечная константа (таймаут, батч, буфер) — с единицей, формулой следствия и
|
||
направлением компромисса, иначе следующая сессия крутит её вслепую *(VOX: DMA-буферы
|
||
«4 мс; меньше → щелчки; больше → латентность»)*.
|
||
11. **Contract First для многослойных контрактов.** Контракт, потребляемый несколькими
|
||
артефактами — таблица слоёв в CLAUDE.md, изменение обновляет ВСЕ слои одним
|
||
коммитом. Wire-протокол версионируется отдельно от приложений — два разных SoT,
|
||
с письменной матрицей «что бампает протокол» (optional-поле → minor, required/
|
||
переименование → major, багфикс payload не бампает) *(АПЕКС versioning.md)*.
|
||
**Порядок выката — часть контракта:** сервер раньше клиента, новые поля optional
|
||
(expand→contract для провода). Совместимость — **декларация клиента**
|
||
(`api_version_min` в манифесте, клиент сам блокируется), а не блокировка сервером:
|
||
отклонение данных по версии создаёт слепые зоны ровно у проблемных клиентов
|
||
*(АПЕКС ADR-016)*. Агент, меняющий контракт, обязан спросить: «нужно ли обновить
|
||
остальные слои?» Удалил поле из контракта — докажи grep'ом, что его никто не
|
||
читает *(АПЕКС: orphan-читатели top-level `version`)*.
|
||
12. **Docker-first** (если проект контейнерный): ничего не запускается на хосте; базовый
|
||
compose + явные именованные override-файлы; healthchecks на всех сервисах; non-root;
|
||
секреты только env. Осознанное отклонение — строка в реестре долгов «принято
|
||
осознанно» + **явный запрет альтернативной команды** («никогда `docker compose build
|
||
frontend`») — запрет важнее правила: именно его агент нарушит по инерции *(АПЕКС)*.
|
||
13. **Fail-safe: неопределённое состояние = безопасное.** Заглушки нереализованных
|
||
модулей отказывают в безопасную сторону (недописанный чек прав — запрещает,
|
||
недописанный лимит — блокирует, фича-флаг по умолчанию выключен); где отказ
|
||
физически опасен — второй барьер вне кода `[железо]` *(REC dimmer: аппаратная
|
||
подтяжка — ресет/прошивка/Hi-Z = ключи закрыты без участия кода)*. **Деградация
|
||
вместо отключения**, и «плохие данные» ≠ «нет данных»: политики разные, обе
|
||
спроектированы явно; **нет данных — не гадать** *(REC dimmer: отказ датчика →
|
||
вентилятор на максимум, лимиты НЕ применяются)*. Отсутствие показателя ≠ ноль:
|
||
прочерк, а не 0 *(tray-monitor; мониторинг: `absent()` — отдельный алерт)*.
|
||
Fail-open/fail-closed выбирается **на каждую точку отдельно, по длительности окна
|
||
риска** *(АПЕКС ADR-017: HTTP fail-open — окно один запрос; WS fail-closed — канал
|
||
жил бы часами)*; код ошибки, который UI трактует как команду, не получает второго,
|
||
инфраструктурного смысла. Отказ канала связи ≠ отказ узла — различие моделируется
|
||
в протоколе, эскалация зависит от того, что известно *(АПЕКС ADR-011)*.
|
||
14. **Персистентное состояние вне транзакционной БД** (сейв, localStorage, NVS, файл
|
||
конфига, кэш) — та же дисциплина, что схема БД: `version` + контрольная сумма +
|
||
**атомарная запись** (temp + rename; два слота пинг-понгом на flash) + миграция при
|
||
загрузке + roundtrip-тест; битое состояние не роняет приложение — старт с чистого /
|
||
дефолтов с указанием места поломки *(REC dimmer EEPROM-блоб; мониторинг mktemp+mv;
|
||
tray-monitor; Ad-Tycoon: `// TODO: restore staff` — купленное исчезало)*.
|
||
15. **Права — на уровне выборки, не UI:** выдача фильтруется по пользователю в самом
|
||
запросе (IDOR), permission-классы объявлены явно на каждом эндпоинте *(BAZA)*.
|
||
Пагинация на всех list-эндпоинтах, явный ordering (недетерминированный порядок
|
||
ломает пагинацию), запрет N+1.
|
||
16. **Retention фиксируется раньше механизма:** для каждой таблицы, растущей от
|
||
активности (телеметрия, логи, события, аудит) — «сколько храним» решено письменно,
|
||
компенсирующий контроль (индекс, мониторинг объёма) — сразу *(АПЕКС ADR-019)*.
|
||
Класс данных, запрещённый к отправке во внешние сервисы **включая облачные AI**, —
|
||
объявлен письменно ДО первой интеграции *(АПЕКС: 152-ФЗ → только локальная модель)*.
|
||
17. **Один назначенный писатель** — там, где блокировать нельзя (ISR, UI-поток, горячий
|
||
путь): ресурс пишет ровно один владелец, обмен через двойной буфер/очередь; это
|
||
парный паттерн к «блокировка на счётчиках» (`gotcha-increment-race`) *(REC dimmer:
|
||
CCR пишет только ISR TIM6)*. Эксклюзивный ресурс (COM-порт, файл-лок, сокет)
|
||
освобождается явно до передачи следующему; поток без фреймов — дренаж запоздалых
|
||
ответов и фильтрация незапрошенного `[железо]` *(АПЕКС release process)*.
|
||
18. **Не создавай второй канал доставки для того, без чего не работает первый:** конфиг,
|
||
ключ, сертификат, схема — если их доставка идёт другим путём, чем код, отказ
|
||
доставки убивает возможность починки *(АПЕКС ADR-022: CA вшиты в прошивку — битая
|
||
отдельная партиция значила бы мёртвый TLS = мёртвый OTA = физическая перепрошивка)*.
|
||
19. **Файлы:** бинарники не в БД — хранится путь; превью асинхронно; статику/медиа
|
||
отдаёт прокси мимо приложения, приватное — через X-Accel-Redirect/аналог *(BAZA)*.
|
||
Каждый подписчик события — с уникальным идентификатором подписки (dispatch_uid):
|
||
двойное подключение = двойные эффекты, почти не диагностируется *(BAZA)*.
|
||
20. **Автономный/демо/offline-режим — как обычный источник данных, а не ветка `if` во
|
||
всём тракте:** подделывается вход, не тракт *(REC dimmer: STATIC-кадр — обычный
|
||
валидный сигнал для FSM, пайплайн без спецслучаев)*.
|
||
|
||
## II. Код и гейты
|
||
|
||
1. **Гейты с ПЕРВОГО коммита:** форматтер + импорт-сорт + линтер + типы в pre-commit и
|
||
CI. Для нового кода — 0 warnings сразу; для унаследованного долга — **рэтчет**
|
||
warn→error с зафиксированным потолком и планом, не разовая зачистка *(BAZA ADR-051)*.
|
||
Гейты двух уровней: **hard блокирует, soft предупреждает** *(АПЕКС)*. Поведение при
|
||
провале — письменно: остановиться, показать упавший гейт + полный stderr, не чинить
|
||
молча; обход по команде — `NOTE: committed with failing <gate>` в тело коммита.
|
||
Обоснованный пропуск гейта — с условием возврата («тесты — план 0.8.0»), иначе
|
||
«нулевая терпимость» обходится тихо. Неиспользуемая disable-директива = ошибка.
|
||
Ложное срабатывание любого сканера гасится **самым узким скоупом** (allow по пути),
|
||
не глобальным игнором класса правила *(BAZA trivy)*. Локальный гейт и CI — один
|
||
инструмент одной версии. Форматтеры не трогают append-only артефакты (глобальный
|
||
exclude на миграции — правило нарушает автоформат, а не человек) *(BAZA 2026-07-21)*.
|
||
*Инструменты по стеку: Python — black/isort/ruff/mypy; TS — eslint + `tsc -b --noEmit`.*
|
||
2. **Правило, проверяемое машиной — хук, а не абзац.** Каждый инвариант литании,
|
||
выразимый регуляркой/AST, дублируется PreToolUse-хуком в момент формулировки —
|
||
иначе живёт до первой спешки *(BAZA: 12 блокирующих — float у денег, физический
|
||
delete, правка миграции, секреты, DEBUG в prod…)*. Блокирующие и напоминающие хуки —
|
||
два разных класса; Stop-хук — для напоминаний о ритуалах. Обязательные спутники
|
||
хука: список исключений (migrations/, node_modules/, собственные литералы паттернов),
|
||
тесты на сам хук, быстрый путь выхода (оверхед на каждый tool call). Покрытие
|
||
хука проверяется по **всем шеллам**, которыми реально пользуется агент
|
||
(`gotcha-hook-shell-blind`).
|
||
3. **Каждый слой каркаса проверяй сразу, не в конце:** после каждого слоя — прогон
|
||
гейтов. Ошибки ловятся дёшево у источника *(EventPlan)*.
|
||
4. **Тулчейн и системные зависимости проверяй фактически ДО написания конфигов:**
|
||
запусти и убедись, не предполагай. Версии пинуй; что тянет либа — в ADR/Dockerfile
|
||
в момент выбора *(EventPlan: corepack pnpm; Shapely→GEOS, weasyprint→pango)*.
|
||
5. **Типы обязательны** на всех функциях. **Функции ≤40 строк** без явного обоснования.
|
||
6. **Тесты зеркалят структуру**, фабрики, AAA. Тест = полная жизненная цепочка, не
|
||
изолированный вызов. Каждый багфикс приносит тест. Интеграционные — на реальной БД,
|
||
мок только для внешних сервисов. Фича, меняющая контракт, обновляет свои тесты в том
|
||
же коммите (`gotcha-feature-test-debt`). Для вычислительного ядра цепочка — не то:
|
||
там **инварианты алгоритма в docstring** как контракт + property-based тесты, автор
|
||
инварианта и автор теста — разные агенты *(EventPlan: hypothesis)*. Цифра покрытия —
|
||
только с конфигурацией замера («69% с greenlet, без него фиктивные 56%»); расхождение
|
||
тестовой и прод-СУБД — задокументированное ограничение, не умолчание *(АПЕКС)*.
|
||
7. **Тесты wiring — отдельный класс от тестов логики.** Юнит-тест, импортирующий объект
|
||
напрямую, не проверяет, что система его находит: любая регистрация «по конвенции»
|
||
(задачи, сигналы, плагины, роуты) требует теста «всё, на что ссылается конфиг,
|
||
реально зарегистрировано» (`gotcha-silent-unregistered`). **Orphan-check:** публичная
|
||
функция ядра без единого вызывающего — баг интеграции или мёртвый код
|
||
(`gotcha-green-modules-dead-system`). Конфиг-поле без потребителя — ложь в диффе;
|
||
конфиг валидируется при старте (fail fast), единицы измерения совпадают с кодом
|
||
*(Ad-Tycoon: в конфиге 2, в коде хардкод 0.02 — расхождение в 100 раз)*.
|
||
8. **Тест без боевой среды — спроектирован, не случаен.** Ядро не импортирует ни строчки
|
||
среды исполнения И ни строчки вендорского SDK — это две разные оси изоляции, обе
|
||
проверяются **сборкой** (второй target «на хосте»), а не дисциплиной *(REC dimmer:
|
||
core/ не видит hal/; АПЕКС ADR-021: изоляция окупается тестируемостью даже без
|
||
миграции; VOX: dsp.h собирается на ПК)*. Внутри ядра запрещены Date.now() /
|
||
Math.random(): часы и seeded RNG инжектируются — детерминизм = воспроизводимые
|
||
тесты *(Ad-Tycoon)*. Матрица средств тестирования — с честным «чего НЕ покрывает
|
||
ни один» *(VOX: Wokwi vs WAV-стенд)*. Мок-режим — полноценный режим приложения со
|
||
сценарием по расписанию, включая негативные состояния *(tray-monitor: три сервера
|
||
со сдвинутыми фазами, один намеренно без датчика)*. Симулятор внешней системы —
|
||
первоклассный артефакт со своими правилами: те же схемы, что у прод-кода (не
|
||
копипаст полей), seed, префикс SIM_/флаг is_simulated, assert «не прод» *(АПЕКС)*.
|
||
Для доменов с накопительной динамикой — headless-прогон N шагов ботом с проверкой,
|
||
что метрики двигаются *(Ad-Tycoon: «7 дней, seed 42» показал экономический тупик)*.
|
||
Смоук-сценарий на то, что уже ломалось — для слоёв, не берущихся юнит-тестами
|
||
(GUI, трей, жизненный цикл процесса) *(tray-monitor)*.
|
||
9. **Фоновые задачи** (если есть очередь): никакой бизнес-логики в таске — таска
|
||
вызывает сервис; queue, time_limit, retry с backoff, идемпотентность; передавать id,
|
||
не объекты.
|
||
10. **Фронтенд** (если есть): strict-типизация без `any`; единый api-клиент (auth +
|
||
refresh + interceptor в одном месте); server state отдельно от клиентского *(у нас
|
||
react-query + zustand)*; формы со схемной валидацией *(RHF + zod)*; дизайн-система
|
||
классов вместо inline-стилей; error boundary на каждый маршрут **с key**; скачивание
|
||
защищённых файлов — только через api-клиент (blob); единый паттерн деталей сущностей.
|
||
**Строки UI — в один ресурс с первого дня**, даже в одноязычном проекте: ретрофит
|
||
i18n дороже в разы, а правки текстов не должны требовать правки кода *(Ad-Tycoon:
|
||
файл есть, UI захардкожен — местами показывались ключи)*. **Бюджеты числами**
|
||
(размер сборки, TTI, запросы) — проверяются при добавлении тяжёлого, не «когда
|
||
станет медленно».
|
||
11. **CI — это не только гейты:** CI слушает **рабочую** ветку — сменил ветвенную
|
||
модель → в тот же коммит триггеры CI/хуков (`gotcha-ci-wrong-branch`); для
|
||
кроссплатформенного артефакта — матрица `ubuntu + windows` (автоматически ловит всю
|
||
группу Windows-граблей); CI **собирает** релизный артефакт (ловит зависимость от
|
||
файла вне git); гейт «чистый клон собирается и стартует»; supply-chain в базовом
|
||
наборе (audit зависимостей, скан образа, встроенный `check --deploy` фреймворка —
|
||
бесплатный гейт, который никто не включает); coverage-порог *(BAZA)*. Свой
|
||
CI-раннер не селить рядом с боевыми сервисами — 1600 тестов = OOM соседям *(BAZA)*.
|
||
Прод-образ намеренно без dev-тулинга; ожидаемое «падение pytest на проде» —
|
||
задокументированная фича, не поломка *(BAZA)*.
|
||
12. **Лицензионный гейт:** политика лицензий стороннего кода письменно (для закрытого
|
||
продукта — только пермиссивные); новый компонент — сначала строка в
|
||
THIRD_PARTY_LICENSES.md, потом в сборку *(REC dimmer)*.
|
||
|
||
## III. Бумажная работа (карта + документация + версии)
|
||
|
||
Развернуть с первого дня — «потом» не наступает (`gotcha-docs-drift`).
|
||
|
||
1. **Карта навигации:** Module Map в CLAUDE.md (строка на модуль: путь — назначение —
|
||
ключевые сущности) + navigation-док (дерево каталогов; таблица сущностей —
|
||
генерируется grep'ом, не по памяти; «задача → где искать»). Список крупных файлов —
|
||
не как список, а как **порог (параметр) + команда генерации + дата сверки +
|
||
автопроверка в обе стороны** («перерос, но не в списке» и «в списке, но похудел»)
|
||
*(АПЕКС check-integrity)*. Правило контекст-экономии первым пунктом workflow;
|
||
большие файлы — поиск → чтение диапазона; правило передавать субагентам.
|
||
2. **Документация — один индекс и один гейт.** Два независимых дерева = двойная цена
|
||
синхронизации *(BAZA проходила)*. Артефакт, потребляемый кодом (changelog в UI,
|
||
схема в сборке), законно живёт в коде — но обязан быть в таблице маршрутизации
|
||
ритуала закрытия. Формат — под проект и потребителя, выбор зафиксировать.
|
||
**Документация проходит гейт как код**: strict-сборка доков (битые ссылки, файлы
|
||
вне nav) — дерево без гейта гниёт по ссылкам быстрее, чем по содержанию *(АПЕКС:
|
||
mkdocs --strict)*. Состав дерева: index, architecture, api-reference, decisions
|
||
(ADR), versioning, onboarding, runbook (+production-runbook при проде), по-модульные
|
||
доки; штамп «Обновлено: дата | версия». **Runbook — в формате «Симптом →
|
||
Диагностика → Фикс»**, не описание системы *(×4 проекта независимо)*. Второй
|
||
потребитель — человек вне разработки (сборщик, заказчик): его версия **генерируется**
|
||
из основной, не пишется дважды *(VOX: md→html конвертер «открыть двойным щелчком»)*.
|
||
README = витрина: версия + badge, таблица модулей (число = факт!), старт.
|
||
3. **ADR:** нетривиальное решение (≥2 реальных альтернатив) → Контекст / Альтернативы /
|
||
Решение / Причины / **Компромисс** (обязателен). Существующие ADR не редактируются.
|
||
«Почему не X» — рядом с решением, особенно где ошибка необратима *(Pulse generator:
|
||
таблица отвергнутых MOSFET с причинами)*. Ключ связывания систем — решение с
|
||
**организационным следствием**, и оно пишется в Компромисс *(HS+auth: маппинг по
|
||
email ⇒ «почты сотрудников нельзя переиспользовать» — правило для отдела кадров)*.
|
||
4. **Ритуал закрытия сессии** (скилл с триггер-фразой): «закрываем сессию» → дифф
|
||
сессии (`git log` + `git status`) → свести затронутые зоны (модуль → дока + карта;
|
||
процесс → правило; решение → ADR; бамп → changelog; закрытый долг → реестр) →
|
||
отдельный `docs(sync)`-коммит. **Если сводить нечего — сказать это явно, не молчать**
|
||
(иначе ритуал незаметно отмирает) *(АПЕКС)*. Канонические имена/URL при сведении
|
||
сверяются grep'ом с кодом — SoT имени всегда код *(BAZA: `/healthz` числился
|
||
`/api/health/` в пяти доках)*. После docs-сессии — короткий список реально
|
||
исполняемых изменений *(АПЕКС post-rules-refactor)*. Штамп ≠ гарантия актуальности.
|
||
5. **Статусы в планах — по факту кода, в обе стороны.** Фантомные хвосты: пункт числится
|
||
открытым, а код давно есть — перед реализацией «незакрытого» сверка с кодом *(BAZA:
|
||
2 из 4 хвостов)*. Сводки и индексы правятся **атомарно** с деталью. **Реестр
|
||
«Критические долги» — в НАЧАЛЕ roadmap** (не в подвале): приоритет, слой, условие
|
||
закрытия; закрытие — двухфазно: коммит-фикс, затем коммит-пометка с точным SHA
|
||
первого (смешивать нельзя — SHA фикса ещё не существует в момент правки таблицы)
|
||
*(АПЕКС)*. Чек-лист `[x]` — только если формулировка однозначно совпадает с диффом;
|
||
буллеты закрытых релизов — неизменяемая история. **План фазы — в репозитории, не в
|
||
памяти агента**, с блоком «Ключевые решения (не пере-решать)» со ссылками на ADR —
|
||
прививка от пере-обсуждения решённого *(АПЕКС 0.7.0-execution-plan)*. Опционально —
|
||
HTML-дашборд прогресса с блоком DATA, собираемым из git, обновляется в ритуале
|
||
закрытия *(Dashboard/BAZA)*.
|
||
6. **Версии:** SemVer; письменно объявленный SoT-файл на каждый артефакт; версия
|
||
**наблюдаема на самом артефакте** (health-эндпоинт, UI «Что нового», экран About
|
||
устройства). MAJOR.MINOR синхронны только для платформенной пары; прошивки/утилиты/
|
||
протокол — независимы; при >2 артефактах — **матрица совместимости в changelog
|
||
минорного релиза** *(АПЕКС)*. Канал релиза (dev/beta/rc) — pre-release suffix SemVer,
|
||
не отдельная колонка: парсер сам сравнит `0.1.0-debug.1 < 0.1.0-rc.1 < 0.1.0`;
|
||
префикс артефакта — только в UI/тегах, не в коде *(АПЕКС)*. Changelog — только
|
||
заметное пользователю, не коммит-лог; запись в changelog обязательна — без неё бамп
|
||
запрещён. Бамп ТОЛЬКО по явной команде; ритуал «готовимся к бампу»: git log с
|
||
прошлого бампа → атомарные сценарии ручной проверки, **сгенерированные по диффу, не
|
||
по памяти** (файл чеклиста в .gitignore) → прогон по одному через AskUserQuestion
|
||
(на ✗ — стоп) → полный тест-прогон → два зелёных дают право бампать. Сокращённый
|
||
гейт для PATCH рассматривался и письменно отвергнут — «рождаются вторые патчи в тот
|
||
же день» *(BAZA ADR-068)*. Тег ставится локально; **push тега — отдельное «да»,
|
||
каждый раз** *(АПЕКС)*.
|
||
|
||
## IV. Организация работы с Claude
|
||
|
||
1. **Модель ветвления объявляется письменно в ADR** — trunk-based или dev/master, по
|
||
числу людей и наличию ревью, а не по привычке *(АПЕКС живёт trunk-based, ADR-024;
|
||
BAZA — dev/master)*. Для dev/master: master = стабильный прод, merge только бампом;
|
||
режим стабилизации — dev держится потоком фиксов, фичи во временных `feature/*`,
|
||
постоянную третью ветку не заводить *(BAZA ADR-068)*.
|
||
2. **Делегирование:** нетривиальное — субагентам с явным именованием; main loop
|
||
оставляет себе git, гейты, ревью диффов, интеграцию. **Нижняя граница:** правку 1–3
|
||
строк не делегировать — оверхед дороже. **Нет подходящего агента — остановиться и
|
||
спросить, не выдумывать.** Определения агентов модель-нейтральны: модель и effort —
|
||
во frontmatter, в прозе имён моделей нет (протухают за недели) *(АПЕКС ea13116;
|
||
контрпример — «Opus 4.8» в CLAUDE.md EventPlan)*. Дорогой агент-архитектор
|
||
вызывается по письменному списку **обязательных** триггеров — и только по ним.
|
||
Субагенты не порождают субагентов: лиды возвращают план делегирования текстом,
|
||
исполнителей запускает main loop. Три проверенных архетипа — субагент как **бюджет
|
||
контекста**: reviewer-хранитель пронумерованных инвариантов («не переписывай сам»;
|
||
«чем грозит»), test-runner на дешёвой модели («только вердикт и текст упавших»),
|
||
doc-scout («файл:строка + цитата, не пересказывай») *(REC dimmer)*. Шкала
|
||
оркестрации по размеру: роли в одном файле → именованные субагенты → генерируемая
|
||
студия. Независимых — параллельно, одним сообщением. Субагентам передавать правило
|
||
контекст-экономии и запрет на commit/push.
|
||
3. **Опасные команды** — список письменно в CLAUDE.md с первого дня: rm -rf,
|
||
reset --hard, down -v, DROP, force-push, `git clean -f`, `git checkout --` с потерей
|
||
правок, `docker system prune`, `volume rm`, `dd`, `mkfs`, `pkill -9`, erase-flash,
|
||
любые действия на прод. Выполнение — только после письменного подтверждения, одно
|
||
«да» = один вызов. **Текст без хука — декларация:** список дублируется блокирующим
|
||
хуком, покрытие хука — по всем шеллам (II.2). Письменно же — известные
|
||
escape-вектора ask-gate: `cd x && git push`, `sh -c`, `eval`, pipe через `xargs` —
|
||
договорённость не использовать, распространена на субагентов *(BAZA)*. Опасны они
|
||
не только потерей данных, но и потерей **улик**: сначала понять причину, потом
|
||
чистить *(АПЕКС runbook)*.
|
||
4. **Не переспрашивай и не угадывай:** решение с очевидным дефолтом — прими, озвучь,
|
||
двигайся. Развилку, меняющую архитектуру/данные/UX — AskUserQuestion **до** кода.
|
||
Несколько вопросов — одним заходом.
|
||
5. **TodoWrite** на всё многошаговое; планы — в `docs/plans/`, не в корне. Двухфазность:
|
||
фикс отдельным коммитом, roadmap/доки — отдельным (причину см. III.5).
|
||
6. **Бюджет CLAUDE.md:** там только то, что нужно КАЖДУЮ сессию — постоянная статья
|
||
расхода контекста. Ритуалы — **скиллы** с триггер-фразами; правила — файлы с `globs`
|
||
по зонам кода (грузятся по файлу) *(оба боевых проекта пришли независимо: АПЕКС
|
||
279→149 строк, BAZA rules→skills)*. `.claudeignore` на шумные каталоги — с обратным
|
||
правилом: ничто, на что ссылаются правила или память, не скрыто (указатели в
|
||
невидимое) *(АПЕКС)*. Гигиена памяти: индекс обязателен (нет в MEMORY.md = невидимо
|
||
при recall), лимит размера (большой файл = документ, в docs/), память ≠ хранилище
|
||
документов. **У метаданных проекта — свой прогоняемый чек** (битые ссылки CLAUDE.md,
|
||
захардкоженные счётчики, таблица крупных файлов, покрытие хуков): их дрейф не
|
||
роняет ни один тест *(АПЕКС check-integrity.ps1)*. Одна точка входа для агента,
|
||
инструменто-нейтральная: смена инструмента = миграция содержимого, чужие каталоги
|
||
удаляются тем же коммитом (`gotcha-two-agent-configs`).
|
||
7. **Систематически нарушаемое правило — дефект системы, а не людей.** Гайд не
|
||
покрывает реальную потребность — расширь систему и задокументируй, а не копи
|
||
исключения *(BAZA: один класс кнопки закрыл годы техдолга)*. Осознанное исключение
|
||
пишется **в самом правиле** — с границей применимости *(BAZA viewsets-only)*.
|
||
Заморозка направления фиксируется в правиле явно («i18n ЗАМОРОЖЕН: … не трогать»),
|
||
иначе очередная сессия «доводит до ума» замороженный слой *(BAZA)*. Правило,
|
||
невыполнимое по построению («не портировать вручную» между двумя деревьями одного
|
||
кода) — сигнал менять структуру, не дисциплину: одномоментный перенос, старое
|
||
read-only *(АПЕКС ADR-020)*.
|
||
8. **Гигиена сессии:** следить за автокомпактом — ссылки на docs/ позволяют перечитать
|
||
первоисточник после сжатия контекста; сессия ушла не туда — дешевле поправить
|
||
CLAUDE.md и начать новую, чем выправлять *(REC dimmer)*. Конфиги быстро меняющихся
|
||
сторонних сервисов — по актуальной официальной документации, не по памяти модели;
|
||
версии сверяются ДО генерации конфигов (`gotcha-llm-stale-configs`).
|
||
9. **Протокол отладки** (именованный ритуал с триггер-фразой): снаружи внутрь
|
||
(UI → сеть → бэкенд → БД); **не чинить первую найденную причину** — проверить, нет
|
||
ли слоёв под ней; подтвердить фикс фактически до объявления победы; пойманное —
|
||
в memory/грабли *(BAZA tyranid-hunt)*.
|
||
|
||
## V. Прод, эксплуатация, наблюдаемость
|
||
|
||
1. **Боевые серверы — только команды, никакого «я сделаю сам».** На прод/VPS агент не
|
||
выполняет НИЧЕГО самостоятельно. Он выдаёт готовые команды блоком, выполняет человек.
|
||
Одно письменное подтверждение = одно действие; «да» из прошлого раза не переносится.
|
||
*(АПЕКС)*
|
||
2. **Деплой-чеклист письменно и всегда целиком:** build ВСЕХ артефактов («изменения не
|
||
появились» = собрал не всё — артефактов деплоя больше одного, перечисли ВСЕ и способ
|
||
сборки каждого, `gotcha-partial-build`) → перезапуск ВСЕХ производных контейнеров →
|
||
прокси → статусы → логи воркеров → smoke-тест. Частичные варианты — **флаги одного
|
||
скрипта** (`--backend`/`--frontend`), не отдельные инструкции *(АПЕКС)*.
|
||
3. **Деплой — один канонический скрипт с проверками внутри** *(BAZA deploy.sh)*: отказ
|
||
при грязном дереве/чужой ветке; список пересоздаваемых сервисов **вычисляется из
|
||
compose**, не хардкодится (новый воркер попадает в деплой сам); бэкап — при
|
||
непустом плане миграций; ожидание healthy по inspect с таймаутом, не «на глаз»;
|
||
smoke = версия из health-эндпоинта, не 200 OK; при провале health-gate скрипт
|
||
**печатает точную команду отката**. **Точка отката для проекта с миграциями — пара
|
||
(коммит, дамп)**, образа `:prev` недостаточно: откат кода через миграционный рубеж
|
||
без отката БД падает на отсутствующих колонках. Rollback — отдельный парный скрипт:
|
||
подтверждение словом, страховочный дамп текущего состояния ДО восстановления,
|
||
`--code-ref`, финальная сверка схемы с кодом *(BAZA rollback.sh)*. Фронт-статика:
|
||
новая сборка рядом (`dist_new`) → атомарный swap, старая = точка отката *(АПЕКС)*.
|
||
4. **Секрет-гигиена, три слоя раздельно: код / состояние / секреты.** `.env` в
|
||
`.gitignore`, `.env.example` с плейсхолдерами и маркерами `[SECRET] → менеджер`;
|
||
шифрованные секреты (SOPS+age) коммитятся намеренно, ключ вне репо; учётки внешних
|
||
SaaS — в парольном менеджере, не в `.env` *(HS+auth)*. Клиентские секреты —
|
||
платформенный механизм (DPAPI/keychain) + письменно «от чего это НЕ защищает»
|
||
*(tray-monitor)*. **Секрет в URL = секрет в access-логе и Referer** — маскирование
|
||
в логах приложения + `access_log off` на эндпоинте *(АПЕКС: JWT в query WS)*.
|
||
Предупреждать о риске ДО команды, которая выведет секрет в терминал/историю.
|
||
Утечка = ротация в ту же сессию *(BAZA: PAT)*.
|
||
5. **Канонические пути и имена — письменно в момент создания:** путь на сервере, имена
|
||
контейнеров, бакетов *(АПЕКС: /opt/signe/ vs «угаданный» /opt/signe-server/)*.
|
||
Плюс **реестр занятого**: порты/адреса/имена проверяются на конфликт с соседями,
|
||
включая вендорские дефолты *(REC dimmer: дефолтный IP ноды = дефолт диммера;
|
||
Grafana 3001 из-за forgejo)*. Порядок старта зависимостей (VPN раньше docker) — либо
|
||
в юните (`After=`), либо задокументирован как штатный симптом *(мониторинг)*.
|
||
6. **Наблюдаемость** (при проде — обязательна): **внешний наблюдатель** — всё, что
|
||
запущено на самом сервере, не видит отказ самого сервера *(АПЕКС)*. Health-эндпоинт
|
||
как liveness («200 degraded») → мониторинг по ключевому слову `"status":"ok"`, не по
|
||
коду ответа; публичный health не утекает текст исключений. **Dead man's switch на
|
||
всю периодику** (бэкап, отчёты, синк): «должно было запуститься и не запустилось» —
|
||
отдельный класс отказов, cron сам о себе не сообщит; сигналы «упал» / «успех
|
||
устарел» / «успехов не было ни разу» / «метрики вообще нет» слепы по отдельности —
|
||
нужны все *(мониторинг: BackupNeverSucceeded не видит BackupTooOld)*; ping только на
|
||
успех, grace с запасом, таймзона сверяется, не предполагается. Структурированные
|
||
логи + сквозной request_id — с первого дня, задним числом невозможно *(АПЕКС)*.
|
||
Пороги живут на сервере; клиент отображает решения, не принимает их; цвета клиента =
|
||
правила стека («жёлтая цифра значит то же, что жёлтая иконка») *(tray-monitor)*.
|
||
Healthcheck проверяет живой процесс, а не прокси-артефакт (файл/лог/таймстамп);
|
||
устранив причину — пройди по проверкам, которые на неё опирались
|
||
(`gotcha-proxy-healthcheck`). Предохранители в скриптах: опасная конфигурация не
|
||
стартует, обход — только явным флагом с говорящим именем
|
||
(`ALLOW_PUBLIC_UNAUTHENTICATED=1`) и перечислением того, что утечёт *(мониторинг)*.
|
||
7. **Бэкап не существует, пока не проверено восстановление.** Дамп — вне тома с
|
||
данными; проверка целостности (`--verify`); retention письменно (daily/weekly/
|
||
monthly); **один SoT расписания** (`gotcha-double-cron`); процедура restore
|
||
написана; **поимённый список критических артефактов с ценой пропуска каждого**
|
||
*(HS+auth: noise.private_key — иначе перерегистрация всех узлов)*. Проверка на
|
||
**bootstrap paradox**: пройди по зависимостям процедуры восстановления — нет ли
|
||
тех, что сами восстанавливаются этой процедурой *(HS+auth: бэкап на NAS, доступном
|
||
через ту же mesh-сеть; REC dimmer: «сбить IP с панели → починить с панели» — пункт
|
||
приёмки)*. Внешнее хранилище/LFS считается рабочим только после скачивания объекта
|
||
с чистой машины *(Ad-Tycoon: LFS отдавал 404, 31 файл утерян безвозвратно)*.
|
||
8. **Приёмка и необратимость.** Приёмочный чек-лист — парный артефакт спеки, и он
|
||
**диктует наблюдаемость**: сначала «как проверяем», из этого — какую диагностику
|
||
обязан отдавать продукт (счётчики, uptime, версия на самом устройстве) *(REC
|
||
dimmer)*. **Ворота этапа:** неизвестность закрывается ДО необратимых/дорогих работ;
|
||
условные этапы не проектируются заранее; фазовый гейт — измеримый пользовательский
|
||
результат с правом остановить продукт («загрузил → план ≤3 мин против 2 ч; нет
|
||
„вау“ → пересматриваем») *(EventPlan roadmap)*; ценность раньше «умной» части —
|
||
ML/распознавание после подтверждения тупого варианта. Отказные сценарии
|
||
обновления — часть приёмки: битый файл → отказ по CRC, питание в момент записи →
|
||
грузится старое; «что деградирует во время обновления» записано *(REC dimmer)*.
|
||
В пайплайне с необратимыми шагами guard выполняется **до первого необратимого**
|
||
*(АПЕКС: compat-check до записи identity)*. Запас по предельным параметрам вместо
|
||
защиты, когда отказ необратим («полевик умрёт раньше любой защиты»). Критерий
|
||
приёмки чисто-архитектурного рефакторинга — **байт-идентичный наблюдаемый выход**
|
||
до/после, иначе это не рефакторинг *(АПЕКС ADR-021)*. Debug-функциональность
|
||
физически отсутствует в релизном артефакте (`#ifdef`/сборка), а не «выключена
|
||
настройкой»: debug-роуты, mock-режимы, фейковый логин *(АПЕКС)*.
|
||
9. **Профиль «публичный релиз»** — отдельный от своего прода: как только артефакт
|
||
уходит в чужой магазин/Marketplace/публичный домен — LICENSE + поле в манифесте,
|
||
README-витрина со скриншотами, CHANGELOG, иконка, локализация пользовательских
|
||
доков (внутренние — на одном языке, и это записано), чеклист модерации ДО релиза
|
||
*(claude-office-dashboard)*.
|
||
10. **Межпроектные контракты:** значения, которые один проект ВЫДАЁТ, а другой
|
||
ПОТРЕБЛЯЕТ — таблицей с явным эмитентом и потребителем, «совпадают байт в байт»,
|
||
включая trailing slash и порт *(HS+auth: OIDC)*. Перечислить ВСЕ пары «кто → кому
|
||
ходит»: браузер ≠ контейнер, оба должны достучаться — поломки живут в паре, о
|
||
которой не подумали. **Общий эталон проверяется первым** при «не работает»: земля
|
||
для сигналов, NTP для токенов (clock skew валит exp/iat), кодировка для текста,
|
||
таймзона для дат — и записывается в предусловия *(Pulse generator + HS+auth,
|
||
независимо)*. `[железо]` Однократные ручные предусловия среды («выпаять флеш»,
|
||
modprobe модуля, драйвер) — письменный чек-лист, не проза. Комплект артефактов
|
||
железного проекта: pinout · схема подключения · BOM · порядок сборки · приёмка
|
||
(три проекта пришли независимо); **SoT по «ногам» — документ**, в коде ровно один
|
||
заголовок (pins.h), его отражающий; при противоречии прав документ *(REC dimmer)*.
|
||
|
||
## VI. Литания против граблей
|
||
|
||
> Каждая — реальный инцидент; чти их, дабы не повторить. Теги — к какому стеку/профилю
|
||
> применима; при триаже неприменимые группы отсекай целиком. Ссылайся слагом, не номером.
|
||
|
||
### Контейнеры и деплой `[Docker]`
|
||
|
||
1. `gotcha-migration-drift` **Дрейф миграций** `[+Django]`. makemigrations в контейнере
|
||
без bind-mount → файл живёт в слое образа, БД помнит, git нет; rebuild — файл исчез.
|
||
Потеряно 18 файлов. → makemigrations ТОЛЬКО через dev-override с bind-mount; после —
|
||
`git status`; CI-гейт «чистый migrate с нуля». Рецепт восстановления — записан (I.7).
|
||
*(BAZA)*
|
||
2. `gotcha-stale-workers` **Воркеры на старом образе** `[+очередь]`. `up -d app` не
|
||
трогает worker/beat/asgi — очередь выполняет старый код, симптомов не даёт. →
|
||
деплой-чеклист V.2 целиком; список сервисов вычисляется из compose. *(BAZA)*
|
||
3. `gotcha-proxy-cache` **Прокси кэширует upstream.** После пересборки — 502 или старый
|
||
фронт. → лечить причину конфигом: `resolver 127.0.0.11 valid=10s` + переменные
|
||
upstream в каждом location — после этого рестарт nginx не нужен; ритуал рестарта —
|
||
подстраховка, знай, что он маскирует незакрытую причину. *(BAZA, вылечено 3ae5995)*
|
||
4. `gotcha-partial-build` **Артефактов деплоя больше одного.** Пересборка бэкенда не
|
||
деплоит фронт (в контейнере он или нет — неважно); «изменения не появились» — почти
|
||
всегда это. → перечисли ВСЕ артефакты и способ сборки каждого. *(BAZA, АПЕКС)*
|
||
5. `gotcha-pidfile` **Pidfile в контейнере.** `docker restart` сохраняет ФС →
|
||
осиротевший pidfile → вечный рестарт, периодика молча стоит. → pidfile в
|
||
one-process-контейнере не нужен никогда. Парная: healthcheck, проверявший pidfile,
|
||
стал вечно-ложным после лечения — устранив причину, пройди по проверкам, которые на
|
||
неё опирались (`gotcha-proxy-healthcheck`). *(BAZA)*
|
||
6. `gotcha-interval-schedule` **Интервальные расписания сбрасываются рестартом**
|
||
планировщика → суточная задача «каждые 24ч» не срабатывает никогда. → crontab-выражения
|
||
для суточных/еженедельных. *(BAZA)*
|
||
7. `gotcha-silent-unregistered` **Расписание ≠ реестр** `[+очередь]`. Задача, не
|
||
попавшая в реестр воркера (autodiscover не видит подпакет), отбрасывается МОЛЧА —
|
||
beat шлёт, воркер отвечает «unregistered», симптом — тишина. Юнит-тесты, импортирующие
|
||
задачу напрямую, бага не видят. → тест «расписание ⊆ реестр» + проверка в
|
||
деплой-скрипте; у планировщика нет громкого режима отказа — создай его. *(BAZA, прод)*
|
||
8. `gotcha-dev-prod-settings` **Dev-стек на prod-настройках.** Забытый override →
|
||
prod-whitelist хостов → 400 на локальном домене. → явные именованные override-файлы
|
||
и одна задокументированная команда запуска dev-стека. *(BAZA)*
|
||
9. `gotcha-exec-bit` **Права/окружение контейнера ≠ хоста** `[+Windows]`. Скрипт без +x,
|
||
том с чужим uid → Permission denied. → скрипты звать через `sh <путь>`; явные права
|
||
томов; проверка после первого up. *(BAZA)*
|
||
10. `gotcha-rootowned-bindmount` **Bind-mount на несуществующий путь** — docker создаст
|
||
каталог от root, задача не от root писать не сможет. → создавать каталоги заранее
|
||
в скрипте. *(мониторинг)*
|
||
11. `gotcha-docker-bypasses-ufw` **Границу доступа определяет bind-адрес, не фаервол.**
|
||
Docker пишет правила в nat в ОБХОД ufw — `ufw deny 9090` порт не закроет. → bind
|
||
на tailnet/localhost; публичный bind — осознанное решение. *(мониторинг)*
|
||
12. `gotcha-container-oom` **Контейнерный лимит памяти без внутреннего лимита процесса**
|
||
→ OOM-kill вместо деградации. → лимит процесса ниже лимита контейнера. *(АПЕКС)*
|
||
13. `gotcha-env-special-chars` **Спецсимволы `#$!%&` в пароле** ломают парсер
|
||
.env/compose → контейнер в вечном Restarting. *(АПЕКС)*
|
||
14. `gotcha-compose-env-drift` **Дефолты в compose разошлись с .env.example** → стек
|
||
поднимается с другими именами БД/юзера. → один источник дефолтов. *(АПЕКС)*
|
||
|
||
### Данные и логика
|
||
|
||
15. `gotcha-journal-bypass` **Мутация в обход журнала.** Ручное списание меняло остаток
|
||
напрямую — журнал слеп, аудит дыряв. → ЕДИНАЯ точка применения эффекта, все пути
|
||
через неё. *(BAZA)*
|
||
16. `gotcha-pair-asymmetry` **Асимметрия парных операций.** Создание покрывало 2 метода
|
||
оплаты, отмена — 1: проводка-сирота, отчёт врал. → create+cancel парой, тест на цикл
|
||
create→cancel→след чист. *(BAZA)*
|
||
17. `gotcha-increment-race` **Гонки на инкрементах.** Два параллельных движения читают
|
||
один остаток → lost update. → блокировка (select_for_update) внутри транзакции на
|
||
любых счётчиках с первого дня + конкурентный тест. Где лочить нельзя (ISR, UI) —
|
||
один назначенный писатель (I.17). *(BAZA)*
|
||
18. `gotcha-placeholder-data` **Плейсхолдер, притворяющийся данными.** Черновые значения
|
||
без пометки уезжают как «проверенные». → помечать (`?`, TODO владельцу); гейт перед
|
||
прод — плейсхолдеров не осталось. *(EventPlan)*
|
||
19. `gotcha-number-null` **Number(null) === 0** `[React/формы]`. Трансформ на маунте:
|
||
null FK → 0 → «выбрана» несуществующая запись. → null-безопасные setValueAs. *(BAZA)*
|
||
20. `gotcha-green-modules-dead-system` **Модули зелёные — система мертва.** 74 честных
|
||
юнит-теста, архитектура по гайдлайнам — а ключевая функция ядра не вызывается
|
||
нигде, автосейва не существует (ноль вызовов), софтлок за 12 минут. → orphan-check
|
||
«кто вызывает» по каждой публичной функции ядра; интеграционный тест полного цикла;
|
||
для накопительных доменов — headless-прогон N шагов с проверкой, что метрики
|
||
двигаются. *(Ad-Tycoon, независимое ревью)*
|
||
21. `gotcha-orphan-config` **Конфиг-поле без потребителя.** Поля загружаются,
|
||
валидируются — и никем не читаются; рядом код с хардкодом, расходящимся с конфигом
|
||
в 100 раз. → вынес в конфиг = есть потребитель и тест, что читается именно оно;
|
||
валидация при старте; единицы сходятся. *(Ad-Tycoon)*
|
||
22. `gotcha-gitignored-dependency` **Зависимость от артефакта вне git.** Детект платформы
|
||
завязан на плагин из каталога в .gitignore — работает только на машине разработки,
|
||
в чистом клоне и CI ломается молча. → гейт «чистый клон собирается и стартует».
|
||
*(Ad-Tycoon)*
|
||
|
||
### Версии и контракты
|
||
|
||
23. `gotcha-version-sot` **Несколько «источников истины» версии.** pyproject vs
|
||
настройки vs package.json расползаются. → SoT-файлы письменно, остальное не
|
||
считается. *(BAZA)*
|
||
24. `gotcha-version-symmetry` **Автовыравнивание версий «для симметрии».** PATCH
|
||
независим — ровнять = фейковые релизы. → бамп только изменившегося. *(BAZA)*
|
||
25. `gotcha-lexicographic-semver` **Лексикографическое сравнение версий.**
|
||
`"0.10.0" < "0.9.0"` строками — стреляет в OTA, когда MINOR доходит до 10. →
|
||
сравнение только semver-парсером. И вторая линия: **guard от даунгрейда на стороне
|
||
клиента** — `strcmp(...)!=0` означало «ставлю всё, что отличается»; серверная
|
||
монотонность фида — единая точка отказа, способная забрикать флот одной ошибочной
|
||
публикацией; намеренный откат — «старый код под более высокой версией».
|
||
*(АПЕКС, ADR-023)*
|
||
26. `gotcha-feature-test-debt` **Тестовый долг фичи.** Фича изменила ответ эндпоинта,
|
||
тесты не тронули — красный набор всплыл через неделю у чужой сессии. → тесты
|
||
контракта в том же коммите, полный прогон перед push. *(BAZA)*
|
||
27. `gotcha-tsc-no-b` **`tsc` без `-b` не проверяет project references** `[TS]`.
|
||
Локально зелёный, сборка на сервере падает. → `tsc -b --noEmit` при
|
||
composite/references. *(АПЕКС)*
|
||
|
||
### Windows и кодировки `[Windows]`
|
||
|
||
28. `gotcha-gitattributes` **Переносы строк без `.gitattributes`.** autocrlf →
|
||
LF↔CRLF-дрейф, в Linux-контейнере ломаются скрипты с CRLF. → `* text=auto eol=lf`
|
||
с ПЕРВОГО коммита. *(EventPlan: 80+ предупреждений)*
|
||
29. `gotcha-non-ascii-toolchain` **Не-ASCII там, где системная кодировка.** Три канала:
|
||
(а) файлы, которые парсит тулчейн — только ASCII *(АПЕКС: PlatformIO упал на
|
||
кириллице в partitions_apex.csv — cp1251)*; (б) **stdout вспомогательных скриптов**
|
||
на Windows — cp1251, `UnicodeEncodeError` на любом спецсимволе →
|
||
`PYTHONIOENCODING=utf-8` или ASCII-вывод *(воспроизведено дважды при аудите)*;
|
||
(в) **stdin хуков** читать как UTF-8 байты явно — иначе кириллица-мохито
|
||
*(office-dashboard 2c047ee)*.
|
||
30. `gotcha-windows-bindmount` **Windows bind-mount врёт.** Задержка синхронизации →
|
||
контейнер видит старый файл. → docker cp или --no-cache при сборке фронта. *(BAZA)*
|
||
31. `gotcha-case-insensitive-headers` **`HTTPClient.h` vs `HttpClient.h`** — две
|
||
библиотеки, различающиеся регистром имени, конфликтуют на регистронезависимой ФС.
|
||
*(АПЕКС)*
|
||
|
||
### Инфраструктура `[инфра/прод]`
|
||
|
||
32. `gotcha-shared-proxy` **Общий реверс-прокси: глобальные объекты и Host.**
|
||
Одноимённые `map`/`upstream` → «duplicate map»; proxy_pass по IP без `Host $host` →
|
||
400 от whitelist. → имена глобальных объектов уникальны per-vhost; Host всегда.
|
||
*(BAZA)*
|
||
33. `gotcha-fail2ban-self` **Авто-защиты банят свою автоматизацию.** fail2ban целевой
|
||
системы банит настройщика после 2 SSH-коннектов (ssh-copy-id = 2 = бан). → свой IP
|
||
в доверенные ДО работ. *(BAZA: NAS)*
|
||
34. `gotcha-pipefail` **Пайп без `set -o pipefail`** → код возврата от последней команды:
|
||
упавший pg_dump + живой gzip = пустой архив и «успех». Зелёный статус над битым
|
||
дампом хуже отсутствия бэкапа. *(мониторинг)*
|
||
35. `gotcha-tls-bare-ip` **Запрос по голому IP при сертификате на домен** провалит
|
||
TLS-проверку — в инструкциях и конфигах всегда домен. *(АПЕКС)*
|
||
36. `gotcha-crypto-defaults` **Дефолты криптоутилит небезопасны.** htpasswd по умолчанию
|
||
bcrypt cost 5 (32 раунда) — задавать стоимость явно (`-C 12`). *(мониторинг)*
|
||
37. `gotcha-https-redirect-proxy` **HTTPS-редирект за SSL-прокси хостинга** =
|
||
бесконечный редирект: `RewriteCond %{HTTPS} off` не видит прокси. → редиректы —
|
||
средствами панели/прокси; за прокси о схеме судят по `X-Forwarded-Proto`.
|
||
*(лендинг; родня `gotcha-shared-proxy` — за прокси реальность не та, что видит
|
||
приложение)*
|
||
38. `gotcha-robots-secret` **Секретный путь в robots.txt.** Строка `Disallow` сама
|
||
выдаёт путь любому, кто откроет robots. → секретные пути не упоминать нигде
|
||
публично. *(лендинг)*
|
||
39. `gotcha-double-cron` **Два механизма расписания** (`/etc/cron.d/*` и `crontab -e`) →
|
||
задача дважды за ночь. → SoT расписания — один файл, создаётся setup-скриптом.
|
||
*(АПЕКС)*
|
||
40. `gotcha-nginx-details` **Мелочи nginx:** `expires` + `add_header Cache-Control`
|
||
вместе = дублирующийся заголовок; на Debian пользователь `www-data`, не `nginx`.
|
||
*(АПЕКС)*
|
||
|
||
### Процесс
|
||
|
||
41. `gotcha-docs-drift` **Документация отстаёт молча.** Месяц без сведения = 35 файлов
|
||
лжи и день работы 10 субагентов. → ритуал закрытия сессии (III.4), каждый раз.
|
||
*(BAZA)*
|
||
42. `gotcha-god-files` **God-файлы съедают контекст и дисциплину.** serializers на 940
|
||
строк, страница на 1290. → делить при росте, карта крупных файлов с автопроверкой
|
||
(III.1), точечное чтение. *(BAZA)*
|
||
43. `gotcha-phantom-tails` **Фантомные хвосты плана.** «Незакрытые» пункты roadmap
|
||
давно сделаны — сессия готова повторить работу. → статусы по факту кода, сверка
|
||
перед реализацией (III.5). *(BAZA: 2 из 4)*
|
||
44. `gotcha-silent-later` **Молчаливое «потом».** Каждое «потом допишем» без записи
|
||
исчезает. → всё отложенное — письменно (план, ADR-компромисс, реестр долгов,
|
||
memory) в момент откладывания. *(BAZA)*
|
||
45. `gotcha-ci-wrong-branch` **CI слушает не ту ветку.** Workflows на master, работа
|
||
месяц шла в dev — гейты тихо перестали существовать. → сменил ветвенную модель →
|
||
в тот же коммит триггеры CI/хуков/автоматики. *(BAZA d9804c2)*
|
||
46. `gotcha-hook-shell-blind` **Хук слеп к реальному шеллу.** Matcher `Bash`, работа
|
||
идёт в PowerShell — защита существует и не работает. → покрытие хука по всем
|
||
шеллам, проверяется скриптом целостности. *(АПЕКС)*
|
||
47. `gotcha-renumbered-parent` **Перенумерация родительского документа** тихо ломает все
|
||
производные ссылки. → ссылаться слагом; при реструктуризации — прогнать ссылки в
|
||
производных. *(EventPlan: ссылки на литанию били в пустоту через 2 часа)*
|
||
48. `gotcha-two-agent-configs` **Две конфигурации агента.** Проект вёлся двумя
|
||
инструментами, конфигурация дважды мигрировала и рассинхронизировалась. → одна
|
||
инструменто-нейтральная точка входа; чужие каталоги удаляются тем же коммитом.
|
||
*(Ad-Tycoon ADR-010)*
|
||
49. `gotcha-automated-prompt` **Системные инъекции неотличимы от пользователя.**
|
||
Автоуведомление фоновой задачи пришло как «промпт пользователя» и снимало
|
||
экстренную остановку. → механика, реагирующая на «пользователь написал», обязана
|
||
фильтровать автоматику. *(office-dashboard v0.13.2)*
|
||
50. `gotcha-llm-stale-configs` **Конфиги по памяти модели.** Синтаксис быстро меняющихся
|
||
сервисов, выдуманный по памяти, не совпадает с текущей версией *(HS+auth: Authentik
|
||
2026.x убрал Redis)*. → сверка с актуальной официальной докой; версии пинуются и
|
||
записываются ДО генерации.
|
||
51. `gotcha-modal-drag-close` **Модалка закрывается при drag-выделении текста**
|
||
`[React]` (mouseup ловится на бэкдропе). → закрытие по клику, начатому и
|
||
завершённому на бэкдропе. *(АПЕКС)*
|
||
52. `gotcha-404-swallows-detail` **Глобальный 404-хендлер глотает содержательные
|
||
`detail` роутеров.** → хендлер пропускает существующий detail. *(АПЕКС)*
|
||
|
||
---
|
||
|
||
**Финал:** литания прочитана, профиль определён, триаж проведён, каркас развёрнут и
|
||
отревьюен — можно начинать. Новые грабли проекта — в живой раздел
|
||
`docs/architecture.md#Грабли проекта` (копия литании read-only), обобщаемое —
|
||
периодически в мастер-литанию: она живёт, пока её кормят инцидентами.
|