fullstack-feature

リソース

scripts/
  validate-feature-workflow.sh
references/
  phase-templates.md

フルスタック機能のオーケストレーション

このスキルは、スタックの複数のレイヤーにまたがる機能を実装するための、エンドツーエンドのワークフローを定義します。要件の明確化からデリバリーまで、7つのフェーズを通じて専門エージェントをオーケストレーションします。

このスキルを使うタイミング

ユーザーが次のことを依頼した場合は、fullstack-feature を使います。

• データベース、API、UI の変更が必要な完全な機能
• テストとレビューを含むエンドツーエンドの実装
• 複数のコンポーネントに関わる、新しいユーザー向け機能
• 「X を構築」「X の機能を追加」「X の機能を実装」と表現される依頼

このスキルを使わないでください：

• 単一レイヤーの変更（API のみ、UI のみ）
• バグ修正（bugfix または hotfix スキルを使います）
• コードレビューのみ（review-scoring スキルを使います）
• 新機能を追加しないリファクタリング

概要

フルスタック機能のワークフローは、次の7つのフェーズで構成されます。

1. 理解 - 要件を明確にし、スキルを読み込み、影響を受けるレイヤーを特定します
2. 基盤（順次実行） - データベーススキーマ／マイグレーション、型の生成
3. コア実装（並列実行） - API エンドポイント、UI コンポーネント、状態管理
4. 統合（順次実行） - UI を API に、状態を UI に接続し、データフローを検証します
5. 品質（並列実行） - テスト、セキュリティチェック、アクセシビリティチェック
6. レビュー（ランタイム主導） - 前のフェーズで完了した WRFC チェーンを、ランタイムの <gv> ディレクティブで処理します
7. コミット + ログ - ランタイムが complete ディレクティブを発行した際に開始します。git commit を実行し、メモリ／ログを更新して、ユーザーに報告します

ランタイムエンジンと WRFC チェーン

ランタイムエンジンは、各作業エージェントに対して WRFC（Work-Review-Fix-Complete）チェーンを自動的に作成します。エージェントが作業を完了して <gv> タグを出力すると、ランタイムは次の処理を行います。

1. 設定された score_threshold（デフォルト：goodvibes.json の 9.5）に照らして出力を評価します
2. システムメッセージを通じて、オーケストレーターにディレクティブを発行します
3. オーケストレーターが、それらのディレクティブを機械的に実行します

ディレクティブの種類：

{"action":"spawn","wid":"wrfc_xxx","type":"reviewer","task":"Review the code..."}
{"action":"spawn","wid":"wrfc_xxx","type":"engineer","task":"Fix the issues..."}
{"action":"complete","wid":"wrfc_xxx"}
{"action":"escalate","wid":"wrfc_xxx","reason":"Max fix attempts reached"}

ディレクティブの遵守ルール（絶対）：

1. 即時実行：ディレクティブが届いたら、すぐに実行します。決して先送り、キューへの追加、遅延をしてはいけません。
2. 最優先：ほかの行動を起こす前にディレクティブを実行します。途中でツールを呼び出したり、別のエージェントを起動したり、先にユーザーへメッセージを送ったりしてはいけません。
3. 自律性の終了：WRFC チェーンに対する最初のディレクティブが届いた時点で、オーケストレーターはそのチェーンに対する判断権を持たなくなります。チェーンはディレクティブのみで進行します。
4. ランタイムが優先：ランタイムのワークフローのロジックは、常にオーケストレーターの判断に優先します。ディレクティブがレビューを指示した場合はレビューし、完了を指示した場合は完了します。

オーケストレーターがレビュー担当や修正エージェントを手動で起動することはありません。これらはランタイムのディレクティブによってのみ起動されます。

フェーズ1：理解

目的

作業エージェントを起動する前に、構築する内容を完全に把握します。このフェーズにより、誤解による無駄な作業を防ぎます。

手順

1. ユーザーと要件を明確にします：

   • 具体的にどのような機能が求められていますか？
   • ユーザーは誰で、どのような目標を持っていますか？
   • 受け入れ基準は何ですか（完了したことをどのように確認しますか）？
   • パフォーマンス、アクセシビリティ、ブラウザーのサポートなど、特定の制約はありますか？
   • 従うべき、または避けるべき既存のパターンはありますか？

2. 影響を受けるレイヤーを特定します：

   • データベース：新しいテーブル／カラムは必要ですか？マイグレーションは必要ですか？
   • API：新しいエンドポイントは必要ですか？既存のものを変更しますか？
   • 型：新しい型定義は必要ですか？
   • UI：新しいコンポーネントは必要ですか？既存のものを変更しますか？
   • 状態：新しい状態管理は必要ですか？
   • テスト：単体テスト、統合テスト、E2E テストは必要ですか？

3. 関連する成果スキルを読み込みます：

   • バックエンド：trpc、prisma、postgresql、clerk、nextauth、graphql、rest-api-design
   • フロントエンド：nextjs、react、tailwindcss、shadcn-ui、framer-motion
   • プロトコル：gather-plan-apply、review-scoring、goodvibes-memory

4. goodvibes のメモリを確認します：

   • .goodvibes/memory/decisions.json - アーキテクチャ上の選択
   • .goodvibes/memory/patterns.json - コーディングパターン
   • .goodvibes/memory/failures.json - 避けるべき過去の失敗

5. 実装計画を作成します：

   • 機能をサブタスクに分解する
   • サブタスク間の依存関係を特定する
   • 作業範囲を見積もる（ファイル／コンポーネントの数）
   • サブタスクをフェーズ（基盤、コア、統合）に割り当てる

出力

フェーズ 1 の終了時点で、以下が揃っている必要があります。

• 要件ドキュメント（memory/current-task.md 内）
• 影響を受けるレイヤーの一覧（データベース、API、UI、テスト）
• 実装計画（依存関係を含む、分解されたサブタスク）
• 読み込まれたスキル（関連する成果スキルが利用可能な状態）

モード固有の動作

Vibecoding：フェーズ 2 に進む前に、ユーザーに確認します。 Justvibes：要件が明確であれば自動的に進みます。（曖昧な場合は、確認のため一時停止します。）

フェーズ 2：基盤（順次）

目的

上流のコードを構築する前に、データモデルと型の基盤を確立します。これにより、各レイヤーで型安全性と一貫性を確保できます。

手順

1. データベーススキーマ（必要な場合）：

   • データベースエージェントを起動してスキーマを設計する
   • マイグレーションファイルを作成する
   • マイグレーションを実行する（開発環境）
   • マイグレーションの成功を確認する

2. 型生成（Prisma／Drizzle などを使用する場合）：

   • ORM の型生成コマンドを実行する
   • 型が生成されたことを確認する
   • 生成された型をコミットする（必要な場合）

3. 共有型定義（ORM を使用しない場合）：

   • src/types/[...].ts ファイルを作成する
   • エンティティ、DTO、リクエスト／レスポンスの型を定義する
   • バレルファイル index.ts からエクスポートする

エージェントへの指示

データベースエージェント：

プロトコルスキル（すべてのエージェントで必須）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• gather-plan-apply プロトコルを使用する
• 既存のスキーマパターンに従う（memory/decisions.json を確認する）
• クエリのパフォーマンスに適したインデックスを追加する
• 外部キー制約を追加する
• タイムスタンプ（createdAt、updatedAt）を使用する
• 完了前にマイグレーションをテストする

エンジニアエージェント（型生成）：

プロトコルスキル（すべてのエージェントで必須）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 型生成コマンドを実行する
• 型が正しいことを確認する（生成されたコードを抜き取り確認する）
• tsc を実行し、型エラーがないことを確認する

完了の明確な定義

• データベーススキーマが存在し、マイグレーションが適用されている
• 型が生成され、エクスポートされている
• npm run typecheck が成功する
• すべてのファイルがコミットされている

モード固有の動作

Vibecoding：このフェーズの後にチェックポイントを設けます。checkpoint: foundation - schema and types というメッセージでコミットします。 Justvibes：フェーズ 3 に自動的に進みます。

フェーズ 3：コア実装（並列）

目的

API と UI のレイヤーで、主要な機能を並行して実装します。これにより、処理能力を最大化し、待ち時間を最小限に抑えます。

サブフェーズ

以下のサブフェーズを並行して実行します。

1. API エンドポイント（API エージェント）
2. UI コンポーネント（UI エージェント）
3. 状態管理（状態エージェント）

エージェントへの指示

API エージェント：

プロトコルスキル（すべてのエージェントで必須）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 既存のパターンを使用してエンドポイントを実装します（API のスタイルは decisions.json を確認してください）
• 入力検証を追加します（Zod などを使用してください）
• エラー処理を追加します
• 認証／認可のチェックを追加します
• データベースアクセスには ORM を使用します
• 適切なレベルでログを追加します
• gather-plan-apply プロトコルを使用します

UI エージェント：

プロトコルスキル（すべてのエージェントで必須）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 既存のパターンを使用してコンポーネントを作成します（UI ライブラリは decisions.json を確認してください）
• アクセシビリティのベストプラクティスに従います（ARIA 属性、キーボード操作）
• レスポンシブデザインを実装します
• ローディング状態とエラー状態を追加します
• パフォーマンスを最適化します（useMemo、useCallback）
• gather-plan-apply プロトコルを使用します

状態管理エージェント：

プロトコルスキル（すべてのエージェントで必須）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 既存のパターン（Zustand、Redux など）を使用して状態管理を実装します
• 状態の構造とアクションを定義します
• 派生状態のセレクターを追加します
• 必要に応じて永続化を追加します（localStorage、sessionStorage）
• gather-plan-apply プロトコルを使用します

完了の明確な定義

• すべての API エンドポイントが実装され、検証されている
• すべての UI コンポーネントが作成されている
• 状態管理が実装されている
• npm run typecheck が成功する
• npm run lint が成功する
• すべてのファイルがコミットされている

モード固有の動作

Vibecoding：このフェーズの後にチェックポイントを作成します。コミットメッセージ checkpoint: core implementation でコミットします。 Justvibes：フェーズ 4 に自動的に進みます。

フェーズ 4：統合（順次実行）

目的

UI を API に接続し、状態管理を UI に連携させ、データフローをエンドツーエンドで検証します。このフェーズはフェーズ 3 の完了を前提とするため、順次実行する必要があります。

手順

1. UI を API に接続する：

   • コンポーネントに API クライアント呼び出しを追加します
   • API 呼び出し中のローディング状態を処理します
   • API からのエラー状態を処理します
   • UI に API の応答を表示します

2. 状態管理を UI に連携させる：

   • 状態管理をコンポーネントに接続します
   • セレクターを使って状態にアクセスします
   • ユーザー操作に応じてアクションをディスパッチします
   • 状態が変化したときに UI が更新されることを確認します

3. エンドツーエンド検証：

   • データフローを手動でテストします：UI -> API -> Database -> API -> UI
   • ローディング状態が表示されることを確認します
   • 失敗時にエラー状態が表示されることを確認します
   • 成功時に成功状態が表示されることを確認します

4. 統合の問題を修正する：

   • UI と API 間の型の不一致を修正します
   • データマッピングの問題を修正します
   • 状態同期の問題を修正します

エージェントへの指示

統合エージェント：

プロトコルスキル（すべてのエージェントで必須）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• API と UI の両方のコードを読み、インターフェースを把握します
• 適切なライフサイクルフック（useEffect、イベントハンドラー）に API クライアント呼び出しを追加します
• エラー処理が実装されていることを確認します
• ローディング状態が表示されることを確認します
• 各統合箇所を手動でテストします
• gather-plan-apply プロトコルを使用します

完了の明確な定義

• UI コンポーネントから API エンドポイントを呼び出せる
• データが UI -> API -> DB -> API -> UI の順に流れる
• 状態管理が正しく動作する
• ローディング状態が表示される
• エラー状態が表示される
• npm run typecheck が成功する
• すべてのファイルがコミットされている

モード固有の動作

Vibecoding：このフェーズの後にチェックポイントを作成します。コミットメッセージ checkpoint: integration でコミットします。 Justvibes：フェーズ 5 に自動的に進みます。

フェーズ 5：品質（並列実行）

目的

複数の観点から、実装が品質基準を満たしていることを検証します。これらのチェックは並列で実行されます。起動された各エージェントには、ランタイムエンジンが管理する独自の WRFC チェーンが割り当てられます。

サブフェーズ

以下のサブフェーズを並列で実行します。

1. テスト（テスターエージェント）
2. セキュリティチェック（セキュリティエージェント）
3. アクセシビリティチェック（A11y エージェント）

エージェントへの指示

テスターエージェント：

プロトコルスキル（すべてのエージェントで必須）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• API エンドポイントのユニットテストを作成します
• UI のコンポーネントテストを作成します
• データフローの統合テストを作成します
• 新しいコードのカバレッジを 80% 以上にします
• 正常系とエッジケースの両方をテストします
• gather-plan-apply プロトコルを使用します

セキュリティエージェント：

プロトコルスキル（すべてのエージェントで必須）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• すべてのエンドポイントで入力検証が行われているか確認します
• 認証／認可チェックが行われているか確認します
• SQL インジェクションの脆弱性がないか確認します
• XSS の脆弱性がないか確認します
• シークレットが漏えいしていないか確認します
• CORS の設定を確認します
• gather-plan-apply プロトコルを使用します

A11y エージェント：

プロトコルスキル（すべてのエージェントで必須）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• インタラクティブ要素に ARIA 属性があるか確認します
• キーボードナビゲーションに対応しているか確認します
• 色のコントラスト（WCAG AA）を確認します
• フォーカスインジケーターを確認します
• 画像に代替テキストがあるか確認します
• gather-plan-apply プロトコルを使用します

完了の明確な定義

• テストが作成され、すべて成功している
• セキュリティチェックが完了している（重大な問題がない）
• アクセシビリティチェックが完了している（重大な問題がない）
• すべてのファイルがコミットされている

モード別の動作

Vibecoding：このフェーズの後にチェックポイントを作成します。メッセージ checkpoint: quality checks でコミットします。 Justvibes：自動的に次へ進み、ランタイムがレビューサイクルを処理します。

フェーズ 6：レビュー（ランタイム主導）

目的

体系的なレビューと修正を通じて、すべてのコードが本番環境の基準を満たすようにします。ランタイムエンジンが <gv> ディレクティブを介してこのフェーズを自動的に管理します。

仕組み

オーケストレーターがレビュー担当者を手動で起動することはありません。代わりに、次の処理が行われます。

1. フェーズ 2〜5 の各作業エージェントが完了し、<gv> タグを出力します
2. ランタイムエンジンが出力を評価し、ディレクティブを発行します。
   • レビューが必要な場合：{"action":"spawn","type":"reviewer","task":"..."}
   • レビュー後に修正が必要な場合：{"action":"spawn","type":"engineer","task":"Fix: ..."}
   • スコアが goodvibes.json で設定された score_threshold を満たす場合：{"action":"complete"}
   • max_fix_attempts を使い切った場合：{"action":"escalate","reason":"..."}
3. オーケストレーターは各ディレクティブを直ちに、機械的に実行します

オーケストレーターの動作

• spawn ディレクティブの場合：指定されたエージェントを、与えられたタスクプロンプトとともに起動します
• complete ディレクティブの場合：チェーンを完了としてマークし、すべてのチェーンが完了したらフェーズ 7 に進みます
• escalate ディレクティブの場合：エスカレーションの理由をユーザーに報告します。チェーンを手動で修正しようとしてはいけません

完了の明確な定義

• すべての WRFC チェーンがランタイムから complete ディレクティブを受け取っている
• エスカレーションの解決待ちのチェーンがない

モード別の動作

Vibecoding モードと Justvibes モードは、どちらも同じようにディレクティブに従います。レビューサイクルの終了時点はランタイムエンジンが判断します。このフェーズでは、ディレクティブの実行以外に、オーケストレーターがモードごとに異なる動作をすることはありません。

フェーズ 7：コミット＋ログ

目的

ランタイムがフェーズ 2〜5 のすべての WRFC チェーンに complete ディレクティブを発行した時点で、このフェーズが開始されます。Git へのコミットとプロジェクトメモリーの更新によって、機能を仕上げます。

手順

1. git コミットを作成する：

   • すべての新規／変更ファイルをステージする
   • 明確なコミットメッセージを書く（既存の規約に従う）
   • Co-Authored-By: Claude Opus 4.6 <[email protected]> を含める
   • コミットする

2. goodvibes のメモリを更新する：

   • 新しいパターンが生まれた場合は .goodvibes/memory/patterns.json に追加する
   • 新しい決定を行った場合は .goodvibes/memory/decisions.json に追加する
   • goodvibes-memory スキルを使用する

3. goodvibes のログを更新する：

   • .goodvibes/logs/tasks.jsonl に機能の完了を記録する
   • 機能名、変更したファイル、最終スコアを含める
   • goodvibes-memory スキルを使用する

4. ユーザーに報告する：

   • 実装した内容を要約する
   • 作成／変更したファイルを一覧表示する
   • コミット SHA を記載する
   • 次のステップ（該当する場合）を提示する

明確な完了の定義

• すべてのファイルが git にコミットされている
• メモリが更新されている
• ログが更新されている
• ユーザーへの報告が行われている

モード別の動作

Vibecoding：コミットする前に、コミットメッセージをユーザーに確認します。 Justvibes：生成したメッセージで自動的にコミットします。

モード別の動作

Vibecoding モード

Vibecoding モードは協調的です。オーケストレーターは次のように動作します。

• Phase 1（理解）の後、続行する前に確認する
• Phase 2、3、4、5 の後にチェックポイントを設ける（git コミットを作成する）
• Phase 7 の最終コミットの前に、コミットメッセージを確認する
• 不確かな点が生じた場合は、承認を求めて一時停止する

エージェントが起動されると、ランタイムエンジンが WRFC チェーンを自動的に実行します。オーケストレーターはモードに関係なく、ディレクティブを機械的に実行します。

チェックポイントのコミットメッセージ：

• checkpoint: foundation - schema and types
• checkpoint: core implementation
• checkpoint: integration
• checkpoint: quality checks

Justvibes モード

Justvibes モードは自律的です。オーケストレーターは次のように動作します。

• ユーザーの入力なしに、すべてのフェーズを自動的に進行する
• 要件が曖昧な場合、または重大な決定が必要な場合にのみ一時停止する
• Phase 7 で自動的にコミットする（コミットメッセージを生成する）

ランタイムエンジンは、どちらのモードでもすべての WRFC サイクルを同じように管理します。

エージェントのオーケストレーションパターン

順次フェーズ

Phase 2、4、7 は順次実行する必要があります。

• Phase 2（基盤）：API／UI コードが型に依存するため、Phase 3 の前に完了する必要があります
• Phase 4（統合）：API と UI を接続するため、Phase 3 の後に実行する必要があります
• Phase 7（コミット＋ログ）：すべてのチェーンに対する complete ディレクティブによって開始される、最後のフェーズである必要があります

並列フェーズ

Phase 3 と 5 では、複数のエージェントを並列で起動します。

• Phase 3（コア）：API エージェント、UI エージェント、State エージェントを並列実行する
• Phase 5（品質）：テスターエージェント、セキュリティエージェント、A11y エージェントを並列実行する

次のフェーズに進む前に、並列フェーズ内のすべてのエージェントに complete ディレクティブが届いている必要があります。

エージェント間のコミュニケーション

エージェント同士が直接コミュニケーションを取ってはいけません。代わりに、次のようにします。

• エージェントは結果をファイルシステムに書き込む
• オーケストレーターはエージェントの出力を読み取る
• オーケストレーターは関連情報を次のエージェントに渡す

他のプロトコルとの統合

Gather-Plan-Apply（GPA）

すべての作業エージェントは GPA ループに従う必要があります。

1. 探索：discover ツールを使用して、grep／glob／シンボル検索クエリを並列実行する
2. 計画：作成／変更するファイル、操作の順序、バッチ化の機会を特定する
3. バッチ化：操作をバッチ化した precision_engine 呼び出しにまとめる
4. ループ：前提が変わった場合は探索に戻る

詳細は gather-plan-apply スキルを参照してください。

Review-Scoring（WRFC）

ランタイムエンジンは、レビュアーの起動時にレビュー採点基準を内部的に使用します。オーケストレーターがコードを直接採点することはありません。レビューのしきい値は goodvibes.json（score_threshold、max_fix_attempts）で設定します。

レビュアーエージェントの動作について詳しくは、review-scoring スキルを参照してください。

Goodvibes Memory

goodvibes-memory スキルを使用して、次の操作を行います。

• Phase 1 で .goodvibes/memory/{decisions,patterns,failures}.json を読み取る
• Phase 7 で .goodvibes/logs/tasks.jsonl に書き込む
• Phase 7 で新しいパターン／決定をメモリファイルに反映する

よくある落とし穴

実装を早く始めすぎる

フェーズ 1 が完了するまで、作業エージェントを起動しないでください。まず要件を明確にしてください。

順次実行するフェーズを並列化する

フェーズ 2 とフェーズ 3 を並列で実行しないでください。フェーズ 3 はフェーズ 2 の型に依存します。

品質フェーズを省略する

フェーズ 5 を省略しないでください。テストは必須です。セキュリティも必須です。

レビュアーを手動でスケジュールする

フェーズ 6 にレビュアーのタスクを手動で追加しないでください。各作業エージェントが完了すると、ランタイムエンジンがレビュアーの起動指示を自動的に発行します。手動でスケジュールすると、ランタイムによるしきい値の適用を回避することになります。

指示の実行を先延ばしにする

<gv> の指示を先延ばしにしたり、順序を入れ替えたり、省略したりしないでください。受け取ったら、最初のアクションとして直ちに実行してください。

すべてのチェーンが完了する前にコミットする

WRFC チェーンがすべて complete 指示を受け取るまで、フェーズ 7 でコミットしないでください。一部だけ完了しても、完了したことにはなりません。

メモリの更新を忘れる

フェーズ 7 でメモリの更新を省略しないでください。後続のエージェントはこのコンテキストを必要とします。

検証

scripts/validate-feature-workflow.sh を使用して、オーケストレーションがこのワークフローに沿っていることを確認してください。詳細なテンプレートと例については、references/phase-templates.md を参照してください。