はじめに
Claude Codeを使うと、自然言語で依頼した内容をもとに、調査からコードの変更まで進められます。
一方で、機能を完成させるには、実装の前後にもさまざまな仕事があります。
- 何を満たせば完成なのかを決める
- 不明点や対象外の範囲を整理する
- 必要に応じて作業を分割する
- 変更内容をレビューする
- テストや画面操作で結果を確認する
- レビュアーに確認してほしい点をPRにまとめる
例えば、「会員一覧にCSV出力を追加して」と依頼した場合でも、「表示中のページだけか、検索条件に一致する全件か」という違いがあります。ここが曖昧なままだと、コードが動いていても、欲しかった機能とはずれてしまいます。
こうした開発の各工程をつなぐための選択肢が、Flow-Nextです。
この記事では、Claude CodeでFlow-Nextを使う場合を中心に、基本的な考え方と導入手順、具体的な依頼の組み立て方を紹介します。
本記事は2026年11月16日に確認した公式リポジトリ・ドキュメントをもとにした導入ガイドです。会員管理画面の要件や仕様は説明用の作例です。
Flow-Nextとは
Flow-Nextは、Gordon Mickel氏が公開している、コーディングエージェント向けのOSSワークフロープラグインです。1
Claude Codeなどのエージェント上で動き、依頼内容に合わせて、仕様の作成、実装、設定されたレビュー、検証、PR作成といった工程を進めます。
入口になるのは、次のコマンドです。2
/flow-next:flow 会員一覧にCSV出力機能を追加してください。
ここに渡せるのは、新機能のアイデアだけではありません。不具合報告、性能改善の依頼、既存コードに対する質問なども扱います。
依頼の種類によって、最初に必要な作業は変わります。
| 渡す内容 | 進め方の例 |
|---|---|
| 新機能の要件 | 必要な仕様を整理して実装へ進む |
| 不具合報告 | 再現と原因確認を行い、修正前後で結果を確かめる |
| 遅い画面や処理 | 改善前の状態を計測し、変更後と比較する |
| 既存コードへの質問 | コードや履歴を調べ、根拠を示して回答する |
この振り分けは、依頼内容と現在の作業状態をもとに行われます。質問への回答など、コードの変更を伴わない経路もあります。3
仕様と作業の状態をファイルに残す
Flow-Nextでは、仕様やタスクの状態を、リポジトリ内の .flow/ 配下に保持します。新しいセッションや別のエージェントも、その記録を参照できます。2
主な保存先には、次のようなものがあります。
| 保存先 | 主な内容 |
|---|---|
.flow/specs/ |
目的、受入条件、対象範囲などの仕様 |
.flow/tasks/ |
実装を進めるためのタスク情報 |
.flow/review-receipts/ |
レビューの判定や指摘に関する記録 |
仕様・タスクの出力はPlanのドキュメント、レビュー記録はReceiptsのドキュメントで確認できます。45
会話だけに要件が残っていると、後から参加した人が、どこまで合意したのかを追うのに時間がかかります。仕様がファイルになっていれば、「今回の変更で何を満たすべきか」を確認する場所ができます。
私がこの仕組みで大切だと考えるのは、実装を始める前に、完成の条件を読み返せることです。ファイルが作られた段階で、依頼の抜けや解釈の違いを確認できます。
Claude Codeへの導入
用意するもの
公式ドキュメントでは、Python 3.11以上、コーディングエージェントとモデルの利用環境、プロジェクトをビルド・テストするためのツールが前提になっています。
レビューやPR連携では jq などを使用し、GitHubでPRを作る場合は、認証済みの gh が必要です。別モデルによるレビューや実アプリのQAには、それぞれ利用可能なレビュー環境や操作用ドライバーも必要になります。6
プラグインをインストールする
プロジェクトを開いたClaude Codeの会話欄で、次の順に実行します。
/plugin marketplace add https://github.com/gmickel/flow-next
/plugin install flow-next
/reload-plugins
/flow-next:setup
セットアップでは、.flow/ の初期化やレビュー環境の設定を行い、CLAUDE.md や AGENTS.md にFlow-Nextの案内を追加します。6
セットアップ後は、変更されたファイルと設定を確認しておきます。特に、レビューにどの環境を使うかは、その後の実行結果を読むためにも把握しておきたい点です。
まずは進め方を確認する
すぐに作業を実行する前に、選ばれる経路を確認することもできます。
/flow-next:flow --explain 会員一覧に、現在の検索条件に一致する全件をCSV出力する機能を追加したい。
--explain を付けると、どの経路を選ぶか、その理由や省略する工程を表示します。この確認ではファイルを書き換えません。3
例えば、機能追加として仕様の整理から始めるのか、小さな修正として直接変更するのかを確認できます。
毎回すべての工程を通す必要はありません。まとまった仕様をそのまま実装できる場合は直接実装する経路が基本になり、作業分割を依頼した場合などに計画作成を挟みます。7
実例:会員管理画面にCSV出力を追加する
ここからは、各工程で確認する内容を追うため、個別のコマンドを使って説明します。普段の作業では /flow-next:flow に依頼を渡し、必要な工程を選ばせる使い方もできます。
1. 目的と条件を仕様にする
会話の内容を仕様として保存する工程が、capture です。8
/flow-next:capture
会員管理画面にCSV出力機能を追加するため、仕様を整理してください。
目的:
管理者が、検索結果を社内の集計作業に使えるようにする。
要件:
- 管理者のみ利用できる。API側でも権限を確認する。
- 現在の検索条件に一致する全会員を出力する。
- 画面のページ分割に関係なく、対象データを全件出力する。
- 列は、会員ID、表示名、メールアドレス、登録日とする。
- 対象が0件の場合も、ヘッダー行を含むCSVを出力する。
- 既存の一覧表示と検索の動作を維持する。
今回の対象外:
- 定期実行
- 外部サービスへの自動保存
「CSV出力を追加する」という依頼を、確認できる条件まで具体化しています。
例えば、「全件出力」という言葉だけでは、全会員なのか、検索結果の全件なのかが曖昧です。「現在の検索条件に一致する」「ページ分割に関係なく」と書くことで、期待する挙動が明確になります。
仕様を確認するときは、次のような受入条件になっているかを見ます。以下は、読み方を説明するために整理した例です。
## 受入条件の例
- R1: 管理者のみCSV出力を利用でき、APIでも権限を確認する。
- R2: 現在の検索条件に一致する全件を、ページ分割に関係なく出力する。
- R3: 指定した4列を出力する。
- R4: 対象が0件の場合もヘッダー行を出力する。
- R5: 既存の一覧表示と検索の動作を維持する。
Flow-Nextでは、受入条件に付けたR-IDを、タスクや要件の対応関係を追うために使います。4
また、Captureが作成した条件には、依頼の言い換えを表す [paraphrase] や、エージェントの推論を表す [inferred] などの出所が示されます。8
特に確認したいのは、推論で追加された条件です。自然に見える内容でも、業務として合意していない仕様が含まれている可能性があります。
今回の例なら、文字コード、CSV内の改行や引用符の扱い、大量データ時の上限なども確認候補になります。必要な条件を確定してから、実装へ進みます。
2. 仕様をもとに実装する
仕様を確認したら、実装を進めます。
以下の fn-1 は説明用のIDです。実際には、作成時に表示された仕様IDを指定してください。
/flow-next:work fn-1 --no-plan
--no-plan は、事前にタスク分割する工程を挟まず、仕様全体を実装する経路です。仕様に書かれた受入条件や、設定された検証・レビューは引き続き対象になります。7
実装前にタスク分割を確認したい場合は、先に次の工程を実行します。
/flow-next:plan fn-1
Planでは、受入条件と対応するタスクを整理します。4
ここで見たいのは、タスクの数よりも、どの作業が、どの受入条件を満たすのかです。CSVのダウンロードボタンだけが実装されても、全件取得やAPIの権限制御が抜けていれば、今回の機能は完成していません。
3. レビューが実行されたかを確認する
Flow-Nextでは、設定したレビュー用バックエンドを通してレビューを実行できます。実装とは別のモデル系列を使う構成も選べますが、実際の独立性は、選択したモデルによって変わります。9
プラグインを導入しただけで、すべての変更にレビューが付くとは限りません。レビューを無効にした設定や、軽微な変更として省略される経路もあります。7
実行結果では、各工程が次のように表示されます。
ran
skipped(<reason>)
failed(<reason>)
実行された工程だけでなく、省略された工程とその理由も確認できます。2
今回のCSV出力であれば、レビューでは次の点に注目します。
- 表示中のページだけを出力していないか
- 画面のボタンを隠すだけで、権限制御を済ませていないか
- 検索条件がCSV出力時にも適用されているか
- カンマや改行を含むデータでも、列が崩れないか
これらは、仕様と変更内容を照らして読むための観点です。レビューの文章に加え、何を実行して確かめたかも確認します。
4. 起動したアプリを操作して確かめる
Flow-Nextには、起動中のアプリを実際に操作して確認する、Live QAの工程もあります。仕様の受入条件をもとにシナリオを作り、画面操作や取得した証拠から結果を判断します。10
プロジェクトの手順でアプリを起動し、対応する操作用ドライバーが利用できる状態で、例えば次のように実行します。
/flow-next:qa fn-1 --target http://localhost:3000
今回の例なら、検索条件を設定してからCSVをダウンロードし、ページをまたぐデータも含まれるかを確認する、といった操作が考えられます。
Live QAは、パイプラインの初期設定では無効です。 必要に応じて有効化するか、個別に呼び出します。また、CIやステージング環境、人間による確認と組み合わせて使う位置付けです。10
5. 確認内容をPRにまとめる
変更内容と検証結果を確認したら、PRを作成します。
まず本文だけを確認したい場合は、--dry-run を使えます。
/flow-next:make-pr fn-1 --dry-run
PRを作成する場合は、次を実行します。
/flow-next:make-pr fn-1
後者はブランチをpushし、PRを作成します。PR本文には、レビュアーが注目する場所、受入条件との対応、未確認の項目などがまとめられます。11
ここでも、「テスト済み」という一言より、次のように条件と結果を対応させると確認しやすくなります。
| 受入条件 | 確認したい証拠の例 |
|---|---|
| 管理者のみ利用できる | 管理者以外のAPI呼び出しが拒否されるテスト |
| 検索結果を全件出力する | 複数ページ分のデータで件数を確認した結果 |
| 指定した列を出力する | ヘッダーと各行の値を確認したテスト |
| 0件でも出力できる | ヘッダー行だけのCSVを確認した結果 |
この表は作例ですが、PRを読む側の確認順序を考えるうえで役立ちます。
レビュー結果を記録する「Receipt」
Flow-Nextの特徴の一つが、レビュー結果をJSONとして残す Receipt です。
レビューを実行した環境、判定、今回の変更で生じた指摘、未解決の項目などが記録されます。代表的な判定は次のとおりです。5
| 判定 | 意味 |
|---|---|
SHIP |
今回の変更で生じた、引き渡しを妨げる指摘が残っていない |
NEEDS_WORK |
修正が必要な問題が残っている |
MAJOR_RETHINK |
仕様や設計方針を見直す必要がある |
NEEDS_HUMAN |
人間による判断が必要 |
Receiptを読むときは、判定に加え、未解決の指摘や検証状態も確認します。記録が見つからない状態は、合格と扱いません。5
「何を確認して、その判断に至ったのか」を追えることが、この記録の価値だと考えています。
導入するときに確認したいこと
最初は、小さな機能を一つ選び、仕様、変更差分、検証結果、PRの対応を追うと、Flow-Nextの役割を把握しやすくなります。公式の入門ガイドも、一つの変更を通して使い方を確認する構成です。12
実際の運用では、次の点を確認しておくとよさそうです。
- 生成された受入条件が、業務の期待と一致しているか
- レビューにどのモデル・環境を使うか
- テストやアプリの起動方法を、エージェントが把握できるか
- 未確認の項目が、PRで読み手に伝わるか
レビューの追加や複数の作業担当、Live QAには、エージェントの追加処理が発生します。利用するモデルの契約や利用枠も含めて、必要な工程を選びます。6
Flow-Nextが整えるのは、依頼を受けてから結果を確かめるまでの進め方です。どの機能を作るか、受入条件が適切かという判断は、引き続き人間が担います。2
おわりに
Flow-Nextを使うと、会話から仕様を残し、その仕様をもとに実装し、レビューや検証の結果をPRへつなぐ流れを組み立てられます。
導入する際は、生成された仕様を一度読み、完成の条件が具体的になっているかを確かめてみてください。そこが明確になれば、実装後に何を確認すべきかも見えてきます。
コードの変更だけでなく、その変更が依頼を満たしていると確認できるところまで、開発の流れを整えたいときに検討したいツールです。