build-feature

フルスタック機能実装ワークフロー

データベース、バックエンド、フロントエンド、テストの各レイヤーにわたって、フルスタック機能の実装を実行します。このスキルは、/plan-feature によって作成された実装計画に従い、統合テストを行いながらすべてのレイヤーを構築します。

注意

範囲の境界：このスキルはコードを実装し、コミットします。プルリクエストの作成、リモートへのプッシュ、コードレビューの実施、マージの申請は行いません。実装とコミットが完了したら、停止し、次に /review-code を実行するようユーザーに提案してください。PR の作成には進まないでください。それは /submit-pr の役割です。

ステップ 1：実装計画を読み込む

次の優先順位で実装計画を確認します。

メモ

/plan-feature によって作成された GitHub イシューはタスク指向の作業項目です。決定記録は、評議会による評価、根拠、アーキテクチャのコンテキストに関する正式な情報源です。イシューから読み込む場合は、完全なコンテキストを把握するため、必ず参照先の決定記録も読んでください。

オプション A：GitHub イシュー（優先）

ユーザーから GitHub イシュー番号（例：/build-feature 42 または /build-feature #42）が指定された場合：

1. イシューの詳細を取得します。

   gh issue view <number> --json title,body,labels,state,number
   

2. イシューを検証します。

   • build-ready ラベルが付いていることを確認します（付いていない場合は警告してください。/plan-feature を経ていないか、追加の計画が必要な可能性があります）。
   • イシューがクローズされている場合は、ユーザーに警告し、続行するか確認します。

3. イシューの本文を解析し、次の内容を抽出します。

   • 実装計画：レイヤー（フロントエンド、バックエンド、データベース、テスト）ごとに整理されたタスクのチェックボックス
   • 技術的コンテキスト：アーキテクチャ上の決定、API コントラクト、スキーマの変更
   • 決定記録のパス：評議会のコンテキスト全体を把握するため、参照先の決定記録を読みます
   • フィーチャーフラグ：該当する場合はフラグ名
   • 成功指標：測定可能な成果

4. イシューに指定されたパスから参照先の決定記録を読み込み、評議会による根拠をすべて確認します。

5. 作業を開始したことを通知します（ルールについては AGENTS.md の「Label Management」を参照してください）。

   # Single-developer constraint: only one issue should be in-progress at a time.
   # First, remove in-progress from any other issue that has it:
   gh issue list --label "in-progress" --state open --json number --jq '.[].number' | while read n; do
     gh issue edit "$n" --remove-label "in-progress"
   done
   
   gh issue edit <number> --add-label "in-progress"
   

6. イシューが 製品ロードマップ のプロジェクトボードで管理されていることを確認します。管理されていない場合は追加します。

   # --limit 200 covers the current board size; increase if the project grows beyond 200 items
   EXISTING=$(gh project item-list {PROJECT_NUMBER} --owner {OWNER} --format json --limit 200 \
     | python3 -c "
   import json, sys
   data = json.load(sys.stdin)
   for item in data.get('items', []):
       # <number> must be an integer literal, e.g., == 42, not == '42'
       if item.get('content', {}).get('number') == <number>:
           print(item['id'])
           break
   ")
   
   if [ -z "$EXISTING" ]; then
     ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {OWNER} --url "https://github.com/{OWNER}/{REPO}/issues/<number>" --format json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
     echo "Warning: Issue #<number> was not on the project board. Added it now (item $ITEM_ID)."
   fi
   

   警告

   イシューがプロジェクトボードに登録されていなかった場合、フェーズ、サイズ、日付の各フィールドも未設定の可能性があります。プロジェクト項目を確認し、未設定のフィールドがあればユーザーに警告してください。これは、ボードへの登録とフィールドの入力を確実に行うスキルである /plan-feature または /security-audit を経ずにイシューが作成されたことを示唆します。

オプション B：ロードマップから自動選択

イシュー番号も説明も指定されていない場合、プロジェクトロードマップから次の build-ready チケットを自動的に探します。

1. 現在のフェーズを特定します。 アクティブなマイルストーンを探します。これは、未完了のイシューが残っているオープンなマイルストーンのうち、期限が最も早いものです。

   gh api repos/{OWNER}/{REPO}/milestones \
     --jq 'sort_by(.due_on) | map(select(.state == "open" and .open_issues > 0)) | .[0] | {title, number, due_on, open_issues}'
   

   すでに in-progress ラベルが付いたイシューがある場合は、そのイシューのマイルストーンを使用します。

   gh issue list --state open --label "in-progress" --json number,title,milestone --jq '.[0]'
   

2. build-ready の候補を取得します。 そのマイルストーン内にある、オープンで build-ready ラベルが付いたイシューを一覧表示します。ただし、すでに in-progress ラベルが付いているものは除外します。

   gh issue list --state open --label "build-ready" --milestone "<milestone-title>" \
     --json number,title,labels \
     --jq '[.[] | select(.labels | map(.name) | index("in-progress") | not)]'
   

3. プロジェクトの開始日で並べ替えます。 プロジェクト項目を取得し、イシュー番号を使って候補と照合してから、start フィールドの昇順で並べ替えます。

   gh project item-list {PROJECT_NUMBER} --owner {OWNER} --format json --limit 200 | python3 -c "
   import json, sys
   data = json.load(sys.stdin)
   # <candidates> is a Python set literal of issue numbers, e.g., {22, 23, 10}
   candidates = <candidates>
   results = []
   for item in data.get('items', []):
       num = item.get('content', {}).get('number')
       if num in candidates:
           # Field is 'start', not 'startDate'
           start = item.get('start') or '9999-12-31'
           results.append((start, num, item.get('title', '')))
   results.sort()
   for start, num, title in results:
       display_start = start if start != '9999-12-31' else 'N/A'
       print(f'{display_start}\t#{num}\t{title}')
   "
   

   最初の候補（start の日付が最も早いもの）が、次に作業するチケットです。start の日付がないイシューは最後に並べます。

4. 候補が見つからない場合は、オプション C（決定記録）に進みます。

CHECKPOINT：推奨チケットと候補の全リストをユーザーに提示します。

現在のフェーズにあるすべての build-ready 候補を開始日の順に並べた表を表示し、最上位の候補を推奨として強調表示します。

#	Issue	タイトル	開始日
→	#N	最上位候補のタイトル	YYYY-MM-DD
2	#N	その他の候補	YYYY-MM-DD

ユーザーに確認します：

• (a) 推奨チケットに取り組む
• (b) リストから別のチケットを選ぶ（Issue 番号を指定）
• (c) 自動選択をスキップし、代わりに何を構築するかを説明する

ユーザーがチケットを選択した場合は、Option A と同じフローでその Issue 番号を使用して進めます（Issue の詳細全体を取得し、build-ready を検証し、計画を抽出し、in-progress ラベルを設定するなど）。

Option C：Decision Record（フォールバック）

Issue 番号が指定されておらず、ロードマップに build-ready のチケットが見つからない場合：

1. docs/decisions/ から、現在の機能に一致する最新の Decision Record を読み取ります
2. Decision Record が存在しない場合は、Option D に進みます

Option D：ユーザーによる説明（最終手段）

Decision Record が存在しない場合は、何を構築するかユーザーに尋ねます。

警告

GitHub Issue も Decision Record も見つかりません。これは計画パイプライン（/plan-feature）がスキップされたことを意味します。評議会による評価も、文書化された根拠も、構造化されたタスク分解もありません。まず /plan-feature を実行することを検討してください。計画なしで進めると、レビューされていないアーキテクチャ上の決定を行うリスクがあります。

タスクの抽出

計画の出所にかかわらず、次の項目を特定します。

• データベースの変更：スキーマの変更、マイグレーション、シードデータ
• バックエンドのタスク：API エンドポイント、サービス、ビジネスロジック
• フロントエンドのタスク：コンポーネント、ルーティング、状態管理、スタイリング
• テスト要件：カバレッジ目標、E2E シナリオ、エッジケース
• フィーチャーフラグ：フラグの適用対象にするかどうか

最新の main をベースとするフィーチャーブランチにいることを確認します。必ず最初に fetch します。

git fetch origin main

main にいる場合は、最新の origin/main から新しいフィーチャーブランチを作成します。

git checkout -b feature/<feature-slug> origin/main

既存のフィーチャーブランチにいる場合は、変更を取り込むため、最新の origin/main にリベースします。

git status --porcelain

作業ツリーに変更がある場合は、リベース前に変更を stash します。

git stash push -m "build-feature: stash before rebase"
git rebase origin/main
git stash pop

作業ツリーがクリーンな場合は、そのままリベースします。

git rebase origin/main

Step 2：データベース層

データベースの変更が必要な場合：

1. スキーマ設計のガイダンスを得るため、/database-design:postgresql を呼び出します

2. Prisma スキーマの変更を設計します。

   • 適切なフィールド型とデフォルト値を持つモデル
   • 参照整合性を備えたリレーション
   • クエリパフォーマンスのためのインデックス
   • 制約とバリデーション
   • 適切な場合は Enum

3. マイグレーションのベストプラクティスを得るため、/database-migrations:sql-migrations を呼び出します

CHECKPOINT：スキーマの変更とマイグレーション計画をユーザーに提示します。実行前に承認を待ちます。

4. マイグレーションを生成して適用します。

   pnpm db:migrate
   

Step 3：バックエンドの実装

バックエンドの足場作りに関するガイダンスを得るため、/backend-development:feature-development を呼び出します。

計画に含まれるバックエンドのタスクごとに、以下を行います。

型とバリデーション

• リクエスト／レスポンス型の TypeScript インターフェースを定義します
• 実行時バリデーション用の Zod スキーマを作成します
• フロントエンドで利用する共有型をエクスポートします

サービス層

• NestJS サービスにビジネスロジックを実装します
• 型付き例外を使って適切にエラーを処理します
• ビジネスルールを検証し、不変条件を適用します
• サービスをテスト可能に保ちます（依存性注入）

API 層

• tRPC プロシージャまたは NestJS コントローラーを作成します
• バリデーション、認証ガード、レート制限を接続します
• 適切なステータスコードとエラー形式を返します

バックエンドのテスト

• サービスのユニットテスト（依存関係をモック）
• API エンドポイントの統合テスト
• バリデーション、認証、エラー処理のテスト

バックエンドのテストを実行します。

pnpm test

チェックポイント：API コントラクト（エンドポイント、リクエスト／レスポンスの型）をユーザーに提示します。それに基づいてフロントエンドを構築する前に、コントラクトを確認します。

ステップ 4：フロントエンドの実装

計画に含まれる各フロントエンドタスクについて、以下を行います。

コンポーネントの作成

ガイドに沿ってコンポーネントを作成するには、/ui-design:create-component を呼び出し、以下を適用します。

• 完全な TypeScript の props インターフェース
• Tailwind CSS と shadcn/ui によるスタイリング（パターンについては /frontend-mobile-development:tailwind-design-system を呼び出します）
• キーボード操作と ARIA 属性
• レスポンシブデザイン
• ダークモードのサポート（該当する場合）

メモ

ユーザーに表示されるすべてのテキスト（見出し、ラベル、説明、空の状態、エラーメッセージ、ツールチップ）は、AGENTS.md の ユーザー向けコンテンツのスタイルのルールに従う必要があります。エムダッシュ、AI らしさを感じさせる語彙、過度な宣伝表現は使用しません。

状態管理

機能でクライアント側の状態管理が必要な場合：

• 状態管理のパターンについて /frontend-mobile-development:react-state-management を呼び出します
• サーバー状態には React Query／tRPC のフックを使用します
• UI の状態にはローカル状態（useState/useReducer）を使用します
• 共有クライアント状態には context または Zustand を使用します

ルーティング

新しいページやルートが必要な場合：

• ルート定義を追加します
• ページコンポーネントを作成します
• ナビゲーションリンクを追加します

コンテンツと SEO（マーケティングページまたはユーザー向けページの場合）

この機能にマーケティングページ、ランディングページのコピー、または製品説明が含まれる場合：

• SEO コンテンツの品質と E-E-A-T の最適化のために /seo-content-creation:seo-content-writer を呼び出します
• コンテンツ戦略のガイダンスを得るために /content-marketing:content-marketer を呼び出します
• より詳細な WCAG 準拠のために、/accessibility-compliance:wcag-audit-patterns と /ui-design:accessibility-audit を併せて呼び出します

API の統合

• tRPC クライアントまたは API フックを介して、コンポーネントをバックエンドに接続します
• ローディング状態、エラー状態、空の状態に対応します
• 適切な場合は楽観的更新を追加します

フィーチャーフラグ（該当する場合）

計画でフィーチャーフラグが指定されている場合：

const isEnabled = useFeatureFlag('FEATURE_NAME');
if (!isEnabled) return <ExistingComponent />;
return <NewFeature />;

フロントエンドのテスト

• コンポーネントのレンダリングテスト（React Testing Library）
• ユーザー操作のテスト（クリック、入力、送信）
• モック API レスポンスを使用した統合テスト

チェックポイント：フロントエンドの実装をユーザーに提示します。構築した内容を説明し、コンポーネントの構成と主な操作を示します。

ステップ 5：エンドツーエンドテスト

重要なユーザーフローについて、E2E テストの概要を作成します。

• 正常系：ユーザーがメインフローを正常に完了する
• エラー系：ユーザーが入力検証エラーや API 障害に遭遇する
• エッジケース：空の状態、境界条件、同時操作

E2E テストのインフラストラクチャが存在する場合は、テストを実装します。

テストスイート全体を実行します。

pnpm test

カバレッジと失敗があれば報告します。

ステップ 6：セルフレビュー

ユーザーに提示する前に、包括的なセルフレビューを実施します。

pnpm type-check      # No TypeScript errors
pnpm lint            # No linting violations
pnpm format:check    # No Prettier formatting issues
pnpm test            # All unit tests pass
pnpm test:smoke      # DI wiring and component tree render OK

format:check が失敗した場合は、先に進む前に、報告されたファイルに対して pnpm exec prettier --write を実行します。

以下を確認します。

• ハードコードされたシークレットや認証情報がない
• ユーザー向けのすべての入力が検証されている
• 適切なエラー処理（エラーを握りつぶさない）
• コンポーネントがアクセシブルである（ARIA、キーボード操作）
• TypeScript で any 型を使用していない
• UI に適切なローディング状態とエラー状態がある

ステップ 7：ドキュメントを更新する

この機能によってプロジェクトのセットアップ、ビルド、実行方法が変わる場合は、コミットする前に関連ドキュメントを更新してください。

1. README.md — この機能によって新しいインフラストラクチャ、サービス、環境変数、コマンドが追加される場合は、クイックスタート、アプリケーションの実行、またはプロジェクト構成のセクションを更新します
2. docs/DEVELOPMENT.md — 必要に応じて、前提条件、ローカル開発環境のセットアップ、データベース操作、またはトラブルシューティングのセクションを更新します
3. Makefile — よく使う操作（新しい Docker サービス、データベースコマンドなど）のターゲットを追加します
4. .env.example files — 新しい環境変数を、明確な説明と安全なデフォルト値とともに追加します
5. docs/INDEX.md — docs/ に新しいファイルを追加した場合は、マスタードキュメントインデックスの適切な表に追加します

重要

リポジトリを新たにクローンした開発者が、README.md だけに従ってプロジェクトを実行できる必要があります。この機能によって Docker サービス、データベース、新しい開発サーバー、または環境変数が追加される場合は、ドキュメントに必ず反映してください。

ステップ 8：コミットする

チェックポイント：完全な概要をユーザーに提示します。

• 作成・変更したファイル（レイヤーごとに整理）
• データベースの変更（ある場合）
• 追加した API エンドポイント（ある場合）
• 作成したコンポーネント（ある場合）
• テスト結果とカバレッジ
• 既知の制限事項または先送りした項目

コミットする前に、ユーザーの承認を待ちます。

アトミックで規約に沿ったコミットを作成します。機能が小さく、1 つのコミットで済む場合：

feat(<scope>): implement <feature-name>

機能が大規模な場合は、論理的な単位に分けてコミットします。

feat(db): add <model> schema and migration
feat(api): add <resource> endpoints
feat(web): add <feature> components and pages
test: add tests for <feature>

GitHub Issue を更新する

GitHub Issue から実装を開始した場合：

1. 進捗をコメントします。

   gh issue comment <number> --body "Implementation committed on branch \`<branch-name>\`. Proceeding to code review via \`/review-code\`."
   

メモ

ここでは in-progress ラベルを削除しないでください。Issue がクローズされるまで、ラベルはそのまま残ります（.github/workflows/label-cleanup.yml によって自動的に処理されます）。これにより、コードレビューと PR の提出が終わるまで、Issue が進行中であることを明示できます。

ステップ 9：引き継ぐ — ここで停止する

注意

このスキルの作業は完了です。 プルリクエストの作成、リモートへのプッシュ、コードレビューは行わないでください。これらは、それぞれ独自のワークフローとチェックポイントを持つ別のスキルです。

次のステップをユーザーに提示します。

• 推奨：提出前に複数の視点からレビューするため、/review-code を実行します
• 作業が残っている場合：実装計画の残りのタスクを続けてから、/review-code を実行します
• UI の比重が高い場合：コードレビューの前に /ui-design:design-review の実行を検討します

GitHub Issue から作業している場合は、ユーザーに次の点を伝えます。

• PR に Closes #<number> を記載すると、マージ時に Issue が自動的にクローズされます
• /submit-pr はコミットメッセージから関連する Issue を検出します

このスキル内からブランチをプッシュしたり、PR を作成したり、/submit-pr を呼び出したりしないでください。