quality-gates

このスキルは、コードの品質、セキュリティ、パフォーマンス、本番環境への準備状況を納品前に確認するための、エンジニアリング規律の原則と体系的な品質ゲート手順を提供します。

このスキルを呼び出すタイミング

次の場合に自動的に有効化します。

• コードレビューと検証
• マージ前の品質チェック
• デプロイ前の検証
• リリース準備状況の評価
• 実装後の品質監査
• エンジニアリングの厳密さが求められるあらゆる作業

エンジニアリング規律

基本ルール

1. 近道をしない

• すべての解決策は、長期的に持続可能でなければなりません
• 一時的な修正は、恒久的な負債になります
• 回避策のように感じるなら、それは回避策です

2. 変更は最小限に

• 1つのコミットにつき、論理的な変更は1つ
• 必要な箇所だけを変更する
• Write より Edit（コンテキストを維持）

3. 完了前に検証する

• テストが合格する
• リントエラーがない
• 必要に応じて手動で検証する

判断ルール

リファクタリングするタイミング

次の場合はリファクタリングします。

• 機能の追加が困難
• バグが連鎖する
• コードが分かりにくい

次の場合はリファクタリングしません。

• コードが動作しており、変更もほとんどない
• すぐに必要ではない

抽象化するタイミング

次の場合は抽象化します。

• パターンが3回以上登場する
• 抽象化によって複雑さが軽減される

次の場合は抽象化しません。

• 該当箇所が1〜2か所だけ
• 抽象化によって複雑さが増す

アンチパターン

悪い例	理由	良い例
マジックナンバー	意図が不明確	名前付き定数
神オブジェクト	保守できない	単一責任
コピー＆ペースト	バグが増殖する	共通部分を抽出
コメントアウトされたコード	混乱を招く	Git の履歴
時期尚早な最適化	注目すべき点が違う	まず測定する

品質ゲートのレベル

標準（デフォルト）

通常の変更、バグ修正、小規模な機能向け：

┌─────────────────────────────────────────────────────────┐
│                    STANDARD GATES                        │
├─────────────────────────────────────────────────────────┤
│ ✓ All tests pass                                        │
│ ✓ Linting clean (no errors)                             │
│ ✓ TypeScript compiles (no type errors)                  │
│ ✓ Code follows project patterns                         │
│ ✓ No obvious security issues                            │
│ ✓ Changes match requirements                            │
└─────────────────────────────────────────────────────────┘

厳格

重要な機能、リファクタリング、公開 API 向け：

┌─────────────────────────────────────────────────────────┐
│                     STRICT GATES                         │
├─────────────────────────────────────────────────────────┤
│ All Standard gates PLUS:                                │
│ ✓ Test coverage ≥ 90% for new code                      │
│ ✓ Security scan passes (no high/critical)               │
│ ✓ Performance benchmarks met                            │
│ ✓ API documentation updated                             │
│ ✓ Breaking changes documented                           │
│ ✓ Peer review completed                                 │
└─────────────────────────────────────────────────────────┘

クリティカル

セキュリティ上の機微、本番環境での重要度、リスクの高い変更向け：

┌─────────────────────────────────────────────────────────┐
│                    CRITICAL GATES                        │
├─────────────────────────────────────────────────────────┤
│ All Strict gates PLUS:                                  │
│ ✓ Security audit by security-focused review             │
│ ✓ Load testing completed                                │
│ ✓ Rollback procedure documented and tested              │
│ ✓ Monitoring and alerting configured                    │
│ ✓ Stakeholder sign-off obtained                         │
│ ✓ Incident response plan updated                        │
└─────────────────────────────────────────────────────────┘

品質ゲートの手順

1. コード品質ゲート

# Run these checks in sequence
npm run lint          # or: bun run lint
npm run type-check    # or: bun run type-check
npm run test          # or: bun run test
npm run build         # Verify build succeeds

検証チェックリスト：

• リントエラーがゼロ
• TypeScript エラーがゼロ
• すべてのテストが合格
• ビルドが正常に完了
• 本番コードに console.log 文がない
• リリースを妨げる TODO コメントがない
• ハードコードされた値がない
• エラー処理が実装されている
• 境界で入力を検証している

2. テストカバレッジゲート

npm run test:coverage

レベル別カバレッジ要件：

レベル	行カバレッジ	分岐カバレッジ	関数カバレッジ
標準	≥ 70%	≥ 60%	≥ 70%
厳格	≥ 90%	≥ 80%	≥ 90%
クリティカル	≥ 95%	≥ 90%	≥ 95%

テスト対象：

• 正常系のシナリオ
• エラー処理の経路
• 境界ケース（null、空、境界値）
• 統合ポイント
• ユーザー向けの動作
• テストの結果が決定的である

3. セキュリティゲート

自動チェック：

npm audit              # Dependency vulnerabilities
npm run lint:security  # Security-focused lint rules (if configured)

手動レビューのチェックリスト：

• ハードコードされたシークレットや認証情報がない
• すべてのユーザー入力を検証している
• XSS を防ぐために出力をエンコードしている
• SQL／NoSQL インジェクションを防止している
• 保護されたルートで認証を確認している
• 機密性の高い操作について認可を検証している
• 機密データには HTTPS を適用している
• 機密データをログに記録していない
• CORS を正しく設定している

厳格／クリティカルの場合：

• OWASP Top 10 のレビューを完了している
• 別のエンジニアによるセキュリティ重視のコードレビューを実施している
• ペネトレーションテストを実施している（クリティカルのみ）

4. パフォーマンスゲート

検証する指標：

指標	標準	厳格	クリティカル
ページ読み込み	< 3s	< 2s	< 1s
API 応答	< 500ms	< 200ms	< 100ms
バンドルサイズ	< 500KB	< 300KB	< 200KB
メモリリーク	なし	なし	なし

検証手順：

• N+1 クエリを新たに導入していない
• データベースクエリでインデックスを使用している
• 大きなリストをページネーションしている
• 画像を最適化している
• 適切な箇所にキャッシュを実装している
• メインスレッドでブロッキング処理を行っていない
• リソースを適切にクリーンアップしている

5. ドキュメントゲート

必須ドキュメント：

レベル	README	API ドキュメント	変更履歴	アーキテクチャ
標準	✓	-	✓	-
厳格	✓	✓	✓	-
クリティカル	✓	✓	✓	✓

チェックリスト：

• 新機能や変更内容を README に反映済み
• API エンドポイントを文書化済み（厳格以上）
• 破壊的変更を明確に記載済み
• 該当する場合、移行ガイドを用意済み
• アーキテクチャ上の決定を記録済み（クリティカル）

6. 統合ゲート

検証手順：

• 機能がエンドツーエンドで動作する
• 既存機能にリグレッションがない
• クロスブラウザテストを実施済み（フロントエンドの場合）
• モバイルでの表示に問題がないことを確認済み（該当する場合）
• サードパーティとの統合をテスト済み

厳格／クリティカルの場合：

• E2E テストスイートが成功する
• ステージング環境で検証済み
• ユーザー受け入れテストが完了済み

品質ゲートレポートのテンプレート

## Quality Gate Report

**Feature**: [Feature Name]
**Level**: [Standard | Strict | Critical]
**Date**: [YYYY-MM-DD]
**Reviewer**: [Name]

### Summary
| Gate | Status | Notes |
|------|--------|-------|
| Code Quality | ✅ PASS | All checks clean |
| Test Coverage | ✅ PASS | 92% coverage |
| Security | ✅ PASS | No vulnerabilities |
| Performance | ⚠️ WARN | API slightly slow |
| Documentation | ✅ PASS | Updated |
| Integration | ✅ PASS | E2E passing |

### Detailed Results

#### Code Quality
- Lint: 0 errors, 0 warnings
- TypeScript: 0 errors
- Tests: 47 passed, 0 failed
- Build: Success

#### Test Coverage
- Lines: 92% (target: 90%)
- Branches: 85% (target: 80%)
- Functions: 94% (target: 90%)

#### Security
- npm audit: 0 vulnerabilities
- Manual review: Completed, no issues
- [x] Input validation verified
- [x] Auth checks verified

#### Performance
- Page load: 1.8s (target: < 2s)
- API response: 180ms (target: < 200ms)
- Bundle size: 287KB (target: < 300KB)

#### Issues Found
1. [WARN] API endpoint `/api/users` responds in 450ms under load
   - Recommendation: Add caching layer
   - Severity: Low
   - Blocking: No

### Verdict

**✅ APPROVED FOR MERGE**

All critical gates pass. Performance warning noted for future optimization.

ゲート失敗時の対応

ゲートが失敗した場合：

1. 重大度を特定する

重大度	説明	対応
ブロッカー	デプロイを妨げる	マージ前に必ず修正する
クリティカル	セキュリティ／データのリスク	マージ前に必ず修正する
メジャー	重大な問題	修正すべきだが、承認があれば先送り可能
マイナー	品質上の懸念	フォローアップに先送り可能

2. 問題を記録する

### Gate Failure: [Gate Name]

**Severity**: [Blocker | Critical | Major | Minor]
**Description**: [What failed and why]
**Impact**: [What happens if not fixed]
**Remediation**: [How to fix]
**Timeline**: [When it will be fixed]
**Approved By**: [If deferring, who approved]

3. 解決への手順

Blocker/Critical → Fix immediately → Re-run gates
Major → Fix or get approval → Document decision
Minor → Create follow-up ticket → Proceed with caution

コマンドのクイックリファレンス

# Standard gate check
npm run lint && npm run type-check && npm run test && npm run build

# Coverage check
npm run test:coverage

# Security audit
npm audit

# Full strict gate
npm run lint && npm run type-check && npm run test:coverage && npm run build && npm audit

チェックリストの概要

レビュー前（作成者）

• コード変更を自己レビュー済み
• テストを追加／更新済み
• ドキュメントを更新済み
• デバッグ用コードが残っていない
• コミットメッセージが明確

コードレビュー（レビュアー）

• ロジックが正しい
• コードが読みやすい
• プロジェクトのパターンに準拠している
• セキュリティ上の懸念がない
• テストに意味がある
• エラー処理が適切

マージ前

• すべての CI チェックに合格
• 必要な承認を取得済み
• コンフリクトを解消済み
• ブランチが最新

デプロイ前（クリティカル）

• ロールバック計画を文書化済み
• モニタリングを設定済み
• ステークホルダーに通知済み
• デプロイ時間枠を確認済み