build-api

バックエンド API 開発ワークフロー

NestJS のパターン、Prisma のスキーマ設計、プロジェクトのクリーンアーキテクチャの規約に従って、バックエンド API のエンドポイント、サービス、データベースの変更を実装します。

注意

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

Step 1: API 要件を定義する

最新の main を基にしたフィーチャーブランチにいることを確認します。必ず最初にフェッチしてください。

git fetch origin main

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

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

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

git status --porcelain

作業ツリーに変更がある場合は、リベースの前に変更をスタッシュします。

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

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

git rebase origin/main

ユーザーが GitHub の Issue 番号（例：/build-api 42 または /build-api #42）を指定した場合は、Issue を取得し、作業中であることを示します（ルールについては AGENTS.md の「ラベル管理」を参照してください）。

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

# 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"

Issue が Product Roadmap プロジェクトボードで追跡されていることを確認します。追跡されていない場合は追加します。

# --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

警告

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

ユーザーに質問するか、（先に /plan-feature が実行されている場合は）決定記録または Issue の本文から確認します。

• 作成または変更するリソースやエンドポイントは何ですか？
• 必要な操作（CRUD、カスタムアクション、クエリ）は何ですか？
• データベーススキーマの変更はありますか？
• tRPC のプロシージャですか、それとも REST エンドポイントですか？
• 認証または認可の要件はありますか？

docs/decisions/ に決定記録がある場合は、それを読み、タスクの内訳を確認します。

Step 2: API コントラクトを設計する

API 設計の指針として /backend-development:api-design-principles を呼び出します。

API コントラクト全体を設計します。

• エンドポイントのパスと HTTP メソッド（REST）またはプロシージャ名（tRPC）
• リクエストの型：すべてのフィールドと任意／必須の指定を含む、完全な TypeScript インターフェース
• レスポンスの型：該当する場合は、成功レスポンス、エラーレスポンス、ページネーション
• バリデーションルール：実行時バリデーションに Zod スキーマを使用
• エラー形式：標準化されたエラーレスポンス構造
• 認証要件：認証が必要なエンドポイント、ロールベースのアクセス制御

これが重要な API の決定（新しいリソースタイプ、既存 API の破壊的変更、新しいアーキテクチャパターン）にあたる場合は、.claude/councils/architecture-council.md を使用して Architecture Council を招集します。

モデルの選択：エージェントのモデル仕様を Task ツールのパラメーターに対応付ける方法については、README.md の モデルの選択 セクションを参照してください。

プリンシパルエンジニア — 相談先：full-stack-orchestration

• 投票：承認／懸念あり／反対
• 根拠：アーキテクチャの妥当性、スケーラビリティ、保守性
• 推奨事項：従うべきパターン、検討すべきトレードオフ

プラットフォームエンジニア — 相談先：cloud-infrastructure

• 投票：承認／懸念あり／反対
• 根拠：運用への影響、デプロイに関する検討事項
• 推奨事項：インフラストラクチャに関する懸念、監視の必要性

セキュリティエンジニア — 相談先：security-scanning

• 投票：承認／懸念あり／反対
• 根拠：セキュリティリスク、攻撃対象領域、コンプライアンス
• 推奨事項：セキュリティ強化の手順、入力バリデーション

バックエンドスペシャリスト — 相談先：backend-development

• 投票：承認／懸念あり／反対
• 根拠：API 設計の品質、NestJS のパターン、開発者体験
• 推奨事項：実装方法、エコシステムとの統合

チェックポイント：API コントラクト（有効化されている場合はアーキテクチャ評議会による評価も）をユーザーに提示します。実装を開始する前に承認を待ちます。

ステップ 3：データベースレイヤー（必要な場合）

スキーマの変更が必要な場合：

1. PostgreSQL のスキーマ設計に関するガイダンスとして /database-design:postgresql を呼び出します

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

   • 適切なフィールド型を使ったモデル定義
   • リレーションと外部キー
   • クエリのパフォーマンス向上のためのインデックス
   • 一意制約と検証
   • 適切な場合は列挙型

3. マイグレーション生成に関するガイダンスとして /database-migrations:sql-migrations を呼び出します

チェックポイント：Prisma スキーマの変更とマイグレーション計画をユーザーに提示します。マイグレーションを実行する前に承認を待ちます。

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

   pnpm db:migrate
   

5. シードデータが必要な場合は、シードスクリプトを更新します。

ステップ 4：バックエンドを実装する

クリーンアーキテクチャのために、NestJS のパターンと /backend-development:architecture-patterns に従います：

型と DTO

• リクエスト／レスポンス用の TypeScript インターフェースを定義します
• 実行時検証用の Zod バリデーションスキーマを作成します
• フロントエンドで利用する型をエクスポートします（tRPC または共有パッケージ経由）

リポジトリ／データアクセスレイヤー

• Prisma クエリを作成または更新します
• データアクセスパターンを実装します（使用している場合はリポジトリパターン）
• クエリを最適化します（特定のフィールドを選択し、include を慎重に使用します）

サービスレイヤー

• NestJS サービスにビジネスロジックを実装します
• 入力検証とビジネスルールの適用を追加します
• 型付き例外でエラーケースを処理します
• サービスをテスト可能な状態に保ちます（依存関係を注入します）

コントローラー／ルーターレイヤー

• tRPC プロシージャまたは NestJS コントローラーを作成します
• バリデーション、認証ガード、サービスを接続します
• 適切な HTTP ステータスコード（REST）またはエラーコード（tRPC）を実装します
• 公開エンドポイントで必要な場合はレート制限を追加します

ガードとミドルウェア

• 必要な箇所に認証ガードを追加します
• 認可チェック（ロールベースまたはリソースベース）を追加します
• デバッグ用のリクエストログを追加します

複雑な型のシナリオ（ジェネリクス、条件付き型、マップ型）には、/javascript-typescript:typescript-advanced-types を使用します。

パフォーマンスが重要なエンドポイントでは、API のプロファイリングと最適化パターンのために /application-performance:performance-optimization を呼び出します。

ステップ 5：テストを作成する

QA リードのテスト戦略に従います：

ユニットテスト

• 各サービスメソッドを個別にテストします
• Prisma クライアントと外部依存関係をモックします
• ビジネスロジック、検証ルール、エラー処理をテストします
• 正常系とエッジケースを網羅します

統合テスト

• 実際の（テスト用）データベースに対してエンドポイントをテストします
• リクエストのバリデーションで不正な入力が拒否されることを確認します
• 認証と認可が適切に適用されていることを確認します
• さまざまな失敗パターンに対するエラーレスポンスをテストします

検証テスト

• 境界条件（空文字列、最大長、特殊文字）
• 無効な入力形式
• 必須フィールドの欠落
• 型の強制変換とキャスト

テストを実行し、カバレッジを確認します：

pnpm test

カバレッジが 80% 超の目標を満たしていることを確認します。

ステップ 6：API ドキュメントを生成する

新しいエンドポイントの API ドキュメントを生成または更新するために、/documentation-generation:openapi-spec-generation を呼び出します。

tRPC を使用する場合は、プロシージャのシグネチャと使用例を記載します。 REST を使用する場合は、OpenAPI／Swagger 仕様を生成または更新します。

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

ユーザーに提示する前に、次の点を確認します：

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 container and HTTP pipeline boot OK

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

よくある問題がないか確認します：

• ハードコードされたシークレットや認証情報がない
• 適切なエラー処理（エラーを握りつぶしていない）
• 外部に公開されるすべてのエンドポイントで入力を検証している
• TypeScript の strict モードを適切に使用している（any 型を使っていない）

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

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

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

重要

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

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

チェックポイント：変更内容の概要（変更したファイル、実装した API コントラクト、テスト結果、ドキュメント）を提示します。ユーザーの承認を待ちます。

Conventional Commits 形式でコミットします。

feat(api): add <resource> endpoints

既存のエンドポイントを変更する場合：

feat(api): update <resource> with <change-description>

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 が進行中であることを明確に示せます。

ステップ 10：引き継ぐ — ここで停止

注意

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

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

• 推奨：提出前に、多角的なセキュリティと品質のレビューを行うため、/review-code を実行します
• 作業が残っている場合：残りのタスクを続けてから、/review-code を実行します

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

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

パイプライン：/plan-feature → /build-feature または /build-api → /review-code → /submit-pr

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