Зачем это нужно
AI способен написать много кода за минуты. Но скорость генерации кода сама по себе не означает, что результат соответствует требованиям, архитектуре и реальному состоянию проекта.
Первая ошибка новичка в AI-разработке - думать, что LLM "понимает проект" примерно так же, как разработчик, который несколько месяцев работал в команде. На практике модель работает иначе: она получает ограниченный контекст, генерирует наиболее вероятное продолжение и может вызывать инструменты, если agent runtime дает ей такую возможность.
Для управляемой разработки нужно понимать не внутреннюю математику transformer'ов, а инженерные последствия:
- модель не имеет гарантированной памяти о проекте;
- большой prompt не равен хорошей specification;
- уверенный ответ не является доказательством;
- код, написанный AI, нужно проверять внешними системами;
- чем больше задача, тем выше риск drift.
Главная цель урока - дать ментальную модель, которая позволит дальше строить controlled agent workflow: specification, context, task decomposition, tests, review и verification.
Основная идея
LLM - это модель, которая получает последовательность tokens и генерирует следующую последовательность tokens на основе своего обучения и текущего контекста.
Для разработчика важны три свойства:
- Модель видит только то, что находится в ее текущем context window.
- Модель генерирует вероятностный ответ, а не доказательство истины.
- Модель не выполняет действия сама: действия выполняются инструментами, терминалом, файловой системой, браузером, CI и другими внешними системами.
Из этого следует главный практический вывод:
LLM output
!=
verified result
Если agent сказал "я исправил баг" или "тесты проходят", это еще не evidence. Evidence появляется, когда есть конкретная команда, ее output, exit code, diff и проверка acceptance criteria.
Ключевые термины
| Термин | Значение для курса |
|---|---|
| Token | Единица текста, с которой работает модель. Это может быть слово, часть слова, символ или фрагмент кода. |
| Context window | Ограниченный объем tokens, который модель может учитывать в одном запросе или agent run. |
| Prompt | Текстовая инструкция или входные данные, которые попадают в context. |
| System instructions | Более высокоуровневые инструкции, которые задают поведение агента или приложения. |
| Hallucination | Уверенно выглядящий ответ, который не подтвержден источниками, кодом, инструментами или проверкой. |
| Probabilistic generation | Генерация ответа как вероятного продолжения контекста, а не как строгого логического вывода. |
| Tool calling | Механизм, при котором модель выбирает инструмент, а внешняя система выполняет действие и возвращает результат. |
| Verification | Внешняя проверка результата: tests, typecheck, lint, build, review, CI, acceptance checklist. |
| Drift | Постепенное отклонение агента от исходной цели, требований, архитектуры или allowed scope. |
Как LLM получает контекст
Модель не открывает репозиторий "мысленно". Она получает подготовленный пакет данных: инструкции, сообщения, фрагменты файлов, результаты поиска, вывод команд и ответы инструментов.
Типичный context для coding agent выглядит так:
System instructions
+
Project rules
+
User task
+
Selected files
+
Tool outputs
+
Previous messages in the run
Если важного файла нет в context, модель может не знать о нем. Если в context лежит устаревшая информация, модель может использовать ее как актуальную. Если в context есть противоречивые инструкции, модель может выбрать одну из них не так, как ожидает разработчик.
Для AI Agent Development это означает: качество результата начинается не с "умности" модели, а с качества контекста.
Обратите внимание: инструмент выполняется не внутри LLM. Модель выбирает или предлагает действие, а agent runtime вызывает реальный tool и возвращает результат обратно в контекст.
Почему context window ограничивает надежность
Context window кажется простым ограничением по размеру, но для разработки важнее несколько практических последствий.
Во-первых, если задача слишком большая, в context приходится положить слишком много всего: требования, архитектуру, существующий код, тесты, историю обсуждения, ошибки команд. Чем больше информации, тем труднее удержать фокус на текущем проверяемом результате.
Во-вторых, длинный context часто содержит шум. Модель может уделить внимание второстепенной детали и пропустить важное ограничение.
В-третьих, часть контекста может быть неактуальной. Например, в начале сессии было сказано "не менять frontend", а позже агент увидел похожий компонент и решил, что нужно поправить UI. Если нет жесткого allowed scope и verification, такой drift легко пропустить.
Плохая стратегия:
Дать агенту 50 страниц контекста
↓
Попросить сделать большую фичу
↓
Надеяться, что он все удержит
Более надежная стратегия:
Specification
↓
Small task
↓
Relevant files only
↓
Test or acceptance check
↓
Review diff
Именно поэтому дальше в курсе появятся spec.md, design.md, tasks.md, project rules, skills, tools, tests и CI.
Почему модель может ошибаться
LLM не обязана "врать", чтобы ошибиться. Ей достаточно продолжить текст правдоподобно, но без проверки реального мира.
Типовые причины ошибок:
| Причина | Как выглядит в разработке | Как снижать риск |
|---|---|---|
| Недостаточный контекст | Агент реализует новый helper, хотя в проекте уже есть готовый | Сначала inspect existing code |
| Устаревший контекст | Агент следует старому API contract | Хранить source of truth в файлах, а не в chat history |
| Противоречивые инструкции | Агент одновременно пытается "не менять API" и "добавить поле в response" | Clarification phase до кода |
| Вероятностная генерация | Агент придумывает несуществующий config option | Проверять docs, types, tests, build |
| Слишком большой scope | Агент чинит одно и ломает другое | One task - one verifiable result |
| Нет внешней проверки | Агент сообщает "тесты должны проходить" | Запускать реальные команды |
Ключевая мысль: ошибка LLM часто выглядит не как грубая нелепость, а как уверенное, аккуратно оформленное, но неподтвержденное решение.
Hallucination в coding tasks
В обычном chat hallucination может выглядеть как выдуманная ссылка или неверный факт. В coding agent workflow она часто тоньше.
Примеры:
- агент ссылается на функцию, которой нет в кодовой базе;
- использует dependency, которая не установлена;
- предполагает структуру таблицы без проверки schema;
- пишет тест под поведение, которого нет в specification;
- говорит, что "линтер проходит", хотя команду не запускал;
- меняет API contract, потому что "так обычно делают".
Важно различать:
| Утверждение | Это evidence? | Почему |
|---|---|---|
| "Я думаю, тесты должны проходить" | Нет | Это прогноз модели |
"Я запустил pytest, все прошло" без вывода |
Слабое | Нет проверяемого output |
pytest tests/auth -q вернул exit code 0 |
Да | Есть внешняя проверка |
| CI job green на pull request | Да | Есть независимая автоматическая проверка |
| Reviewer проверил diff на соответствие AC | Да | Есть отдельная проверка результата |
Для курса мы будем считать завершенной только ту работу, у которой есть evidence.
Знание, рассуждение и выполнение
В AI-разработке часто смешивают три разных уровня.
Знание
Модель может знать общий паттерн:
Password reset обычно использует одноразовый token с ограниченным сроком действия.
Это полезно, но не говорит, как устроен конкретный проект.
Рассуждение
Модель может предложить план:
Добавить ResetTokenRepository, ResetPasswordService и endpoint POST /reset-password.
Это может быть хорошим направлением, но план еще не является изменением кода.
Выполнение
Выполнение начинается, когда агент читает файлы, редактирует код, запускает тесты и получает результаты.
Read files
↓
Edit code
↓
Run tests
↓
Observe output
↓
Review diff
Главная ошибка: принимать рассуждение за выполнение. Агент может идеально описать, что нужно сделать, но не сделать это в репозитории или сделать с ошибками.
Tool calling не делает модель безошибочной
Tools повышают надежность, потому что агент может обращаться к внешним источникам и выполнять действия. Но tool calling не отменяет необходимость контроля.
Пример:
Модель: Нужно проверить tests.
Tool call: run_tests("tests/auth")
Tool output: 3 failed, 12 passed
Модель: Нужно исправить причину failures.
Здесь tool дает реальное наблюдение. Но модель все равно может:
- неправильно интерпретировать output;
- исправить не root cause, а симптом;
- изменить лишние файлы;
- повторять одну и ту же попытку;
- объявить задачу завершенной после частичного успеха.
Поэтому tool output должен быть связан с process:
Tool output
↓
Analysis
↓
Minimal fix
↓
Re-run verification
↓
Diff review
↓
Acceptance criteria status
Инструменты нужны не для "магии", а для observable feedback loop.
Отсутствие гарантированной памяти
У модели нет надежной проектной памяти в человеческом смысле. Даже если agent помнит часть истории сессии, это не должно быть source of truth.
Плохо:
"Мы же вчера обсуждали, что reset token действует 15 минут.
Пусть агент сам вспомнит."
Хорошо:
specs/password-reset/spec.md
REQ-AUTH-003:
Reset token expires 15 minutes after creation.
В управляемой разработке важные решения должны жить в файлах:
spec.md- observable behavior;design.md- техническое устройство;ADR- архитектурные решения;tasks.md- маленькие проверяемые задачи;- tests - исполняемые проверки;
- project rules - короткие стабильные ограничения.
Chat может быть рабочим пространством. Source of truth должен быть в репозитории.
Мини-демо: где начинается drift
Цель практики - увидеть, как большая задача начинает расползаться.
Входная задача
Дайте coding agent большую команду:
Добавь password reset: backend endpoints, email sending, frontend forms,
валидацию, тесты и обнови документацию.
Не добавляйте подробную specification. Не ограничивайте allowed scope. Не давайте готовые acceptance criteria.
Что наблюдать
Во время работы отметьте:
- какие product decisions агент принял сам;
- какие файлы изменил без явной необходимости;
- добавил ли новые dependencies;
- нашел ли существующие patterns в проекте;
- написал ли tests до реализации;
- запускал ли verification commands;
- сохранил ли совместимость API;
- где начал отклоняться от исходной цели.
Ожидаемый вывод
Вывод практики не в том, что "агент плохой". Вывод в том, что задача была поставлена так, что даже сильная модель вынуждена угадывать.
После этого ту же фичу нужно будет разложить иначе:
Password Reset feature
↓
Specification
↓
Clarification questions
↓
Design
↓
Task DAG
↓
One task
↓
Test
↓
Implementation
↓
Verification
Это и есть переход от one-shot prompting к Specification-Driven Development.
Типичные ошибки
Ошибка 1. Считать prompt спецификацией
Prompt может быть входом для работы, но specification должна описывать поведение, ограничения и acceptance criteria в проверяемой форме.
Ошибка 2. Давать модели весь репозиторий вместо нужного контекста
Большой контекст может добавить шум. Лучше дать текущую specification, текущую task и релевантные файлы.
Ошибка 3. Верить уверенности ответа
Фраза "готово" ничего не доказывает. Нужны tests, command output, diff review и acceptance checklist.
Ошибка 4. Просить агента одновременно проектировать и реализовывать большую фичу
Когда design и implementation смешаны, агент начинает принимать product и architecture decisions на ходу. В следующих уроках мы будем разделять Plan Mode и Act Mode.
Ошибка 5. Хранить решения только в chat history
История чата не должна быть source of truth. Решения нужно переносить в specs, ADR, tasks, rules или tests.
Критерии готовности
После урока студент должен уметь:
- объяснить, что такое token и context window на уровне, достаточном для работы с coding agent;
- назвать минимум 4 причины, почему LLM может ошибиться в coding task;
- отличить LLM answer от verified result;
- объяснить, почему большой prompt не заменяет specification;
- описать, какую внешнюю verification нужно получить перед завершением agent task.
Краткое резюме
LLM - мощный генератор и reasoning engine, но не источник гарантированной истины. Она работает с ограниченным context window, может ошибаться уверенно, не имеет надежной проектной памяти и нуждается во внешнем feedback loop.
В AI Agent Development качество появляется не от одного большого prompt'а, а от системы:
Good context
+
Small task
+
Clear acceptance criteria
+
Tool feedback
+
Tests and review
Именно эту систему мы будем строить дальше.
Вопросы для самопроверки
- Почему уверенный ответ LLM не является evidence?
- Чем отличается знание модели о типовом password reset от знания о конкретном проекте?
- Какие данные обычно входят в context coding agent?
- Почему большой prompt может ухудшить управляемость задачи?
- Что должно произойти, прежде чем agent task можно считать завершенной?
Что дальше
В следующем уроке мы отделим обычный chatbot от agent и coding agent. Это важно, потому что управляемая AI-разработка начинается там, где модель не просто отвечает текстом, а действует через инструменты, наблюдает результат и продолжает работу внутри controlled loop.