用語集¶

このページは flower ドキュメントの用語基準です。同じものは全サイトで一つの呼び方しかせず、中英対照はここで固定します —— 翻訳版もこの表に従います。

各項目で三つのことを示します:その語が何を指すか、コード上では何か、何ではないか。三つ目が一番役に立つことが多い。誤解のほとんどは、ある語を別の語と取り違えることから生まれるからです。

フレームワークと run¶

long-horizon¶

long-horizon

一回の run が数時間から数日にわたり、複数の session をまたぎ、プロセス再起動をまたぐ —— 一問一答ではない。flower のすべての機構は、この種の run が途中で崩れないためにあります。

実測の参照:HT001 は連続で 10.4 時間走りました。

run¶

run

一つの Runtime が開始から終了までたどる全過程。一回の run の内部には複数のstep、複数のsessionがありえて、中断してからcontinuityで続けられます。run の記録は runs/manifest.json と runs/sessions.db に残ります。

そうではないもの:1 回の API 呼び出しでも、1 本の session でもありません。

session¶

session

モデル側のコンテキスト 1 本。自分の session_id を持ち、resume でき、fork できます。一回のrunは session を何本も焼き潰すことがあります —— handoff のたびに新しい 1 本に切り替わります。

step¶

step · Step

workflow の中の実行単位。コンテキスト辞書を受け取り、agent を 1 回走らせ、結果を辞書に書き戻します。Step はクラスです。Python API を参照。

workflow¶

workflow · Workflow

順番に連ねたstepの集合と、step 間で状態をどう渡すか、いつ早期終了するかの取り決め。

役割¶

役割は flower における agent の分業です。各役割 = 注入されるルールテキスト 1 本 + ツール一式 + hook 一式。5 つの役割はすべてファクトリ関数です。Python API を参照。

coordinator¶

coordinator · coordinator()

main thread 上にいる agent。タスクを分解し、仕事を割り振り、報告を読み、判断を下す。しかし自分では手を動かさない —— Write / Edit を持ちません。基本ツールは Agent、TodoWrite、Read(roles.py:27)ですが、それが最終的な一覧ではなく、引数に応じて 3 種類が追加されます:glance=True(デフォルト)は制限付きの Bash を足し(git status / ls のような一目見て終わるコマンドだけ、delegate_guard が門番)、質問チャネルを渡すと inbox と ask が足され、配下のworkerが WebFetch / WebSearch を持つならこの 2 つも合流します —— allowed_tools はsession 単位なので、合流させないと subagent が自分で呼んだときに誰も応答しない権限承認で固まります(roles.py:513-526)。

役割設定は「Claude Code を使える人」であって、実行者ではありません。

そうではないもの:より賢い agent ではありません。worker とデフォルトで同じモデル階層を使い、節約しているのはコンテキストであってモデルではありません。

worker¶

worker · worker()

実際に手を動かす subagent:コードを書き、テストを走らせ、資料を調べる。ツールは Read Write Edit Bash Glob Grep WebFetch WebSearch。

返答フォーマットはルールテキストで 4 段に固定されます —— 結論 / 根拠 / 成果物 / 未検証、30 行以内、ファイル内容・コマンド出力・ログ・diff 原文の貼り付けは禁止。

clarifier¶

clarifier · clarify()

手を動かす前に要求を問い詰める役割。仕事はせず、質問だけをし、明確になるまで問う(ラウンド数の上限なし)。最後にbriefを 1 部出力します。clarify を参照。

judge¶

judge · judge()

「終わったかどうか」を判定する役割。次の 2 つのうち 1 つを行います:走り出す前に目標を設定する(目標 + 判定チェックリストを産出)、または各ラウンド終了後にそのラウンドを判定する(verdict を産出)。goal guard を参照。

要点:judge が判定するのは成果物であって、ソースコードではありません。

HT001 で一度転んでいます:受け入れ基準は「macOS ターミナルで直接実行できること」だったのに、納品された成果物に file をかけると ELF 64-bit LSB pie executable, ARM aarch64, GNU/Linux、それでも判定は合格でした。

2 点はっきりさせておかないと、この例は誤読されます:

1. あのとき誤判したのは goal guard ではない —— HT001 にはまだこの機構がなく、誤判したのは coordinator が自発的に派遣した監査役でした。
2. デフォルト設定の judge でも、おそらく同じく見逃します。 judge() はデフォルトで can_run=False、ツールは Read/Glob/Grep のみ —— file を走らせられません。Makefile を読んで確かに Darwin ブランチがあると確認し、達成と判定するだけです。

本当に効いたのは HT002 です:judge が judge_can_run を有効にし、自分で file と lsof を走らせて現場を見に行き、この落とし穴を明確に回避しました。つまり「成果物を判定する」という一文は、can_run=True があって初めて地に足がつきます。

oracle¶

oracle · oracle()

読み取り専用のバイパス 1 本。run が走っている最中に「今どこまで進んだ?」と聞くと、直近の event とworkbenchを一目見てから答えます。その発言はその run のコンテキストには入りません —— 聞いても run に影響せず、答えたら捨てられます。

subagent¶

Claude Agent SDK の概念:主 agent が Agent ツールで派遣する子 agent。自分自身の transcript を 1 本持ち、ツール呼び出しも試行錯誤もそちらに記録され、main thread は最終報告だけを受け取ります。

これは flower がコンテキストを節約する第一層であり、最も節約量の大きい層でもあります。コンテキスト経済学 を参照。

4 つの機構¶

clarify¶

clarify

手を動かす前に要求を問い詰め、brief 1 部に凍結してから実行を始める。防いでいるのは「作ったものが望んだものではない」です。clarify を参照。

brief¶

brief · Brief

clarifier が問い終えた後に産出する文書。ちょうど 4 段。後続の step はこれを読み、要求を推測し直しません。

task brief と混同しないこと。brief は「人が何を望むか」、task brief は「この subagent が今回何をするか」です。

task brief¶

task brief

coordinator が仕事を割り振るとき、worker に書いて渡す文章。今回のタスク固有のことだけを書く —— 相手がすでに知っている規律を繰り返さない。

実測:8/8 部の task brief が相手の既知の規律を繰り返しており、最短の 1 部は 521 文字のうち約 120 文字だけがタスク固有、1 ラウンドで約 4.8k の永久コンテキストを無駄に占めていました。

goal guard¶

goal guard

judge が各ラウンド終了後に独立して目標達成を判定し、未達なら差し戻して続行させる。防いでいるのは「終わったと言うが実は終わっていない」です。goal guard を参照。

verdict¶

verdict · Verdict

judge の 1 ラウンドの判定結果。ちょうど 3 段:結論 / 理由 / 未通過。

結論は 3 種類、ACHIEVED(達成)、NOT_YET(未到達)、UNREACHABLE(この環境では検証できない)。後の 2 つは別の結論です —— 「ここでは検証できない」は絶対に合格と判定しません。

continuity¶

continuity

同じディレクトリでもう一度走らせると、前回の進捗に自動で接続する —— プロセスが kill されても、マシンが再起動しても同じ。防いでいるのは「数時間走って落ちたら最初からやり直し」です。continuity を参照。

handoff と混同しないこと:continuity はプロセスをまたいで前回の run に接続すること、handoff は同じ run の内部で新しい session に切り替えることです。

handoff¶

handoff

コンテキストが満杯に近づいたら、今の session に人が読めて直せるhandoff documentを書かせ、新しい session を立てて引き継がせる。防いでいるのは「コンテキストが満杯になって要約一段に潰される」ことです。handoff を参照。

compact ではありません。 compact を参照。

handoff document¶

handoff document · Handoff

handoff のときに書く文書。5 段:doing(何をしているか)、decided(何を決めたか)、deadends(通らなかった道)、next(次の一手)、scene(現場)。

必須は doing と next だけ —— 「通らなかった道」を必ず非空にしろと強制すると、モデルが捏造します。

compact¶

compact

Claude Code のネイティブなやり方:コンテキストが満杯になったら、それまでの会話を要約 1 段にまとめる。

flower はこれを使わず、handoff で代替します。違いは:要約はモデルが生成したもので、読めず直せず、何を捨てたかわからない。handoff document は構造化され、ディスクに落ち、開いて 1 行直してから続きを走らせられます。

コンテキスト管理¶

main thread¶

main thread

coordinator がいる session コンテキスト。run 全体を貫く唯一のコンテキストなので、最も節約が必要です。

コード上で main thread を判定する方法:hook データに agent_id がないこと。subagent の hook には agent_id が付きます。

workbench¶

workbench · Workbench

ディスクに落ちた作業ディレクトリ。サブディレクトリは 3 つ:

INDEX.md はこの 3 ディレクトリのインデックスで、system prompt に注入されるため、agent は毎ラウンド手元に何があるかを把握します。

spill¶

spill

ツール結果がしきい値(デフォルト 4000 文字)を超えると、PostToolUse hook がそれを <workbench ルート>/spill/ に書き出し、コンテキストにはパス 1 行だけを残します。

パスはworkbench に追従し、固定ではありません —— workbench がデフォルト位置 <ワークスペース>/.flower にあるときだけ、ちょうど .flower/spill/ になります。isolation を有効にして workbench を home= でリポジトリ外に指したときは、spill も一緒に外へ移ります。

その場で剪るのであって、コンテキストが満杯になってから振り返ってcompact するのではありません。

ephemeral command¶

ephemeral command

結果が期限切れになり保存価値のないコマンド —— ls、git status、ps の類。その結果は永続化される session 記録に入りません。「main thread に一目見に行かせてよいか」と「結果が trim されるか」の判断には同じ関数を使うので、2 つの集合は常に等しくなります。

trim¶

trim · TrimmingSessionStore

resume の前に、モデルへ戻すメッセージ一式を書き換えます(ephemeral commandの結果、超長のツール出力)。

これは load() だけをオーバーライドします:SQLite 内の原文は一切動かさず、trim されるのは今回の resume でコンテキストへ送る分だけです。つまり trim は可逆です —— 方針を変えてもう一度 resume すれば、また完全な記録が得られます。

prune¶

prune · PruningSessionStore

エラーメッセージをコンテキストの外に締め出します。ネットワーク断のリトライ中に生じた大量のエラーが、resume 後のコンテキストを占めるべきではありません。

trim と混同しないこと:trim は体積と価値で捨て、prune は「エラーかどうか」で捨てます。

ランタイム¶

isolation¶

isolation

印を付けた役割は自動で独立した git worktree に割り当てられます。hook が強制し、プロンプトには頼りません。同じリポジトリを並行で変更してもぶつかりません。

resilience¶

resilience · Resilience

ネットワークが切れたら失敗終了せずにぶら下がって待ちます:DNS + TCP プローブが見張り、回線が戻ったら resume して続行します。待機中に生じたエラーメッセージはprune がコンテキストの外に締め出します。

lineage¶

lineage · Lineage

「この run はどの session から fork したか」をプロセスをまたいで記録し、lineage.json に落とします。continuity はこれを頼りに前回どこまで走ったかを見つけます。

run manifest と混同しないこと —— あちらは runs/manifest.json で、各 run の帳簿を記録します。

run manifest¶

run manifest · runs/manifest.json

各runの帳簿記録:いくら使ったか、どれだけ走ったか、コンテキストがどれだけ大きかったか。ケースページの数字はすべてここで再計算できます。

wake¶

wake · wake_state()

走り出す前の読み取り専用の探査:このワークスペースにすでにbriefと目標があるかを見て、今回が新規開始かcontinuityかを決めます。1 バイトも書きません。

wake_state() は workbench の位置の唯一の定義箇所です —— ドライバが brief の在り処を知りたいときも、ここを通す必要があります。自分でパスを組み立てて間違えてもエラーにはならず、静かに機能しなくなるだけです。

event¶

event · Event

SDK のメッセージストリームを平坦化した安定構造。interaction layer は Event しか知らず、SDK の型を一切 import しません —— これが UI を差し替えてもコアを直さずに済む境界です。

interaction layer¶

interaction layer

人と run の間にある UI の層。デフォルトはターミナル、Web、TUI、HTTP に差し替えられ、完全自動の無人運転にもできます。interaction layer を差し替える を参照。

session store¶

session store · SessionStore

session メッセージの永続化バックエンド。デフォルトの SqliteSessionStore は runs/sessions.db に書き、trim とprune の 2 層でラップできます。

budget¶

budget · max_budget_usd

1 回の run の費用上限。超えたら停止します。long-horizon な run はこれがないと非常に高くつきます —— HT001 は $171.62 かかりました。

可搬性¶

portable¶

portable

別のマシンに移しても挙動が同じ。やり方は setting_sources=[] —— ホストマシンの ~/.claude/ を読まず、プロジェクトの .claude/ も読みません。ドメイン能力は plugin がリポジトリと一緒に移動し、資格情報は .env で自前で持ちます。

代償:資格情報は自前で用意する必要があり、ホストマシンの設定を自動継承しません。

append¶

append

ドメイン指示は Claude Code ネイティブの system prompt の後ろに追記され、置き換えません:

system_prompt = {"type": "preset", "preset": "claude_code", "append": spec.instructions}

だから専門化は汎用能力の喪失を代償にしません。

plugin¶

リポジトリと一緒に移動するドメイン能力パッケージ。plugins=[local] で読み込み、ディレクトリには skills/、agents/、hooks/、.mcp.json を置けます。デプロイ を参照。