Senior-практики: архитектура, решения, лидерство

System design (модуль 12) отвечает на вопрос «как устроить систему». Здесь — что начинается после доски: как решение записать, провести через ревью, пересмотреть, эксплуатировать и объяснить людям, которые не читают трейсы. Код — калькулятор TCO, error budget и линтер ADR на GoJava — лежит в examples/m13-seniorexamples/java/m13-senior, шаблоны документов — в examples/m13-senior/templates.

Архитектурные решения: ADR для AI-систем

ADR (Architecture Decision Record, запись об архитектурном решении) — короткий документ об одном решении. Формат предложил Майкл Найгард в 2011 году: заголовок, контекст (какие силы конфликтуют), решение («мы будем…»), статус (предложено, принято, заменено) и последствия — хорошие, плохие и нейтральные. ADR лежат в репозитории рядом с кодом (обычно docs/adr/0007-….md), нумеруются и не переписываются: если решение поменялось, пишут новый ADR со ссылкой «заменяет ADR-0007», а старый получает статус «заменено». Через год история решений читается как changelog архитектуры.

Для AI-системы пяти разделов мало: решения устаревают быстрее и опираются на доказательства, которые сами устаревают. Модели выводят из эксплуатации — Anthropic, например, предупреждает о выводе публично выпущенной модели минимум за 60 дней (по состоянию на октябрь 2026). Цены сдвигаются, и «self-host, потому что API дорого» однажды становится неверным. «Haiku достаточно» верно только для конкретной версии eval-набора. А модель не падает с 500, она уверенно ошибается. Поэтому в ADR добавляются разделы:

Когда писать ADR: решение дорого развернуть назад (вендор, где хранятся данные, граница между моделью и кодом), затрагивает другие команды или через полгода вызовет вопрос «почему так?». Правке промпта хватает PR с evals (модуль 3), смене модели в продакшене — нет.

# ADR-NNNN: <решение одной строкой: глагол + объект>

## Статус
Предложено | Принято | Заменено ADR-NNNN. Дата: ГГГГ-ММ-ДД. Владелец, кто утверждает.

## Контекст
Задача и метрика успеха; ограничения (латентность, бюджет, PII, регуляторика); почему решать сейчас.

## Решение
«Мы будем …». Модель, промпт (имя@версия), параметры, граница между моделью и кодом.

## Альтернативы
| Вариант | Качество на eval | $ за запрос | p95 латентности | Почему не выбран |
|---|---|---|---|---|
| Ничего не менять | | | | |
| Без LLM (правила, классический ML) | | | | |
| <реальная альтернатива> | | | | |

## Последствия
Что лучше, что хуже, что сложнее. Lock-in: что переделывать при смене модели или провайдера.

## Eval-доказательства
Набор (имя, версия, n), метрики с интервалами, критичные кейсы, прогон в CI. Где хуже baseline — прямо.

## Стоимость
$ за запрос и в месяц сейчас и при ×10; токены, доля кэша, цены с датой; TCO.

## Данные и комплаенс
Что уходит провайдеру, маскирование PII, хранение логов, регион; вопросы юристу.

## Режимы отказа
Провайдер недоступен, уверенная ошибка, рост латентности, атака: что видит пользователь, чем ловим.

## План отката
Механизм (флаг, реестр), время, кто может, по какому сигналу, когда проверяли.

## Пересмотр
Дата: ГГГГ-ММ-ДД. Досрочно: вывод модели из эксплуатации, цена ±N%, объём ×N, метрика ниже порога.

В примере решение принято ради латентности, а экономия ≈ $900 в месяц названа побочным эффектом: это снимает на ревью спор «ради $900 усложнили систему». И роутер честно хуже Sonnet по точности: минус с доверительным интервалом убеждает лучше таблицы, где выбранный вариант выигрывает во всех столбцах.

Срок пересмотра работает, только если его проверяют. Дешевле всего — линтер обязательных разделов в CI и ночная джоба, открывающая задачу на каждый ADR с прошедшей датой: функции MissingSections и ReviewBy в examples/m13-senior/adr.gomissingSections и reviewBy в examples/java/m13-senior/…/Adr.java, тест прогоняет их по шаблону выше.

Design review: какие вопросы задавать AI-системе

Design doc описывает систему целиком и ссылается на ADR по ключевым решениям. Структура — как в эссе Мальте Убля «Design Docs at Google»: контекст и масштаб, цели и не-цели, решение, альтернативы, сквозные вопросы (безопасность, приватность, наблюдаемость). Для AI-системы добавляются метрика успеха и критерии запуска, evals и стоимость. Шаблон из examples/m13-senior/templates/design-doc.md:

# Design doc: <название>

Автор · ревьюеры (данные, безопасность, SRE, продукт) · статус · дата · ADR: <ссылки>

## 1. Контекст и масштаб
Кто пользователи, какая боль, что уже есть.

## 2. Цели и не-цели
Что система делает и что сознательно НЕ делает.

## 3. Метрика успеха и критерии запуска
Метрика и способ измерения, baseline без AI, порог запуска, guardrail-метрики, kill-критерий.

## 4. Требования и цифры
Нагрузка и пик, латентность (TTFT, полное время), бюджет, PII, регуляторика.

## 5. Решение
Схема и поток данных, модель на каждом шаге. Права, деньги и необратимые действия — в коде.

## 6. Альтернативы
Минимум две, включая «без LLM»: качество, стоимость, латентность, риски.

## 7. Evals
Набор и критичные кейсы, судья и калибровка, онлайн-метрики, гейты в CI.

## 8. Безопасность и данные
Модель угроз, права инструментов, PII, хранение логов и доступ к ним.

## 9. Надёжность и эксплуатация
SLO и политика error budget, fallback, деградация, runbook, эскалация к людям.

## 10. Стоимость
$ за запрос и в месяц, TCO, рычаги снижения.

## 11. Запуск и откат
Этапы, canary, критерии перехода, откат.

## 12. Открытые вопросы
Что не решено, кто и к какому сроку решает.

Чек-лист ревьюера

Ревью ищет риски, а не проверяет эрудицию автора. Третий столбец — ответы, после которых стоит копать глубже.

Как проводить ревью

• Сначала асинхронно: документ за 2–3 дня до встречи, встреча — только для неснятых разногласий.
• Ревьюеры: безопасность, данные (DPO при PII), будущий дежурный, продукт; один явно принимает решение.
• Уровни замечаний: «блокер», «до запуска», «пожелание» — иначе автор тонет в 40 комментариях одного веса.
• Вопросы вместо предписаний: «что будет, если retrieval вернёт ноль документов?» лучше, чем «добавьте fallback».
• Итог записан: принято, с условиями (с владельцами) или на доработку; ключевые решения — в ADR.

Как защищать свой дизайн

• Не-цели вслух. Половина споров — о том, чего система и не собиралась делать.
• Цифры против мнений. На «а давайте агента» — «workflow даёт 91% на eval за $0.004, агент — 92% за $0.03 и втрое дольше; 1 п.п. в пределах шума».
• «Не знаю» с планом: «не мерил; к четвергу прогоню 200 кейсов». Выдуманные цифры ревьюеры запоминают.
• Обратимое и необратимое. Идея «дверей в одну и в две стороны» из писем акционерам Amazon: вендор, схема хранения PII, публичный API обсуждаются долго; формулировку промпта или порог роутера меняют конфигом — тут предлагайте эксперимент вместо спора.
• Disagree and commit. Решение не в вашу пользу — запишите несогласие и условия пересмотра в ADR и делайте как решили.

Build-vs-buy и выбор модели или вендора

На senior-уровне вопрос не «какую модель взять», а какой вариант реализации даёт нужное качество при приемлемых стоимости, латентности и рисках на горизонте года, с учётом людей на эксплуатацию. В книге Chip Huyen «AI Engineering» это раздел «Model Build Versus Buy» (глава 4); ниже — рабочая версия для команды.

Жёсткие ограничения отсекают, веса ранжируют. «Данные не покидают периметр банка» — не вес 5 из 5, а фильтр: нарушающие его варианты не участвуют в сравнении. Если после фильтров не осталось ничего, это результат: требования пересматривают с бизнесом.

Четыре типичных варианта: API frontier (максимум качества, ноль инфраструктуры, самая дорогая цена токена), API дешёвая модель (в разы дешевле и быстрее, хуже на сложном), self-host open-weight (данные в периметре, но GPU, минимум две реплики и люди — модуль 10) и fine-tuned малая модель (на узкой задаче догоняет большие, цена — датасет и переобучение при смене базы).

TCO: что входит кроме токенов

Последние две строки обычно забывают: разметку для fine-tuned модели перепроверяют при каждой смене базы, а миграции у API неизбежны. Стоимость на успешную задачу честнее стоимости на запрос: модель, решающая 70% задач, может обойтись дороже модели, решающей 90%, если неуспешные уходят оператору.

На пресете «Банк» включите ограничение по периметру: API-варианты исчезают. Добавьте «качество ≥ 8» — не останется ничего, и это честный ответ: требования противоречат друг другу. Если лидер меняется при сдвиге одного веса на единицу, решение хрупкое, и в ADR стоит записать, на какие веса оно опирается.

Тот же расчёт на Go (цена вызова API — APICost в том же файле,Java (цена вызова API — Tco.apiCost в том же классе, формула из модуля 12):

// Фрагмент Tco.java
    /**
     * Вариант реализации фичи. Все цифры — ваши параметры, а не справочник.
     *
     * @param perRequest  $ переменной части: токены API (0 для self-host)
     * @param unitMonthly $ в месяц за реплику self-host: GPU, хостинг (0 для API)
     * @param unitCap     запросов в месяц на реплику при целевой утилизации
     * @param minUnits    минимум реплик ради отказоустойчивости
     * @param opsFte      доля инженера: эксплуатация, on-call, обновления, evals, разметка
     * @param successRate доля успешно решённых задач на вашем eval-наборе
     */
    public record Option(String name, double perRequest, double unitMonthly, double unitCap, int minUnits,
                         double opsFte, double successRate) {
        public static Option api(String name, double perRequest, double opsFte, double successRate) {
            return new Option(name, perRequest, 0, 0, 0, opsFte, successRate);
        }

        public static Option selfHost(String name, double unitMonthly, double unitCap, int minUnits,
                                      double opsFte, double successRate) {
            return new Option(name, 0, unitMonthly, unitCap, minUnits, opsFte, successRate);
        }
    }

    /** Полная стоимость владения в месяц и её структура. */
    public record Result(double variable, double infra, double people, double total, int units,
                         double perRequest, double perSuccess) {}

    /**
     * TCO при объёме requests в месяц; fteMonthly — полная стоимость инженера в месяц.
     * Упрощение: evals и разметка сидят в opsFte. Выделите их отдельной строкой, если они заметны в бюджете.
     */
    public static Result monthly(Option o, double requests, double fteMonthly) {
        double variable = o.perRequest() * requests, people = o.opsFte() * fteMonthly, infra = 0;
        int units = 0;
        if (o.unitCap() > 0) {
            units = Math.max(o.minUnits(), (int) Math.ceil(requests / o.unitCap()));
            infra = units * o.unitMonthly();
        }
        double total = variable + infra + people, perRequest = 0, perSuccess = 0;
        if (requests > 0) {
            perRequest = total / requests;
            if (o.successRate() > 0) perSuccess = total / (requests * o.successRate());
        }
        return new Result(variable, infra, people, total, units, perRequest, perSuccess);
    }
}

// Option — вариант реализации фичи. Все цифры — ваши параметры, а не справочник.
type Option struct {
	Name        string
	PerRequest  float64 // $ переменной части: токены API (0 для self-host)
	UnitMonthly float64 // $ в месяц за реплику self-host: GPU, хостинг (0 для API)
	UnitCap     float64 // запросов в месяц на реплику при целевой утилизации
	MinUnits    int     // минимум реплик ради отказоустойчивости
	OpsFTE      float64 // доля инженера: эксплуатация, on-call, обновления, evals, разметка
	SuccessRate float64 // доля успешно решённых задач на вашем eval-наборе
}

// TCO — полная стоимость владения в месяц и её структура.
type TCO struct {
	Variable, Infra, People, Total float64
	Units                          int
	PerRequest, PerSuccess         float64
}

// MonthlyTCO считает TCO при объёме requests в месяц; fteMonthly — полная стоимость инженера в месяц.
// Упрощение: evals и разметка сидят в OpsFTE. Выделите их отдельной строкой, если они заметны в бюджете.
func MonthlyTCO(o Option, requests, fteMonthly float64) TCO {
	t := TCO{Variable: o.PerRequest * requests, People: o.OpsFTE * fteMonthly}
	if o.UnitCap > 0 {
		t.Units = max(o.MinUnits, int(math.Ceil(requests/o.UnitCap)))
		t.Infra = float64(t.Units) * o.UnitMonthly
	}
	t.Total = t.Variable + t.Infra + t.People
	if requests > 0 {
		t.PerRequest = t.Total / requests
		if o.SuccessRate > 0 {
			t.PerSuccess = t.Total / (requests * o.SuccessRate)
		}
	}
	return t
}

Как не проиграть на смене модели

Выбранная сегодня модель через год будет либо выведена из эксплуатации, либо проиграет новой. Выигрывает тот, кто меняет её за дни, а не за квартал.

• Тонкая абстракция на вашей стороне: бизнес-код зовёт Classify(ctx, ticket)classifier.classify(ticket), а не SDK; роутинг и fallback — в шлюзе (модуль 9).
• Промпт привязан к модели: версия — пара «промпт + модель + параметры» (модуль 3), миграция — новая версия промпта.
• Eval-гейт, независимый от вендора: новая модель проходит тот же golden set в CI (модуль 8), затем shadow-трафик и canary.
• Календарь вывода моделей и дата пересмотра в ADR: 60 дней уведомления хватает, только если гейт и абстракция уже есть.
• Записанный план выхода. Для финансовых организаций в ЕС это требование регламента DORA (Regulation (EU) 2022/2554, применяется с 17 января 2025 года): статья 28(8) — стратегии выхода для ИКТ-услуг, поддерживающих критичные или важные функции. Применимость определяет юрист; инженерный вывод — переход к другому поставщику должен быть проверенным сценарием.

SLO, error budget и on-call для недетерминированных систем

Термины из книги Google SRE. SLI — доля хороших событий: ответов без ошибки, быстрее порога, признанных судьёй верными. SLO — цель для SLI за скользящее окно, например 98% за 28 дней. Error budget — допустимая доля плохих событий, 1 − SLO. Бюджет превращает спор «релизить или чинить» в арифметику: бюджет есть — команда меняет систему, кончился — чинит надёжность. Техническая сторона (SLI по трейсам, burn-rate алерты в Prometheus) — в модуле 9 (SLO в продакшене), здесь — что из этого следует для команды.

Что считать плохим событием

У LLM-системы ответ может прийти за секунду с кодом 200 и быть неверным, поэтому SLI несколько (латентность — как обычно, по трейсам):

Пример: 50 000 ответов в сутки, SLO качества 98% за 28 дней — 1.4 млн ответов, бюджет 28 000 плохих. Burn rate — во сколько раз быстрее нормы сжигается бюджет: при 1% плохих он 0.5, при 2% — 1 (бюджет кончится в последний день), при 30% — 15 (меньше двух суток).

Алерты строят по скорости сжигания на двух окнах сразу. SRE Workbook рекомендует для 30-дневного окна: 2% бюджета за 1 час (burn rate 14.4, будить), 5% за 6 часов (6, будить), 10% за 3 дня (1, тикет); короткое окно (5 мин, 30 мин, 6 ч) подтверждает, что сжигание идёт сейчас, и гасит алерт после инцидента. Порог = доля бюджета × окно SLO ÷ длинное окно; для 28 дней — 13.44, 5.6 и 0.93.

Политика error budget

Бюджет без политики — просто график. Политику заранее подписывают продукт, разработка и дежурные. В примере из SRE Workbook: бюджет за четыре недели превышен — релизы, кроме исправлений P0 и безопасности, останавливаются до возвращения в SLO; инцидент съел больше 20% бюджета — постмортем хотя бы с одним действием P0; споры о расчёте решает CTO. Для AI-фичи релиз — любое изменение поведения: промпт, модель, параметры, индекс.

Политика как код — фрагмент examples/m13-senior/budget.go (там же FromSample:examples/java/m13-senior/…/Budget.java (там же Window.fromSample: перенос доли плохих по выборке судьи на весь трафик):

// Фрагмент Budget.java
/**
 * Правило multiwindow multi-burn-rate из Google SRE Workbook («Alerting on SLOs»):
 * за окно long сожжена доля budget бюджета, и сжигание всё ещё идёт на коротком окне shortW.
 *
 * @param budget доля бюджета всего окна SLO, например 0.02
 * @param page   true — будить дежурного, false — тикет в рабочее время
 */
public record Alert(String name, Duration longW, Duration shortW, double budget, boolean page) {}

/** Рекомендованные пороги SRE Workbook (таблица 5-8), от срочного к медленному. */
public static final List<Alert> DEFAULT_ALERTS = List.of(
        new Alert("page-fast", Duration.ofHours(1), Duration.ofMinutes(5), 0.02, true),
        new Alert("page-slow", Duration.ofHours(6), Duration.ofMinutes(30), 0.05, true),
        new Alert("ticket", Duration.ofHours(72), Duration.ofHours(6), 0.10, false));

/** События за последние d — обёртка над вашим Prometheus или ClickHouse. */
public interface Metrics extends Function<Duration, Window> {}

/**
 * Что говорит политика error budget прямо сейчас.
 *
 * @param budgetLeft доля оставшегося бюджета окна, бывает &lt; 0
 * @param fired      первый сработавший алерт, null — тихо
 * @param freeze     бюджет исчерпан: релизы промптов и моделей заморожены, кроме фиксов
 */
public record Status(double budgetLeft, Alert fired, boolean freeze) {}

/** Цель по доле хороших событий за скользящее окно, например 0.99 за 28 суток. */
public record Slo(double target, Duration period) {
    /** Во сколько раз быстрее нормы сжигается бюджет; 1 — ровно к концу окна. */
    public double burnRate(Window w) {
        return w.total() == 0 ? 0 : w.bad() / w.total() / (1 - target);
    }

    /** Доля бюджета → порог burn rate: 2% за 1 ч при окне 30 суток → 14.4. */
    public double threshold(Alert a) {
        return a.budget() * period.toNanos() / a.longW().toNanos();
    }

    /** Применяет алерты и политику заморозки к текущим метрикам. */
    public Status check(Metrics m, List<Alert> alerts) {
        double left = 1;
        Window w = m.apply(period);
        if (w.total() > 0) left = 1 - w.bad() / ((1 - target) * w.total());
        for (Alert a : alerts) {
            double th = threshold(a);
            if (burnRate(m.apply(a.longW())) >= th && burnRate(m.apply(a.shortW())) >= th) {
                return new Status(left, a, left <= 0);
            }
        }
        return new Status(left, null, left <= 0);
    }
}

// Alert — правило multiwindow multi-burn-rate из Google SRE Workbook («Alerting on SLOs»):
// за окно Long сожжена доля Budget бюджета, и сжигание всё ещё идёт на коротком окне Short.
type Alert struct {
	Name        string
	Long, Short time.Duration
	Budget      float64 // доля бюджета всего окна SLO, например 0.02
	Page        bool    // true — будить дежурного, false — тикет в рабочее время
}

// Threshold переводит долю бюджета в порог burn rate: 2% за 1 ч при окне 30 суток → 14.4.
func (s SLO) Threshold(a Alert) float64 { return a.Budget * float64(s.Period) / float64(a.Long) }

// DefaultAlerts — рекомендованные пороги SRE Workbook (таблица 5-8), от срочного к медленному.
var DefaultAlerts = []Alert{
	{"page-fast", time.Hour, 5 * time.Minute, 0.02, true},
	{"page-slow", 6 * time.Hour, 30 * time.Minute, 0.05, true},
	{"ticket", 72 * time.Hour, 6 * time.Hour, 0.10, false},
}

// Metrics отдаёт события за последние d — обёртка над вашим Prometheus или ClickHouse.
type Metrics func(d time.Duration) Window

// Status — что говорит политика error budget прямо сейчас.
type Status struct {
	BudgetLeft float64 // доля оставшегося бюджета окна, бывает < 0
	Fired      *Alert  // первый сработавший алерт, nil — тихо
	Freeze     bool    // бюджет исчерпан: релизы промптов и моделей заморожены, кроме фиксов
}

// Check применяет алерты и политику заморозки к текущим метрикам.
func (s SLO) Check(m Metrics, alerts []Alert) Status {
	st := Status{BudgetLeft: 1}
	if w := m(s.Period); w.Total > 0 {
		st.BudgetLeft = 1 - w.Bad/((1-s.Target)*w.Total)
	}
	st.Freeze = st.BudgetLeft <= 0
	for i, a := range alerts {
		th := s.Threshold(a)
		if s.BurnRate(m(a.Long)) >= th && s.BurnRate(m(a.Short)) >= th {
			st.Fired = &alerts[i]
			break
		}
	}
	return st
}

On-call и runbook

У дежурства по AI-фиче три особенности: сигнал о качестве приходит медленно и часто от людей; главный рычаг — откат версии промпта или модели в реестре; живой fallback — операторы с ограниченной ёмкостью. Runbook — до первого инцидента:

• Kill switch без согласований: дежурный выключает AI-фичу или инструмент сам, ночью, без звонка руководителю. Право записано в политике, иначе его не используют вовремя.
• Ёмкость людей — часть дизайна: «переводим на операторов» работает, только если поддержка заранее согласилась принять, скажем, +30% обращений на несколько часов.

Постмортем AI-инцидента

Постмортем — письменный разбор инцидента: влияние, сдерживание, причины и меры против повторения. Культура blameless из книги Google SRE: разбор ищет условия, в которых ошибка стала возможной, исходит из добросовестности участников и не обвиняет людей или команды. Это не «ничего не делаем»: результат — изменения в системе и процессе с владельцами и сроками. Если причина звучит как «инженер не проверил», настоящий вопрос — почему система позволила выкатить непроверенное.

Когда писать: видимый пользователям простой или деградация сверх порога, потеря данных, ручное вмешательство дежурного, слишком долгое устранение, инцидент, найденный людьми, а не мониторингом. Для AI-систем добавьте любой инцидент безопасности или PII, любое обязательство, данное системой от имени компании, и регрессию качества, которую первыми заметили пользователи.

Главное отличие AI-постмортема — обязательный вопрос «почему evals и гейты не поймали»: корневая причина чаще в пробеле набора или метрики, чем в строке кода.

# Постмортем: <короткое название инцидента>

Статус · SEV-N · начало и конец · авторы · blameless: ищем условия, а не виноватых.

## Кратко
3–5 предложений: что случилось, влияние, причина, что меняем.

## Влияние
Пользователи, диалоги, деньги, регуляторика. Как посчитано и с какой погрешностью.

## Таймлайн (UTC)
| Время | Событие | Источник (трейс, алерт, релиз) |
|---|---|---|

## Обнаружение
Как узнали, сколько прошло с начала, почему не раньше.

## Корневая причина и способствующие факторы

## Почему evals и гейты не поймали
Каких кейсов не было, какой проверки не было в CI, какая онлайн-метрика молчала.

## Что сработало и где повезло

## Действия
| Действие | Тип: предотвратить / обнаружить / смягчить | Владелец | Срок |
|---|---|---|---|
Обязательно: кейсы в golden set, гейт или метрика canary, guardrail, правка runbook.

Разбор: бот поддержки обещает компенсации

Кратко. Релиз support_reply@v12 вместе с переходом с Opus 5 на более новую и дешёвую Opus 5.5 привёл к тому, что бот обещал клиентам вернуть комиссии и зачислить компенсации, не имея на это полномочий. Заметили операторы; до дежурного сигнал дошёл через 31 час после выкатки на 100%, откатили через 22 минуты.

Влияние. ≈ 1 380 клиентов получили обещание денег, ≈ 940 обратились за выполнением; обещания до установленной суммы решили выполнить. Около 120 часов работы операторов.

Корневая причина. Система позволяла модели давать денежные обязательства текстом. Запрет существовал только как инструкция в промпте, и ни одна проверка не измеряла это свойство. Способствующие факторы: новая инструкция конфликтовала со старым запретом, и новая модель разрешала конфликт в пользу «помочь»; модель и промпт поменяли в одном релизе; у сигнала операторов не было пути к дежурному.

Почему evals не поймали.

• Golden set был одношаговым, а 78% обещаний случились после двух негативных реплик клиента.
• Проверка must_not_contain: ["компенсац"] искала подстроку, а модель писала «вернём комиссию» и «зачислим на счёт».
• Рубрика онлайн-судьи оценивала полезность, корректность и тон, но не «обязательства вне полномочий».
• Метрики canary улучшились: клиентам нравится, когда им обещают деньги. Прокси совпала по направлению с режимом отказа.
• Владелец политики поддержки не был ревьюером PR.

Сработало: откат флагом без деплоя; версия промпта в трейсах дала точный подсчёт влияния. Повезло: суммы были небольшими.

В действиях есть все три типа: предотвращение (кейсы, инструмент вместо текста), обнаружение (судья, метрика, кнопка) и смягчение (guardrail). Постмортем только с «улучшить промпт» не дошёл до системных причин: следующая версия найдёт новый способ пообещать.

Встреча: ведущий — не участник инцидента; таймлайн по трейсам, потом причины, потом действия; язык «система позволила», а не «Петя выкатил»; через две недели — проверка действий.

Коммуникация: метрики evals на языке бизнеса

Руководителю нужны не κ и p95 TTFT, а ответы на четыре вопроса: сколько задач система решает, сколько это стоит, чем рискуем и что даст следующее вложение.

Правила: всегда знаменатель, примеры ошибок, деньги рядом с риском, диапазон там, где есть неопределённость. И точность на golden set — не доля решённых обращений: между ними вопросы, на которые бот не отвечает вовсе, и клиенты, не поверившие правильному ответу.

Договориться о метрике до разработки

Самый дорогой провал — запуск, после которого никто не может сказать, удался ли он. Метрика успеха согласуется до первой строки кода, как контракт. Пример для бота PayFlow (вымышленный):

Контракт подписывают продукт, техлид и руководитель операторов. Kill-критерий делает проект безопасным для заказчика: известна максимальная цена неудачи. Guardrail-метрики защищают от оптимизации любой ценой: бот, обещающий компенсации, отлично закрывает обращения.

Схема показывает маржинальную цену улучшений: если ошибка дорогая, −0.1 п.п. ошибок ценнее +1 п.п. автоматизации, и роадмап должен это отражать. На планировании это сильнее, чем «качество стало выше».

Как сказать «здесь LLM не нужна»

Иногда лучший вклад сеньора — убедить не делать AI-часть. Когда стоит предложить альтернативу:

Как сказать: не «нет», а «вот что даст результат быстрее и дешевле», с цифрами и гибридом. «Правила по 30 шаблонам закрывают 80% таких обращений за неделю работы и бесплатно в эксплуатации. Для оставшихся 20% LLM имеет смысл — вернёмся к ней, когда соберём 300 размеченных примеров для evals». Тот же вопрос в формате собеседования — в модуле 14 (вопросы с собеседований).

Команда: менторство, ревью промптов и evals, стандарты

Сеньор масштабируется через других: стандарты, которые не нужно помнить, ревью, которое учит, и людей, которые через год пишут ADR без него. В AI-команде к обычным стандартам добавляются промпты, eval-наборы и данные — артефакты, которые по привычке живут вне процессов.

Ревью PR с изменением промпта

• Зачем: ссылка на кейсы или инцидент, которые чинит изменение. «Улучшил промпт» без примеров не ревьюится.
• Дифф evals против baseline по сегментам, критичные кейсы 100%, атаки без новых успешных (модуль 7). Рост в одной категории часто сопровождается падением в другой.
• Новые кейсы на чинимую проблему, которые падают на старой версии промпта.
• Стоимость и латентность: токены промпта, $ за запрос, кэшируемый префикс.
• Скрытые части промпта: описания инструментов, схема вывода, параметры модели; few-shot без реальных PII.
• Одна переменная за раз: не меняются вместе промпт и модель или промпт и eval-набор. Если из набора тихо удалены «неудобные» кейсы, гейт проходит, а система не стала лучше; изменения набора — отдельный PR. Изменился судья — перекалибровка до мержа (модуль 8).

Менторство и онбординг

• Трейсы вместе. Error analysis (модуль 8) учат вживую: час над 50 реальными ответами с вопросом «почему плохо и какой тест это поймает» даёт больше статьи.
• Задачи с метрикой: «подними recall@5 с 0.71 до 0.80 на наборе v3» вместо «улучши поиск». Первое ревью задачи мидла — как он будет мерить результат.
• Владение целиком: фича, eval-набор, SLO и дежурство у одного человека или пары. Раз в квартал — ADR или постмортем под ревью сеньора: так растут до сеньоров.
• Учите вопросам: «как мы узнаем, что это сломалось?», «что будет при ×10?», «что сделает скомпрометированная модель с этим инструментом?».
• Онбординг за месяц: в первые дни — окружение и evals одной командой (не запускается — первый PR в документацию), 100 трейсов с наставником, ADR и постмортемы; потом маленькое изменение промпта через весь путь до прода, тень дежурного и 10 новых кейсов в golden set.

Coding agents как командная дисциплина

Инструментальная часть — AGENTS.md и CLAUDE.md, режимы разрешений, sandbox, хуки, рабочий цикл «план → тесты → реализация → ревью диффа» — в модуле 4 (coding agents). Здесь — правила для команды, где агенты пишут заметную часть кода. Без них получается либо запрет, который тихо нарушают, либо «каждый как хочет» и код, который через полгода никто не понимает.

Узкие права нужны ещё и потому, что агент читает недоверенный контент — issues, README зависимостей, чужой код. Это непрямая инъекция (модуль 7), и lethal trifecta собирается легко: секреты в окружении, недоверенный текст, сеть. Разрывать её проще всего на секретах и сети.

Что мерить. Не «долю кода от агента» — она поощряет объём. Отчёт DORA 2024 связал рост использования AI с ростом индивидуальной продуктивности, но со снижением стабильности и пропускной способности поставки. Смотрите на метрики поставки: время до прода, долю изменений с инцидентами, время восстановления, размер PR. Выросли PR и откаты — правила ужесточают, даже если все довольны.

Практика

Самопроверка

Вопросы с собеседований

Тренировка senior-вопросов — модуль 14.

Источники

• Michael Nygard — Documenting Architecture Decisions (2011, исходный формат ADR)
• Martin Fowler — Architecture Decision Record (хранение в репозитории, статусы, замена вместо правки) и adr.github.io (шаблоны и инструменты)
• Malte Ubl — Design Docs at Google
• Google SRE Book — Service Level Objectives и Embracing Risk (SLI, SLO, error budget)
• Google SRE Workbook — Implementing SLOs, Alerting on SLOs (пороги burn rate) и Example Error Budget Policy
• Google SRE Book — Postmortem Culture и пример постмортема
• PagerDuty — Incident Response (роли и процесс инцидента)
• Chip Huyen — AI Engineering (O'Reilly, 2025) (гл. 4: выбор модели, build vs buy; гл. 10: архитектура и фидбек)
• Hamel Husain — Your AI Product Needs Evals
• Anthropic — Model deprecations (жизненный цикл моделей, сроки уведомления)
• Regulation (EU) 2022/2554 (DORA) (ст. 28: риски ИКТ-поставщиков, стратегии выхода)
• Moffatt v. Air Canada, 2024 BCCRT 149 (ответственность компании за слова чат-бота)
• Claude Code — How Claude remembers your project (CLAUDE.md как контекст, а не принуждение; чтение AGENTS.md) и agents.md (открытый формат инструкций для агентов)
• DORA — Accelerate State of DevOps Report 2024 (влияние AI на поставку)
• Google Engineering Practices — Code Review