Поурочная карта¶
Карта помогает быстро подготовить 34 урока полного маршрута и два урока-показа вводной главы «Экскурсия по AI: что есть что» (Э1–Э2, сверх 34 часов); содержание сверено с поурочным планом и текстом книги, а при расхождении используется формулировка книги.
Урок Э1. Модель и два входа к ней¶
Страница в книге: ↗
Цель: Различить по наблюдениям, что сделала модель, а что — приложение; показать, где хранится история разговора в чате и при обращении через API, и почему «лучшая модель вообще» — неверная постановка вопроса.
Формат: показ, а не практикум. Показывает учитель или видео автора; ученик до каждого показа записывает прогноз, после — наблюдение. Регистрация, установка и оплата от ученика не требуются; starter не используется.
Ход урока: 5 мин — сцена, вопрос-прогноз, карта «что есть что» в тетради; 7 мин — показ 1 «Куда мы попали?»; 9 мин — показ 2 «Что внутри»; 10 мин — показ 3 «Модели разные»; 9 мин — показ 4 «Второй вход: API»; 5 мин — таблица «чат / API», выходной билет. Итого 45 мин. Хронометраж — гипотеза до пилота.
Трек A: прогноз до каждого показа и таблица наблюдений (четыре строки: прогноз; что произошло; чья это работа — модели или приложения; вывод в одну фразу).
Трек B: необязательный — показы 1–3 повторить в чате, которым школа разрешает пользоваться, только вместе с учителем; результат — в ту же таблицу с пометкой «наш опыт». Личные данные не вводятся.
Распечатать или раздать: лист таблицы наблюдений; заготовка карты «что есть что» с двумя рамками-входами.
Проверка: мини-проверка «шесть наблюдений в два столбца» в итоге урока Э1 — ответы в книге сразу после неё; выходной билет: закончить фразу «В чате историю разговора хранит и присылает модели…, а при обращении через API — …» (ожидается: приложение; программа, которую пишет автор). Владение словами первого знакомства (модель, приложение, контекст, версия модели, API, ключ API, обвязка) не проверяется.
Типичная ошибка: «ИИ — это сайт»; «модель сама помнит разговор и сама ищет в интернете».
Безопасность: личные данные, свои и чужие, в чат не вводятся; адрес сайта проверяется до ввода чего-либо; ключ API — секрет, его не показывают и не записывают в тетрадь.
Продукт и домашняя работа: четыре строки таблицы наблюдений и карта с двумя входами; домашней работы нет.
Упрощение и усложнение: упростить — в показе 3 обсудить только итоговую таблицу сравнения; усложнить — ученик предлагает свою задачу и критерий для набора показа 3.
Схема на 18 часов: один урок-показ на обе части — показы 1, 4, 5, 7 (только три роли), 8 и карта; показы 2, 3, 6 — домашний просмотр видео или чтение. Либо вся Экскурсия — домашним просмотром; тогда первые 5 минут занятия 1 — сверка таблиц наблюдений.
Урок Э2. Агент и его упряжка¶
Страница в книге: ↗
Цель: Сравнить три входа к модели — чат, агент для кода и программу через API — по трём вопросам (что система может изменить, кто подтверждает действие, где записаны шаги) и показать на схеме папки агента файл инструкций, файл с записанной процедурой и файл подключений.
Формат: показ, как в уроке Э1. Требуется таблица наблюдений урока Э1. Самый плотный урок Экскурсии — держать темп показов.
Ход урока: 3 мин — возврат к прогнозу сцены, карта «что есть что»; 10 мин — показ 5 «Чат советует — агент делает»; 7 мин — показ 6 «Папка агента»; 9 мин — показ 7 «Skill и MCP»; 9 мин — показ 8 «Всё вместе» и итоговая таблица; 3 мин — «Какие бывают агенты»; 4 мин — возврат к сцене, выходной билет, мост к главе 1. Итого 45 мин. Хронометраж — гипотеза до пилота.
Трек A: прогноз до каждого показа; таблица наблюдений дополняется строками показов 5–8; карта «что есть что» заполняется до конца.
Трек B: нет.
Распечатать или раздать: лист таблицы наблюдений (продолжение); карта из урока Э1; схема папки агента (три файла: инструкции проекта, записанная процедура, подключения).
Проверка: мини-проверка «пять ситуаций — выбери вход» с ответами в книге; выходной билет: «Назови три вопроса, которые нужно задать любому агенту, прежде чем пустить его в папку» (ожидается: что может изменить; кто подтверждает; где записаны шаги); «Проверь себя» главы ↗ — с ответами в книге, разбираются в классе или дома. Таблица «Обязательные проверки» (должен / не должен / ошибка / граница) в конце урока — опора для разбора спорных ответов.
Типичная ошибка: «агент — это более умная модель»; «раз агент спросил подтверждение, действие безопасно».
Безопасность: агент запускается в отдельной папке; человек читает, что именно подтверждает; режим без вопросов — не знак безопасности, скорее наоборот; учётные записи — только с разрешения взрослых и по правилам сервиса, обходить ограничения сервиса или школы нельзя.
Продукт и домашняя работа: восемь строк таблицы наблюдений и заполненная карта «что есть что»; домашняя работа необязательна — таблица «что есть что» для одной знакомой системы, без её использования.
Упрощение и усложнение: упростить — показ 6 только по схеме папки; усложнить — объяснить, почему чат с поиском тоже можно назвать агентом.
Связь с проектом: шага проекта нет; на схеме ученик видит папки skills/ и workspace/my_agent/, которые откроет в главах 9 и 1.
Урок 1. Что скрывается за одним окном чата¶
Страница в книге: ↗
Цель: Развести роли человека, интерфейса, приложения и модели и показать, что убедительная фраза ещё не доказывает выполненное действие.
Ход урока: 5 мин — ситуация «чат обещает прочитать файл»; 10 мин — разбор ролей; 23 мин — работа парами со схемой потока данных; 7 мин — взаимная проверка схем. Итого 45 мин.
Трек A: разложить карточки «пользователь», «интерфейс», «приложение», «модель», «ответ» и собрать цепочку передачи данных.
Трек B: запустить локальную заглушку: python chat_stub.py.
Распечатать или раздать: карточки ролей и лист потока данных.
Проверка: мини-проверка ↗ с ответами сразу после неё; выходной билет ↗; «Проверь себя» главы ↗ — без напечатанных ответов, их сверяют по уроку 2.
Типичная ошибка: приписывать модели открытие окна, чтение файлов и запуск кода.
Безопасность: не помещать в учебные запросы пароли и реальные персональные данные.
Продукт и домашняя работа: схема «человек → приложение → модель → приложение → человек»; домашней работы нет.
Упрощение и усложнение: упростить до трёх ролей; усложнить добавлением сервера и сетевого интерфейса.
Урок 2. Когда помощник начинает выбирать¶
Страница в книге: ↗
Цель: Отличить текстовое обещание от выполненного действия и объяснить, когда приложение становится агентом.
Ход урока: 4 мин — сравнение обещания и реального чтения; 11 мин — демонстрация; 23 мин — классификация «ответ / действие / агентный шаг»; 7 мин — разбор спорных случаев. Итого 45 мин.
Трек A: роли «модель», «приложение» и tool чтения карточки; участники передают запрос и наблюдаемый результат.
Трек B: сравнить обычный и ошибочный сценарии: python chat_stub.py, python chat_stub.py --scenario missing_file, затем машинно-читаемую форму python chat_stub.py --json.
Распечатать или раздать: три синтетические карточки задач и лист классификации.
Проверка: «Проверь себя на ходу» ↗; выходной билет урока 2 ↗; «Проверь себя» главы ↗ — без напечатанных ответов, их сверяют по тексту урока 2.
Типичная ошибка: считать агентом любую программу с чат-интерфейсом.
Безопасность: первые tools работают только на чтение.
Продукт и домашняя работа: цель проектного агента и три нецели; необязательно — разобрать знакомое ИИ-приложение по ролям.
Упрощение и усложнение: сравнить только чат и функцию; усложнить примером, где tool есть, а агентный цикл не нужен.
Урок 3. Один шаг и обратная связь¶
Страница в книге: ↗
Цель: Восстановить агентный цикл и показать, как observation меняет следующий шаг.
Ход урока: 5 мин — два похожих файла; 8 мин — схема цикла; 25 мин — ролевая симуляция; 7 мин — восстановление цикла по памяти. Итого 45 мин.
Трек A: роли модели, приложения и двух tools; observations выдаются закрытыми карточками после действия.
Трек B: работать с loop_demo.py; выполнить python loop_demo.py --scenario one_match и python loop_demo.py --scenario two_matches.
Распечатать или раздать: карточки состояний, действий и observations.
Проверка: раздел урока ↗ и выходной билет ↗; итоговая проверка главы — ↗.
Типичная ошибка: считать observation пояснением, которое не влияет на продолжение работы.
Безопасность: действия симуляции обратимы и выполняются на копиях данных.
Продукт и домашняя работа: диаграмма agent loop проектного бюро; домашней работы нет.
Упрощение и усложнение: один проход цикла; усложнение — два разных observation после одного действия.
Урок 4. Четыре способа завершить запуск¶
Страница в книге: ↗
Цель: Развести success, needs_input, error и limit и связать остановку с observation, retry и пределом шагов.
Ход урока: 5 мин — повтор одной ошибки; 10 мин — завершение, повтор и отказ; 20 мин — дополнение диаграмм; 3 мин — короткий показ учителя; 7 мин — контрольная точка. Итого 45 мин.
Трек A: карточки «повторить», «попросить данные», «остановиться», «передать человеку» и выбор корректного терминала.
Трек B: разобрать полный loop_demo.py; проверить пять сценариев: python loop_demo.py --scenario one_match, python loop_demo.py --scenario two_matches, python loop_demo.py --scenario temporary_error, python loop_demo.py --scenario permanent_error, python loop_demo.py --scenario limit; короткий учительский показ — python agent_demo.py --scenario success.
Распечатать или раздать: неполные блок-схемы и ошибочная карточка задачи.
Проверка: «Проверь себя на ходу» ↗; выходной билет урока 4 с ответом для сверки ↗; итог главы — ↗.
Контроль: КТ 1: цикл — четыре терминала, пять сценариев, error на действии 2.
Типичная ошибка: «агент должен повторять, пока не получится».
Безопасность: предел шагов и повторов не даёт ошибке бесконечно расходовать ресурсы.
Продукт и домашняя работа: политика остановки: не более пяти шагов и одной повторной попытки чтения; добровольно — сравнить пять сценариев.
Упрощение и усложнение: только success и одна ошибка; усложнение — различить временную и постоянную ошибку.
Урок 5. Кто организует знакомый цикл¶
Страница в книге: ↗
Цель: Показать harness как программную среду вокруг модели и распределить его обязанности.
Ход урока: 5 мин — «двигатель без машины»; 10 мин — схема компонентов; 23 мин — групповая сборка архитектуры; 7 мин — защита одной связи. Итого 45 мин.
Трек A: распределить карточки по группам «решение», «выполнение», «состояние», «контроль», «интерфейс».
Трек B: исследовать структуру loop_demo.py, school_agent/, workspace/, tests/, workspace/traces/; отдельного командного запуска в практике урока нет.
Распечатать или раздать: карточки компонентов и большая схема harness.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: считать harness разновидностью нейросети.
Безопасность: ограничения и permissions проектируются как часть harness, а не как пожелание в prompt.
Продукт и домашняя работа: архитектурная карта проектного агента v0.1; домашней работы нет.
Упрощение и усложнение: пять групп компонентов; усложнение — retries и управление контекстом.
Урок 6. Что видно сейчас и что действительно разрешено¶
Страница в книге: ↗
Цель: Развести активный контекст, состояние и техническую границу доступа.
Ход урока: 4 мин — текстовый запрет против фактического запрета; 11 мин — демонстрация двух границ; 23 мин — сортировка данных и проектирование workspace; 7 мин — проверка схем. Итого 45 мин.
Трек A: распределить примеры по зонам «видит сейчас / хранится между запусками / недоступно».
Трек B: проверить доступ командами python access_demo.py --access read --path tasks/task-003.json, python access_demo.py --access write --path tasks/task-003.json, python access_demo.py --access read --path tasks/missing.json, python access_demo.py --access read --path ../outside.json; затем карту частей — python harness_demo.py --show-parts.
Распечатать или раздать: карточки данных и дерево каталогов.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: считать историю чата единственным состоянием.
Безопасность: скрытый в инструкции пароль не становится безопасным; права проверяются до операции.
Продукт и домашняя работа: политика рабочей папки и карта доступов; домашней работы нет.
Упрощение и усложнение: контекст против файла; усложнение — read-only и read-write.
Урок 7. Почему пять похожих слов обозначают разные механизмы¶
Страница в книге: ↗
Цель: Различить prompt, structured output, tool, MCP и Agent Skill по роли, а не по слову в запросе.
Ход урока: 5 мин — пять решений одной задачи; 12 мин — таблица различий; 21 мин — парная классификация; 7 мин — пограничные случаи. Итого 45 мин.
Трек A: классифицировать карточки ситуаций и объяснить главный вопрос каждого механизма.
Трек B: показать фрагменты python mechanisms_demo.py fragments, затем проверить свои ответы python mechanisms_demo.py check workspace/drafts/ch04_choices.txt; для границ использовать готовые случаи из книги.
Распечатать или раздать: карточки ситуаций и сравнительную таблицу пяти механизмов.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: называть любой prompt или функцию Agent Skill.
Безопасность: протокол подключения не является доказательством доверия.
Продукт и домашняя работа: матрица пяти механизмов; домашней работы нет.
Упрощение и усложнение: оставить prompt, tool и Agent Skill; усложнить дополнительным разбором соседних механизмов.
Урок 8. Как механизмы работают вместе¶
Страница в книге: ↗
Цель: Собрать host/client/server/resource и progressive disclosure в одну архитектуру без ложной лестницы «tool → MCP → Agent Skill».
Ход урока: 5 мин — каталог и вложенные материалы; 10 мин — «описание → SKILL.md → reference»; 23 мин — архитектурное ревью; 7 мин — рефлексия. Итого 45 мин.
Трек A: три вложенных конверта, моделирующие progressive disclosure.
Трек B: python mechanisms_demo.py mcp; затем python mechanisms_demo.py skill --layer catalog, python mechanisms_demo.py skill --layer instructions, python mechanisms_demo.py skill --layer reference.
Распечатать или раздать: три конверта или сложенных листа и карта архитектуры.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Контроль: КТ 2: архитектура — роли механизмов и связная карта системы.
Типичная ошибка: изображать tool, MCP и Agent Skill как поколения, заменяющие друг друга.
Безопасность: внешний server и исполняемый script считаются недоверенными до проверки.
Продукт и домашняя работа: полная архитектурная схема проекта; домашней работы нет.
Упрощение и усложнение: без деталей client/server; усложнение — показать место согласия пользователя.
Урок 9. От просьбы к договору задачи¶
Страница в книге: ↗
Цель: Зафиксировать цель, входы, результат, ограничения, неизвестность и критерий готовности до выбора tools и кода.
Ход урока: 5 мин — расплывчатая просьба; 10 мин — разбор хорошего договора; 23 мин — заполнение паспорта; 7 мин — чек-лист. Итого 45 мин.
Трек A: заполнить бумажный технический паспорт проекта.
Трек B: создать task_spec.json по структуре урока; отдельной команды запуска в практике нет.
Распечатать или раздать: шаблон договора задачи, плохие и хорошие примеры.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: описывать действие «обработать данные» вместо наблюдаемого результата.
Безопасность: запрещённые действия записываются в договоре заранее.
Продукт и домашняя работа: технический паспорт проекта v0.1; домашней работы нет.
Упрощение и усложнение: цель, вход и результат; усложнение — неизвестность и условия остановки.
Урок 10. Когда агент не нужен¶
Страница в книге: ↗
Цель: Выбрать между обычным кодом, моделью и агентным циклом и не добавлять агента без необходимости.
Ход урока: 5 мин — три способа проверить поля; 10 мин — критерии выбора; 23 мин — классификация 12 задач; 7 мин — обсуждение разногласий. Итого 45 мин.
Трек A: таблица «обычный код / модель / агент» для двенадцати ситуаций.
Трек B: записать сигнатуры функций и входные значения без реализации; отдельного командного запуска в практике нет.
Распечатать или раздать: карточки задач и шаблон декомпозиции.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: добавлять agent loop только потому, что задача связана с ИИ.
Безопасность: чем выше цена ошибки, тем меньше оснований передавать решение автономной системе.
Продукт и домашняя работа: карта четырёх tools и список задач, которые агент не выполняет; домашней работы нет.
Упрощение и усложнение: выбрать из готовых вариантов; усложнение — сравнить две архитектуры по риску и сложности.
Урок 11. Как модель запрашивает tool¶
Страница в книге: ↗
Цель: Восстановить цепочку tool calling и назвать исполнителя каждого шага.
Ход урока: 5 мин — имя и arguments ещё не действие; 10 мин — семишаговая схема; 23 мин — ролевая или программная симуляция; 7 мин — проверка цепочки. Итого 45 мин.
Трек A: модель пишет карточку вызова, приложение её проверяет, tool выполняет операцию и возвращает результат.
Трек B: python tool_call_demo.py show, затем python tool_call_demo.py execute.
Распечатать или раздать: карточки tool calls и схема цепочки.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: считать появление tool call доказательством выполнения.
Безопасность: запрос модели не является разрешением на выполнение.
Продукт и домашняя работа: схема первого tool проекта; домашней работы нет.
Упрощение и усложнение: один tool без аргументов; усложнение — два последовательных вызова.
Урок 12. Параметры как договор¶
Страница в книге: ↗
Цель: Сделать arguments проверяемыми через schema и согласовать их с сигнатурой функции.
Ход урока: 5 мин — несовпадающее имя поля; 10 мин — элементы schema; 23 мин — исправление плохих описаний; 7 мин — короткий тест. Итого 45 мин.
Трек A: собрать schema из карточек полей и проверить правильный, неполный и недопустимый объект.
Трек B: python tool_call_demo.py schema read_task_cards, python tool_call_demo.py schema validate_task_card, python tool_call_demo.py schema task_card; для проверки — python tool_call_demo.py check workspace/ch06/cases/validate_missing_task_id.json и python tool_call_demo.py check workspace/ch06/cases/read_with_path.json.
Распечатать или раздать: карточки типов, полей и обязательности; шаблон schema.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: включить поле в required, но не описать его в properties.
Безопасность: arguments проверяются до вызова функции.
Продукт и домашняя работа: схема карточки задачи; домашняя работа — один дополнительный отрицательный пример.
Упрощение и усложнение: только строки и обязательные поля; усложнение — массив blockers и enum статусов.
Урок 13. Диспетчер и белый список¶
Страница в книге: ↗
Цель: Связать имя tool только с разрешённой функцией через dispatch table и allowlist.
Ход урока: 5 мин — запрос delete_everything; 10 мин — таблица соответствий; 23 мин — сборка маршрутизатора; 7 мин — тест неизвестного имени. Итого 45 мин.
Трек A: диспетчер получает карточку запроса и передаёт её только разрешённому исполнителю.
Трек B: проверить три случая: python dispatcher_demo.py case allowed, python dispatcher_demo.py case unknown-tool, python dispatcher_demo.py case invalid-arguments.
Распечатать или раздать: карточки имён tool и таблицу allowlist.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: искать функцию по строке и вызывать её без белого списка.
Безопасность: не использовать eval, произвольные команды и подбор «похожего» имени.
Продукт и домашняя работа: диспетчер разрешённых tools; домашней работы нет.
Упрощение и усложнение: два tools; усложнение — метаданные режима доступа.
Урок 14. Ошибки, несколько вызовов и возврат результата¶
Страница в книге: ↗
Цель: Обрабатывать ошибки и несколько tool calls так, чтобы каждый результат становился наблюдаемым событием.
Ход урока: 5 мин — повреждённый файл; 10 мин — ветви обработки; 8 мин — офлайн-проверка ошибок; 15 мин — bridge и разбор; 7 мин — демонстрация результата. Итого 45 мин.
Трек A: карточки «успех / ошибка / неизвестный tool» и решение, что записать в журнал.
Трек B: python dispatcher_demo.py case tool-exception, python dispatcher_demo.py run two-calls, python dispatcher_demo.py run stop-after-decision, python dispatcher_demo.py run missing-file; локальная ошибка — python agent_demo.py --scenario missing_file. Для обязательного живого сеанса книга даёт команду python agent_demo.py --adapter bridge --scenario success --trace traces/bridge-lesson14-group-a.jsonl; порядок bridge —, паспорт —.
Распечатать или раздать: сценарии ошибок и карточки исходов; для bridge — шаблон паспорта.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Контроль: КТ 3: цикл и bridge — чтение, ошибка и результат; в треке B — паспорт bridge-сеанса.
Типичная ошибка: перехватить ошибку и не оставить о ней наблюдаемой записи.
Безопасность: текст ошибки не раскрывает секреты и лишние системные пути.
Продукт и домашняя работа: первый работающий локальный цикл; добровольно — разобрать уже выполненный bridge-сеанс.
Упрощение и усложнение: один тип ошибки; усложнение — несколько независимых результатов.
Урок 15. Хороший tool начинается с границы¶
Страница в книге: ↗
Цель: Ограничить scope tool и сформулировать описание «что / над чем / когда / когда не применять».
Ход урока: 5 мин — review плохого helper; 10 мин — четыре правила описания; 23 мин — ревью tools проекта; 7 мин — обмен запросами. Итого 45 мин.
Трек A: заполнить карточку описания tool и проверить границы на двух запросах.
Трек B: python tool_quality_demo.py passport validate_task_card; затем python tool_quality_demo.py route --case should-validate-card и python tool_quality_demo.py route --case should-read-board.
Распечатать или раздать: плохие descriptions и паспорт tool.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: описание «работает с данными и помогает пользователю».
Безопасность: слишком широкий scope увеличивает число ложных вызовов и поверхность риска.
Продукт и домашняя работа: паспорта tools; домашней работы нет.
Упрощение и усложнение: один tool; усложнение — пересечение двух descriptions.
Урок 16. Validator и три обязательных теста¶
Страница в книге: ↗
Цель: Проверить tool случаями «должен / не должен / ошибка» и отличить форму от замысла.
Ход урока: 5 мин — один успешный тест недостаточен; 10 мин — минимальный набор; 23 мин — практический зачёт; 7 мин — взаимное ревью. Итого 45 мин.
Трек A: провести три сценария с ролевым агентом.
Трек B: python tool_call_demo.py check workspace/ch06/cases/validate_missing_task_id.json, python tool_quality_demo.py suite, python access_demo.py --access read --path ../outside.json.
Распечатать или раздать: три карточки сценариев и чек-лист проверки.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Контроль: Проверочная работа 1 — tool, schema, validator и три теста.
Типичная ошибка: тестировать только «счастливый путь».
Безопасность: обязательный отрицательный случай — попытка обратиться к пути вне workspace.
Продукт и домашняя работа: проверенный пакет tools и отчёт тестирования; домашней работы нет.
Упрощение и усложнение: ручной чек-лист; усложнение — автоматический отчёт.
Урок 17. Что такое настоящий Agent Skill¶
Страница в книге: ↗
Цель: Развести Agent Skill, prompt, tool и учебный каталог и определить роль SKILL.md.
Ход урока: 5 мин — три папки; 10 мин — структура каталога; 23 мин — проектирование skill; 7 мин — проверка обязательных элементов. Итого 45 мин.
Трек A: собрать бумажный каталог из карточек-файлов.
Трек B: python skill_demo.py catalog, python skill_demo.py load project-status, затем python skill_demo.py check workspace/ch09/cases/project-status-valid и python skill_demo.py check workspace/ch09/cases/function-only.
Распечатать или раздать: карточки файлов, шаблон паспорта skill и примеры каталогов.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: считать любые дополнительные папки обязательными для Agent Skill.
Безопасность: до подключения проверяются происхождение, scripts, сеть и permissions.
Продукт и домашняя работа: паспорт Agent Skill v0.1; домашней работы нет.
Упрощение и усложнение: только SKILL.md и reference; усложнение — совместимость и лицензия.
Урок 18. Пишем SKILL.md¶
Страница в книге: ↗
Цель: Описать повторяемую процедуру компактно, с trigger, шагами, запретами, неизвестностью и критерием готовности.
Ход урока: 5 мин — слишком общий SKILL.md; 10 мин — структура процедуры; 15 мин — проектный skill; 8 мин — личный skill и три проверки; 7 мин — активационный тест. Итого 45 мин.
Трек A: бумажный SKILL.md и отдельные reference-карточки.
Трек B: python skill_demo.py resource project-status references/report-template.md; затем случаи python skill_demo.py check workspace/ch09/cases/bad-frontmatter, python skill_demo.py check workspace/ch09/cases/script-present, python skill_demo.py check workspace/drafts/ch09/project-status и python skill_demo.py replay.
Распечатать или раздать: шаблон SKILL.md, примеры процедур и чек-лист.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Контроль: КТ 4: skill — проектный и личный skill, три проверки.
Типичная ошибка: превращать SKILL.md в энциклопедию вместо порядка работы.
Безопасность: не хранить в skill реальные пароли, токены и персональные сведения.
Продукт и домашняя работа: проектный Agent Skill и личный учебный skill v1; добровольно — улучшить reference и проверки.
Упрощение и усложнение: шесть шагов процедуры; усложнение — детерминированный script после аудита.
Урок 19. Состояние, память, RAG и журнал — не одно и то же¶
Страница в книге: ↗
Цель: Выбрать подходящее место для процедуры, текущего состояния, фактов и истории событий.
Ход урока: 5 мин — где хранить «задача заблокирована»; 10 мин — карта механизмов; 23 мин — классификация 15 примеров; 7 мин — разбор. Итого 45 мин.
Трек A: разложить карточки по хранилищам.
Трек B: python skill_demo.py load project-status и python state_demo.py classify; затем отделить project_state.json от SKILL.md.
Распечатать или раздать: карточки данных и карта механизмов хранения.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: складывать все данные внутрь Agent Skill.
Безопасность: профиль и чувствительные сведения требуют отдельного решения и в проекте не используются.
Продукт и домашняя работа: модель состояния проекта; домашней работы нет.
Упрощение и усложнение: procedure/state/journal; усложнение — добавить RAG и профиль.
Урок 20. Как передать работу следующему запуску¶
Страница в книге: ↗
Цель: Сохранить минимальное проверяемое состояние для продолжения работы без полной истории чата.
Ход урока: 5 мин — длинная стенограмма вместо состояния; 10 мин — файлы и защищаемые данные; 23 мин — передача проекта; 7 мин — проверка восстановления. Итого 45 мин.
Трек A: одна группа оставляет состояние, другая продолжает без устного объяснения.
Трек B: python state_demo.py resume workspace/ch10/cases/project_state_ready.json, python state_demo.py resume workspace/ch10/cases/project_state_missing_next_step.json, затем python state_demo.py checkpoint workspace/ch10/cases/project_state_ready.json --out drafts/ch10/project_state.json; проверить handoff командами из урока.
Распечатать или раздать: карточки хранилищ и шаблон handoff.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Контроль: КТ 5: состояние — handoff между запусками.
Типичная ошибка: сохранять всю переписку вместо проверяемого рабочего результата.
Безопасность: в handoff не включаются секреты и реальные персональные данные.
Продукт и домашняя работа: пакет возобновляемого состояния; домашней работы нет.
Упрощение и усложнение: один JSON-файл; усложнение — безопасная атомарная запись.
Урок 21. От теста к Eval¶
Страница в книге: ↗
Цель: Превратить отдельные тесты в проверяемый eval-набор и зафиксировать baseline.
Ход урока: 5 мин — два красивых, но непроверенных отчёта; 10 мин — критерии и повторяемость; 23 мин — набор случаев; 7 мин — ревью критериев. Итого 45 мин.
Трек A: таблица «вход → ожидаемое действие → ожидаемый результат».
Трек B: python eval_runner.py --summary, затем python eval_runner.py; результаты harness и model_behavior рассматривать отдельно.
Распечатать или раздать: шаблон Eval case и примеры отчётов.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: оценивать ответ по впечатлению «умный и подробный».
Безопасность: в eval-набор включается запрос на запрещённое действие.
Продукт и домашняя работа: план eval-набора из шести случаев; дома — один граничный случай.
Упрощение и усложнение: три случая; усложнение — отдельные критерии маршрута и результата.
Урок 22. Сравниваем две версии на одном наборе¶
Страница в книге: ↗
Цель: Сравнить версии на одинаковых входах и критериях и отделить реальное улучшение от удачного запуска.
Ход урока: 5 мин — версия B лучше на одном примере; 10 мин — одинаковые условия; 23 мин — слепое оценивание; 7 мин — вывод. Итого 45 мин.
Трек A: оценить два набора результатов, не зная названия версии.
Трек B: python eval_runner.py --summary; для проекта — python dezhurny.py eval --dir workspace/my_agent/examples/full.
Распечатать или раздать: два комплекта результатов и рубрику.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Контроль: Проверочная работа 2 — harness отдельно от model_behavior; baseline.
Типичная ошибка: менять входные данные одновременно с процедурой.
Безопасность: высокий общий балл не отменяет критического нарушения безопасности.
Продукт и домашняя работа: baseline-отчёт версии 1.0.0; домашней работы нет.
Упрощение и усложнение: pass/fail; усложнение — взвешенная рубрика.
Урок 23. Trace: что происходило на самом деле¶
Страница в книге: ↗
Цель: Восстановить запуск по наблюдаемым событиям и спроектировать trace без скрытых рассуждений.
Ход урока: 5 мин — правильный итог неправильным маршрутом; 10 мин — структура trace; 23 мин — восстановление событий; 7 мин — проверка. Итого 45 мин.
Трек A: собрать trace из перемешанных карточек событий.
Трек B: python dispatcher_demo.py run two-calls; затем python trace_demo.py record --scenario missing_file --out traces/ch12_lesson23.jsonl и python trace_demo.py show traces/ch12_lesson23.jsonl.
Распечатать или раздать: карточки событий и шаблон JSONL.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: логировать только финальный текст.
Безопасность: trace хранит наблюдаемые события, а не пароли, чувствительные данные или скрытые рассуждения модели.
Продукт и домашняя работа: схема trace проекта; домашней работы нет.
Упрощение и усложнение: пять типов событий; усложнение — временные метки и call id.
Урок 24. Ищем ошибку по Trace¶
Страница в книге: ↗
Цель: Найти первую failure point и отличить ошибку выбора, arguments, выполнения и обработки результата.
Ход урока: 5 мин — три traces с одинаковым плохим итогом; 8 мин — виды отказов; 25 мин — диагностика; 7 мин — защита вывода. Итого 45 мин.
Трек A: заполнить incident report по бумажному trace.
Трек B: python trace_demo.py analyze workspace/ch12/cases/wrong_tool.jsonl, python trace_demo.py analyze workspace/ch12/cases/invalid_arguments.jsonl, python trace_demo.py analyze workspace/ch12/cases/tool_exception.jsonl; в проекте — python dezhurny.py run и python dezhurny.py trace --last.
Распечатать или раздать: три намеренно повреждённых trace и бланк incident report.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Контроль: КТ 6: диагностика — incident report по trace.
Типичная ошибка: объяснять всё «ошибкой модели».
Безопасность: журнал должен позволять расследование, но не становиться хранилищем лишних данных.
Продукт и домашняя работа: incident report и локальное предложение исправления; домашней работы нет.
Упрощение и усложнение: одна явная ошибка; усложнение — несколько вторичных симптомов.
Урок 25. Как поправка превращается в опыт¶
Страница в книге: ↗
Цель: Отличить разовую поправку от переносимого изменения процедуры, связанного с неуспешным Eval case.
Ход урока: 5 мин — повтор пропуска blocker; 10 мин — «ошибка → урок → предложение»; 23 мин — работа с примерами; 7 мин — ревью. Итого 45 мин.
Трек A: превратить три пользовательские поправки в правила или обоснованно отклонить их.
Трек B: python trace_demo.py analyze workspace/ch12/cases/invalid_arguments.jsonl; затем python change_demo.py proposal workspace/ch13/change_proposals/validate-task-id.json и python eval_runner.py --summary.
Распечатать или раздать: карточки feedback и шаблон change proposal.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: записывать в skill единичный факт вместо общего правила.
Безопасность: агент может предложить изменение, но не назначает его новой нормой сам.
Продукт и домашняя работа: change proposal личного skill v1→v2, связанный с одним неуспешным кейсом; домашней работы нет.
Упрощение и усложнение: один пример; усложнение — проверка конфликта нового правила со старым.
Урок 26. Version, Regression и Rollback¶
Страница в книге: ↗
Цель: Сравнить Version по diff и прежним тестам и принять keep/revert без потери старой версии.
Ход урока: 5 мин — одна ошибка исправлена, две появились; 10 мин — цикл изменения; 23 мин — сравнение версий; 7 мин — решение. Итого 45 мин.
Трек A: две распечатанные Version и четыре одинаковые карточки Test case; отметить diff, повторить случаи и принять keep/revert.
Трек B: python change_demo.py diff workspace/ch13/versions/1.0.0/project-status workspace/ch13/versions/1.1.0-candidate/project-status; затем python change_demo.py compare workspace/ch13/versions/1.0.0/project-status workspace/ch13/versions/1.1.0-candidate/project-status --cases workspace/ch13/version_cases.json и хороший вариант из книги.
Распечатать или раздать: обязательно две короткие распечатки одной процедуры и четыре одинаковые карточки Test case; шаблон release note.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Контроль: КТ 7: версии — личный skill v1/v2, diff, повтор случаев, keep/revert.
Типичная ошибка: удалить старую Version до проверки новой.
Безопасность: возможность Rollback — часть безопасного улучшения.
Продукт и домашняя работа: Version 1.1.0 либо обоснованный Rollback; домашней работы нет.
Упрощение и усложнение: ручное сравнение; усложнение — Git commit и автоматическая регрессия.
Урок 27. Модель угроз и минимальные полномочия¶
Страница в книге: ↗
Цель: Связать каждое разрешение с конкретной операцией и применить least privilege.
Ход урока: 5 мин — чтению дали право удаления; 10 мин — простая модель угроз; 23 мин — аудит архитектуры; 7 мин — защита ограничения. Итого 45 мин.
Трек A: таблица «операция → необходимый доступ → запрещённый доступ».
Трек B: проверить техническую границу записи на знакомом примере python access_demo.py --access write --path tasks/task-003.json и сопоставить её с матрицей permissions урока.
Распечатать или раздать: карточки угроз, дерево файлов и шаблон permissions.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: выдавать максимальные права «чтобы точно работало».
Безопасность: технические ограничения сильнее словесного запрета.
Продукт и домашняя работа: модель угроз и матрица разрешений; домашней работы нет.
Упрощение и усложнение: чтение/запись; усложнение — сеть, процессы и временные разрешения.
Урок 28. Человек внутри цикла¶
Страница в книге: ↗
Цель: Спроектировать approval gate до значимого действия и развести предложение системы и решение человека.
Ход урока: 5 мин — изменение статуса без разрешения; 10 мин — уровни автономности; 23 мин — подтверждение; 7 мин — практический зачёт. Итого 45 мин.
Трек A: агент формирует предложение, человек проверяет diff и принимает решение.
Трек B: python permissions_demo.py policy --dir workspace/my_agent; затем python permissions_demo.py approval --decision deny, python permissions_demo.py approval --decision approve и граничные случаи из урока.
Распечатать или раздать: карточки действий и шаблон экрана подтверждения.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Контроль: Проверочная работа 3 — permissions и approval gate.
Типичная ошибка: спрашивать подтверждение после выполнения действия.
Безопасность: в проекте нет автоматического удаления, публикации и внешней отправки.
Продукт и домашняя работа: работающий approval gate; домашней работы нет.
Упрощение и усложнение: решение да/нет; усложнение — показать diff и причину действия.
Урок 29. Prompt injection внутри обычного документа¶
Страница в книге: ↗
Цель: Распознать недоверенный текст как данные и ограничить его последствия техническими границами.
Ход урока: 5 мин — команда внутри карточки; 10 мин — разбор атаки; 23 мин — заражённые документы; 7 мин — обсуждение защиты. Итого 45 мин.
Трек A: маркировать фрагменты как «данные», «инструкция системы», «подозрительный текст».
Трек B: python tool_call_demo.py execute, затем python trust_demo.py document --case task-901 и python trust_demo.py replay.
Распечатать или раздать: синтетические документы с инъекциями и лист анализа.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: искать только явную фразу «игнорируй предыдущие инструкции».
Безопасность: текстовый фильтр недостаточен; последствия ограничиваются permissions и approval gate.
Продукт и домашняя работа: протокол обработки недоверенного содержимого; домашней работы нет.
Упрощение и усложнение: явная инъекция; усложнение — скрытая команда в таблице или reference.
Урок 30. Аудит чужого skill и MCP-подключения¶
Страница в книге: ↗
Цель: Проверить provenance, scripts, зависимости, сеть и permission scope до подключения внешнего skill или MCP-стороны.
Ход урока: 5 мин — полезный skill просит широкие права; 10 мин — чек-лист доверия; 23 мин — командный аудит; 7 мин — защита решения. Итого 45 мин.
Трек A: аудит mock-пакетов и карточки MCP-сервера по чек-листу.
Трек B: python trust_demo.py audit skill --sample project-status, python trust_demo.py audit skill --sample project-sync, python trust_demo.py audit skill --sample suspicious-skill, python trust_demo.py audit mcp --sample mock-mcp-server.
Распечатать или раздать: обязательно распечатки SKILL.md, дерева файлов и текста scripts пакетов project-status и project-sync, а также карточку mock_mcp_server.json.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Контроль: КТ 8: аудит доверия — внешний аудит skill другой группы с обоснованным отказом или условиями подключения.
Типичная ошибка: «открытый стандарт означает, что источнику можно доверять».
Безопасность: подключение начинается с минимального доступа; решение isolate значит «не подключать до дополнительной проверки» — отдельной защищённой среды (sandbox) starter не создаёт.
Продукт и домашняя работа: отчёт аудита и решение о подключении; домашней работы нет.
Упрощение и усложнение: готовый чек-лист; усложнение — лицензия, совместимость и транзитивные зависимости.
Урок 31. Один проект — несколько запусков¶
Страница в книге: ↗
Цель: Восстановить проект после завершения Session по resumable state и не повторить уже выполненное действие.
Ход урока: 5 мин — работа прервана после третьего шага; 10 мин — inner/outer loop; 23 мин — передача проекта; 7 мин — восстановление. Итого 45 мин.
Трек A: одна группа оставляет допустимый handoff, вторая продолжает по нему.
Трек B: python state_demo.py resume workspace/ch10/cases/project_state_ready.json; затем python dezhurny.py status --chapter 16, несколько запусков python dezhurny.py run --dir workspace/ch16/cases/long-work и граничная проверка python long_work_demo.py repeat.
Распечатать или раздать: неполное состояние и checklist восстановления.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: сохранять только сообщение «мы почти закончили».
Безопасность: возобновление не должно повторно применять уже подтверждённое изменение.
Продукт и домашняя работа: инструкция восстановления после сбоя; домашней работы нет.
Упрощение и усложнение: один checkpoint; усложнение — operation id и защита от повторного выполнения.
Урок 32. Один агент, несколько агентов или человек¶
Страница в книге: ↗
Цель: Выбрать одноагентную, многоагентную или человеческую схему и назвать владельца итогового решения.
Ход урока: 5 мин — два агента меняют одно состояние; 10 мин — критерии разделения; 23 мин — анализ архитектур и утверждений; 7 мин — решение. Итого 45 мин.
Трек A: сравнить «один агент», «два агента», «агент + человек».
Трек B: python long_work_demo.py handoff --case analyzer, затем отрицательный случай python long_work_demo.py handoff --case missing-owner.
Распечатать или раздать: карточки архитектур и кейсы для обсуждения.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Типичная ошибка: считать multi-agent архитектуру автоматически более умной.
Безопасность: агент не принимает кадровые, медицинские, юридические или финансовые решения.
Продукт и домашняя работа: записка об архитектурном выборе и границах применения; домашней работы нет.
Упрощение и усложнение: один агент или человек; усложнение — конфликт состояния и протокол handoff.
Урок 33. Интеграция: проект как единая система¶
Страница в книге: ↗
Цель: Выполнить согласованный полный прогон tools, skill, состояния, evals и ограничений и зафиксировать Release candidate.
Ход урока: 4 мин — критерии готовности; 8 мин — демонстрация полного прогона; 26 мин — командная интеграция; 7 мин — обмен проектами. Итого 45 мин.
Трек A: ролевая симуляция полного маршрута по карточкам и бумажному trace.
Трек B: python dezhurny.py candidate --label festival-rc1 --dir workspace/ch17/cases/release-candidate, python dezhurny.py status --chapter 17 --dir workspace/ch17/cases/release-candidate, python dezhurny.py run --dir workspace/ch17/cases/release-candidate, python dezhurny.py eval --dir workspace/ch17/cases/release-candidate, затем python eval_runner.py --summary.
Распечатать или раздать: финальный checklist, рубрику защиты и набор синтетических данных.
Проверка: мини-проверка ↗; выходной билет ↗; ответы главы — ↗.
Контроль: Интеграция — кандидат проекта для итоговой проверки ↗.
Типичная ошибка: улучшать презентацию при непройденном критическом тесте.
Безопасность: перед обменом удаляются временные данные; permissions фиксируются и не расширяются.
Продукт и домашняя работа: Release candidate, постер архитектуры, папка доказательств; дома — репетиция защиты.
Упрощение и усложнение: защита только трека A; усложнение — дополнительный API-adapter, не влияющий на основную версию.
Урок 34. Публичная защита и инженерная рефлексия¶
Страница в книге: ↗
Цель: Доказать понятность, проверяемость и ограниченность системы через проект, неуспешный сценарий и безопасную реакцию.
Ход урока: 5 мин — подготовка рабочих мест; 28 мин — защиты; 7 мин — взаимное оценивание; 5 мин — индивидуальная рефлексия. Итого 45 мин.
Трек A: показать ролевую модель, документы, trace и eval-таблицу.
Трек B: показать локальный запуск подготовленного Release candidate и свидетельство минимум одного bridge-сеанса; новых обязательных команд в уроке 34 книга не вводит, используются проверенные артефакты урока 33.
Распечатать или раздать: рубрику защиты, форму самооценки и форму взаимного ревью.
Проверка: мини-проверка ↗; выходной билет ↗; рубрика защиты и ответы главы ↗.
Контроль: Итог — защита, bridge-доказательство трека B и личный skill; рубрика.
Типичная ошибка: демонстрировать только успешный красивый сценарий и скрывать ограничения.
Безопасность: критическое нарушение не компенсируется презентацией; обязательны минимальные permissions и решение человека там, где оно требуется.
Продукт и домашняя работа: публичная защита, личный skill с тремя проверками и решением keep/revert, индивидуальная рефлексия; домашней работы нет.
Упрощение и усложнение: упрощение — защита минимального обязательного маршрута; усложнение — доказанное улучшение и переносимость по бонусной части рубрики.