Project 08. Нарисуйте ваш workflow как граф

Связанная лекция: L14. От одиночных циклов к графовой инженерии

Что вы будете делать

Это переходный проект от «Loop» к «Graph». В прошлой лекции вы построили maker-checker loop — реализация, верификация, обратная связь, снова реализация, все решения в контекстном окне одного и того же агента. В этой лекции вы явно выпишете структуру, спрятанную в цикле: узлы, рёбра, общее состояние, правила маршрутизации — слово за словом.

Вы сделаете три следующих эксперимента: сначала нарисуете maker-checker loop из P07 как явный граф, затем добавите графу параллельный узел fan-out/fan-in, и наконец добавите условное ребро отката и узел ручного согласования. По завершении вы на себе почувствуете одну вещь: граф — не новое изобретение, это то, во что превращается ваш loop, когда становится достаточно сложным.

Какие инструменты

• Claude Code или Codex
• Git
• maker-checker loop, который вы построили в P07 (или любой другой агентный workflow, который вы можете многократно запускать)
• текстовый редактор или инструмент для рисования (рисовать не ради красоты, а чтобы выписать структуру; подойдёт mermaid или рукописный graph.md)

Конкретные шаги

Подготовка

1. Начните с репозитория после P07 или просто возьмите любой агентный workflow, который вы сейчас запускаете.
2. Создайте три ветки: p08-explicit-graph, p08-parallel, p08-human-in-the-loop.
3. Подготовьте state.md как файл общего состояния: требования, прогресс, результаты верификации — всё записывается сюда. Это «общий рабочий стол» графа.

Эксперимент 1: нарисуйте Loop как явный граф

Переключитесь на ветку p08-explicit-graph.

1. Перечислите все узлы: запишите каждый шаг maker-checker loop из P07 как узел. Для каждого узла выпишите: его ответственность, его вход, его выход, агент это или детерминированный код.
2. Нарисуйте все рёбра: перечислите каждое ребро между узлами. Особо отметьте два особых ребра:
   • условное ребро: верификация пройдена/упала — куда идём
   • ребро отката: сбой возвращается к какому узлу
3. Напишите общее состояние: явно перечислите, какие поля есть в состоянии (требования, код, результаты тестов, вывод ревью), кто читает, кто пишет.
4. Напишите правила маршрутизации: самым простым языком if-then запишите правила «куда идти дальше», например:

   if верификация пройдена → узел слияния
   if верификация упала → узел реализации
   if узлу реализации не хватает данных → узел исследования

5. Оформите в graph.md: соберите всё выше в документ. Нарисуйте граф через mermaid, приложите таблицу узлов и правила маршрутизации.
6. Ответьте на вопрос: после рисования найдите как минимум одно бывшее неявным ребро — путь решения, который раньше прятался в контексте агента и о котором вы даже не знали, что он существует.

Эксперимент 2: добавьте параллельный узел Fan-out / Fan-in

Переключитесь на ветку p08-parallel.

1. Выберите точку для параллелизма: найдите в задаче место, которое можно разбить на две независимые части. Например:
   • реализацию разбить на два независимых модуля, два агента пишут параллельно
   • верификацию разбить на две независимые проверки: один запускает тесты и линт, другой делает ревью кода (разные инструкции, разные фокусы)
   • исследование разбить на два направления, два агента ведут каждый свою линию
2. Напишите правило fan-out: в общем состоянии запишите «эта задача разбита на N параллельных подзадач», у каждой подзадачи отдельный контекст и отдельный узел.
3. Напишите правило fan-in: когда все подзадачи завершены, кто объединяет результаты? Каков критерий объединения (например, объединяем только если обе проверки прошли, или достаточно одной)?
4. Изолируйте с помощью worktree: каждая параллельная подзадача работает в отдельном git worktree, физически исключая коллизии файлов (вспомните примитив Worktree из тринадцатой лекции).
5. Запустите один раз и запишите: зафиксируйте wall-clock время до и после параллелизма, расход токенов, качество результата. Параллелизм реально быстрее? Или накладные расходы на координацию съели сэкономленное время?

Эксперимент 3: добавьте ребро отката и узел ручного согласования

Переключитесь на ветку p08-human-in-the-loop.

Это самый важный из трёх экспериментов. Вы добавите к графу два вида узлов:

1. Условное ребро отката: добавьте узлу верификации путь «частично пройдено» — не возвращать всё к узлу реализации, а с конкретной обратной связью вернуться к узлу, породившему проблему. Например: тесты прошли, но ревью кода обнаружило, что требования поняты неверно — откат к узлу исследования, а не к реализации. Это требует, чтобы ваше общее состояние фиксировало «на каком уровне возникла проблема».
2. Узел ручного согласования (Human-in-the-loop): перед узлом слияния добавьте человеческий узел. Дойдя до него, граф останавливается и ждёт, пока вы напишете в state.md «одобрить» или «отклонить». У узла согласования может быть правило таймаута: если за N часов нет ответа — автоотклонение или авто-эскалация.
3. Напишите формат interrupt: как чётко оформить запрос на согласование — что произошло, что изменилось, зачем нужен человек, каковы последствия одобрения/отклонения.
4. Пройдите минимум 2 полных цикла: в каждом цикле дойдите до узла ручного согласования и сами одобрите или отклоните один раз. Запишите: совпадает ли ваше решение с суждением узла верификации? Останавливал ли узел согласования то, что узел верификации не остановил?

Как измерять результат

Показатель	Эксперимент 1 (явный граф)	Эксперимент 2 (параллелизм)	Эксперимент 3 (человек+машина)
Видимость структуры	Сколько неявных рёбер вы нашли?	Может ли общее состояние поддерживать параллельные подзадачи?	Может ли ребро отката точно локализовать проблемный слой?
Локализация сбоя	При сбое можно ли напрямую указать, какое ребро неверно?	При сбое параллельной подзадачи можно ли локализовать, какой именно?	При отклонении можно ли указать, проблема какого слоя?
Накладные расходы на сотрудничество	Сколько времени заняло рисование графа?	Сэкономленное на параллелизме время vs накладные расходы на координацию	Время ожидания согласования vs ценность остановленных проблем
Наблюдаемость	Что происходит на каждом шаге, теперь видно?	Виден ли статус каждой параллельной подзадачи?	Достаточно ли чётко написан запрос на согласование?
Надёжность	Совпадает ли описание графа с реальным запуском?	Корректен ли критерий объединения fan-in?	Действительно ли срабатывают правила таймаута/эскалации?

Что сдать

• graph.md (полное описание графа из эксперимента 1: mermaid-диаграмма + таблица узлов + таблица рёбер + поля общего состояния + правила маршрутизации)
• список неявных рёбер, найденных в эксперименте 1 (минимум одно)
• правила fan-out/fan-in из эксперимента 2 и одна запись параллельного запуска (сравнение времени/стоимости/качества)
• правила ребра отката из эксперимента 3, формат узла согласования и записи 2 циклов человек+машина
• финальная рефлексия: от loop к graph — как изменился ваш способ работы? Какие задачи заслуживают графа, а какие нет?

Связанные лекции

• Lecture 14 — От одиночных циклов к графовой инженерии
• Lecture 13 — От ручных запросов к автономным циклам (ваш loop — это узел графа; этот проект раскрывает внутреннюю структуру узла)
• Lecture 09 — Почему агенты объявляют победу слишком рано (почему узел верификации должен быть независим от узла реализации; в графе это структурная проблема)
• Lecture 11 — Почему наблюдаемость должна быть внутри harness (чем сложнее граф, тем больше нужно видеть, что делает каждый узел)