feature-factory

Feature Factory

1 つの機能を、意図からリリースまで導く、目標主導でローカルファーストなループです。この手法のすべては、1 つの考え方を貫くためにあります。**プロセスを機能より先走らせないでください。**中核（目標 → TDD → 決定論的な検証 → 人間によるマージ → 必要な場合のエビデンス）を維持し、儀式的な手順は徹底的に削ってください。

これは**行動指針であり、エンジンではありません。**汎用設定、実行機能、テレメトリー、最適化機能、汎用の factory verify ラッパーは構築しないでください。行動指針を実践し、その機能に必要性を証明できないものはパッケージ化しないでください。

基本原則

*人間が望ましいシステムの状態を定義します。エージェントが仕様を維持します。テストとエビデンスが、現実がそれに従ったかを判定します。*人間によるゲートは常に 2 つ必要です。Goal Contract の承認（変更コストが低いタイミング）とマージのレビュー（取り消せないタイミング）です。さらに、サイズ／リスクのトリガーが発動した場合は、条件付きで 3 つ目のゲート（計画の承認）も必要になります（ステップ 2 を参照）。その間は、1 つの作業に集中するエージェントループです。

適用するケースと省略するケース

• 適用するのは、範囲が限定され、リリース可能な機能です。
• 些細な変更では重い手順を省略します。S サイズの修正なら、頭の中で短い目標を立てる → TDD → リポジトリのチェックを実行 → マージ、で十分です。1 行の変更のためにドキュメントを作成しないでください。
• XL は受け付けません。共有契約、マイグレーション、認証／課金、またはプロダクト上の曖昧さを伴う複数日規模の機能は、先に分割してください。XL の機能全体をこのループに通さないでください。

ループ（6 つのステップ）

1. 受付 — Goal Contract を作成または修復する

まず、すばやくサイズを判断します（ステップ 2 で正式に決定します）。受付の手順をどこまで重くするか決めるために必要です。S サイズ／些細な変更では、ファイルの作成を省略します。チャットで短い目標を提示し、人間の確認を得れば十分です。ステップ 3 に進んでください。それ以外の場合は、assets/goal-contract.md を対象リポジトリにコピーし、機能ディレクトリ内の goal.md として保存します（推奨パス：docs/factory/<date>-<slug>/goal.md）。期待される調整の記入例については、記入済みの assets/goal-contract-example.md を参照してください。M サイズの機能では、テンプレートの基本フィールドで十分です。条件付きの後半部分は、L サイズの場合、またはトリガーが発動した場合に使用します。まず依頼内容から草案を作成し、その後、人間に各フィールドを確認・修正してもらってください。空欄のフォームが埋まるまで作業を止めず、人間が文言を承認するまで受付を完了しないでください。次の点を徹底します。

• `` の全フィールドが記入されていること：リリース可能な最小スライスと終了条件。
• 上限（≤3、≤5）を守ります。上限のある目標は目標のままにし、Markdown でウォーターフォール型の計画にしないでください。
• **望まれる成果はすべて、具体的なエビデンスに対応していること。**曖昧な成果や、特定の解決策に依存する成果は認めません。
• **不合格ルール：**目標からエビデンスを得られない場合、それは書式を整えただけの願望であり、合格とはみなしません。
• エージェントは目標の修正案を提示できます。目標をひそかに書き換えてはいけません。

2. サイズとリスクのトリアージ — プロセスの量を決める

• **サイズ：**S（½ 日未満、公開 API／マイグレーションなし） · M（1～2 日、一部の UI／統合あり） · L（複数日規模。共有契約、マイグレーション、認証／課金／権限、AI の挙動、データ保持を伴う） · XL（先に分割）。
• **リスク：**R0 なし · R1 内部開発支援 · R2 ユーザー向け、リスクが低い · R3 機微データ／推奨／プロファイリング · R4 禁止／高リスク（EU AI Act Art 5、または各地域の同等規制に該当）、あるいは法務レビューが必要 → 停止。外部レビューが完了するまで実装しないでください。また、AI 生成／チャットボット／ディープフェイクの出力について、Art 50 のラベル表示（または各地域の同等規制）も確認してください。
• **プロセスは少ないほうを標準とします。**プラン承認、トラッカー、視覚的エビデンス、監査（計画および／または差分。ステップ 4 を参照）は、サイズ／リスクのトリガーが発動した場合に限り追加します（references/process-budget.md を参照）。迷ったら、手順を減らしてください。
• **計画の監査（計画承認が必要な場合）：**構築を始める前に、独立した新しいコンテキストのレビュアー（Codex などの別のエージェント／モデル）に、実際のコードベースに照らして目標と計画を確認してもらい、順序、アーキテクチャ、正確性に問題がないかチェックします。ブロッカーを発見するには、ここが最もコストの低い段階です。構築の途中で問題を発見するのではなく、計画を修正してください。タイムアウトと自己レビューへのフォールバックは、ステップ 4 と同じです。

3. TDD 実装ループ

機能ブランチまたはワークツリーで作業します。作業がすでにメインライン上にある場合、マージゲートは実質的な判断ポイントにならないためです。その後、1つの集中したループで、レッド → グリーン → リファクタリングを進めます。**スウォームも並列展開も、先走った抽象化も、気づかれないスコープ拡大も行いません。**まず失敗するテストを書きます。利用可能なTDDスキル（例：superpowers:test-driven-development）を使い、なければレッド → グリーン → リファクタリングをそのまま実行します。

• **リポジトリにテストハーネスがありませんか？**スタック標準のランナーを最小限の構成で用意します（設定ファイル1つ、テストディレクトリ1つ。references/stack-discovery.mdを参照）。ハーネスも機能のコストに含まれます。立ち上げに1日かかる場合は、規模を再トリアージしてください。
• **スパイクの例外措置：**失敗するテストを書くための情報がまだ足りない場合（不慣れなライブラリ、APIの動作が不明確など）は、時間を区切って使い捨てのスパイクを行い、スパイクコードを破棄してから、得られた知見をもとにレッド → グリーンを開始します。テストを偽装したり、スパイクをいつの間にか実装にしてはいけません。
• **決定性：**壁時計やスリープに依存するテストアサーションは使わず、同期バリアまたはコールバックを使います。
• **契約変更 ⇒ すべての呼び出し箇所を検証：**共有関数の契約を変更する場合は、すべての呼び出し元と並行する経路を列挙し、それぞれが契約を守ることを証明する必要があります。

4. 検証と監査の規律

対象リポジトリの実際の検証コマンド（テスト・リント・型チェック・ビルド、および利用可能な場合はシークレットスキャン）を実行します。ローカルとCIで同じコマンドを使います。リポジトリにfactory verifyまたはプロジェクトの検証コマンドがある場合は、それを実行します。**ない場合は、リポジトリで実際に使われているコマンドを実行し、その正確なコマンドと出力を機能ディレクトリ内のevidence/verify.logに記録します。リポジトリに必要性が生じる前に、汎用ラッパーをでっち上げてはいけません。**実際のコマンドがわからない場合は、references/stack-discovery.mdに従い、CIワークフロー、Makefile／justfile、コントリビューター向けドキュメント、エコシステムのマニフェストの順に調べます。

• **不安定なテストは失敗であり、再試行では解決しません。**断続的な失敗があれば、根本原因を特定するか、決定的に書き直すまでマージを止めます。隔離はしません。
• 監査（独立した新しいコンテキストでのレビュー）は標準の工程であり、後回しにするものではありません。新しいコンテキストを持つ別のエージェントまたはモデル（例：Codex、または別のモデル）が、2つの時点で作業をレビューします。（a）着手前の計画監査（ステップ2を参照）、（b）マージゲート前の差分監査です。規模やリスクに応じた実施方法（必須となる条件、省略可能な条件、タイムアウト、および自己レビューへのフォールバック）はreferences/process-budget.mdで一元的に定義されています。再判断せず、その表に従ってください。指摘事項はevidence/audit-*.mdに保存し、次に進む前に計画または差分へ反映します（対応しない監査は見せかけにすぎません）。最終判断は引き続き人間が行います。監査は判断材料を提供しますが、目標の承認やマージ承認に取って代わるものではありません。

5. エビデンスの整理

機能ディレクトリ内のevidence/には関連するエビデンスのみを保存します。verify.log（コマンドと出力）、および条件を満たすUI変更の場合に限り、evidence/screenshots/内のスクリーンショット（対象となる変更と、標準の1ビューポート設定については、references/process-budget.mdの「Visual evidence」で定義されています）を保存します。ゴール追跡表は、有益な情報を加える場合にのみ作成します。エビデンスは成果物であり、主張ではありません。「完了」は監査可能でなければなりません。エビデンス用フォルダーをプロダクト化してはいけません。

• **例外措置 — 統計的・行動的な主張：**望ましい成果が、合否テストではなく、ノイズのある実世界のデータで測定する効果（エンゲージメント、レイテンシ分布、拒否率、ML指標など）である場合、テストスイートがすべて成功しても、その成果の証明にはなりません。指標をGoal Contractに事前登録し、実験として評価します（置換検定を行い、分析を敵対的にレビューします）。利用可能であればrigorous-experimentsスキルを使い、なければホールドアウト検証を行います。実際にテストしていない測定結果を主張してはいけません。これは、失敗ルールが検出する、操作された代理指標の問題と同じものが、さらに1層下で起きている状態です。

6. レトロスペクティブ削除フック（キュレーター）

リリース後、機能ディレクトリの retro.md に必ず4行だけ記述します（別ファイルを用意するのが現実的でない場合に限り、goal.md に追記します。検索しやすい既定の方法を1つに絞るほうが、2つの慣例を設けるより優れています）。

1. リリースを遅らせたものは何ですか？
2. 実際のバグの発見につながったものは何ですか？
3. 一度も使われなかった成果物はどれですか？
4. 次の機能に取りかかる前に何を削除しますか？

これが小規模な N での自己改善の仕組みのすべてです。手作業で、人が読める形式にし、過剰な構築ができないようにします。使用状況のテレメトリ、ダッシュボード、カウンターは追加しないでください。（およそ5機能の後に限り、Markdown の表に集約します。さらに複雑なものを検討するのは、およそ10機能を超えてからにしてください。）

意味保持ガード（この手法自体の成果物を編集する場合）

このガードが適用されるのは、手法自体、つまり Goal Contract のテンプレート、リスク評価基準、検証チェックを編集するときです。通常の機能開発には適用されません。編集、最適化、書き換えでこれらの成果物に手を加える場合、洗練された文章に、重要な制約を削除させないでください。 書き換えを採用する前に、必須フィールド、≤N の上限、失敗ルール、停止条件、リリース可能な最小スライス、リスク分類、エビデンスの対応付け、サイレントな書き換えの禁止、エンジン／設定の抽象化の禁止が維持されていることを確認してください。矛盾する場合は、読みやすさより運用上の有用性を優先してください。 詳細：references/semantic-preservation.md。

課題追跡 — 機能ごとに台帳を1つ（抽象化しない）

追跡は条件付きです。機能が複数の追跡対象タスクに実際に分解される場合に限り、エピックと課題を作成します。単一タスクの S/M 機能では、トラッカーは不要です。Goal Contract の ## Tracker セクションで、人が機能ごとに台帳を1つ選びます。環境で実際に利用できるツール（例：bd、Linear、GitHub Issues）を選ぶか、none を指定します。アダプター層は設けません。

• bd（beads） — ローカル／単独作業での既定の選択肢として適しています。Git ネイティブで、依存関係を考慮できます。.beads ストアがない場合は bd init を実行します。エピックには親の bead、タスクには子の bead を使い、依存関係は bd link で設定します。
• ホスト型トラッカー（Linear、GitHub Issues、…） — 作業を他の人にも見えるようにする必要がある場合や、作業がすでにそこにある場合に使います。この環境で利用可能なアクセス方法（CLI または MCP）を使います。エピックにはプロジェクト／親課題、タスクには課題を使います。人が明示的に選んだトラッカーをこの環境で利用できない場合は、停止して確認してください。トラッカーの切り替えや none への変更は Goal Amendment であり、黙って格下げしてはなりません。
• 同じ作業に対して2つの台帳（例：Linear のプロジェクトとbeads のエピック）を作成しないでください。

手作業のままにするもの／対象外（構築しない）

GEPA／テンプレートの最適化・成果物使用状況のテレメトリ・汎用の pipeline.config・実行者の抽象化・トラッカーの自動連携・視覚的エビデンスのマトリックス・比較評価の自動化・自己評価プロンプトを超えるリスクガバナンス・エージェント指示ファイル（AGENTS.md／CLAUDE.md）の自動更新・「エンジン」のようなものすべて。エンジンを作る価値が生まれるのは、実際に5～10個の機能に取り組んだ後であり、それ以前ではありません。

移植性 — あらゆるエージェントから実行できます（Codex、Copilot、Gemini、…）

このスキルはプレーンな Markdown で、プラットフォームに依存しません。ループはシェル／CLIでの作業であり、Claude 固有のツールは使いません。ここで名前が挙がっているもの（bd、Linear、TDD サブスキル、セカンドオピニオン用モデル）はすべて任意です。現在の環境で利用できない場合は、記載されている代替手段を使って続行してください。追跡が明示的に必須とされていない限り、任意のツールがなくても作業が妨げられることはありません。

スキルを自動検出しないエージェント（Codex CLI など）は、ファイルがあるだけではこのスキルを認識しません。対象リポジトリで検出できるようにするには、そのリポジトリのエージェント指示ファイル（AGENTS.md または CLAUDE.md）に次の項目を追加してください。

## feature-factory
When asked to build/ship a single feature, or to "write a goal contract", read
<path-to>/feature-factory/SKILL.md and follow it. For non-trivial features, copy
<path-to>/feature-factory/assets/goal-contract.md to docs/factory/<date>-<slug>/goal.md.

スキルランナーを使わずにこれに従う場合は、references/process-budget.md（サイズ／リスクのトリガー）、references/stack-discovery.md（リポジトリの検証コマンドの確認、テストハーネスがない場合のセットアップ）、および references/semantic-preservation.md（この手法自体の成果物を編集する場合のみ）を直接読んでください。

このスキルを別のリポジトリにコピーする場合は、内容ファイル（SKILL.md、assets/、references/）のみをコピーしてください。ローカルのツール状態（例：.enzyme/、.claude/）がこれらと一緒に置かれている場合がありますが、同梱してはいけません。

背景

feature-factory メソッドを要約したものです。公開リポジトリ：https://github.com/glebis/feature-factory（README ＋ Goal Contract テンプレート）。詳細な設計仕様と、3つの外部監査調査の流れは非公開で保管されています。このスキルは、実行可能な形に要約したものです。最もリスクの高い前提については、誠実に評価し続ける必要があります。つまり、範囲が限定されたロジック中心のパイロットで機能したプロセスが、複雑な UI／統合の作業でも軽量さを保てるとは、まだ証明されていません。次は、意図的に異なる機能でその有効性を厳しく検証してください。