AI Engineering Course

Workflow и наблюдаемость

Лекция 5

Фокус: дисциплина и анализ работы агента

Содержание

1. Зачем процесс и наблюдение

Ловушки доверия

2. Столп 1 · Дисциплина

Spec, plan, TDD, verification, готовые наборы

3. Столп 2 · Наблюдаемость

Loop, трейсы, ревью, CI

4. Поддержка в инструментах

Claude Code, Kilo, OpenCode

5. Подводные камни

6 типичных ловушек

6. Итоги и практика

Чеклист и задания

Часть 1

Зачем процесс и наблюдение

Инструментария из лекций 1-4 достаточно, чтобы агент мог. Недостаточно — чтобы делал правильно.

Знакомая история

Дал задачу агенту...

Он подумал, поправил несколько файлов, написал «всё готово, тесты проходят». Закоммитил. Через день — открыл код и увидел: тесты, оказывается, никто не запускал; один из файлов агент даже не открыл; в другом — лишний try/except, который маскирует баг.

Это симптом отсутствующего процесса. Лечится структурой работы, а не промптом.

Две ловушки доверия

Ложная продуктивность

Агент пишет много, но не то. Симптом: «ещё чуть-чуть, и готово». Корень: нет проверяемых критериев — агент сам додумывает рамки и каждый раз додумывает иначе.

Ложное «готово»

Уверенные слова без доказательств. Нет запуска тестов, нет вывода линта, нет сборки. Корень: LLM оптимизирована быть уверенной, а не верной. Заявление «готово» — естественный завершающий ход, а не результат проверки.

Карта лекции

Столп 1 · Дисциплина

Каждая задача проходит через читаемые артефакты: спека, план, тесты, итог. Чекпоинты, в которых можно остановиться, прочитать и одобрить — или развернуть.

Столп 2 · Наблюдаемость

Видеть, что реально сделал агент: какие tools вызывал, в каком порядке, с каким результатом. Читать трейс и диф. CI как финальный фильтр.

Дисциплина создаёт правила. Наблюдаемость проверяет, что правила выполнены.

Часть 2

Столп 1 · Дисциплина процесса

Каждая задача проходит через читаемые артефакты.

Цикл одной задачи

Шаг	Артефакт	Что проверяем
Brainstorm	набор уточнений и ответов	Понял ли агент намерение
Spec	`specs/<date>-<topic>.md`	Согласны ли с тем, что делаем
Plan	`plans/<date>-<topic>.md`	Согласны ли с тем, как делаем
Implement	код + тесты + коммиты	Соответствует ли плану
Review	отчёт / диф	Что сломалось, что пропущено

Артефакты должны существовать на диске — не «в чате», не «в голове агента». Файл, переживший перезапуск сессии — единственный надёжный носитель решения.

Spec-first: чтобы агент не «дорисовал»

Чеклист спеки

Цель — одно предложение, что мы решаем
Критерии приёмки — проверяемые утверждения, не общие слова
Out-of-scope — что не делаем (явный список)
Ограничения — производительность, совместимость, зависимости

Анти-паттерн

«добавь валидацию форм» → агент обвешает всё, что похоже на форму. Результат: 50 проверок, половина не нужна, половина не работает.

Лучше

«Валидация поля email и пароля на форме /login. Критерии: email — RFC 5322; пароль — минимум 8 символов и одна цифра. Не трогаем форму регистрации.»

Plan-first: разбиение перед кодом

План = последовательность маленьких проверяемых шагов

Пример: «добавить кэширование результатов API»

Написать тест: повторный вызов с тем же аргументом не идёт в сеть
Запустить тест → красный
Добавить in-memory словарь в модуль api_client
Обернуть fetch_user(id) в lookup по словарю
Запустить тест → зелёный
Добавить тест на TTL: после time.sleep(ttl+1) повторный вызов снова идёт в сеть
Реализовать TTL через timestamp в значении словаря
Запустить оба теста → зелёные
Коммит

Девять шагов вместо одного «сделай кэширование». Каждый шаг занимает минуты и оставляет проверяемое состояние.

TDD с агентом

Red

Агент пишет тест. Тест падает в реальном выводе инструмента.

Green

Агент пишет минимальный код. Тест проходит. Вывод видно в трейсе.

Refactor

Чистим код. Тесты остаются зелёными.

Красная фаза должна быть в выводе. Тест «всегда зелёный с первого запуска» → подогнан под код, фальшивый TDD. Test-функции, которые проверяют «что код вернул то, что код вернул» — признак подгонки.

Проверка перед завершением

Нет вывода — нет готово. Прежде чем сказать «готово», агент должен показать доказательства: вывод тестов, линта, билда. Текстом, из реального вывода tool'а.

Машинная реализация правила:

Claude Code: Stop / PostToolUse hooks — проверяет наличие свежего зелёного build-log'а; если нет — блокирует завершение
OpenCode: плагин на событие session.idle, требует артефакт перед закрытием
Kilo Code: custom MCP tool verify_completion, который агент обязан вызывать

Дисциплина не должна держаться только на доброй воле модели — она поддерживается инфраструктурой инструмента.

Mini-case: до и после дисциплины

Без дисциплины

Задача: «отрефактори обработчик загрузки файлов, чтобы не падал на больших». Одна итерация, агент переписал функцию, добавил streaming, сказал «готово».

Через день: тестов на эту функцию не было. Streaming реализован неправильно. Большие файлы продолжают падать.

С дисциплиной

Brainstorm → «Что значит "большие"? Файлы > 100MB. OOM при 50MB.»

Spec → Цель: не падать до 1GB. Критерии: 500MB за < 60s без OOM.

Plan → 6 шагов. Сначала failing test с моком на streaming.

Implement → TDD-цикл по плану. Каждый шаг — коммит.

Review → Проверка на реальном файле 500MB.

Одинаковые токены. Разный результат.

Готовые наборы скиллов

`superpowers` — open-source плагин

brainstorming → спека до кода
writing-plans → атомарные шаги
test-driven-development → красная фаза в выводе
verification-before-completion → нет вывода — нет готово
subagent-driven-development → делегирование + ревью

Поддерживаемые инструменты

Claude Code — marketplace
Cursor — marketplace
OpenCode — строка в opencode.json
Codex / Gemini CLI — ручной install
Kilo Code — нет пакета, собирай сам через .kilocodemodes или .kilo/agents/

AGENTS.md — tool-agnostic базис для смешанных команд.

Часть 3

Столп 2 · Наблюдаемость

Видеть, что реально сделал агент. Читать трейс и диф. CI как финальный фильтр.

Что такое agent loop и зачем его читать

Цикл агента

think

→

tool call

→

observe

→

think…

В нормальной работе loop спрятан за UI. Когда что-то идёт не так — нужно раскатать его как лог и прочитать глазами.

Live

Текущее сообщение агента, текущие вызовы инструментов, их вывод. Для остановки в реальном времени.

Session history

Последняя сессия целиком. Открываешь после завершения и проходишь по шагам.

Длинная история

Предыдущие сессии, пересечения между ними, эволюция решений. Для аудита и повторяющихся проблем.

Что искать в трейсе (чеклист)

Tool calls

Правильные ли инструменты, в правильном ли порядке, с правильными ли аргументами? Часто: агент вызвал Read с offset, который пропустил нужный фрагмент.

Повторения и зацикливания

Одно и то же действие дважды — почти всегда симптом. Либо зацикливание (A→B→A), либо потерянный контекст.

Молчаливые упрощения

Ожидал чтение всего файла — агент прочитал 50 строк. Ожидал все тесты — запущен один. Видны только в трейсе.

Признаки путаницы

Агент говорит про файл X, правит Y. Ссылается на несуществующую функцию. Имя класса меняется от шага к шагу.

Всплески токенов

Резкий рост потребления токенов в одной секции — агент зашёл в болото, контекст забит мусором.

Инструменты наблюдаемости

Claude Code

/statusline и кастомные скрипты — индикатор состояния
hooks (PreToolUse / PostToolUse) → лог каждого вызова в jsonl
Session history в ~/.claude/projects/ — plain jsonl, читается грепом
output-styles для кастомного отображения

Kilo Code

История агентов (code/plan/ask/debug) — VS Code panel
Логи через VS Code output panel
Нативных hook-based трассировок нет
Обходной путь: MCP tool, пишущий аргументы и результаты в лог-файл

OpenCode

Плагины с событиями tool.execute.before / tool.execute.after
Пишем свой логгер на TypeScript
Session state доступен программно через SDK

Внешние платформы

Langfuse / LangSmith — трейсы централизованно поверх API
Полноценный дашборд по проекту и команде
Командная аналитика: токены, типичные ошибки

Базовый минимум: завести лог-файл tool calls. Без него остальные практики слепые.

Критическое ревью диффа

Ревью кода агента ≠ обычное ревью. Свои риски.

Лишнее

Дорисовки «на будущее»: лишние аргументы, fallback'и для невозможных случаев, try/except: pass «на всякий случай».

Хардкод

Магические числа, строки вроде "example.com" или "test-user", которые выглядят «для примера», но остались в коммите.

Мёртвый код

Неиспользуемые импорты, закомментированные блоки «на случай отката», переменные, которые присваиваются, но не читаются.

Ложное «готово»

Тесты помечены @skip / xfail. assert True вместо проверки. «Тесты обновлены» без объяснения, почему поведение изменилось.

Туманные коммит-сообщения

«fix stuff», «improvements», «update» — сигнал, что агент сам не понимает, что сделал.

Регрессии

Агент «починил» одно и сломал соседнее. Запусти полный тестран сам — не доверяй фразе «все тесты проходят».

CI/CD как независимый верификатор

Не доверяй success-сообщениям агента — доверяй зелёному pipeline'у на отдельной машине. Локально агент может «забыть» запустить часть тестов, использовать кешированный билд. CI этого не умеет.

Что должно быть в pipeline

Полный test run — не выборочный
Lint и type-check — отдельной стадией
Build / type-check без эмита — tsc --noEmit, mypy, cargo check
Diff-coverage — упал ли coverage на новых строках?

Принцип двух наблюдателей

Агент и CI — независимы. Агент может убедить себя (и тебя), что всё работает. CI запускает реальные тесты в чистом окружении.

Verification-before-completion — локально, для скорости. CI — глобально, для финальной гарантии. Они не заменяют друг друга.

CI: защита от анти-паттернов

Запретить `--no-verify`

Server-side hook или branch protection. Агент обходит упавшие хуки именно этим флагом — в момент, когда сдаётся.

Skipped тесты — отдельный шаг

Pipeline падает, если в diff появились новые skip / xfail / it.skip. Без этого «зелёный CI» получают, выключая тест.

Branch protection как контракт

Merge только при зелёном CI — даже у тебя как автора. Если CI упал — это факт, а не «флаки». Сначала разбираемся, потом ругаем CI.

Анти-паттерн: агент работает в worktree, локально зелёное, прямой push в master. Через час кто-то клонирует — ничего не работает: забытая зависимость, кэш, переменная окружения. CI поймал бы сразу.

Mini-case: чтение реального трейса

[14:02:11] tool: Read("src/auth/jwt.py", limit=50)
[14:02:11] tool result: <первые 50 строк>
[14:02:14] message: "Я вижу функцию verify_token. Изменю её, чтобы..."
[14:02:18] tool: Edit("src/auth/jwt.py", old="def verify_token...", new="def verify_token...")
[14:02:18] tool result: edit failed — old_string not unique
[14:02:21] tool: Edit("src/auth/jwt.py", old="def verify_token", new="def verify_token") (с другим контекстом)
[14:02:21] tool result: ok
[14:02:25] message: "Готово, функция исправлена"

Шаг 1: Read(limit=50)

Файл из 200 строк. Агент мог не увидеть второго определения verify_token ниже.

Шаг 4: Edit failed — old_string not unique

Точка невозврата. Сигнал: «в файле есть похожий блок, я его не учёл». Надо остановиться и перечитать файл целиком.

Шаг 5: подбор контекста

Вместо перечитывания — агент подобрал новый контекст для обхода. Мог попасть не в ту функцию.

Шаг 6: «Готово» без verification

Где запуск тестов? Где доказательства? «Готово» — завершающий ход, а не результат проверки.

Часть 4

Поддержка в инструментах

Одни и те же практики реализованы по-разному. Где-то — полноценная поддержка, где-то — обходные пути.

Сводная таблица

Практика	Claude Code	Kilo Code	OpenCode
Plan mode (отделение плана от impl)	Нативный `EnterPlanMode` / `ExitPlanMode`	`plan` agent (built-in)	Через системный промпт агента
Skills / методология как код	`~/.claude/skills/`, `Skill` tool	Custom agents (`.kilocodemodes` / `.kilo/agents/`)	Agents в `opencode.json`
Чекпоинты / approval gates	Plan approval, `AskUserQuestion`	Подтверждение шагов между агентами	Approval prompts через плагин
Verification-before-completion	`Stop` / `PostToolUse` hooks	Эмуляция через правила агента + custom MCP tool	Плагины с событиями
Statusline / live observability	`/statusline`, кастомные скрипты	VS Code output panel	Plugin events
Session history / трейсы	`~/.claude/projects/` (jsonl)	VS Code logs	Программно через session API
Логирование tool calls	Hook → файл	Custom MCP tool-логгер	Plugin event handler
Output styles	`output-styles`	Нет нативного	Через плагины

Что выбрать под практику

«Хочу строгий процесс с гарантиями»

→ Claude Code

Нативные hooks + plan mode + skills — самый прямой путь к verification-before-completion.

«Хочу гибкий tooling, готов писать TS»

→ OpenCode плагины

Выше порог входа, зато всё можно дописать самим.

«Хочу VS Code-интеграцию и визуальную панель агентов»

→ Kilo Code

Native subagents (code/plan/ask/debug) + VS Code UI. Для строгости нужны workaround'ы (правила агента + custom MCP tools).

Часть 5

Подводные камни

Дисциплина и наблюдаемость снимают много рисков, но не все. Шесть типичных ловушек.

Театр процесса + Фальшивый TDD

Театр процесса (cargo cult)

Проблема: Спека и план написаны «под уже задуманный код». Дисциплина превращается в ритуал, а не контракт.

Симптом: Реализация отличается от плана; спека написана общими словами без проверяемых критериев.

Решение: Критерии приёмки — проверяемые утверждения с цифрами. Спека без цифр — не спека.

Фальшивый TDD

Проблема: Агент пишет тест и реализацию одновременно; тест подгоняется под уже задуманный код.

Симптом: Тесты всегда зелёные с первого запуска; тест проверяет «что функция вернула то, что вернула».

Решение: Требовать красную фазу в явном виде — упавший тест в реальном выводе, затем код.

Ложное «готово» + Слепое доверие трейсу

Ложное «готово» без доказательств

Проблема: Агент пишет «всё работает», не запустив проверки.

Симптом: В ответе нет вывода тестов / линта / билда — только текстовые утверждения.

Решение: Правило «нет вывода — нет готово». Stop / PostToolUse hooks локально; CI как финальный фильтр глобально.

Слепое доверие трейсу

Проблема: Трейс показывает, что агент «вызвал тесты», — но ты не проверил, какие именно и с каким результатом.

Симптом: В логе видно run_tests, в сообщении — «tests passed». На CI — красно.

Решение: Читать не только что вызвано, но и вывод tool'а. CI как независимый верификатор.

Паралич планирования + Забывание контекста

Паралич планирования

Проблема: Обратная крайность — на каждое чихание полная цепочка spec → plan → TDD → review. Накладные расходы больше пользы.

Симптом: Для задачи «переименовать переменную» агент создаёт три документа и ждёт одобрения после каждого.

Решение: Правило оценки масштаба: spec/plan только для нетривиальных задач (>1 файл, >1 шаг). Тривиальное — делать сразу.

Молчаливое забывание контекста

Проблема: Новая сессия не знает, что было в предыдущей; агент переоткрывает уже решённые вопросы.

Симптом: Агент во второй сессии переписывает уже одобренное. «А почему мы не используем X?» — потому что решили в прошлой сессии.

Решение: Артефакты передачи контекста на диске: план и спека в репо, осмысленные коммиты, AGENTS.md / CLAUDE.md как инструкция для будущих сессий.

Часть 6

Итоги и практика

Главные выводы лекции и практические задания.

Ключевые выводы

1. Процесс обязателен

Без процесса агент производит правдоподобный мусор. Дисциплина превращает скорость в результат.

2. Артефакты — чекпоинты доверия

Spec → Plan → Implement → Review: каждый шаг производит читаемый файл, который можно одобрить или развернуть.

3. TDD обязателен

Тест — единственный верификатор, который не подкупается словами. Красная фаза должна быть в выводе.

4. «Готово» без доказательств — не готово

Verification локально + CI глобально. Они не заменяют друг друга.

5. Читать трейс = читать диф

Tool calls, повторения, молчаливые упрощения, всплески токенов — всё это сигналы, которые надо уметь видеть.

6. Ревью агентского кода ≠ обычное ревью

Свои анти-паттерны: лишнее, хардкод, фальшивые тесты, туманные коммиты.

Практическое задание

Задание 1 — Дисциплина

Возьми небольшую фичу (1-2 файла). Прогони brainstorm → spec → plan → implement → review. Сохрани артефакты (spec.md, plan.md). Покажи минимум один полный TDD-цикл: red → code → green.

Задание 2 — Наблюдаемость

Настрой трейс tool calls в своём инструменте. Найди два случая, где агент свернул не туда.

Claude Code: PostToolUse hook → ~/.claude/agent-trace.jsonl (время, инструмент, успех/ошибка). Бонус: индикатор ошибки в statusline.
OpenCode: плагин на tool.execute.before / tool.execute.after.
Kilo Code: custom MCP tool log_action + правило в .kilocodemodes (или в .kilo/agents/logger.md), обязывающее вызывать его перед Edit.

Дальше

Лекция 6

Context Engineering — токенизация, контекстное окно, стратегии управления контекстом и memory-системы.

Слайды · Лекция 1 Слайды · Лекция 2 Слайды · Лекция 3 Слайды · Лекция 4 Слайды · Лекция 6 Главная

Workflow и наблюдаемость

Содержание

1. Зачем процесс и наблюдение

2. Столп 1 · Дисциплина

3. Столп 2 · Наблюдаемость

4. Поддержка в инструментах

5. Подводные камни

6. Итоги и практика

Зачем процесс и наблюдение

Знакомая история

Дал задачу агенту...

Две ловушки доверия

Ложная продуктивность

Ложное «готово»

Карта лекции

Столп 1 · Дисциплина

Столп 2 · Наблюдаемость

Столп 1 · Дисциплина процесса

Цикл одной задачи

Spec-first: чтобы агент не «дорисовал»

Чеклист спеки

Анти-паттерн

Лучше

Plan-first: разбиение перед кодом

Пример: «добавить кэширование результатов API»

TDD с агентом

Red

Green

Refactor

Проверка перед завершением

Mini-case: до и после дисциплины

Без дисциплины

С дисциплиной

Готовые наборы скиллов

superpowers — open-source плагин

Поддерживаемые инструменты

Столп 2 · Наблюдаемость

Что такое agent loop и зачем его читать

Цикл агента

think

tool call

observe

think…

Live

Session history

Длинная история

Что искать в трейсе (чеклист)

Tool calls

Повторения и зацикливания

Молчаливые упрощения

Признаки путаницы

Всплески токенов

Инструменты наблюдаемости

Claude Code

Kilo Code

OpenCode

Внешние платформы

Критическое ревью диффа

Лишнее

Хардкод

Мёртвый код

Ложное «готово»

Туманные коммит-сообщения

Регрессии

CI/CD как независимый верификатор

Что должно быть в pipeline

Принцип двух наблюдателей

CI: защита от анти-паттернов

Запретить --no-verify

Skipped тесты — отдельный шаг

Branch protection как контракт

Mini-case: чтение реального трейса

Шаг 1: Read(limit=50)

Шаг 4: Edit failed — old_string not unique

Шаг 5: подбор контекста

Шаг 6: «Готово» без verification

Поддержка в инструментах

Сводная таблица

Что выбрать под практику

«Хочу строгий процесс с гарантиями»

`superpowers` — open-source плагин

Запретить `--no-verify`