コアコンセプト¶

flower には独自の語彙がある。実行、ステップ、セッション、コーディネーター、ワーカー、事前確認、ゴールガード、継続、ハンドオフ。 このページでそれらを一度に説明しきる。読み終われば、他のページを読みながら推測する必要はなくなる。5 分で読める。

ここで扱うのは概念だけで、API シグネチャは出さない —— シグネチャは Python API、 一行定義と中英対照は用語集、コマンドラインのオプションは コマンドライン リファレンスを見てほしい。

1 回の実行はどんな形をしているか¶

大きい順に 3 階層:

この 3 つの入れ子関係は 1 対 1 対応ではない:

実行 ── あなたが叩いたこの 1 回の flower
 ├── ステップ 要件確認 ──── セッション A
 ├── ステップ 目標設定 ──── セッション B
 └── ステップ 実作業 ────── セッション C ──[コンテキストが満杯間近]──> セッション C'
      └── 実作業・判定#1 ─ セッション D

• 1 つのステップが複数のセッションを焼き尽くすことがある。 コンテキストが満杯間近になったとき、compact せずに ハンドオフ文書を書き、新しいセッションを開いて引き継ぐ —— これがハンドオフで、同一の実行の内部で起きる。
• 新しい実行が古いセッションに接続できる。 同じディレクトリでもう一度 flower を叩くと、各ステップは前回のセッションに戻る —— これが継続で、プロセスをまたいで起きる。runs/lineage.json が「どのステップ名がどの session_id に対応するか」を覚えている。
• 判定のラウンドは常に新しいセッション。 継続もしないしリネージにも入らない —— 「終わったかどうか」を判定する者が、いま作業したワーカーであってはならない。

順に連ねた一連のステップをワークフローと呼ぶ。 flower を素で走らせると、フレームワーク同梱の 3 ステップのワークフローが使われる:要件確認 → 目標設定 → 実作業。

分業:コーディネーターは手を動かさない¶

これがこのフレームワーク全体の土台となる一条だ。

コーディネーターはメインスレッド上の agent だ。 タスクを分解し、割り振り、報告を読み、意思決定をする —— しかし Write と Edit は持たない。 Bash も ls や git status のような使い捨てコマンドをちらっと見る程度しかできない (hook が門番をしており、プロンプトによる制約に頼らない。しかもこの種の結果は永続化されるセッション記録に入らない)。 ツール一覧は Agent、TodoWrite、Read と、その制限された Bash だけ。

実際に手を動かすのはワーカー —— Agent ツールで派遣される subagent だ。

なぜこう分けるのか。 subagent は自分専用の transcript を持つ:何個のファイルを読んだか、テストを何回走らせたか、 試行錯誤でどれだけ回り道したか、すべてそこに記録される。メインスレッドが受け取るのは最終報告だけだ。そしてメインスレッドは実行全体を貫く唯一のコンテキストであり、 だからこそ最も節約すべき 1 本になる。

実測(HT001、10.4 時間の実行 1 回):

1 回派遣するごとに、平均 82 回のツール呼び出しをメインスレッドはまったく見ていない。これがコンテキスト節約の第一層であり、最も節約できる層でもある。 完全な論証はコンテキストの経済学を参照。

誤解されやすい点が 2 つ:

• コーディネーターはより賢い agent ではない。 ワーカーとデフォルトで同じモデル階層を使う。節約しているのはコンテキストであってモデルではない。
• 返答フォーマットは制約されている。 ワーカーの返答はちょうど 4 節 —— 結論 / 根拠 / 産出物 / 未検証、30 行を超えない。 ファイル内容、コマンド出力、ログ、diff の原文を貼ることは禁止。長いものはワークベンチの artifacts/ に書き、返答にはパスだけを載せる。

flower のロールは全部で 5 つ。どれも同じ作り方だ:注入される規則テキスト 1 本 + ツール 1 組 + hook 1 組。

ファクトリ関数の引数とデフォルト値は Python API を参照。

long-horizon は 4 か所で壊れる¶

1 回の long-horizon な実行は数時間から数日にまたがり、複数のセッションをまたぎ、プロセスの再起動をまたぐ。 崩れ方はそう何通りもない。それぞれに機構が 1 つ対応している:

単独で覚えておく価値のある点が 2 つ:

判定の結論は 3 種類であって 2 種類ではない。 達成、未達、この環境では検証できない。 後ろの 2 つは異なる結論だ —— 「ここでは検証できない」は絶対に合格と判定せず、立ち止まって人に聞く。 さらに判定者が判定するのは産出物であって、ソースコードではない。HT002 で一度これに転んだ: Makefile の macOS ブランチだけを見て合格と判定したが、実際に納品されたのは Linux の ELF だった。

ハンドオフは compact ではない。 compact はモデルが見えないところで前の会話を要約 1 段に潰すもので、 読めず、直せず、何が失われたかも分からない。ハンドオフ文書は構造化されていてディスク上に落ちており、開いて 1 行直してから続きを走らせられる。 flower はネイティブの auto-compact をデフォルトで切り、ハンドオフで代替する。

この表には載っていないが、毎回の実行で動いている層があと 2 つある:

• スピル spill —— ツール結果が 4000 文字を超えたら .flower/spill/ に書き、 コンテキストにはパス 1 行だけを残す。その場で切る。満杯になってから遡って compact するのではない。
• ワークベンチ workbench —— .flower/ 配下の scripts/、artifacts/、 notes/ の 3 ディレクトリと、system prompt に注入される INDEX.md インデックス 1 枚。だから agent は毎ラウンド、手元に何があるかを把握している。 HT001 では 61 個のスクリプトが貯まり、331 回実行された。うち 92% は 2 回以上実行されている。

flower がやらないこと¶

1. 出来合いのワークフローは提供しない。 フレームワークが面倒を見るのは機構だけだ:1 ステップをどう走らせるか、コンテキストをどう節約するか、ネットワークが切れたときどう継続するか、 並行して同じリポジトリを変更してもぶつからないようにするにはどうするか、人に聞く必要があるときにどう止まるか。ワークフローはあなたが書く。 flower を素で走らせたときのあの 3 ステップは flower/workflow/starter.py に由来し、いかなるドメイン仮定も含まないほど汎用だ —— 出発点として用意されたものであって、フレームワークの能力の境界ではない。 自分で書くならワークフローの設計を参照。

2. ホストマシンの設定を継承しない。 flower は setting_sources=[] で走る:ホストの ~/.claude/ も読まず、 プロジェクトの .claude/ も読まない。これがポータブルということだ —— マシンを変えても挙動が同じ。 ドメイン能力はリポジトリと一緒に移動する plugin で持ち込む。このマシンにたまたま何が入っているかには依存しない。

3. 認証情報は自前で持ち込む必要がある。 これが 2 番目の代償だ。flower は固定の優先順位で認証情報を探す(プロセス環境変数 → $FLOWER_ENV → カレントディレクトリの .env → ~/.config/flower/.env → ソースリポジトリ root の .env)。 最後に ~/.claude/settings.json の env ブロックから、あの 9 個の認証キーをフォールバックとして借りる —— 借りるのは「token をどこに探しに行くか」という 1 点だけで、settings.json の他のいかなる内容も agent の挙動には影響しない。 完全な順序と各変数の意味は設定リファレンスを参照。

4. システムプロンプトを置き換えない。 ドメイン指示は Claude Code のネイティブなシステムプロンプトの後ろに append されるのであって、それを差し替えるのではない。だから専門化は汎用能力を犠牲にしない。

ここまで読めば、クイックスタートにあった出力はすべて読めるはずだ。 これらの機構をそれぞれどう調整するか、どういうときに使うべきでないかを知りたければ、コンテキストの経済学から読み進めてほしい。 コマンドだけ写したいならコマンドライン リファレンスへ。