debug-fe-be-integration

フロントエンドとバックエンドの連携をデバッグするスキル

自由度：混合。 どちら側に問題があるか [自由度：高]； 両側を追跡するための調査 [自由度：低 — 指示どおりに実行]。

バックエンドのログ、本番環境のエラー、ソースコードを分析して根本原因を特定し、両側を修正するための、フロントエンドとバックエンドの連携問題に対する体系的なデバッグ方法です。

推論方法

1. 確認 — ステータス、ペイロード、検証エラー、両側のログ
2. 解釈 — FE がフィールドを省略したのか、BE のスキーマがずれたのか、認証／CORS の問題なのか
3. 分類 — パラメーター不足／型／404／401／500／CORS
4. 重大度 — 書き込み処理の 500 は、見た目だけの 422 メッセージより優先度が高くなります

作業例

確認： FE の GET /api/reports → 500；BE のログに year で ZodError: expected string, received undefined。 解釈： FE が year を省略していました；BE のスキーマではデフォルト値なしで必須になっていました。 分類： パラメーター不足 — FE の呼び出しを修正し、BE で明確な 422 またはデフォルト値を追加します。 検証： 同じリクエストが年を指定した状態で 200 を返します；両側を更新済みです。

報告前の自己批評

• 両側を確認 — FE の呼び出しと BE のスキーマ／ログを確認し、片側だけを推測していません
• 契約を明示 — 「両者に食い違いがある」ではなく、ステータスとペイロードのフィールドを示しています
• 分類に合った修正 — 404 を Zod のデフォルト値で修正していません
• 適切な担当 — 単一レイヤーのクラッシュ → debug-error；事前の契約監査 → audit-fe-api

---

ステップ 0：スタックを自動検出する

デバッグを始める前に、プロジェクトのアーキテクチャを特定します。

0a. フロントエンドフレームワークを検出する

package.json を読み、以下を確認します。

シグナル	フレームワーク
next	Next.js
nuxt	Nuxt
@remix-run/react	Remix
@sveltejs/kit	SvelteKit
vite + react	Vite React SPA
@angular/core	Angular

0b. バックエンドフレームワークを検出する

Glob: **/app/api/**/route.ts → Next.js App Router
Glob: **/pages/api/**/*.ts → Next.js Pages Router
Glob: **/server/api/**/*.ts → Nuxt server
Glob: **/src/routes/**/*.ts → Express/Hono/Fastify
Glob: **/src/app.ts or **/src/index.ts → Node backend entry
Glob: **/main.py or **/app.py → Python backend
Glob: **/main.go → Go backend

0c. API スタイルと検証を検出する

シグナル	テクノロジー
@trpc/server	tRPC（型安全、REST の監査は不要）
graphql または @apollo/server	GraphQL
BE の依存関係に zod	Zod による検証
BE の依存関係に joi	Joi による検証
BE の依存関係に yup	Yup による検証
class-validator	NestJS スタイルの検証
pydantic	Python の Pydantic による検証

0d. ルートとコントローラーのパターンを見つける

Grep: pattern "router\.(get|post|patch|put|delete)" glob "*.{ts,js}" — Express-style
Grep: pattern "app\.(get|post|patch|put|delete)" glob "*.{ts,js}" — Hono/Express
Grep: pattern "export (async function |const )(GET|POST|PATCH|PUT|DELETE)" glob "**/route.ts" — Next.js
Grep: pattern "defineEventHandler" glob "*.{ts,js}" — Nuxt/H3

0e. 検出結果を記録する

STACK DISCOVERY:
- Frontend: [framework + version]
- Backend: [framework + version]
- API style: [REST / GraphQL / tRPC]
- Validation: [Zod / Joi / Yup / Pydantic / none]
- Route files: [pattern and locations]
- Controller files: [pattern and locations]
- Schema files: [pattern and locations]

---

ステップ 1：デバッグのパターンを調査する

1a. Firecrawl — 連携のデバッグ

フレームワークと検証ライブラリは、記載されている名前のまま検索します。名前を知っていることと、現在の API やエラー形式を把握していることは別です。

firecrawl:firecrawl_search
{
 "query": "<FE_FRAMEWORK> <BE_FRAMEWORK> API integration debugging best practices [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

追加の対象を絞った検索：

トピック	クエリ
検証エラー	<VALIDATION_LIB> error handling API response best practices
CORS の問題	<BE_FRAMEWORK> CORS configuration debugging
型の不一致	TypeScript API type safety frontend backend shared types

1b. Context7 — フレームワークのドキュメント

context7:resolve-library-id
{
 "libraryName": "<VALIDATION_LIB>",
 "query": "error handling error messages custom errors"
}

---

ステップ 2：エラーの証拠を集める

2a. Sentry で本番環境のエラーを確認する

sentry:search_issues
{
 "organizationSlug": "<ORG_SLUG>",
 "query": "API integration errors 4xx 5xx validation from the last 7 days",
 "projectSlugOrId": "<PROJECT_SLUG>",
 "regionUrl": "<REGION_URL>",
 "limit": 25
}

プロジェクトで FE と BE の Sentry プロジェクトが分かれている場合は、両方を確認します。

• FE プロジェクト：API 呼び出しによるネットワークエラー、未処理の拒否
• BE プロジェクト：検証エラー、未処理の例外、500 エラー

2b. バックエンドのターミナルログを読む

バックエンドを実行しているターミナル（npm run dev または同等のもの）の出力を読みます。Cursor では terminals/*.txt、Claude Code では、起動したシェルまたはログファイルを確認します。

直近 3〜5 分間のエラーを確認します。

• 4xx エラー（400、401、403、404、422）
• 5xx エラー（500、502、503）
• ZodError / ValidationError — 検証の失敗
• AppError / カスタムエラークラス
• スタックトレース
• 警告メッセージ

2c. 検出したエラーを分類する

カテゴリ	ログパターン	根本原因
パラメーター不足	ZodError: expected string, received undefined	FE が必須パラメーターを送信していない
型の誤り	ZodError: invalid_type	FE が誤った型を送信している
エンドポイントが見つからない	404 /api/...	FE が存在しないエンドポイントを呼び出している
認証エラー	401 Unauthorized	トークンがない、または無効
権限エラー	403 Forbidden	ユーザーに権限がない
バリデーションエラー	422 Unprocessable	リクエストボディが無効
サーバーエラー	500 Internal	バックエンドのバグ
CORS エラー	CORS policy	CORS 設定がない

---

ステップ 3：エラーをソースコードまで追跡する

3a. エラーをエンドポイントに対応付ける

検出した各エラーについて、Grep を使って次の箇所を検索します。

フロントエンドの呼び出し：

Grep: pattern "<ERROR_ENDPOINT>" glob "*.{ts,tsx,js,jsx}"

バックエンドのルート：

Grep: pattern "<ERROR_ENDPOINT>" glob "*.{ts,js,py,go,rb}" — in backend source

バリデーションスキーマ：

Grep: pattern "z\.object|z\.string|z\.number" in the controller/route file
SemanticSearch: "validation schema for <ENDPOINT>" target: [backend directory]

3b. リクエストの全経路を確認する

各エラーについて、リクエストの経路全体を読みます。

1. フロントエンドの呼び出し — API 呼び出しを行うファイル（サービス、フック、またはコンポーネント）を読みます
2. API クライアント設定 — axios/fetch のインターセプター設定を読みます
3. バックエンドのルート — ルートハンドラーを読みます
4. バックエンドのコントローラー — コントローラー／サービスのロジックを読みます
5. バリデーションスキーマ — エンドポイントの Zod/Joi/Yup スキーマを読みます
6. データベースクエリ — エラーがデータに関連する場合は、DB クエリを読みます

3c. Supabase MCP でデータの状態を確認する

エラーがデータに関連する可能性がある場合：

supabase:execute_sql
{
 "query": "SELECT * FROM <TABLE> WHERE <CONDITION> LIMIT 5"
}

確認事項：

• FE が想定しているデータは実際に存在しますか？
• enum 値は正しいですか？
• 外部キーの関係は保たれていますか？
• RLS ポリシーはこのユーザーのアクセスを許可していますか？

---

ステップ 4：修正の推奨事項を作成する

4a. フロントエンドの修正

各エラーについて、次の内容を提示します。

### Issue: [Endpoint] — [Error Type]

**Current FE Call:**
[show the actual code from Grep results]

**Correct FE Call:**
[show the fixed code]

**Why:** [explanation of required parameter/type/format]

**Files to Update:** [list specific files]

4b. バックエンドの改善

各エラーについて、バックエンドの改善案を検討し、レポート内で推奨事項として提示します。該当する契約違反を修正し、堅牢性の改善はユーザーから依頼された場合にのみ実施します。編集はすべて必要最小限にとどめます。

### Backend Enhancement: [Endpoint]

**Current Behavior:** Returns 500 with cryptic validation error

**Recommended Enhancement:**
- Add default value for optional params
- Add clear error message for required params
- Add type coercion where appropriate
- Return helpful 422 instead of 500

バックエンド改善パターンの例：

// Before: bare schema, cryptic error on missing param
const schema = z.object({
 year: z.string(),
});

// After: defaults, coercion, clear errors
const schema = z.object({
 year: z.string({
 required_error: "year is required (format: YYYY)"
 }).default(() => new Date().getFullYear().toString()),
 page: z.coerce.number().default(1).int().positive(),
 limit: z.coerce.number().default(10).int().max(100),
});

---

ステップ 5：バックエンドの堅牢性チェックリスト

入力バリデーション

• すべての必須パラメーターに明確なエラーメッセージがある
• 適切なデフォルト値がある任意パラメーターには、デフォルト値が設定されている
• 適切な場合に型変換を行う（文字列から数値など）
• 範囲を検証する（日付、数値）
• 形式を検証する（メールアドレス、UUID、日付文字列）

エラー処理

• データベースエラーを捕捉してラップする
• 対応可能なエラーメッセージを提示する（「Internal Server Error」ではない）
• コンテキスト（userId、エンドポイント、パラメーター）とともにエラーをログに記録する
• 内部情報（スタックトレース、SQL）をクライアントに公開しない

API 契約の一貫性

• レスポンスの形式に一貫性がある（{ data } または { error }）
• ステータスコードが正しい（成功は 200、作成は 201、削除は 204）
• すべてのリストエンドポイントでページネーション形式に一貫性がある
• 日付形式に一貫性がある（ISO 8601）
• エラーレスポンスの形式に一貫性がある

---

出力テンプレート

## Frontend-Backend Integration Debug Report

**Analyzed:** [timestamp range]
**Frontend:** [framework]
**Backend:** [framework]
**API style:** [REST/GraphQL/tRPC]

---

### Production Errors (Sentry)

| Endpoint | Error | Events (7d) | Root Cause |
|----------|-------|-------------|------------|
| [endpoint] | [error msg] | [count] | [FE/BE/Data] |

---

### Backend Log Errors

| Endpoint | Method | Status | Error Type | Root Cause |
|----------|--------|--------|------------|------------|
| `/api/...` | GET | 500 | ZodError | Missing `year` param |
| `/api/...` | GET | 404 | Not Found | Endpoint not implemented |

---

### Critical Issues (Must Fix)

#### 1. [Endpoint] — [Status Code]
- **Error:** [error message]
- **Root Cause:** [explanation]
- **Frontend Fix:** [what FE needs to change, with code]
- **Backend Enhancement:** [optional BE improvement, with code]
- **Files:** FE: [path], BE: [path]

---

### Warnings (Should Fix)

#### 1. [Issue description]
- **Impact:** [what happens if not fixed]
- **Recommendation:** [how to fix]

---

### Backend Enhancements (Robustness)

#### 1. [Enhancement description]
- **Current:** [current behavior]
- **Recommended:** [better approach]
- **Benefit:** [why this helps]

---

### Research Findings Applied
- [Pattern from research]: [how it applies]
- [Best practice]: [gap identified]

---

### Summary Table

| Endpoint | Issue | Fix Required | Priority |
|----------|-------|--------------|----------|
| `/api/...` | Missing param | Frontend | HIGH |
| `/api/...` | No error handling | Both | MEDIUM |
| `/api/...` | Endpoint 404 | Remove or implement | LOW |

---

### Next Steps

1. [ ] Frontend fixes: [action items with files]
2. [ ] Backend enhancements: [action items with files]
3. [ ] Re-test: [verification steps]
4. [ ] Monitor: Check Sentry after deploy for regression

---

よくあるパターンと修正方法

パターン 1：クエリパラメーター不足

症状： ZodError: expected string, received undefined

FE の修正： API 呼び出しに不足しているパラメーターを追加します。

BE の修正： デフォルト値または明確なエラーメッセージを追加します。

パターン 2：エンドポイントが見つからない（404）

症状： 404 /api/endpoint-name

デバッグ手順：

1. バックエンドのルートファイルでエンドポイントのパスを Grep で検索する
2. エンドポイントが別の名前で存在していないか確認する
3. 利用可能な場合は API ドキュメントを確認する
4. FE の呼び出しを削除する、誤記を修正する、またはエンドポイントを実装する、のいずれかを判断する

パターン 3：サービスの障害（500）

症状： 有用なメッセージのない 500 Internal Server Error

デバッグ手順：

1. バックエンドのコントローラーを読み、未処理の例外がないか確認する
2. サービスが DB エラーを適切に処理しているか確認する
3. Supabase を使用している場合は RLS ポリシーを確認する（データがブロックされている可能性があります）
4. 意味のあるエラーレスポンスを返す try/catch を追加する

パターン 4：CORS エラー

症状： CORS policy: No 'Access-Control-Allow-Origin'

デバッグ手順：

1. バックエンドの CORS 設定を確認します
2. 許可されているオリジン、メソッド、ヘッダーを確認します
3. FE と BE でクレデンシャルモードが一致しているか確認します

パターン 5：重複したリクエスト／古いリクエスト

症状： 同じ API が複数回呼び出される、または古いデータが表示される

デバッグ手順：

1. TanStack Query ／ SWR の staleTime が設定されているか確認します
2. ミューテーション後にキャッシュの無効化が行われるか確認します
3. queryKey が正しく、一意であるか確認します
4. コンポーネントの再マウントによって再フェッチが発生していないか確認します

---

他のスキルとの連携

• audit-fe-api：FE コードの観点から先回りして監査します（最初に実行してください）。
• debug-sentry-monitor：本番環境の Sentry エラーをトリアージして修正します。
• audit-db-schema：DB スキーマが API の想定と一致しているか確認します。