senior-backend

シニアバックエンドエンジニア

バックエンド開発のパターン、API 設計、データベースの最適化、セキュリティ対策について説明します。

---

クイックスタート

# Generate API routes from OpenAPI spec
python scripts/api_scaffolder.py openapi.yaml --framework express --output src/routes/

# Analyze database schema and generate migrations
python scripts/database_migration_tool.py --connection postgres://localhost/mydb --analyze

# Load test an API endpoint
python scripts/api_load_tester.py https://api.example.com/users --concurrency 50 --duration 30

---

ツールの概要

1. API スキャフォルダー

スキーマ定義から API ルートハンドラー、ミドルウェア、OpenAPI 仕様を生成します。

入力： OpenAPI 仕様（YAML/JSON）またはデータベーススキーマ
出力： ルートハンドラー、バリデーションミドルウェア、TypeScript 型

使用方法：

# Generate Express routes from OpenAPI spec
python scripts/api_scaffolder.py openapi.yaml --framework express --output src/routes/
# Output: Generated 12 route handlers, validation middleware, and TypeScript types

# Generate from database schema
python scripts/api_scaffolder.py --from-db postgres://localhost/mydb --output src/routes/

# Generate OpenAPI spec from existing routes
python scripts/api_scaffolder.py src/routes/ --generate-spec --output openapi.yaml

対応フレームワーク：

• Express.js（--framework express）
• Fastify（--framework fastify）
• Koa（--framework koa）

---

2. データベースマイグレーションツール

データベーススキーマを分析して変更を検出し、ロールバックに対応したマイグレーションファイルを生成します。

入力： データベース接続文字列またはスキーマファイル
出力： マイグレーションファイル、スキーマ差分レポート、最適化の提案

使用方法：

# Analyze current schema and suggest optimizations
python scripts/database_migration_tool.py --connection postgres://localhost/mydb --analyze
# Output: Missing indexes, N+1 query risks, and suggested migration files

# Generate migration from schema diff
python scripts/database_migration_tool.py --connection postgres://localhost/mydb \
  --compare schema/v2.sql --output migrations/

# Dry-run a migration
python scripts/database_migration_tool.py --connection postgres://localhost/mydb \
  --migrate migrations/20240115_add_user_indexes.sql --dry-run

---

3. API 負荷テストツール

同時実行数を設定できる HTTP 負荷テストを実施し、レイテンシのパーセンタイルとスループットを測定します。

入力： API エンドポイント URL とテスト設定
出力： レイテンシ分布、エラー率、スループット指標を含むパフォーマンスレポート

使用方法：

# Basic load test
python scripts/api_load_tester.py https://api.example.com/users --concurrency 50 --duration 30
# Output: Throughput (req/sec), latency percentiles (P50/P95/P99), error counts, and scaling recommendations

# Test with custom headers and body
python scripts/api_load_tester.py https://api.example.com/orders \
  --method POST \
  --header "Authorization: Bearer token123" \
  --body '{"product_id": 1, "quantity": 2}' \
  --concurrency 100 \
  --duration 60

# Compare two endpoints
python scripts/api_load_tester.py https://api.example.com/v1/users https://api.example.com/v2/users \
  --compare --concurrency 50 --duration 30

---

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

API 設計ワークフロー

新しい API を設計するとき、または既存のエンドポイントをリファクタリングするときに使用します。

ステップ 1：リソースと操作を定義する

# openapi.yaml
openapi: 3.0.3
info:
  title: User Service API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: "limit"
          in: query
          schema:
            type: integer
            default: 20
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'

ステップ 2：ルートのスキャフォールディングを生成する

python scripts/api_scaffolder.py openapi.yaml --framework express --output src/routes/

ステップ 3：ビジネスロジックを実装する

// src/routes/users.ts (generated, then customized)
export const createUser = async (req: Request, res: Response) => {
  const { email, name } = req.body;

  // Add business logic
  const user = await userService.create({ email, name });

  res.status(201).json(user);
};

ステップ 4：バリデーションミドルウェアを追加する

# Validation is auto-generated from OpenAPI schema
# src/middleware/validators.ts includes:
# - Request body validation
# - Query parameter validation
# - Path parameter validation

ステップ 5：更新した OpenAPI 仕様を生成する

python scripts/api_scaffolder.py src/routes/ --generate-spec --output openapi.yaml

---

データベース最適化ワークフロー

クエリの実行が遅いときや、データベースのパフォーマンスを改善する必要があるときに使用します。

ステップ 1：現在のパフォーマンスを分析する

python scripts/database_migration_tool.py --connection $DATABASE_URL --analyze

ステップ 2：遅いクエリを特定する

-- Check query execution plans
EXPLAIN ANALYZE SELECT * FROM orders
WHERE user_id = 123
ORDER BY created_at DESC
LIMIT 10;

-- Look for: Seq Scan (bad), Index Scan (good)

ステップ 3：インデックスのマイグレーションを生成する

python scripts/database_migration_tool.py --connection $DATABASE_URL \
  --suggest-indexes --output migrations/

ステップ 4：マイグレーションをテストする（ドライラン）

python scripts/database_migration_tool.py --connection $DATABASE_URL \
  --migrate migrations/add_indexes.sql --dry-run

ステップ 5：適用して検証する

# Apply migration
python scripts/database_migration_tool.py --connection $DATABASE_URL \
  --migrate migrations/add_indexes.sql

# Verify improvement
python scripts/database_migration_tool.py --connection $DATABASE_URL --analyze

---

セキュリティ強化ワークフロー

API を本番環境に導入する準備をするとき、またはセキュリティレビューの後に使用します。

ステップ 1：認証の設定を確認する

// Verify JWT configuration
const jwtConfig = {
  secret: process.env.JWT_SECRET,  // Must be from env, never hardcoded
  expiresIn: '1h',                 // Short-lived tokens
  algorithm: 'RS256'               // Prefer asymmetric
};

ステップ 2：レート制限を追加する

import rateLimit from 'express-rate-limit';

const apiLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,  // 15 minutes
  max: 100,                   // 100 requests per window
  standardHeaders: true,
  legacyHeaders: false,
});

app.use('/api/', apiLimiter);

ステップ 3：すべての入力を検証する

import { z } from 'zod';

const CreateUserSchema = z.object({
  email: z.string().email().max(255),
  name: z.string().min(1).max(100),
  age: z.number().int().positive().optional()
});

// Use in route handler
const data = CreateUserSchema.parse(req.body);

ステップ 4：攻撃パターンを用いて負荷テストを行う

# Test rate limiting
python scripts/api_load_tester.py https://api.example.com/login \
  --concurrency 200 --duration 10 --expect-rate-limit

# Test input validation
python scripts/api_load_tester.py https://api.example.com/users \
  --method POST \
  --body '{"email": "not-an-email"}' \
  --expect-status 400

ステップ 5：セキュリティヘッダーを確認する

import helmet from 'helmet';

app.use(helmet({
  contentSecurityPolicy: true,
  crossOriginEmbedderPolicy: true,
  crossOriginOpenerPolicy: true,
  crossOriginResourcePolicy: true,
  hsts: { maxAge: 31536000, includeSubDomains: true },
}));

---

リファレンスドキュメント

ファイル	内容	使用する場面
references/api_design_patterns.md	REST と GraphQL の比較、バージョニング、エラーハンドリング、ページネーション	新しい API の設計
references/database_optimization_guide.md	インデックス戦略、クエリ最適化、N+1 問題の解決策	遅いクエリの改善
references/backend_security_practices.md	OWASP Top 10、認証パターン、入力検証	セキュリティの強化

---

よく使うパターンのクイックリファレンス

REST API レスポンス形式

{
  "data": { "id": 1, "name": "John" },
  "meta": { "requestId": "abc-123" }
}

エラーレスポンス形式

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [{ "field": "email", "message": "must be valid email" }]
  },
  "meta": { "requestId": "abc-123" }
}

HTTP ステータスコード

コード	用途
200	成功（GET、PUT、PATCH）
201	作成済み（POST）
204	コンテンツなし（DELETE）
400	バリデーションエラー
401	認証が必要
403	アクセス権限なし
404	リソースが見つからない
429	レート制限超過
500	内部サーバーエラー

データベースのインデックス戦略

-- Single column (equality lookups)
CREATE INDEX idx_users_email ON users(email);

-- Composite (multi-column queries)
CREATE INDEX idx_orders_user_status ON orders(user_id, status);

-- Partial (filtered queries)
CREATE INDEX idx_orders_active ON orders(created_at) WHERE status = 'active';

-- Covering (avoid table lookup)
CREATE INDEX idx_users_email_name ON users(email) INCLUDE (name);

---

よく使うコマンド

# API Development
python scripts/api_scaffolder.py openapi.yaml --framework express
python scripts/api_scaffolder.py src/routes/ --generate-spec

# Database Operations
python scripts/database_migration_tool.py --connection $DATABASE_URL --analyze
python scripts/database_migration_tool.py --connection $DATABASE_URL --migrate file.sql

# Performance Testing
python scripts/api_load_tester.py https://api.example.com/endpoint --concurrency 50
python scripts/api_load_tester.py https://api.example.com/endpoint --compare baseline.json

---

前提条件と検証可能な成功基準（Karpathy の規律）

このスキルでスキャフォールディング、パターンの推奨、スキーマの変更を行う前に、以下の4つの前提条件を必ず明示する必要があります。不明な項目があれば、このスキルは停止し、強制質問ライブラリに従って質問を進めます。

1. 読み取り／書き込み比率 + 1年後の p99 QPS — DB、キャッシュ、キュー、パーティショニングの選択に影響します。Kleppmann 著、DDIA（2017年）。
2. テナンシーモデル — シングルテナント、共有マルチテナント、分離型マルチテナント。データアクセスパターンに影響します。
3. データ機密性の区分 — 公開／社内／PII／PHI／PCI。コンプライアンスの最低要件に影響します。
4. SLO + エラーバジェットの責任者 — Google SRE Workbook の定説です。SLO がなければ、信頼性向上作業の優先順位は付けられません。

検証可能な成功基準（Karpathy #4）— このスキルが出すすべての推奨には、以下を含める必要があります。

• レイテンシ目標（p50、p95、p99、単位は ms）
• 稼働率／SLO 目標
• RPO + RTO

この3項目のいずれかが記載されていない場合、推奨は不完全です。強制質問ライブラリの Q7 に戻ってください。

 scripts/backend_decision_engine.py ツールには、これらのチェックが実装されています。このツールは、読み取り／書き込み比率 + QPS + テナンシー + データ機密性 + パターンの選好がなければ、プロファイルの推奨を拒否します。

---

カスタマイズ用プロファイル

profiles/ にある4つの組み込みプロファイルが、すべての推奨内容を調整します。

プロファイル	選択する状況	パターン	レイテンシの下限（p99）
node-express	TS チーム、エンジニア15人未満、顧客向け SaaS	Postgres 上のモジュラーモノリス	600ms
fastapi-python	Python チーム、エンジニア20人未満、ML に隣接する領域	Postgres 上のモジュラーモノリス（非同期）	500ms
django-monolith	コンテンツ主体の CRUD + 管理機能、エンジニア25人未満	Postgres 上のモジュラーモノリス	800ms
go-or-rust-microservice	切り出されたサービス、エンジニア30人以上、プラットフォームチーム、QPS ≥ 1000	切り出されたサービス	200ms

次の方法でプロファイルを選択します。

python scripts/backend_decision_engine.py \
  --team-size 8 --qps-p99 50 --read-write-ratio 20 \
  --tenancy shared-multi-tenant --data-sensitivity pii \
  --pattern modular-monolith --language-preference typescript

このツールは、最適なプロファイル、次点候補とのトレードオフ（差が15％以内の場合）、スタックの選択肢、アンチパターン、指名された承認者、SLO の下限を返します。このツールが自動承認することはありません。

カスタムプロファイルを追加するには、profiles/node-express.json を profiles/<your-org>.json にコピーし、constraints + success_thresholds + named_approver_chain を調整してください。

---

構成マップ

このスキルは、POWERFUL 階層の専門スキルが担当する範囲を再実装しません。それらのスキルに引き継ぎます。すべてのルーティング表は references/composition_map.md を参照してください。主な引き継ぎ先は次のとおりです。

懸念事項	引き継ぎ先
API 契約／破壊的変更のリスク	engineering/skills/api-design-reviewer/
スキーマ設計 + ERD + インデックス作成	engineering/skills/database-designer/
ゼロダウンタイムのスキーマ移行	engineering/skills/migration-architect/
SLO + SLI + エラーバジェット	engineering/slo-architect/
オブザーバビリティ／ゴールデンシグナル	engineering/skills/observability-designer/
CI/CD パイプライン	engineering/skills/ci-cd-pipeline-builder/
セキュリティ／脅威モデル	engineering-team/skills/senior-security/、adversarial-reviewer
コンプライアンスの証跡（HIPAA / ISO 27001）	ra-qm-team/
コミット前の Karpathy レビュー	engineering/karpathy-coder/
飛行前のアーキテクチャ質問会	engineering/grill-me/

cs-backend-engineer エージェントは、context: fork を介してこれらの引き継ぎを統括します。別のエージェントから Agent({subagent_type: "cs-backend-engineer", prompt: "..."}) を使って呼び出すか、/cs-backend-review <your problem> を実行してください。

---

強制質問ライブラリ（Matt Pocock grill）

バックエンドに関する決定を確定する前に、references/forcing_questions.md にある7つの強制質問を順に確認してください。以下のルールを守ってください。

1. 1ターンにつき質問は1つです。まとめて質問しないでください。
2. 根拠となる規範を引用して、必ず回答を推奨してください。
3. 回答を /tmp/backend-grill-<date>.md に記録してください。
4. 中止基準に該当したら停止してください。未解決の問題を抱えたまま、ひな形を作成して先に進まないでください。
5. Q7の後に、7つの回答を使って backend_decision_engine.py を実行してください。

概要：

1. 読み取り／書き込み比率と、p99のQPS予測は？
2. テナンシーモデル — シングル／共有／分離のどれですか？
3. 同期／非同期／イベント駆動 — デフォルトと例外は？
4. データの機密性レベル — PII／PHI／PCIのどれですか？
5. モノリス／モジュラーモノリス／マイクロサービス — チーム規模に基づく理由は？
6. RPOとRTOは？
7. SLOと、エラーバジェットの責任者は？

---

他のエージェントやスキルからの呼び出し

呼び出し方法は3つあります。

1. スラッシュコマンド： /cs-backend-review <prompt> — 強制質問、意思決定エンジン、構成の振り分けをすべて実行します。
2. エージェントのサブエージェント： Agent({subagent_type: "cs-backend-engineer", prompt: "..."}) — コンテキストを分岐し、200語以内の要約を返します。
3. ツールを直接呼び出す： python scripts/backend_decision_engine.py ... — 入力が既知の場合に、決定論的なプロファイル照合を行います。

呼び出し規約の全文については、agents/engineering/cs-backend-engineer.md を参照してください。