agent-quality-kit 0.2.2

package/kit/docs/ai/app-owner-strategy.md

@@ -0,0 +1,921 @@
+
+<!-- источник: audit_project/docs/ai/Стратегия_по_разработки_приложений.md -->
+Существует принципиально 2 разных слоя разработки:
+- Слой A — харнес разработки (.claude/: пайплайн агентов, хуки, скиллы, память). Тут мы зрелые, местами впереди сигнала.
+- Слой B — сам продукт
+
+---
+Список действий
+
+1. ФОРМУЛИРОВКА ЗАДАЧИ (БИЗНЕС ТЗ)
+2. ОГРАНИЧЕНИЯ (constraints): данности среды
+3. САЙЗИНГ: цифры
+4. ТЕХ-ДИЗАЙН: как именно   ← стек, топология, модель данных, API
+---
+
+Общие принципы
+
+1. Декомпозиция — разбить туманную цель на части, которые правильно складываются.
+2. Предвидение отказов — знать, что и как может сломаться
+3. Замыкание обратной связи — сделать систему прозрачной (наблюдаемой)
+
+---
+# ФОРМУЛИРОВКА ЗАДАЧИ (БИЗНЕС ТЗ)
+
+Описание самого проекта и зачем в целом он создается. Здесь крупно описывается, смысл, цель и стремления которые хотят быть осуществлены заказчиком. Необходимо для формирования фундамента и выбора правильно архитектуры и стека проекта. Задача должна быть описана простыми словами без технической составляющей, ровно таким способом как бы это делал человек не зная вообще программирование. Чем подробней и детальней будет описано виденье проекта тем лучше. Как итог получаем 1 файлик.
+
+Данный файл эволюционирует вместе с проектом и в процессе разработки может дополняться и расширяться.
+
+1. Необходимо описать проблему (боль) зачем в целом нужен программный продукт
+2. Цель и критерий успеха (измеримые)
+3. Пользователи (роли, язык)
+4. и тд можно дополнять пункты
+
+
+
+# РЕСУРСОЕМКОСТЬ + ОГРАНИЧЕНИЯ (constraints)
+
+1. Описание того сколько человек будет заниматься проектом.
+2. Какие компьютерный мощности у нас есть
+3. Где распологается сервер
+4. Есть ли домен
+5. Бюджет
+6. Сроки
+7. и тд то есть вопросы общего характера
+
+
+# Сайзинг
+
+Cуществует устоявшийся список — нефункциональные требования (NFR), стандарт ISO/IEC 25010 и чек-лист Volere. Там не 8, а ~10-14 категорий. (Forasoft — 14 категорий NFR (https://www.forasoft.com/blog/article/non-functional-requirements-checklist-2026), Altexsoft (https://www.altexsoft.com/blog/non-functional-requirements/))
+
+Прежде чем строить, надо понять «какая нагрузка нас ждёт» — чтобы сервер не упал, но и чтобы не построить дорогущий кластер там, где хватит одного компа.
+
+<font color="#ffff00">DAU </font>— сколько людей пользуется за день?
+DAU = Daily Active Users = сколько разных аудиторов реально заходят и работают за сутки.
+Пример: 100 аудиторов в день.
+  👉 Но не все они кликают в одну и ту же секунду. Поэтому следующий вопрос:
+
+<font color="#ffff00">Пиковая одновременность</font> — сколько работают В ОДИН МОМЕНТ (в час пик)?
+  Из 100 за день — сколько сидят и кликают одновременно в самый загруженный момент (скажем, 11 утра)?
+  Пример: пик — 30 одновременно.
+  👉 Грузят систему те, кто работает СЕЙЧАС, а не «за весь день». Но и сидящие не долбят без остановки. Поэтому:
+
+
+<font color="#ffff00">Частота запросов (RPS)</font> — сколько кликов/запросов в секунду прилетает на сервер?
+  Каждый сидящий открывает отчёт/фильтрует раз в сколько-то секунд. Сложили всех → столько запросов в секунду валится на сервер. RPS = requests per second.
+  Это и есть «сколько работы в секунду».
+  👉 Но запросы бывают разные — одни читают, другие пишут. Поэтому:
+
+<font color="#ffff00">Read/Write</font> — доля чтения и записи?
+  «Чтение» = просто посмотреть/построить отчёт (ничего не меняем). «Запись» = изменить/добавить данные (у нас — загрузка снимка из 1С).
+  Пример: у нас почти всё — чтение. Запись редкая (по клику админа).
+  👉 Это ВАЖНО: чтение масштабировать легко (копии, кэш), запись — тяжело.
+
+<font color="#ffff00">Объём данных + рост</font> — сколько данных и как быстро растёт?
+  Пример: на клиента — миллионы строк, клиентов — тысячи. Много.
+  👉 Миллион строк и миллиард — это разные машины и подходы (индексы, архивация старых клиентов).
+
+
+<font color="#ffff00">Латентность (скорость ответа)</font> — как быстро отвечаем?
+  Латентность = задержка, сколько ждёшь ответа. «p95 ≤ 1 сек» читается так: «95% запросов быстрее 1 секунды» (почти всем быстро, кроме худших 5%).
+  Пример: хотим отчёт за ≤1 сек для 95% случаев.
+  👉 Это наша цель по скорости, под неё строим.
+
+
+<font color="#ffff00">Доступность (SLO) Service Level Objectiv</font> — сколько система обязана быть «живой»? «99.9%» = разрешено лежать ~8 часов в год. SLO = твоё обещание по доступности.
+ Пример: для внутреннего аудит-инструмента 99.9% норм.
+  👉 Чем выше требование — тем больше дублирования (и денег).
+
+<font color="#ffff00">Консистентность</font> — можно ли показывать слегка устаревшие данные? Если можно секунду показать «старое» — можно кэшировать (быстро и дёшево). Если нужно строго самое свежее — сложнее.
+
+<font color="#ffff00">Рост / запас (headroom)</font> — на сколько раз вперёд закладываемся? (×2 за год? ×10?) Влияет на то, оставлять ли место для масштабирования.
+
+<font color="#ffff00">Паттерн нагрузки / сезонность</font> — откуда берётся «пик»? У аудита есть горячий сезон (сдача отчётности) → пик в разы выше среднего.
+
+
+🔒 Безопасность и доступ
+
+
+💾 Хранение + бэкап/восстановление (RPO / RTO)
+
+  - RPO (Recovery Point Objective) = сколько данных не жалко потерять, в единицах времени. «RPO = 1 час» → бэкап минимум раз в час.
+  - RTO (Recovery Time Objective) = за сколько обязаны поднять систему после сбоя. «RTO = 2 часа».
+  - Срок хранения (retention) — сколько лет держим (аудит — по закону годами).
+
+🌐 Совместимость / локализация
+
+
+  ▎ 1. Литтл ($L=λW$) — связь «сколько одновременно / как часто / как долго». Рычаг: ускоряй запрос (W↓).
+  ▎ 2. Колено ($W=\frac{S}{1-ρ}$) — у 100% задержка взрывается → держи пик на ~70%, оставляй запас.
+  ▎ 3. Всплески — планируй по пику (пик-фактор), меряй p95/p99 из реальных трейсов, гаси burst кэшем/очередью/лимитом.
+  ▎ 4. Надёжность — девятки дороги; Люссер: меньше узлов = надёжнее (P4); чинись быстро (MTTR↓ = P6).
+
+
+Утилизация и «колено»: почему нельзя грузить на 100%
+
+  Что такое утилизация
+
+  Утилизация (ρ, «ро») = насколько сервер занят, в долях от потолка. 0% — простаивает, 100% — забит под завязку.
+  Пример: потолок 2 запроса/с, приходит 1 запрос/с → утилизация 50%.
+
+  Главная (неинтуитивная) правда
+
+  Кажется логичным: «потолок 2/с — значит гоним 2/с, выжимаем по максимуму». Это грубая ошибка.
+
+  ▎ Когда утилизация подходит к 100%, задержка растёт не плавно — она ВЗРЫВАЕТСЯ.
+
+  Интуиция — шоссе (без формул)
+
+  Дорога с пропускной способностью X машин/час:
+  - загружена на 50% → едешь свободно, задержки ноль;
+  - на 80% → начинает уплотняться, лёгкие торможения;
+  - на 95% → пробка, одна лишняя машина = большая задержка для всех;
+  - на 100% → намертво стоит.
+
+  Пропускная способность та же, а ожидание у предела взрывается. Почему? Потому что машины приходят неравномерно (всплесками). Когда дорога почти полная,
+  любому случайному сгустку некуда деться → затор каскадом.
+
+  С сервером ровно так же: запросы приходят неровно (случайность/burst). У 100% занятости любой всплеск упирается в отсутствие свободной ёмкости → очередь →
+  задержка летит в небо.
+
+  Формула (простая) и почему это «колено»
+
+  $$W = \frac{S}{1 - \rho}$$
+  W — полное время (ожидание + обработка), S — время одного запроса, ρ — утилизация.
+
+   🔑 Практическое правило Никогда не планируй сервер выше ~70-80% утилизации. Оставляй запас (это и есть наш пункт 15 — headroom).
+
+
+
+Всплески и вероятность: почему среднее врёт
+
+Запросы приходят НЕровно (это и есть burst) Пользователи не кликают как метроном. Они сбиваются в кучу: все логинятся в 9:00, все жмут «обновить» после загрузки снимка, конец дня.
+
+- Научная модель этого — пуассоновский поток: случайные независимые приходы со средней частотой. Главное свойство: даже при стабильном среднем бывают
+  случайные сгустки.
+  - Интуиция — дождь: в среднем 10 капель/мин, но они не падают строго раз в 6 сек — иногда 3 разом.
+  - Пик-фактор = пиковая частота ÷ средняя. Вот почему планируем по пику, а не по среднему. У людей часто ×5…×20. А сезонность аудита (горячий сезон
+  отчётности) умножает ещё.
+
+  → Связка с прошлым: burst поднимает утилизацию → ты подлетаешь к «колену» (Шаг 2) → задержка взрывается. Поэтому пик — это не каприз, это где система
+  умирает.
+
+
+Среднее ВРЁТ → меряем перцентилями
+
+  Если смотришь только на среднюю задержку — ты прячешь больной хвост.
+
+  - Перцентили: p50 (медиана) = половина быстрее; p95 = 95% быстрее (худшие 5% медленнее); p99 = 99% быстрее (худший 1%).
+  - Почему важно: среднее может быть 100 мс, а p99 = 3 сек — значит каждый сотый запрос ужасен. Аудитор за сессию делает ~100 действий → он гарантированно
+  поймает этот 3-сек тормоз. На масштабе p99 = много реально страдающих людей.
+  - Принцип Amazon: оптимизируют хвост (p99), а не среднее — потому что именно худшие случаи формируют ощущение «тормозит».
+  - ⚠️ И хвост раздувается под нагрузкой (Шаг 2): в burst p99 улетает, даже если среднее выглядит ок.
+
+  Часть C. Перцентили НЕ угадывают — их МЕРЯЮТ (вот тут наши рекомендации)
+
+  Это прямо из knowledge:
+  - Валера: «смотри логи всех сторон» + наблюдаемость (трейсы) → ты читаешь реальный p95/p99, а не предполагаешь.
+  - Термометр (твоя же метафора + Рефат): p99 говорит «ты болен», трейс показывает ГДЕ (вон тот медленный запрос к БД). Метрика диагностирует, трейс лечит.
+  - Это и есть внешний арбитр (P2): latency не «по ощущениям», а измеренная из реальности.
+
+
+🛡️  Надёжность: «девятки», Люссер, резерв
+
+  Часть A. «Девятки» — что такое доступность в цифрах
+
+  Доступность = % времени, что система жива. Каждая девятка дороже предыдущей ~в 10 раз:
+
+  ┌─────────────┬───────────────┬──────────────────┐
+  │ Доступность │ Простой в год │    Как зовут     │
+  ├─────────────┼───────────────┼──────────────────┤
+  │ 99%         │ ~3.6 дня      │ «две девятки»    │
+  ├─────────────┼───────────────┼──────────────────┤
+  │ 99.9%       │ ~8.8 часов    │ «три девятки»    │
+  ├─────────────┼───────────────┼──────────────────┤
+  │ 99.99%      │ ~53 минуты    │ «четыре девятки» │
+  ├─────────────┼───────────────┼──────────────────┤
+  │ 99.999%     │ ~5 минут      │ «пять девяток»   │
+  └─────────────┴───────────────┴──────────────────┘
+
+  👉 Не гонись за девятками бездумно — каждая стоит кратно дороже. Выбери нужную и остановись.
+
+  Часть B. Закон Люссера — почему каждый узел РОНЯЕТ надёжность
+
+  Если узлы стоят последовательно (для работы нужны ВСЕ — цепочка), их надёжности перемножаются:
+  $$R = R_1 \times R_2 \times ... \times R_n$$
+
+  Каждый $R_i < 1$ → чем больше узлов, тем ниже итог. Считаем:
+  - 5 узлов по 99% → $0.99^5 = 0.951$ → всего 95%! (хотя каждый «надёжный»)
+  - 10 узлов по 99.9% → $0.999^{10} = 0.990$ → 99%
+
+  ▎ «Цепь не прочнее слабого звена» — а Люссер уточняет: она ещё слабее, потому что звенья перемножаются.
+
+  🔑 Это математическое доказательство нашего P4 (минимальная достаточность): каждый лишний сервис/зависимость/узел умножает твою надёжность вниз. Меньше
+  деталей = надёжнее. Ровно «чем проще велосипед, тем надёжнее едет» — теперь ты знаешь, почему это математически верно.
+
+  Часть C. Резерв (параллель) — как отбиваться
+
+  Если поставить узлы параллельно (система жива, если работает ХОТЯ БЫ один — резерв), перемножаются уже вероятности отказа:
+  $$R = 1 - (1-R_1)(1-R_2)...$$
+
+  - 2 сервера по 99% → отказ каждого 1% → оба упали $0.01 × 0.01 = 0.0001$ → доступность 99.99%!
+
+  Два дешёвых ненадёжных в параллели = очень надёжно. Вывод: последовательное перемножает надёжность вниз (плохо) → минимизируй узлы (P4); параллельное
+  перемножает отказ вниз (хорошо) → добавляй резерв только там, где реально нужны девятки (это деньги).
+
+  Часть D. MTBF / MTTR — два рычага (и связь с P6!)
+
+  $$\text{Доступность} = \frac{MTBF}{MTBF + MTTR}$$
+  - MTBF = среднее время между поломками (как редко ломается).
+  - MTTR = среднее время починки (как быстро поднимаешь).
+
+  🔑 Доступность улучшают двумя способами: ломаться реже (MTBF↑) ИЛИ чиниться быстрее (MTTR↓). И часто быстро чиниться — дешевле, чем никогда не ломаться.
+
+  → Это и есть наш P6 «дёшево ошибаться, быстро чинить» на языке математики! А из knowledge: NixOS-откат и snapshot-revert (Валера/Абдуллин) — это буквально
+  оптимизация MTTR (сломал → откатил за секунды).
+
+---
+
+# Этап 4 — Архитектура
+
+Осуществляется на основе предыдущих этапов
+
+- SOLID (5 принципов) — особенно Single Responsibility (одна работа на модуль — это мы и делали) и Dependency Inversion (завись от интерфейсов, не от конкретики).
+- Coupling & Cohesion — это почему за слоями: low coupling (части слабо связаны) + high cohesion (родственный код вместе). Главная мера хорошей структуры.
+- Стили архитектуры и выбор — слоистая (наша), Clean/Hexagonal (домен изолирован от внешнего), модульный монолит, микросервисы.
+- 🔴 Ключевое правило: «монолит-первым» (модульный монолит); микросервисы — только когда заставит масштаб (они добавляют ад распределёнки)
+
+
+<font color="#ffff00">Модель данных: фундамент всего</font>
+
+Почему это самое дорогое (повтор, но важно)
+
+  Код менять легко. Данные — тяжело. Почему: если поменял схему, надо перенести (мигрировать) все уже накопленные строки — миллионы. Код переписал за
+  минуты, а данные так просто не переложишь. Поэтому схема — это фундамент дома: стены (код) перекрасишь, а фундамент потом не подвинешь.
+
+  Что такое «модель данных» (на пальцах)
+
+  Это три решения:
+  1. Какие «вещи» храним → таблицы (Клиент, Аудитор, Проводка, Счёт…).
+  2. Какие у них поля → колонки (у Клиента: id, название, ИНН).
+  3. Как они связаны → связи (Проводка принадлежит Клиенту).
+
+  Почему модель проектируешь ТЫ, а не агент
+
+  Схема кодирует доменную правду, которую знает только эксперт:
+  - двойная запись (у проводки дебет-счёт И кредит-счёт),
+  - что такое сальдо, как считается ОСВ,
+  - грязь 1С (byte-swap UUID, физические имена _Fld620).
+
+  Агент твоего домена не знает → тут твоя аудиторская экспертиза = реальный ров. Ты определяешь модель (или жёстко ревьюишь).
+
+
+Модель данных = фундамент слоя Repo (из 4.1) и контракт, на котором стоит всё остальное. Сначала она — потом логика и UI.
+
+
+- Нормализация (1NF/2NF/3NF) — не дублируй данные (одно и то же в одном месте). + денормализация ради скорости чтения — это ровно наши матвьюхи для отчётов.
+  - Индексы — на колонки в WHERE/JOIN/ORDER BY: ускоряют чтение, замедляют запись. У нас чтение-тяжёлое → индексы важны.
+  - 🔴 Транзакции / ACID (важный пропуск для тебя!) — операция «всё-или-ничего». Sync 1С должен быть атомарным: либо загрузился весь снимок, либо откат. Иначе полузагруженные данные = битый «байт-в-байт». Это критично для аудита.
+  - SQL vs NoSQL — реляционная (SQL) для связанных данных с целостностью (твой случай — однозначно SQL). NoSQL — для иного, не твоё.
+
+
+<font color="#ffff00">Контракт API: договор между фронтом и бэком</font>
+
+- 🟢 OpenAPI / Swagger (сильный добавок!) — контракт пишут как машиночитаемую спеку. Она = и документация, и контракт, из неё генерят моки/проверки.
+  Идеально для агента (это «legible» контракт, который агент читает) — прямо в дух harness-инжиниринга.
+  - Идемпотентность — повтор одного запроса = тот же результат. Idempotency-Key на POST → решает «двойной клик» на уровне API (а не только теста).
+  - Валидация на входе — проверяй данные на границе, fail fast, возвращай 422 с ошибками по полям (это и «разбирай формы на границе» из статьи OpenAI).
+  - Курсорная vs offset пагинация — курсорная стабильнее, когда данные меняются. Нюанс в нашу пользу: у нас снимок неизменен между sync → offset нам ок
+  (проще).
+
+
+Как проектировать контракт (практика)
+
+  1. Контракт — ПЕРВЫМ (до фронта и бэка). Обе стороны договариваются о форме → потом каждый строит под неё. Вот почему «бэк раньше фронта» = на деле
+  «контракт раньше обоих». Можно даже фронт делать на «фейковом» бэке (заглушке), пока бэк пишется.
+  2. Форму делай под нужду ФРОНТА, а не под таблицы БД. Не вываливай сырые строки базы — отдавай то, что удобно показать. (Бэк сам перекладывает из БД в
+  форму ответа.)
+  3. Базовые правила REST: GET = прочитать, POST = создать/действие, PUT/PATCH = изменить, DELETE = удалить. Адрес называет «вещь»: /clients, /reports.
+  4. Коды ответа: 200 ок, 400 кривой запрос, 401/403 нет прав, 404 не найдено, 500 ошибка сервера. (Фронт по коду понимает, что случилось.)
+  5. Пагинация для больших ответов: карточка счёта = миллионы строк → НЕ отдавай всё разом, отдавай страницами (?page=2&size=100). Это прямо из сайзинга
+  (латентность/трафик).
+  6. Версионирование: если ВЫНУЖДЕН сломать форму — делай /api/v2/..., не ломай тихо /v1 (старые потребители продолжат жить). Это про 🔴 «дверь в одну
+  сторону».
+
+  Контракт = цель приёмочного теста
+
+Кто проектирует
+
+  Ты определяешь контракт (это 🔴 граница + доменная форма), агент реализует. И договариваешься о нём до постройки обеих сторон — чтобы фронт и бэк не
+  разъехались.
+
+Брандмауэр (firewall, «файрвол») — это система, которая фильтрует сетевой трафик: решает, какие соединения пропустить, а какие заблокировать. По сути —
+  «охранник на двери» между сетями.
+
+
+<font color="#ffff00">🧰  Выбор стека: «скучные технологии»</font>
+
+  Принцип
+
+  По умолчанию бери скучные технологии — проверенные, популярные, стабильные. Не потому что «старьё хорошо», а потому что:
+  - 🤖 их много в обучении модели → агент пишет их хорошо, и ты можешь проверить (полно примеров/доков). Экзотику агент галлюцинирует, а ты не сверишь.
+  - 👥 большое комьюнити = грабли уже собраны, паттерны проверены, «если сломается — есть кому помочь».
+  - 🛡 стабильно = меньше сюрпризов (Люссер/P4).
+
+  Два правила
+
+  1. Меньше технологий = надёжнее (Люссер). Не тащи новую либу под каждую мелочь — переиспользуй.
+  2. Стек = 🔴 дорого менять (язык, БД). Выбирай вдумчиво. А на дешёвом (какая именно Excel-либа) — не агонизируй, поменяешь.
+
+
+ Цикл постройки
+
+  Единица работы — вертикальный срез
+
+  Напомню: строишь не «слой», а тонкий срез сквозь все слои — одну фичу от данных до UI, работающую end-to-end. Так петля обратной связи живёт с первого
+  дня, а не «в конце ад интеграции».
+
+  Цикл одного среза — пошагово (рецепт, который повторяешь)
+
+  Шаг 0. Выбери наименьший срез. Не «весь сайт», а одна фича. Пример: отчёт ОСВ для одного клиента.
+
+  Шаг 1. Мини-спека среза (5–10 строк): что делает, входы/выходы. «Аудитор выбирает клиента+период → видит ОСВ → итоги совпадают с 1С → может выгрузить в
+  Excel».
+
+  Шаг 2. Приёмочный e2e-тест = арбитр, ПЕРВЫМ. До кода. «POST /api/reports/osv {client_id, period} → totals = эталон из 1С байт-в-байт». Это и есть
+  «готово».
+
+  Шаг 3. Предскажи (письменно): что жду + что может сломаться («наверное, поплывут sentinel-даты», «UUID byte-swap»). Это твой тренажёр суждения.
+
+  Шаг 4. Агент строит срез — конкретным заданием, не «сделай ОСВ»:
+
+  ▎ «Сделай срез ОСВ: (1) repo getEntries(schema, period); (2) service buildOSV с правилами сальдо/оборотов; (3) endpoint POST /api/reports/osv; (4)
+  ▎ React-страница с гридом. Должен пройти вот этот приёмочный тест: [...]. Тесты — только этот e2e + юнит на расчёт сальдо.»
+
+  Шаг 5. Запусти и проверь ВНЕ себя: тесты зелёные + подними приложение + глазами дёрни отчёт + глянь логи всех сторон. (Не «агент сказал готово» — а арбитр
+  сказал + ты увидел.)
+
+  Шаг 6. Сравни предсказание ↔ реальность. Где разрыв — пойми ПОЧЕМУ (вот тут рождается твоё понимание), потом чини. Сначала своя гипотеза, потом спрашивай
+  агента.
+
+  Шаг 7. Ревью → мердж → деплой. Cross-model ревью (другой агент проверил), короткий PR, выкатил.
+
+  Шаг 8. Повторяющийся баг → затяни контроль. Если что-то сломалось второй раз — новый тест / линтер / правило в доке (это harness-петля OpenAI: «сделай
+  способность enforceable»). Дальше — следующий срез (карточка счёта).
+
+  Ralph-loop (автономный цикл)
+
+  Внутри Шага 4-5 агент может крутить сам: запустил тест → не прошёл → поправил → запустил → ... пока арбитр не станет зелёным. Ты задаёшь цель + арбитра,
+  агент итерирует. (Для этого дай агенту возможность сам запускать тесты/приложение — «agent-legible» среда из статьи OpenAI.)
+
+  Правила работы с агентом
+
+  - Мелкие срезы, короткие PR (фиксы дёшевы, ожидание дорого).
+  - Задание конкретное (что в каком слое), тесты — списком, не «напиши тесты».
+  - Дай агенту сам запускать и проверять (тесты, приложение, логи) — тогда он сам себя верифицирует.
+
+  Грабли (из knowledge)
+
+  - ⚠️ Агент рапортует «готово» на ~80% → проверяй финал (лучше в новой сессии).
+  - ⚠️ Агент ленится: может закомментить тест ради зелёного → e2e-арбитр это ловит (он про поведение, не подкрутишь).
+  - ⚠️ Дрейф (копирует плохие паттерны) → «золотые принципы» в репо + периодический GC-проход.
+
+
+
+
+Статика (проверка БЕЗ запуска)
+
+  Что это
+
+  Статика = проверки кода, которые читают его, НЕ запуская. Самый дешёвый и быстрый слой: ловит ошибки за миллисекунды, ещё до единого теста. Три вида:
+
+  1. Форматтер (formatter)
+
+  Авто-причёсывает код к единому стилю (отступы, пробелы, кавычки). Убирает все споры про стиль — нажал «сохранить», и код всегда одинаковый.
+  - Python: Ruff / Black · JS/TS: Prettier · Go: gofmt
+  - Не про баги — про единообразие.
+
+  2. Линтер (linter)
+
+  Читает код и подсвечивает вероятные БАГИ и плохие паттерны: неиспользуемая переменная, обращение к несуществующей, == вместо ===, недостижимый код,
+  опасные конструкции.
+  - Python: Ruff / Flake8 · JS/TS: ESLint
+  - Ловит целый класс ошибок до запуска.
+
+  3. Проверка типов (type checker)
+
+  Проверяет, что типы сходятся: не передал строку туда, где ждут число; не вызвал метод, которого нет.
+  - TS даёт это для фронта · Python: mypy / pyright · в Go/Rust встроено.
+  - 🔑 Вот почему берут TypeScript, а не голый JavaScript: TS добавляет проверку типов → ловит кучу багов до запуска.
+
+  Почему это ПЕРВАЯ линия (shift-left)
+
+  Ловит ошибку за миллисекунды, без запуска приложения и без написания теста. Самая дешёвая обратная связь. Опечатка/неверный тип/несуществующая переменная
+  никогда не доберутся до теста — их срубит статика.
+
+  🤖 Связь с агентом (урок OpenAI)
+
+  - Линтер = feedforward+feedback для агента: запускается сам, агент читает ошибку → сам исправляется.
+  - Трюк OpenAI: пиши инструкцию по починке прямо в текст ошибки линтера → агент знает, как чинить.
+  - Кастомные линтеры принуждают ТВОИ инварианты — те самые правила слоёв из 4.1 («UI не импортит Repo»). Вот так архитектура держится механически, а не «на
+  честном слове».
+
+  Best practice
+
+  Включи статику с дня 1 (у OpenAI настройка CI/формата/линта была буквально в первом коммите). Дёшево, эффект огромный, плюс держит код агента
+  единообразным и legible.
+
+🔒 Триада безопасности в статике (для аудита/финансов — обязательно)
+
+  1. SAST (Static Application Security Testing) — ищет уязвимости (инъекции, дыры в авторизации, кривая криптография) глубоким анализом по всему коду
+  (taint/data-flow). Это НЕ линтер: линтер = стиль/баги в одном файле, SAST = безопасность через весь код. Инструменты: Semgrep, Bearer, CodeQL, Bandit
+  (Python).
+  2. Secret scanning — ловит захардкоженные секреты (ключи, пароли, токены) до того, как они попадут в git. Инструменты: gitleaks, GitGuardian. (Ровно наш
+  «секреты не в коде».)
+  3. SCA (Software Composition Analysis) / сканирование зависимостей — проверяет чужие библиотеки на известные уязвимости (CVE), вредоносные пакеты,
+  лицензии + делает SBOM (опись компонентов). Инструменты: Dependabot, npm audit, Snyk. 👉 Это защита от supply-chain атак (axios/litellm из наших чатов!).
+
+
+📊 Метрики качества
+
+  - Сложность / дублирование / поддерживаемость (cyclomatic complexity, duplication). SonarQube собирает всё в одну панель. (У OpenAI это был документ
+  QUALITY_SCORE.md.)
+
+  ⏱ Важный нюанс ПО ВРЕМЕНИ (best practice)
+
+  - Быстрое (форматтер/линтер/типы) → на каждое сохранение/коммит (миллисекунды).
+  - Тяжёлое (полный SAST, SCA) → на PR / ночью в CI, НЕ на каждое нажатие (иначе тормозит работу).
+
+  🛠 Оркестратор
+
+  - pre-commit (фреймворк) — гоняет все быстрые проверки автоматически перед коммитом.
+  - Минорно по инструментам: Ruff (Python — дефолт), Biome (JS/TS — современный всё-в-одном lint+format).
+
+
+
+Шаг 2 — Тесты: как писать и запускать
+
+  Анатомия любого теста: AAA (Arrange–Act–Assert)
+
+  Любой тест = три части (это же = Given/When/Then из BDD):
+  Arrange (подготовь)  — задай ситуацию (данные, состояние)
+  Act     (сделай)     — вызови функцию / дёрни эндпоинт
+  Assert  (проверь)    — сверь результат с ожидаемым
+  Наш test_ping был Act+Assert. А вот unit на бизнес-логику:
+  def test_build_osv_totals():
+      entries = [Проводка(дебет=100), Проводка(кредит=100)]   # Arrange
+      osv = build_osv(entries)                                  # Act
+      assert osv.totals.обороты == 100                          # Assert
+
+  Test runner — инструмент, который находит и гоняет тесты
+
+  ┌───────────────────────────────────────────────────────────────────────────────┬───────────────────┐
+  │                                     Стек                                      │      Раннер       │
+  ├───────────────────────────────────────────────────────────────────────────────┼───────────────────┤
+  │ Python (бек)                                                                  │ pytest            │
+  ├───────────────────────────────────────────────────────────────────────────────┼───────────────────┤
+  │ React/TS (фронт)                                                              │ Vitest (или Jest) │
+  ├───────────────────────────────────────────────────────────────────────────────┼───────────────────┤
+  │ E2E (браузер)                                                                 │ Playwright        │
+  ├───────────────────────────────────────────────────────────────────────────────┼───────────────────┤
+  │ Запускаешь (pytest) → он находит все test_*, гоняет, пишет ✅/❌ + что упало. │                   │
+  └───────────────────────────────────────────────────────────────────────────────┴───────────────────┘
+
+  Как писать каждый тип (на нашем стеке)
+
+  - Unit (pytest): чистая функция (расчёт сальдо, byte-swap UUID). Быстро, без БД.
+  - Integration (pytest + реальная тестовая БД): repo против настоящего Postgres — «сохранил → достал → совпало».
+  - E2E (Playwright): робот открывает страницу, кликает, проверяет, что отчёт совпал с эталоном.
+
+  Test doubles — подделки (mock / stub / fake)
+
+  Подменяешь медленное/внешнее (например, источник 1С) фейком → тесты быстрые и детерминированные.
+  ⚠️ Но не перемокай! Если замокать всё — тест ничего реального не проверяет. Для integration бери реальную тестовую БД, а не мок.
+
+  Coverage (покрытие) — сигнал, НЕ цель
+
+  % кода, который трогают тесты. Полезно как индикатор, но 100% ≠ хорошие тесты (можно «пройти» строку, ничего не проверив). Не гонись за цифрой — лучше
+  mutation testing покажет, ловят ли тесты реальные баги.
+
+  Качества хорошего теста
+
+  - Быстрый · детерминированный (не флейкает) · изолированный (не зависит от других) · проверяет одно · читаемый · проверяет поведение, не реализацию (→
+  переживает рефакторинг).
+
+  Агент-эра (свод)
+
+  1. Приёмочный e2e пишешь ПЕРВЫМ → красный → код → зелёный (видели на слайсе).
+  2. Тесты заказывай списком, не «напиши тесты».
+  3. Приоритет: e2e критических путей → integration → unit для хитрой логики (трофей).
+  4. Тест = арбитр (если про поведение — агент не подкрутит).
+
+  Подготовка/уборка (fixtures)
+
+  Перед тестом готовишь данные (свежая тестовая БД), после — чистишь. В pytest это fixture.
+
+
+ Тесты делятся не по одной оси, а по нескольким сразу (один и тот же тест попадает в несколько классификаций). Вот оси:
+
+  Ось A — по ОХВАТУ (сколько системы трогает) — главная ось
+
+  1. Unit — одна функция/класс
+  2. Component — один UI-компонент / модуль
+  3. Integration — несколько частей вместе (service+БД, API+service)
+  4. Contract — совпадает ли форма API у фронта и бэка
+  5. E2E / System — вся система как пользователь
+
+  Ось B — функциональные («правильно ли делает»)
+
+  6. Acceptance (приёмочные, BDD) — бизнес-критерий выполнен
+  7. Smoke — «вообще живо?» сразу после деплоя
+  8. Sanity — быстрая проверка конкретной починки
+  9. Regression — старое не сломалось (гоняешь весь набор)
+
+  Ось C — нефункциональные («как хорошо», а не «что»)
+
+  10. Performance — скорость одного действия
+  11. Load — держит ли N юзеров/RPS
+  12. Stress — где ломается под перегрузом
+  13. Soak — держит ли долго (утечки памяти)
+  14. Spike — резкий всплеск
+  15. Security — DAST (на живом), pen-test (+SAST из статики)
+  16. Accessibility (a11y) · 17. Usability · 18. Compatibility (браузеры) · 19. Reliability/Chaos (выживает при падениях)
+
+  Ось D — по ТЕХНИКЕ (как устроен сам тест)
+
+  20. Example-based — конкретные кейсы (обычные)
+  21. Property-based / fuzz — генерит кучу случайных входов → ловит то, что ты не придумал (наши unknown-unknowns!)
+  22. Mutation — тест для тестов (ловят ли баги)
+  23. Snapshot / golden — сравнение с сохранённым эталоном (твоя сверка ОСВ с 1С = golden-тест!)
+  24. Visual regression — diff скриншотов UI
+
+  ▎ ⚠️ Ты не пишешь все 24 на каждый проект. Берёшь подмножество по нужде: типичный набор = unit + integration + e2e + (load) + (security). Экзотика (chaos,
+  ▎ soak) — только на масштабе.
+
+
+ Да, e2e МЕДЛЕННЫЕ — это ключевой компромисс
+
+  ┌─────────────┬────────────────────┬────────────────────────────────────────────┐
+  │     Тип     │ Время ОДНОГО теста │                   Почему                   │
+  ├─────────────┼────────────────────┼────────────────────────────────────────────┤
+  │ Unit        │ миллисекунды       │ ничего не запускает, чистая функция        │
+  ├─────────────┼────────────────────┼────────────────────────────────────────────┤
+  │ Component   │ мс–десятки мс      │ рендер одного компонента                   │
+  ├─────────────┼────────────────────┼────────────────────────────────────────────┤
+  │ Integration │ десятки–сотни мс   │ реальные вызовы к БД                       │
+  ├─────────────┼────────────────────┼────────────────────────────────────────────┤
+  │ E2E         │ СЕКУНДЫ            │ поднимает браузер, кликает, ждёт отрисовки │
+  ├─────────────┼────────────────────┼────────────────────────────────────────────┤
+  │ Load        │ минуты–часы        │ специально гоняешь под нагрузкой           │
+  └─────────────┴────────────────────┴────────────────────────────────────────────┘
+
+  500 e2e × 3 сек = 25 минут. Вот почему пирамида: много быстрых unit, мало медленных e2e (только критические пути).
+
+  🔑 Главный ответ: ты НЕ ждёшь полдня — ты СЛОИШЬ прогоны по скорости
+
+  ┌──────────────────────────┬───────────────────────────────────────┬──────────────────────────────────────────────────────┐
+  │          Когда           │             Что гоняется              │                    Сколько ждёшь                     │
+  ├──────────────────────────┼───────────────────────────────────────┼──────────────────────────────────────────────────────┤
+  │ на сохранение (редактор) │ unit для текущего файла               │ миллисекунды                                         │
+  ├──────────────────────────┼───────────────────────────────────────┼──────────────────────────────────────────────────────┤
+  │ на коммит (pre-commit)   │ быстрые: unit + линтер + типы         │ секунды                                              │
+  ├──────────────────────────┼───────────────────────────────────────┼──────────────────────────────────────────────────────┤
+  │ на PR (CI)               │ весь unit + integration + немного e2e │ минуты — но ты НЕ ждёшь, CI крутит сам, ты работаешь │
+  ├──────────────────────────┼───────────────────────────────────────┼──────────────────────────────────────────────────────┤
+  │ ночью (scheduled)        │ полный e2e + load + полный SAST/SCA   │ 30+ мин — пока ты спишь                              │
+  └──────────────────────────┴───────────────────────────────────────┴──────────────────────────────────────────────────────┘
+
+ 🏭 Часть 5, Шаг 3 — CI/CD (конвейер, который запускает всё сам)
+
+  25. Что это простыми словами
+
+  - CI = Continuous Integration = непрерывная интеграция. На каждое изменение кода автоматически прогоняются все проверки (статика Шаг 1 + тесты Шаг 2).
+  Цель — поймать поломку сразу, а не через 2 дня.
+  - CD = Continuous Delivery/Deployment = непрерывная доставка/развёртывание. Если все проверки зелёные — код сам едет до прода (или до кнопки «выкатить»).
+    - Delivery = доведён до состояния «готов выкатить одной кнопкой» (кнопку жмёт человек).
+    - Deployment = выкатывается сам, без кнопки.
+
+  Для тебя на старте: CI обязателен, CD — сначала с кнопкой (человек подтверждает прод).
+
+  ---
+  2. Зачем — слово практикам (knowledge)
+
+  Остриков (id40, harness-engineering):
+
+  ▎ Ты сэкономил 2 дня на кодинге, а потом ждёшь коммент Васи (LGTM завтра вечером), потом тестинг, потом фикс, потом мерж, потом дежурный толкает до прода…
+  ▎ и твои 2 дня размазались. AI-First = переложить работу всего IT-завода на автоматику.
+
+  Валера (id2165, «человек-оркестр»):
+
+  ▎ Что реально спасло — чёткий пайплайн тестов перед выкаткой, описанный скриптом. Smoke перед каждым пушем, полный прогон перед продом. Деплой не когда
+  ▎ модель написала done, а когда зелёный гейт сказал done и я глазами дёрнул метод и увидел ответ.
+
+  🔑 Это и есть суть: CI/CD — автоматический внешний арбитр для выкатки. Не слово агента «готово» (= ~80%, помнишь?), а зелёный гейт.
+
+  ---
+  3. Мысленная модель — конвейер с воротами (гейтами)
+
+  Пайплайн = цепочка стадий. Каждая стадия — ворота: красное → дальше не пускаем.
+
+  Те самые «слои прогона» из Шага 2 ложатся прямо на триггеры CI:
+
+  коммит (локально, pre-commit)  → формат + линт + типы + unit файла   ~секунды
+  ↓
+  PR открыт (CI-сервер)          → весь unit + integration + чуть e2e   ~минуты
+                                   + SAST/SCA/secret-scan                (ты не ждёшь — CI крутит)
+  ↓ (всё зелёное + ревью)
+  мерж в main                    → собрать артефакт → выкатить на staging → smoke
+  ↓ (кнопка)
+  production
+  ↓
+  ночью (cron)                   → полный e2e + load + golden (ОСВ vs 1С)  ~долго (спишь)
+
+  ---
+  4. Словарь (8 понятий — без них не разберёшься)
+
+  ┌───────────────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+  │      Термин       │                                                        Простыми словами                                                         │
+  ├───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+  │ Триггер           │ что запускает пайплайн: push, открытие PR, мерж, tag, расписание (cron)                                                         │
+  ├───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+  │ Джоба/стадия      │ шаг конвейера: job «линт», job «тесты», job «сборка», job «деплой»                                                              │
+  ├───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+  │ Гейт (quality     │ условие «красное → стоп». Автоматический арбитр                                                                                 │
+  │ gate)             │                                                                                                                                 │
+  ├───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+  │ Артефакт          │ что собрали и передаём дальше — Docker-образ. 🔑 Build once, deploy everywhere: собрал один образ → тот же катишь на staging и  │
+  │                   │ на prod (не пересобираешь)                                                                                                      │
+  ├───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+  │ Среды             │ dev → staging (копия прода, но не прод) → production. Артефакт «промоутишь» по средам                                           │
+  ├───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+  │ Раннер            │ машина, где это исполняется (GitHub Actions runner)                                                                             │
+  ├───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+  │ Кэш               │ кэшировать зависимости/слои Docker → пайплайн быстрый (иначе ставит всё заново каждый раз)                                      │
+  ├───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+  │ Branch protection │ нельзя мержить в main без зелёного CI + ревью. Это «забор» вокруг прода                                                         │
+  └───────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
+
+  Два принципа скорости:
+  - Fail fast — дешёвые проверки первыми. Линт упал → не гоняем дорогие e2e (не жжём время/деньги).
+  - Параллелизм — независимые джобы запускаем разом (линт ∥ тесты) → конвейер короче.
+
+  ---
+  5. CD — как именно выкатывать (стратегии) + откат
+
+  ┌────────────┬──────────────────────────────────────────────┬────────────────────┬────────────────────────────────┐
+  │ Стратегия  │                     Как                      │      Даунтайм      │             Когда              │
+  ├────────────┼──────────────────────────────────────────────┼────────────────────┼────────────────────────────────┤
+  │ Recreate   │ выключил старое → включил новое              │ да, секунды-минуты │ старт, один сервер             │
+  ├────────────┼──────────────────────────────────────────────┼────────────────────┼────────────────────────────────┤
+  │ Rolling    │ заменяем по чуть-чуть                        │ нет                │ нужен HA (несколько инстансов) │
+  ├────────────┼──────────────────────────────────────────────┼────────────────────┼────────────────────────────────┤
+  │ Blue-green │ две копии прода, переключил трафик           │ нет                │ мгновенный откат               │
+  ├────────────┼──────────────────────────────────────────────┼────────────────────┼────────────────────────────────┤
+  │ Canary     │ 5% трафика на новое → смотрим метрики → 100% │ нет                │ важна осторожность             │
+  └────────────┴──────────────────────────────────────────────┴────────────────────┴────────────────────────────────┘
+
+  Практики на одном сервере (как у тебя): Абдуллин (id763) — zero-downtime через systemd socket activation; Остриков (id12716) — pre-stable/stable 5%/95% на
+  одной машине. Но это уже продвинутое.
+
+  Откат (rollback): благодаря build-once у тебя лежит предыдущий Docker-образ → откат = запустить его обратно, секунды. Валера (id2023) идёт дальше —
+  snapshot всей VM. Принцип Recovery-first: система должна быстро возвращаться в рабочую точку.
+
+
+Часть 7 — Наблюдаемость (Observability): что система делает в проде прямо сейчас
+
+  1. Что это — простыми словами
+
+  - Тесты = «правильно ли это ДО деплоя».
+  - Наблюдаемость = «что система делает в проде ПОСЛЕ деплоя, прямо сейчас, под реальными юзерами».
+
+  И сразу важное различие:
+
+  ┌───────────────┬────────────────────────────────────────────────────┬──────────────────────────────────────────────┐
+  │               │                     Что мерит                      │                    Ловит                     │
+  ├───────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
+  │ Мониторинг    │ то, что ты заранее решил мерить (CPU, RPS, ошибки) │ known unknowns — «знаю, что может сломаться» │
+  ├───────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
+  │ Наблюдаемость │ можешь задать любой вопрос системе постфактум      │ unknown unknowns — то, что не предусмотрел   │
+  └───────────────┴────────────────────────────────────────────────────┴──────────────────────────────────────────────┘
+
+  🔑 Помнишь твою тему «нельзя протестировать то, о чём не подумал»? Наблюдаемость — это тот самый механизм, который ловит unknown unknowns уже в ПРОДЕ.
+  Тесты ловят до, наблюдаемость — после.
+
+  ---
+  2. Три столпа (это база, знать наизусть)
+
+  ┌─────────┬─────────────────────────────────────────────────┬──────────────────────┬────────────────────────────────────────────────┐
+  │  Столп  │                     Что это                     │  Отвечает на вопрос  │                     Пример                     │
+  ├─────────┼─────────────────────────────────────────────────┼──────────────────────┼────────────────────────────────────────────────┤
+  │ Логи    │ записи событий «что произошло» (строка + время) │ что именно случилось │ user=42 открыл отчёт ОСВ, 340ms, ok            │
+  ├─────────┼─────────────────────────────────────────────────┼──────────────────────┼────────────────────────────────────────────────┤
+  │ Метрики │ числа во времени (агрегаты)                     │ сколько / как часто  │ p95 latency, RPS, error rate, queue depth      │
+  ├─────────┼─────────────────────────────────────────────────┼──────────────────────┼────────────────────────────────────────────────┤
+  │ Трейсы  │ путь одного запроса через всю систему           │ где ушло время       │ API 5ms → service 10ms → БД 320ms → render 5ms │
+  └─────────┴─────────────────────────────────────────────────┴──────────────────────┴────────────────────────────────────────────────┘
+
+  Мнемоника: Логи = что случилось · Метрики = сколько/тренд · Трейсы = где затык.
+
+  🔑 Структурные логи (JSON), а не текст — чтобы можно было искать/фильтровать (level=error AND user=42), а не глазами читать простыню.
+
+  Рядом:
+  - События (events) — бизнес-факты: «оплата прошла», «отчёт сгенерирован» (иногда 4-й столп).
+  - Алерты — метрика пересекла порог → звонок. ⚠️ Только криты (Остриков id25: «пишем только то, из-за чего собираем звонок в любое время дня и ночи»).
+  - Дашборды — визуализация метрик (Grafana).
+  - SLI/SLO/SLA — Indicator (что мерим, напр. % успешных запросов) → Objective (цель: 99.5%) → Agreement (договор с клиентом + штраф). Разница между целью и
+  реальностью = error budget (бюджет на ошибки).
+
+  ---
+  3. Золотая нить — correlation_id (как связать три столпа)
+
+  Сам по себе каждый столп — половина картины. Связывает их сквозной ID запроса (trace_id / correlation_id), который проходит через все сервисы.
+
+  Тогда работает магия расследования:
+  метрика «p99 подскочил» → проваливаешься в конкретные ТРЕЙСЫ этих запросов
+  → видишь span БД 320ms → открываешь ЛОГИ с тем же trace_id → видишь, какой SQL
+  Без сквозного ID ты не свяжешь «что» + «сколько» + «где». Это первое, что просишь у агента заложить.
+
+  ---
+  4. Три вопроса, на которые отвечает наблюдаемость
+
+  5. Что сломано? → алерт / метрика
+  6. Почему? → трейс (где) + лог (что именно)
+  7. Кого затронуло и насколько? → метрики + события
+
+  ---
+  8. Слово практикам (это ИХ любимая тема — в сигнале её больше всего)
+
+  Валера (id1974): «самое важное — чтобы у агента были логи… не видел, чтобы хоть один блогер настроил логи и трейсинг для своего агента.»
+
+  Валера (id2165): «читать логи всех сторон системы (vllm, litellm, гейт, вебхук) — там вся соль, а не в "агент сказал готово". Единственная фича, которая
+  ни разу не подвела — дисциплина смотреть в логи каждый раз.»
+
+  Абдуллин (id812, AI Ops): node_exporter → VictoriaMetrics (метрики) + ClickHouse (структурные логи) → Grafana (дашборды) + Prometheus-счётчики в рантайм.
+
+  Абдуллин (id73217): «логи в структурированном формате, даём агенту RO-доступ + описываем что где лежит + примеры типичных запросов + скрипты для отладки →
+  агент сам расследует инциденты. Все кластера так обслуживаются.»
+
+  Mike Shevchenko (id58777): «LLM выдаёт текст — непонятно, как пришёл. Навигатор показывает карту — видишь маршрут.» Наблюдаемость = карта для агента
+  (закрывает feedback loop).
+
+  ---
+  9. 🤖 Главное для вайбкодера: «agent-legible app» (приложение, читаемое агентом)
+
+  Это ключ из OpenAI harness + Абдуллина. Если тесты — это feedback loop до деплоя, то наблюдаемость — это feedback loop агента в ПРОДЕ.
+
+  Чтобы агент сам расследовал и чинил, дай ему:
+  - структурные логи (JSON, не текст);
+  - RO-доступ к телеметрии (логи/метрики/трейсы);
+  - doc «что где лежит» + примеры типичных запросов + скрипты отладки;
+  - иногда agent-режим приложения (Абдуллин id755): логов меньше, любая ошибка роняет приложение целиком — чтобы агенту было чисто себя проверять.
+
+  Тогда можно дать задание уровня (Остриков id40): «проверь все варианты создания аккаунта, чтобы в трейсах не было спанов больше 900 мс» — и агент сам
+  пройдёт, посмотрит трейсы, найдёт затык.
+
+  ⚠️ Анти-паттерн (Абдуллин id812): high-cardinality метрика (напр. метрика с user_id в лейбле) может уронить весь Prometheus. Осторожно с тем, что кладёшь
+  в лейблы.
+
+  ---
+  7. Инструменты
+
+  - Стандарт инструментирования: 🔑 OpenTelemetry (OTel) — vendor-neutral, один SDK для логов+метрик+трейсов. Закладывай его, не привязывайся к вендору.
+  - Логи: структурный JSON → ClickHouse / Loki / ELK.
+  - Метрики: Prometheus / VictoriaMetrics → Grafana.
+  - Трейсы: OpenTelemetry → Jaeger / Tempo.
+  - Ошибки: Sentry (стектрейсы + группировка).
+  - Для LLM-под-капотом: Langfuse (трассировка цепочек агента) — у тебя на аудит-сайте пока не нужно, но запомни.
+
+
+4-й столп — Continuous Profiling (Datadog, и OTel уже завёл сигнал для него): логи/метрики/трейсы показывают «какой сервис тормозит», а профайлинг —
+  «какая функция/строка кода ест CPU/RAM в проде». Это последний уровень детализации.
+  2. Фронт тоже наблюдаем (у тебя React!):
+    - RUM (Real User Monitoring) — телеметрия из браузеров реальных юзеров: время загрузки, Core Web Vitals, JS-ошибки.
+    - Synthetic monitoring — бот по расписанию дёргает эндпоинты (ловит проблему до юзеров). Это твой smoke, живущий в проде.
+  3. SRE-дисциплина вокруг алертов (я сказал только «алерты на криты»):
+    - Burn-rate алерты — на скорость сжигания error budget, а не голый порог → меньше шума.
+    - Error budget policy — бюджет сожгли → фриз фич, чиним стабильность.
+    - Runbook — короткая инструкция «что делать по этому алерту», привязана к нему, обновляется после инцидента.
+    - Blameless post-mortem — после инцидента ищем корень, делаем систему лучше (твоя антихрупкость, Остриков id13454: «каждая ошибка должна улучшать
+  систему»).
+  4. Экономика телеметрии (чтобы не разориться и не утонуть):
+    - Tail-based sampling — храним все error-трейсы + % успешных.
+    - Логи на info в проде, debug только при расследовании (один сервис на debug = больше данных, чем весь флот).
+  5. AI-наблюдаемость (на будущее, когда добавишь LLM-под-капотом): трейс = весь путь решения агента (tool calls, retrieved docs, параметры); trace-to-eval
+  loop — прод-фейл становится eval-кейсом → гейт в CI (ровно 9 принципов Рефата). Инструменты: Langfuse (OSS) / LangSmith / Phoenix-Arize
+  (OTel-совместимый).
+
+
+⚙️ Часть 6 — DevOps (как код доезжает до прода и там живёт)
+
+  1. Что это — простыми словами
+
+  Dev (пишет код) + Ops (эксплуатирует на проде) — раньше две команды, кидали через стену: «у меня работает» → «а на проде падает». DevOps = одна
+  ответственность за весь цикл «от кода до прода и эксплуатации».
+
+  🔑 Девиз: «You build it, you run it» — кто построил, тот и отвечает за то, как оно живёт. Это культура/процесс, а не должность.
+
+  Практик-якоря:
+  - Валера (id2165): его база — devops/сети/linux/docker/k8s за 6 лет; без неё агент = «джун с уверенным тоном». [roadmap.sh/devops]
+  - Абдуллин (id769): «теперь можно частично снять DevOps-нагрузку (агент настроит)… но контролировать — не отменяет».
+  - Абдуллин (id812, AI Ops): Codex настроил телеметрию за него, но «не заменяет SRE — уроню стек, моя вина» (= P8).
+
+  ---
+  2. Местность: что где крутится
+
+  ┌─────────────────────────────┬─────────────────────────────────────────────────────────────────────────────────┬───────────────┐
+  │          Компонент          │                                      Роль                                       │   stateful?   │
+  ├─────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────┼───────────────┤
+  │ Reverse-proxy (Caddy/nginx) │ единая точка входа: HTTPS снаружи + авто-TLS (Caddy) + маршрут на app + статика │ нет           │
+  ├─────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────┼───────────────┤
+  │ App (FastAPI)               │ твоя логика                                                                     │ 🔑 stateless! │
+  ├─────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────┼───────────────┤
+  │ БД (Postgres)               │ здесь живёт состояние                                                           │ да            │
+  ├─────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────┼───────────────┤
+  │ Очередь+воркеры (Celery)    │ фоновые задачи (синк из 1С)                                                     │ нет           │
+  ├─────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────┼───────────────┤
+  │ Кэш (Redis)                 │ сессии, кэш отчётов                                                             │ (полу)        │
+  └─────────────────────────────┴─────────────────────────────────────────────────────────────────────────────────┴───────────────┘
+
+  🔑 Stateless-приложение = app не хранит состояние в себе (ни сессий, ни файлов) — всё в БД/Redis. Тогда его можно перезапускать и размножать без потерь.
+  Это фундамент всей эксплуатации. Всё это — в Docker (один образ → воспроизводимо везде).
+
+  ---
+  3. 12-Factor App — канон «приложения, удобного для эксплуатации»
+
+  Стандартный чек-лист (ключевое для тебя):
+  - Конфиг — в env-переменных, не в коде (один образ → разные среды через env).
+  - Stateless-процессы (см. выше).
+  - Логи — в stdout (а не в файл; их забирает система логов — Часть 7).
+  - Dev/prod parity — dev, staging, prod одинаковые, разница только в конфиге.
+  - Зависимости явные (lock-файл), сборка ≠ запуск ≠ конфиг.
+
+  ---
+  4. 📌 Топология — твой реальный вопрос «1С на одном серваке, сайт на другом»
+
+  [Сервер 1С] ──читаем──> [Celery sync] ──пишет──> [твоя Postgres = витрина]
+   (источник,                                            │
+    НЕ трогаем)                                           ▼
+                            [App-сервер: Caddy + FastAPI + React + Celery + Redis + Postgres]
+                                                          │
+                                                приватная сеть/VPN (Tailscale)
+  - 1С-сервер — источник, его только читаем (твоё «копируем БД 1С»).
+  - Sync (Celery) тянет данные 1С → твоя Postgres-витрина (отсюда быстрые аналитические запросы — ты latency-bound).
+  - App-сервер на старте — один сервер, Docker Compose (one-server-first из тех-дизайна).
+  - Сеть между серверами — приватная/VPN (Tailscale — им пользуются Абдуллин/Валера), наружу не торчит.
+  - Разносишь на больше серверов только когда упрёшься (не раньше).
+
+  ---
+  5. Эксплуатация на одном сервере (Ops)
+
+  - Health-checks (liveness «жив?» / readiness «готов принимать?») — proxy/оркестратор не шлёт трафик на мёртвый контейнер.
+  - Restart policy (restart: always в Docker) — упал → поднялся сам.
+  - Лимиты CPU/RAM на контейнеры — чтобы один (напр. тяжёлый отчёт) не сожрал весь сервер.
+  - Нулевой даунтайм на одном сервере: systemd socket activation (Абдуллин id763) ИЛИ blue-green через два compose + переключение Caddy ИЛИ просто recreate
+  + маленькое окно (на старте — норм).
+
+  ---
+  6. 🛟 Бэкапы + Disaster Recovery (для аудита — критично)
+
+  - Бэкап БД регулярно + ПРОВЕРЕННОЕ восстановление. 🔑 Бэкап, который ни разу не разворачивали = нет бэкапа.
+  - Правило 3-2-1: 3 копии · 2 носителя · 1 offsite (вне сервера).
+  - RPO (сколько данных не жалко потерять → как часто бэкапим) / RTO (как быстро поднимаемся).
+  - Recovery-first (Пух id15542) + снапшоты (Валера id2023: snapshot всей VM → откат за секунды). Защита от ransomware (Часть 8).
+
+  ---
+  7. 🔗 Связка ВСЕГО воедино (сквозной маршрут — это замыкает конституцию)
+
+  dev-машина (пишешь с агентом)
+     │ git push
+     ▼
+  CI/CD (Часть 5 Шаг 3): статика → тесты → build → sign → артефакт(Docker)
+     │ deploy
+     ▼
+  Сервер: Caddy(TLS) → App(stateless) → Postgres/Redis/Celery
+     │
+     ▼
+  Наблюдаемость (Часть 7): логи/метрики/трейсы
+     │ инцидент → алерт
+     ▼
+  Агент расследует по логам (agent-legible) → фикс → снова цикл
+     ↑________________ Безопасность (Часть 8) — сквозь весь маршрут _____________↑
+
+  ---
+  8. 🤖 DevOps в агент-эру (твой режим)
+
+  - Агент настраивает сервер/сеть/телеметрию (Абдуллин id812: node_exporter→Prometheus→Grafana; Валера id2168: дал Клоду доступ к MikroTik, «прибрались»;
+  id769: Caddy+TLS+wildcard за минуты).
+  - 🔑 Декларативность = безопасный откат для агента: NixOS/Docker Compose/IaC в git → агент может менять инфру, откатишь rebuild’ом/git revert (Абдуллин
+  id763). Снапшот VM = тот же recovery-first.
+  - Но (P8): человек владеет. «Codex не заменяет SRE». Все изменения инфры смотришь глазами до применения (Абдуллин: NixOS позволяет пробежать диффы до
+  выката).
+
+  ---
+  9. 📌 Под аудит-сайт (чек-лист DevOps)
+
+  - Caddy (авто-TLS) → FastAPI (stateless) + React-статика · Celery+Redis · Postgres — в Docker Compose, один сервер
+  - 1С читаем по приватной сети (Tailscale), sync’им в Postgres-витрину
+  - Конфиг в env, секреты отдельно (Часть 8), dev/staging/prod одинаковы
+  - Health-checks + restart: always + лимиты ресурсов
+  - 🛟 Бэкап Postgres ежедневно + тест восстановления + offsite + снапшот сервера
+  - Нулевой даунтайм — позже (старт: recreate + окно)
+  - Вся инфра = код в git → агент меняет, ты ревьюишь диффы