AIエージェントの多段ワークフローを「1つのYAML」で宣言的に動かす — flowsmith の設計

• URL: https://zenn.dev/kikaikaya/articles/flowsmith-declarative-ai-workflow
• 日付: 2026-06-12
• Tier: Tier 3
• 要旨: Claude Code向けのワークフローエンジン「flowsmith」の設計記録。「セッション途中死で全やり直し」「LLMの自己申告合否が信用できない」「コストが見えない」という3つの問題に対し、宣言的YAML・機械ゲート・状態のディスク永続化で解決。レガシー調査15ステップを35分で完走した実績あり。

詳細

解決した3つの問題:

1. セッション死で全やり直し → 状態をディスクに置き、ステップ・行単位で記録して再開
2. LLMの合否が信用できない → 合否判定をYAMLルールで機械適用（LLMに決めさせない）
3. コストが分からない → run.jsonlで全ログ（所要時間・トークン）を記録

設計判断1: 合否をLLMに決めさせない

• checkerが返すのは観点ごとの構造化判定（{id: V01, verdict: pass}）のみ
• 総合合否はエンジンがpass_when: no_high_fail等のルールを機械適用して決定
• さらに機械ゲート（ファイル存在確認・必須見出し・行数チェック）を先に走らせ、落ちたらLLMレビューに進ませない

設計判断2: 状態をディスクに永続化

• state.jsonをステップ・行単位で更新
• 再実行時は完了分をスキップして続きから再開
• 200件処理の150件目で死んでも残り50件だけ再開可能

設計判断3: 行き詰まったら止まる（seized）

• 推測で進まず、「どの観点が・何回・どんな根拠で通らなかったか・人間の選択肢は何か」を出して裁定を人間に返す
• 上限を超えた反復は必ずseizedになる（無限ループが構造的に存在できない）

面白いバグ: 差し戻しの誤読

• 不合格理由を「あるべき姿の説明」と誤読して「変更不要」と返してくるケースが発生
• 解決: 「上記は『解消すべき不足』であり『現状の説明』ではない。変更不要は禁止」と明示することで安定

教訓: マルチエージェントの結合部では、情報の「内容」だけでなく「フレーミング」が動作を決める