ff-dev-toolkitの実例：AIにルールを守らせ、経験を次の開発へ残す

「社内ルールをAIへ配る仕組みは分かった。では、その中に何を書けばよいのか」。第1回と第2回で扱った配布の話を、自社の開発へ持ち帰るときに残る問いです。

私たちは、開発全般に使う手順を ff-dev-toolkit というプラグインにまとめています。2026年10月28日に確認した公開版v0.169.0には、28のSkillsと、仕様書を検索・取得するMCP（Model Context Protocol）サーバー spec-docs が含まれます。この記事では、その機能を順に紹介するのではなく、何を判断させ、どの失敗を止め、経験をどう次へ残すかという設計を説明します。

想定読者は、AIコーディングエージェントをチームへ導入し始めた開発リーダー・CTOです。公開ソースで確認できる3つの実例と、私たちが自社で採用している知見の蓄積、OSS（オープンソースソフトウェア）公開の境界を取り上げます。

Skillsに手順を置き、判定できる部分を検査へ移す

Skillsは、エージェントが読む手順書です。目的、判断基準、必要な証拠、失敗したときの戻り先を書けます。ただし、文章に「必ず確認する」と書くことと、確認しなければ操作が止まることは別です。

そこで、機械で判定できる条件はhooksや検証スクリプトへ移します。hooksはツール実行などの前後に呼ばれる処理で、対応する操作なら、実行前に拒否する検査を置けます。ここでいう「強制」は、その検査が動く範囲に限ります。導入しただけで、すべての実行環境や操作が同じように制約されるわけではありません。実行環境ごとの差は第2回の動作確認表で整理しています。

ff-dev-toolkitの spec-driven は、要件・仕様・計画・実装・検証をG0〜G4の5段階に分け、各段階で何を揃えるかを定めています（ゲートの判定基準）。この枠組みの中で、判断を文章に残す部分と、操作を検査する部分を分けています。

実例1：Issueの「完了」を、観測できる条件にする

「フォームを改善する」だけでは、AIが何を作れば終わりなのか決まりません。create-issue は、誰が、どの状態で、何をすると、何が起きるかをGiven・When・Thenで具体化し、実装以外に必要な完了条件も書く手順を持ちます。

たとえば「エラーを分かりやすくする」なら、「必須項目が空の状態で送信すると、該当項目の近くに理由が表示される」まで落とします。これは読者向けに作った説明例ですが、検証できる条件へ分解する考え方は公開版のcreate-issueにあります。

閉じる側の close-issue は、受け入れ条件ごとに実装と検証の根拠を照合します。たとえばローカルで確認した表示を、本番で確認した証拠として扱わないために、根拠が測った対象と、条件が要求する対象が一致するかを確かめます（close-issue）。

ここは主にSkillsによる判断支援です。文章の意味をすべてhookで判定するのではなく、確認すべき問いを揃えています。

実例2：レビューを起動した事実と、完了した証拠を分ける

multi-review は、セルフレビューに別のAIの視点を加える入口です。公開版では、PR（プルリクエスト）を作成したあとにその差分をレビューし、変更の種類に応じた観点を選びます。レビュー中は対象の作業ツリーを変更せず、失敗や INCOMPLETE を「指摘なし」に読み替えない手順になっています（multi-review）。

私たちのサイトでは、その結果をマージ前に検証するスクリプトも使っています。レビュー後にコードを直したなら、直す前の結果だけで完了とはしません。レビューした差分と、これから統合する差分を対応させるためです。このサイト固有の接続は、ff-dev-toolkitを導入する全プロジェクトへ自動的に入るものではありません。

複数のAIを呼ぶこと自体が品質の保証になるわけではありません。どの差分を見たのか、必要な観点が終わったのか、指摘が残っていないかを確認できるようにすることが、私たちの狙いです。

実例3：ログの末尾だけを見て、失敗を見落とす操作を止める

長い検証ログの最後だけを表示したい場面があります。しかし、パイプの終了コードは、シェルの設定によっては最後のコマンドの結果になります。検証が失敗しても、後ろの表示用コマンドが成功すれば、見かけ上は成功になる場合があります。

公開版の guard-exit-code.sh は、この種の終了コードの隠蔽を起こすコマンドの形を検出し、ログをファイルへ保存して元の処理の終了コードを返す形へ誘導します。hook本体と登録定義を公開しています。

「ログをちゃんと読む」という注意書きだけで繰り返し防ぐより、誤判定を生む操作を検出できる範囲で止める。このように、失敗の形が具体的になったところから検査へ移しています。

ACEで残すのは、次の判断を変える経験

検査を増やすだけでは、新しい失敗には対応できません。作業中に分かったことを、次に使える形へ直す工程も必要です。私たちは、これをACE（Agentic Context Engineering）のサイクルとして運用しています。ここでいう「学習」は、モデルの重みの更新ではなく、次の作業で参照する文書を育てることです。

ace-curateには、次の3段階があります。

1. Generate：候補を抽出する。 PRの変更、レビュー指摘、検証結果から、次にも使えそうな気づきを取り出します。
2. Reflect：残す価値を評価する。 既存の知見と重複しないか、どの条件で使えるか、次の行動へつながるかを見ます。追加だけでなく、既存項目の更新や候補の破棄も選びます。
3. Curate：文書へ反映する。 採用した知見を該当カテゴリへ少しずつ追記・更新し、次の検索で取り出せるようにします。

たとえば私たちのブログでは、記事の要約に文字数の制約を設けています。過去の知見を「要約は短く」と文書へ残すだけでなく、スキーマの最小・最大文字数の検査へ移した例は、以前の記事でも紹介しました。経験を思い出せるようにし、繰り返す失敗は検査へ変えていく流れです。

このサイトのPlaybookは、2026年10月28日の執筆時点で 929件 でした。アーカイブを除く本文のエントリ見出しを数え、索引の記載件数と照合した筆者による社内実測です。昇格先を示す短い項目も含み、件数だけで効果を示すものではありません。

むしろ、蓄積した知見を必要な場面へ届けることが課題になります。現在は、実装前に knowledge-lookup でPlaybookと観測台帳を同じキーワードで検索します。Playbookは再利用する知見、retrospective が記録する観測台帳は作業中の繰り返しや詰まりを残す場所です。検索結果では、有効・廃止・アーカイブなどの状態を区別します（knowledge-lookup）。

記録するだけでは、次の作業は変わりません。「作業前に引く」「条件が合うものを使う」「古くなったら直す」までが、私たちの知見管理です。

社内版とOSSは、会社名より依存関係で分ける

私たちの社内marketplaceである feelflow-plugins は非公開です。その中から、開発の共通手順をまとめたff-dev-toolkitを、Apache-2.0で公開しています。今回はこの共通基盤に対象を絞り、ほかの社内プラグインの内容は扱いません。

切り分けの基準は、「フィールフロウという名前を消せば公開できるか」ではありません。別の会社が、自社のリポジトリや認証で使えるかを見ます。Issueの条件を具体化する手順、レビュー結果の読み方、知見の選別方法は共通化できます。一方で、顧客情報、内部の接続先、社内専用の設定を前提にした処理は、そのまま共通基盤へ出せません。

公開版のREADMEは、内部の正本から一方向に同期する構成を明記しています（公開README「開発とフィードバック」）。以下は、その裏側で私たちが使っている非公開の同期処理を、設計者として説明したものです。

• 許可リストで公開対象を限定する。 リポジトリ全体をコピーしてから秘密を消す方式ではなく、公開を許可したファイル・ディレクトリだけを、固定したコミットから git archive で取り出します。
• 内容とファイル名を検査する。 禁止パターンや、公開を許可していないリポジトリへの参照を検出します。違反の検出だけでなく、検査に失敗した場合も処理を止めます。
• 同期と公開の判断を分ける。 低層の同期スクリプト自体はcommitやpushを行いません。通常のリリースでは、dry-runで差分と予定する公開操作を示し、人が承認してからリリース処理がcommit・pushなどを実行します。

禁止パターンの検査で、あらゆる社内情報を判定できるわけではありません。対象を絞ること、機械検査、人による差分の確認を組み合わせる設計です。「毎回、人が手でcommitする」という意味ではなく、公開する内容と操作を人が確認する境界を残すということです。

また、公開版の現在の導入方針は、私たちのサイト運用をそのまま全社へ必須化するものではありません。AI仕様駆動開発2.0（ASDD 2.0）の新規構成では、ACEと自動振り返りは初期状態で無効です。複数AIレビューやhooks、CI（継続的インテグレーション）も個別に選びます（公開README）。必要な工程を選び、採用した工程が実際に動くかを確かめる前提です。

最初はSkillを1本、hookを1本から

自社で始めるなら、まず「この作業は何を確認すれば終わるのか」をSkillに書くことを勧めます。対象は、普段から手戻りが起きる作業を1つ選びます。たとえばIssue起票なら、利用者、期待する結果、検証方法、範囲外を揃える手順です。

次に、その作業で起きる失敗のうち、機械で判定できるものを1つ選んでhookにします。重要なブランチへの直接pushを拒否する、という小さな条件でも構いません。許可される操作と拒否される操作の両方で、検査の発火を確かめます。

運用して分かったことは、適用条件と次の行動を添えて残し、次の作業前に引きます。最初から28のSkillsや929件の知見を揃える必要はありません。繰り返す失敗を1つ減らし、その経験を次の担当者へ渡すことから始められます。

第4回では、このような「会社ごとのプラグイン」を、どこまで内製し、どこで伴走支援を使うかを扱う予定です。

参考資料と確認範囲

公開ソースは2026年10月28日に確認したff-dev-toolkit v0.169.0（コミット a093707）へリンクを固定しています。公開READMEのSkills記載数と、実際のSkillsディレクトリ28件が一致することを確認しました。Playbookの929件と同期処理の詳細は、筆者による自社実装の確認であり、公開リポジトリの内容とは区別しています。

• FeelFlow. ff-dev-toolkit README — 収録機能、ライセンス、導入方針、内部の正本からの同期。
• FeelFlow. create-issue / close-issue — 受け入れ条件の作成と照合。
• FeelFlow. multi-review / guard-exit-code.sh — レビューの手順と、終了コードを守る検査。
• FeelFlow. ace-curate / knowledge-lookup — 知見の抽出・評価・更新と、次の作業での参照。