設計・実装・運用の各段階で押さえておきたい原則をまとめたチェックリスト形式のガイドです。特定のフレームワークに依存しない内容にしています。
目次
- 設計・アーキテクチャ
- セキュリティ
- パフォーマンス
- フロントエンド
- バックエンド・API
- データベース
- アクセシビリティ
- テスト
- CI/CD・デプロイ
- 監視・ロギング・運用
- コード品質・チーム開発
- プライバシー・コンプライアンス
- リリース前チェックリスト
1. 設計・アーキテクチャ
基本原則
- シンプルに始める: 最初からマイクロサービスにしない。モジュール化されたモノリスから始め、必要になってから分割する。
- 関心の分離: プレゼンテーション層・ビジネスロジック層・データアクセス層を分ける。
- ステートレスなアプリケーションサーバー: セッション等の状態は Redis や DB など外部に置き、水平スケールを可能にする。
- The Twelve-Factor App を指針にする（設定は環境変数、依存関係の明示、ログはストリームとして扱う など）。
設定管理
- 環境ごとの差分（DB接続先、APIキー等）はコードに埋め込まず、環境変数やシークレットマネージャで管理する。
.envファイルはリポジトリにコミットしない（.env.exampleのみコミット）。
依存関係
- ライブラリは必要最小限に。導入前にメンテナンス状況・ライセンス・脆弱性を確認する。
- ロックファイル（
package-lock.json,poetry.lock等）を必ずコミットする。
2. セキュリティ
OWASP Top 10 を定期的に確認し、主要な脆弱性カテゴリへの対策を網羅すること。
入力と出力
- すべての入力を信用しない: サーバー側で必ずバリデーションする（クライアント側の検証はUXのためだけ）。
- SQLインジェクション対策: プレースホルダ／パラメータ化クエリ、またはORMを使う。文字列連結でSQLを組み立てない。
- XSS対策: 出力時にコンテキストに応じたエスケープを行う。フレームワークの自動エスケープを無効化する機能（
dangerouslySetInnerHTML,v-html,|safe等）は極力使わない。 - ファイルアップロード: 拡張子・MIMEタイプ・サイズを検証し、Webルート外に保存。ファイル名はサーバー側で生成する。
認証・認可
- パスワードは bcrypt / scrypt / Argon2 などの低速ハッシュで保存する（MD5・SHA-1・平文は厳禁）。
- 多要素認証（MFA）やパスキーを提供する。
- ログイン試行にレート制限・アカウントロックを設ける。
- 認可チェックはサーバー側で毎リクエスト行う。URLやIDを書き換えるだけで他人のデータにアクセスできないか（IDOR）を確認する。
- 最小権限の原則：ユーザー・サービスアカウント・DBユーザーすべてに必要最小限の権限だけを与える。
- 自前実装より、実績のある認証ライブラリ／IDaaS（OAuth 2.0 / OpenID Connect）の利用を検討する。
セッション・Cookie
- Cookie に
Secure,HttpOnly,SameSite=Lax（またはStrict）を付ける。 - ログイン成功時にセッションIDを再生成する（セッション固定攻撃対策）。
- 適切なセッション有効期限とログアウト時の無効化を実装する。
CSRF
- 状態を変更するリクエスト（POST/PUT/DELETE）にはCSRFトークンを使う、または
SameSiteCookie と組み合わせて対策する。 - GETリクエストで状態を変更しない。
通信・HTTPヘッダー
- 全通信を HTTPS 化し、HSTS（
Strict-Transport-Security）を設定する。 - 推奨セキュリティヘッダー:
| ヘッダー | 目的 |
|---|---|
Content-Security-Policy | XSS・データインジェクションの緩和 |
X-Content-Type-Options: nosniff | MIMEスニッフィング防止 |
Referrer-Policy | リファラ情報の漏洩制御 |
Permissions-Policy | カメラ・位置情報等のブラウザ機能制限 |
frame-ancestors（CSP）/ X-Frame-Options | クリックジャッキング防止 |
- CORS は必要なオリジンのみ許可する（
*と認証情報の併用は不可）。
シークレット管理
- APIキー・パスワードをソースコードやフロントエンドのバンドルに含めない。
- シークレットマネージャ（AWS Secrets Manager, GCP Secret Manager, Vault 等）を利用し、定期的にローテーションする。
- リポジトリへのシークレット混入を検知するツール（secret scanning）をCIに組み込む。
その他
- エラーメッセージにスタックトレースや内部情報を表示しない（本番環境）。
- 依存ライブラリの脆弱性を自動検知する（Dependabot, Renovate,
npm audit等）。 - SSRF対策：ユーザー指定URLへサーバーからリクエストする場合は宛先を許可リストで制限する。
3. パフォーマンス
計測ファースト
- 推測で最適化しない。まず計測する（Lighthouse, WebPageTest, ブラウザDevTools, APM）。
- Core Web Vitals を指標にする:
- LCP（Largest Contentful Paint）: 主要コンテンツの表示速度
- INP（Interaction to Next Paint）: 操作への応答性
- CLS（Cumulative Layout Shift）: レイアウトのズレ
フロントエンド
- JavaScript・CSSの圧縮（minify）とコード分割（code splitting）、遅延読み込み（lazy loading）。
- 画像は適切なサイズ・次世代フォーマット（WebP / AVIF）で配信し、
width/heightを指定してCLSを防ぐ。 loading="lazy"で画面外の画像を遅延読み込みする。- フォントは
font-display: swapを使い、必要なサブセットのみ読み込む。 - 不要なサードパーティスクリプトを削減する。
配信
- 静的アセットはCDNから配信する。
- Gzip / Brotli で圧縮する。
- HTTP/2 または HTTP/3 を有効にする。
- 適切な
Cache-Controlヘッダーを設定する（ハッシュ付きファイル名のアセットは長期キャッシュ）。
バックエンド
- 重い処理はジョブキュー（非同期処理）に逃がす。
- 頻繁に読まれるデータはキャッシュする（Redis等）。キャッシュの無効化戦略も同時に設計する。
- 外部API呼び出しにはタイムアウトとリトライ（指数バックオフ）を設定する。
4. フロントエンド
- セマンティックなHTML を書く（
divの乱用を避け、button,nav,main,article等を適切に使う）。 - レスポンシブデザイン: モバイルファーストで設計し、様々な画面幅で確認する。
- 状態管理: グローバル状態は最小限に。サーバー状態（取得データ）とUI状態を区別する。
- エラーハンドリング: ローディング・エラー・空状態のUIを必ず用意する。
- プログレッシブエンハンスメント: JSが失敗しても最低限の機能が使えるよう配慮する。
- フォームでは適切な
type（email,tel等）とautocomplete属性を指定する。 - TypeScript などの型システムを導入し、実行時エラーを減らす。
5. バックエンド・API
API設計
- 一貫した命名規則とURL設計（RESTならリソース指向:
GET /users/{id}）。 - 適切なHTTPステータスコードを返す（200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500 等）。
- エラーレスポンスの形式を統一する（例: RFC 9457 Problem Details）。
- バージョニングを設計段階で決めておく（
/v1/やヘッダー）。 - 一覧系APIにはページネーションを必ず実装する（大量データではカーソル方式を推奨）。
- OpenAPI 等でAPI仕様をドキュメント化し、コードと同期させる。
堅牢性
- 冪等性: 決済などの重要な操作は冪等キー（Idempotency-Key）で二重実行を防ぐ。
- レート制限を設けて濫用やDoSを緩和する。
- タイムアウトをすべての外部呼び出し（DB・API・キャッシュ）に設定する。
- グレースフルシャットダウン: 処理中のリクエストを完了してから停止する。
- ヘルスチェック用エンドポイント（liveness / readiness）を用意する。
6. データベース
- マイグレーションツールでスキーマ変更をバージョン管理する。手動でのスキーマ変更はしない。
- 本番マイグレーションは後方互換を保つ（カラム追加 → デプロイ → 旧カラム削除 の段階的変更）。
- 検索条件・結合に使うカラムにはインデックスを張る。実行計画（
EXPLAIN）で確認する。 - N+1問題を避ける（ORMのEager Loading等を活用）。
- 複数の更新が一貫している必要がある場合はトランザクションを使う。
- 制約（NOT NULL, UNIQUE, 外部キー, CHECK）でデータ整合性をDB層でも担保する。
- バックアップを自動化し、リストア手順を定期的にテストする（復元できないバックアップは無意味）。
- 接続プーリングを適切に設定する。
- 個人情報などの機密データは必要に応じて暗号化して保存する。
7. アクセシビリティ
WCAG（Web Content Accessibility Guidelines）の AA レベル準拠を目標にする。
- 画像に適切な
altテキストを付ける（装飾画像はalt=""）。 - キーボードだけで全操作が可能であること。フォーカスが視覚的に分かること。
- テキストと背景のコントラスト比を十分に確保する（通常テキストで 4.5:1 以上）。
- フォーム要素には
<label>を関連付ける。 - 見出し（
h1〜h6）を論理的な階層で使う。 - 色だけで情報を伝えない（エラーを赤色だけで示さない等）。
- ARIA属性はネイティブHTMLで表現できない場合にのみ使う。
lang属性でページの言語を指定する。- 自動チェックツール（axe, Lighthouse）に加え、スクリーンリーダーでの手動確認も行う。
8. テスト
テストピラミッド
| 種類 | 量 | 目的 |
|---|---|---|
| ユニットテスト | 多 | 関数・クラス単位のロジック検証。高速 |
| 結合テスト | 中 | DB・API・モジュール間連携の検証 |
| E2Eテスト | 少 | 主要なユーザーフローの検証（Playwright, Cypress 等） |
原則
- 重要なビジネスロジックと、過去にバグが出た箇所を優先してテストする。
- カバレッジの数値より、テストが意味のある振る舞いを検証しているかを重視する。
- テストは独立して実行でき、順序に依存しないこと。
- 不安定なテスト（flaky test）は放置せず修正または隔離する。
- バグ修正時は、まずそのバグを再現するテストを書く。
- 負荷テスト・セキュリティテスト（DAST/SAST）も定期的に実施する。
9. CI/CD・デプロイ
- すべての変更はプルリクエスト経由でマージし、CIで自動テスト・リント・型チェック・ビルドを実行する。
- 環境を分ける: 開発 → ステージング → 本番。ステージングは本番にできるだけ近づける。
- Infrastructure as Code（Terraform, Pulumi 等）でインフラを再現可能にする。
- コンテナ化（Docker）で環境差異をなくす。
- デプロイは自動化し、ワンクリックでロールバックできるようにする。
- ブルーグリーンデプロイやカナリアリリースでリスクを低減する。
- フィーチャーフラグでデプロイとリリースを分離する。
- ビルド成果物は一度だけ作り、同じ成果物を各環境にプロモートする。
10. 監視・ロギング・運用
ロギング
- 構造化ログ（JSON等）で出力し、集約基盤（Datadog, CloudWatch, Loki 等）に集める。
- リクエストIDを付与し、サービスをまたいで追跡可能にする。
- ログレベル（DEBUG / INFO / WARN / ERROR）を適切に使い分ける。
- パスワード・トークン・個人情報をログに出さない。
監視・可観測性
- メトリクス・ログ・トレースの3本柱を整備する（OpenTelemetry の活用を検討）。
- 主要指標を監視する: レイテンシ、エラー率、トラフィック、リソース飽和度（Golden Signals）。
- エラートラッキングツール（Sentry 等）でフロント・バックの例外を収集する。
- SLO（サービスレベル目標）を定め、それに基づいてアラートを設定する。
- アラートは「対応が必要なもの」だけに絞り、アラート疲れを防ぐ。
運用
- 障害対応手順（ランブック）を整備する。
- 障害後はポストモーテムを書き、責任追及ではなく再発防止に焦点を当てる。
- 定期的に依存関係・OS・ランタイムを更新する。
11. コード品質・チーム開発
- リンター・フォーマッター（ESLint, Prettier, Ruff 等）を導入し、CIとエディタで自動適用する。
- コードレビューを必須にし、小さなPRを心がける。
- 命名は意図が伝わるように。コメントは「なぜ」を書き、「何を」はコードで表現する。
- README に、セットアップ手順・開発方法・デプロイ方法を記載する。
- 重要な設計判断は ADR（Architecture Decision Record）として残す。
- Git のブランチ戦略とコミットメッセージ規約（Conventional Commits 等）をチームで統一する。
- 技術的負債は可視化し、計画的に返済する時間を確保する。
12. プライバシー・コンプライアンス
- 収集する個人データは必要最小限にする（データ最小化）。
- プライバシーポリシーを明示し、利用目的を説明する。
- 適用される法令（個人情報保護法、GDPR、CCPA 等）を確認し、必要な対応を行う。
- Cookie・トラッキングについて必要に応じて同意を取得する。
- ユーザーによるデータの閲覧・削除リクエストに対応できる仕組みを用意する。
- データの保持期間を定め、不要になったデータは削除する。
13. リリース前チェックリスト
セキュリティ
- HTTPS 化と HSTS 設定済み
- セキュリティヘッダー（CSP 等）設定済み
- 認可チェックが全エンドポイントで実装されている
- シークレットがコード・リポジトリに含まれていない
- 依存ライブラリに既知の重大な脆弱性がない
- 本番でデバッグモード・詳細エラー表示が無効
品質
- 主要フローのE2Eテストが通る
- Lighthouse でパフォーマンス・アクセシビリティを確認済み
- 主要ブラウザ・モバイル端末で動作確認済み
- 404 / 500 などのエラーページを用意している
運用
- ログ・メトリクス・エラー通知が設定されている
- バックアップが取得され、リストアを検証済み
- ロールバック手順が確立されている
- ヘルスチェックエンドポイントがある
その他
-
title/meta description/ OGP 等の基本SEO設定 -
robots.txtとsitemap.xml - favicon の設定
- プライバシーポリシー・利用規約の掲載