Основные понятия¶

У flower есть собственный словарь: прогон, шаг, сессия, координатор, исполнитель, предварительное уточнение, страж цели, непрерывность, handoff. Эта страница объясняет их все сразу — прочитав её, вы не будете гадать по ходу остальных страниц. На чтение уходит пять минут.

Здесь только понятия, сигнатур API нет — за сигнатурами идите в Python API, за однострочными определениями и соответствием терминов — в глоссарий, за ключами командной строки — в справочник CLI.

Какую форму имеет один прогон¶

Три уровня, от большего к меньшему:

Вложенность между ними не взаимно однозначная:

Прогон ── этот один запуск flower
 ├── Шаг «уточнение требований» ── Сессия A
 ├── Шаг «постановка цели» ─────── Сессия B
 └── Шаг «работа» ──────────────── Сессия C ──[контекст почти полон]──> Сессия C'
      └── работа·вердикт#1 ─────── Сессия D

• Один шаг может сжечь несколько сессий. Когда контекст почти полон, шаг не делает compact, а пишет handoff-документ и открывает новую сессию, которая подхватывает работу — это handoff, и происходит он внутри одного прогона.
• Новый прогон может подхватить старые сессии. Запустите flower в том же каталоге ещё раз — каждый шаг вернётся в ту же сессию, что и в прошлый раз. Это непрерывность, и она работает между процессами. Держится на runs/lineage.json, который помнит, «какому имени шага соответствует какой session_id».
• Раунд вердикта — всегда новая сессия. У него нет непрерывности, он не попадает в lineage: тот, кто судит «сделано или нет», не может быть тем самым исполнителем, который только что работал.

Набор шагов, выстроенных в последовательность, называется workflow. Голый flower использует встроенный трёхшаговый workflow: уточнение требований → постановка цели → работа.

Разделение труда: координатор не работает руками¶

Это тот единственный принцип, на котором стоит весь фреймворк.

Координатор — это agent в главном потоке. Он разбирает задачу, раздаёт работу, читает отчёты, принимает решения — но у него нет Write и Edit, а Bash хватает только на то, чтобы одним взглядом выполнить одноразовую команду вроде ls или git status (проверяет hook, а не ограничение в prompt; и такие результаты не попадают в персистентную запись сессии). Его таблица инструментов — это Agent, TodoWrite, Read плюс тот самый ограниченный Bash.

Работу реально делает исполнитель — subagent, отправленный инструментом Agent.

Почему именно так. У subagent своя собственная transcript: сколько файлов он прочитал, сколько раз прогнал тесты, сколько кругов сделал по ошибке — всё записано там; главный поток получает только итоговый отчёт. А главный поток — единственный контекст, который тянется через весь прогон, поэтому именно его нужно экономить в первую очередь.

Замеры (HT001, прогон длиной 10.4 часа):

В среднем на каждую отправку исполнителя 82 вызова инструментов главный поток вообще не видит. Это первый слой экономии контекста и слой, экономящий больше всех остальных; полное обоснование — в экономике контекста.

Два момента, которые легко понять неправильно:

• Координатор — это не более умный agent. По умолчанию он и исполнитель используют модель одного класса; экономится контекст, а не модель.
• Формат ответа жёстко ограничен. Ответ исполнителя — ровно четыре раздела: вывод / основания / артефакты / не проверено, не длиннее 30 строк; запрещено вставлять содержимое файлов, вывод команд, логи и сырые diff. Длинные вещи пишутся в artifacts/ workbench, а в ответе даётся только путь.

Всего в flower пять ролей, и все сделаны одинаково: внедрённый текст правил + набор инструментов + набор hook'ов.

Параметры фабричных функций и их значения по умолчанию — в Python API.

Long-horizon ломается в четырёх местах¶

Один long-horizon прогон длится от нескольких часов до нескольких дней, пересекает несколько сессий и переживает перезапуски процесса. Разваливается он всего несколькими способами, и каждому соответствует свой механизм:

Две вещи стоит запомнить отдельно:

У вердикта три исхода, а не два. Достигнуто, не достигнуто и в этой среде проверить невозможно. Последние два — разные выводы: «здесь проверить нельзя» никогда не засчитывается как «пройдено», работа останавливается и задаётся вопрос человеку. И судья судит артефакты, а не исходники: в HT002 на этом уже спотыкались — посмотрели только macOS-ветку Makefile и вынесли «пройдено», а поставлялся в реальности Linux ELF.

Handoff — это не compact. Compact — это когда модель сама, втихую, сворачивает предыдущий диалог в одну сводку: нечитаемую, неправимую, и вы не знаете, что потерялось. Handoff-документ структурирован и лежит на диске — вы можете открыть его, поправить строку и дать работе идти дальше. flower по умолчанию отключает нативный auto-compact и ставит на его место handoff.

Есть ещё два слоя, которых нет в этой таблице, но они работают в каждом прогоне:

• Spill spill — результат инструмента длиннее 4000 символов пишется в .flower/spill/, а в контексте остаётся одна строка с путём. Обрезка происходит сразу, а не потом, когда контекст уже полон.
• Workbench workbench — три каталога scripts/, artifacts/, notes/ внутри .flower/ плюс индекс INDEX.md, внедряемый в system prompt, — поэтому agent в каждом раунде знает, что у него под рукой. В том прогоне HT001 накопилось 61 скрипт, выполненных 331 раз, причём 92 % из них запускались больше одного раза.

Чего flower не делает¶

Первое: он не даёт готовых workflow. Фреймворк отвечает только за механику: как выполняется шаг, как экономится контекст, как продолжить после обрыва сети, как не подраться при параллельной правке одного репозитория, как остановиться, когда нужно спросить человека. Workflow пишете вы. Те три шага голого flower берутся из flower/workflow/starter.py и настолько универсальны, что не содержат никаких предметных допущений — это стартовая точка для вас, а не граница возможностей фреймворка. Как написать свой — см. проектирование workflow.

Второе: он не наследует конфигурацию хост-машины. flower работает с setting_sources=[]: он не читает ~/.claude/ хоста и не читает .claude/ проекта. Это и есть переносимость — на другой машине поведение будет тем же. Предметные способности приезжают plugin'ами, которые лежат в репозитории, а не тем, что случайно оказалось установлено на этой машине.

Третье: учётные данные вы приносите сами. Это цена второго пункта. flower ищет учётные данные в фиксированном порядке (переменные окружения процесса → $FLOWER_ENV → .env в текущем каталоге → ~/.config/flower/.env → .env в корне репозитория с исходниками), и в последнюю очередь занимает те 9 ключей из блока env в ~/.claude/settings.json как запасной вариант — занимает ровно одну вещь: «где искать token», а всё остальное в settings.json на поведение agent'а не влияет. Полный порядок и семантика каждой переменной — в справочнике конфигурации.

Четвёртое: он не заменяет системный prompt. Предметные инструкции надстраиваются после нативного системного prompt'а Claude Code, а не подменяют его. Поэтому специализация не покупается ценой потери общих способностей.

Дочитав до этого места, вы должны понимать весь вывод из быстрого старта. Если хотите знать, как настраивается каждый из этих механизмов и когда его не стоит применять, читайте дальше с экономики контекста; если нужно просто скопировать команды — идите в справочник CLI.