pre-merge-checklist

マージ前チェックリスト

使用するタイミング

次の場合にこのスキルを有効にしてください：

• 承認前にプルリクエストをレビューするとき
• 自分の PR をマージに向けて準備するとき
• マージ前に自動チェックがすべて通ることを確認するとき
• 承認済みで、まだマージされていない PR を監査するとき
• レビューのフィードバックに対応した後、最終検証を実施するとき

出力： 各チェックの合否状況とブロッキングする問題を記載した pre-merge-report.md に結果を書き込みます。

次の場合、このスキルは使用しないでください：

• 詳細なセキュリティレビュー（code-review-security を使用）
• 実装コードの作成（python-backend-expert または react-frontend-expert を使用）
• アーキテクチャ上の判断（system-architecture を使用）
• E2E テストの作成（e2e-testing を使用）

手順

自動チェック（順番どおり）

自動チェックをこの順番で実行します。次のチェックに進む前に、各チェックに合格する必要があります。すべてのチェックを一度に実行するには、scripts/run-all-checks.sh を使用してください。

1. リンティングとフォーマット

Python（ruff）：

# Check linting
ruff check app/ tests/

# Check formatting
ruff format --check app/ tests/

# Auto-fix (if needed before commit)
ruff check --fix app/ tests/
ruff format app/ tests/

TypeScript/React（eslint + prettier）：

# Check linting
npx eslint 'src/**/*.{ts,tsx}' --max-warnings 0

# Check formatting
npx prettier --check 'src/**/*.{ts,tsx}'

# Auto-fix (if needed)
npx eslint 'src/**/*.{ts,tsx}' --fix
npx prettier --write 'src/**/*.{ts,tsx}'

合格基準：

• lint エラーがゼロであること（警告は、正当な理由がある場合に限り許容されます）
• すべてのファイルのフォーマットが一貫していること
• 理由を説明するコメントのない # noqa または eslint-disable がないこと

2. 型チェック

Python（mypy）：

mypy app/ --strict --no-error-summary

TypeScript：

npx tsc --noEmit

両方を順番に実行し、レポートを出力するには scripts/type-check.sh を使用してください。

合格基準：

• 変更したファイルに型エラーがゼロであること
• 正当な理由のない新しい type: ignore または @ts-ignore がないこと
• ジェネリック型が正しく使用されていること（Any が漏れていないこと）

3. テスト

Python：

pytest tests/ -q --tb=short

React：

npm test -- --run --reporter=verbose

合格基準：

• すべてのテストに合格すること（失敗がゼロであること）
• 関連する課題／チケットが紐付いていないスキップ済みテストがないこと
• 新しいコードに対応するテストがあること

4. カバレッジ

Python：

pytest --cov=app --cov-report=term-missing --cov-fail-under=80

React：

npx vitest run --coverage --coverage.thresholds.lines=80

合格基準：

• 全体のカバレッジが 80% 以上であること
• 新しいコードのカバレッジが 90% 以上であること
• カバーされていない重要な処理経路（認証、決済、データ変更）がないこと

5. セキュリティスキャン

# Python dependencies
pip-audit --requirement requirements.txt

# npm dependencies
npm audit --audit-level=high

# Custom code scan (if code-review-security skill is available)
python scripts/security-scan.py --path app/ --output-dir ./security-results

合格基準：

• 依存関係に重大または高深刻度の脆弱性がないこと
• コードスキャンで重大な指摘がないこと
• 新しいエンドポイントすべてに認証チェックがあること

---

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

自動チェックに合格したら、次の項目に照らして PR を手動でレビューします。

コード品質

• 命名： 変数、関数、クラスに、明確で説明的な名前が付いている
• 関数： 各関数が単一の処理を行い、50 行を超える関数がない
• DRY： 共通関数として切り出すべきロジックの重複がない
• コメント： 複雑なロジックが文書化され、コメントアウトされたコードが残っていない
• インポート： 未使用のインポートがなく、インポートが整理されている（標準ライブラリ、サードパーティ、ローカル）
• 定数： マジックナンバーやマジック文字列を使わず、名前付き定数または列挙型を使用している
• ログ： 新機能に、適切なログレベルで必要なログ文が追加されている

テスト

• カバレッジ： 新しいコードにテストがある（適宜、ユニットテストおよび／または統合テスト）
• エッジケース： 正常系、エラー系、境界条件をテストでカバーしている
• テスト名： テスト名からシナリオと期待される結果がわかる
• テストの独立性： テストが互いに依存せず、実行順序にも依存しない
• 不安定さがないこと： ハードコードされた待機時間や環境固有のパスをテストで使用していない
• ファクトリー： テストデータにハードコードされたフィクスチャではなく、ファクトリーを使用している

型安全性

• Any がないこと： 戻り値の型とパラメーターに適切な型が付いており、型チェックを回避する手段を使っていない
• Null 安全性： オプション値を適切に処理している（null チェック、デフォルト値）
• スキーマ検証： API 入力に Pydantic スキーマ（Python）または Zod（React）を使用している
• ジェネリック型： コレクションに適切なジェネリック型を使用している（list ではなく list[User]）

エラー処理

• 適切なエラー処理： すべてのエラーパスで、意味のあるメッセージを返します
• HTTP ステータスコード： 適切なコードを使用します（見つからない場合は404、競合の場合は409など）
• エラーバウンダリー： React コンポーネントに、非同期処理の失敗に対応するエラーバウンダリーを設けます
• 再試行ロジック： 外部サービスの呼び出しでは、適切な場合にバックオフを伴う再試行を行います
• サイレントな失敗の防止： 捕捉した例外はログに記録し、黙って無視しません

後方互換性

• API コントラクト： 既存の API レスポンスの形式に破壊的変更を加えません
• データベースマイグレーション： マイグレーションは元に戻せるものであり、データを破壊しません
• 機能フラグ： 破壊的変更は機能フラグで制御します
• 非推奨化： 削除する機能には、直前のリリースで非推奨の警告を表示します
• 設定： ドキュメントに記載せずに、新たな必須環境変数を追加しません

ドキュメント

• API ドキュメント： 新しいエンドポイントをドキュメント化します（FastAPI 経由の OpenAPI/Swagger）
• README： 新しい依存関係や手順を追加した場合、セットアップ手順を更新します
• マイグレーションノート： データベースマイグレーションに説明コメントを追加します
• ADR： 重要なアーキテクチャ上の決定をドキュメント化します（該当する場合）

パフォーマンス

• N+1 クエリ： N+1 のデータベースクエリパターンを使用しません（Eager Loading を使用します）
• ページネーション： 一覧エンドポイントでは、カーソルベースのページネーションを使用します
• インデックス： 新しいクエリパターンをサポートするデータベースインデックスを追加します
• バンドルサイズ： フロントエンドに不要でサイズの大きい依存関係を追加しません

アクセシビリティ

• セマンティック HTML： 適切な HTML 要素を使用します（button、nav、main など）
• ARIA ラベル： インタラクティブな要素に、アクセシブルなラベルを設定します
• キーボード操作： 新しい UI 要素をキーボードで操作できるようにします
• 色のコントラスト： テキストは WCAG 2.1 AA のコントラスト要件を満たします

scripts/accessibility-check.sh を実行して、アクセシビリティの自動チェックを行います。

---

失敗時の対応手順

チェックに失敗した場合は、次のエスカレーション手順に従います。

自動チェックの失敗：

1. PR で問題を修正します
2. 修正をプッシュして、チェックを再実行します
3. すべての自動チェックに合格するまで、マージしないでください

手動レビューでの指摘：

1. 指摘内容をレビューコメントに追加します
2. PR で変更をリクエストします
3. 作成者がフィードバックに対応した後、再レビューします

重要度に応じた対応：

指摘の種類	対応	例外を認められるか
Lint／フォーマットエラー	マージ前に修正	いいえ
型エラー	マージ前に修正	いいえ
テストの失敗	マージ前に修正	いいえ
カバレッジがしきい値未満	テストを追加するか、理由を説明	はい。テックリードの承認が必要
セキュリティ上の指摘（重大／高）	マージ前に修正	いいえ
セキュリティ上の指摘（中／低）	修正するか、フォローアップチケットを作成	はい。チケットへの参照が必要
アクセシビリティ違反	修正するか、フォローアップチケットを作成	はい。理由の説明が必要
パフォーマンス上の懸念	PR で話し合い、対応を延期する場合があります	はい。テックリードの承認が必要

例外の手順

チェックに例外を設ける必要がある場合：

1. 理由を記録する： 例外を認めても問題ない理由を説明する PR コメントを追加します
2. 明示的な承認を得る： テックリードまたはシニアエンジニアから承認を得ます
3. フォローアップチケットを作成する： 根本的な問題を解決するためのチケットを作成します
4. コードコメントを追加する： 例外を設ける箇所に、チケットを参照するコードコメントを追加します

# OVERRIDE: Coverage below 80% for this module. See TICKET-1234.
# Approved by @tech-lead on 2024-01-15.
# Reason: Legacy code migration in progress; full coverage planned for Sprint 12.

次の場合は、例外を決して認めません：

• 重大なセキュリティ脆弱性
• テストの失敗
• バグを見逃す原因となる型エラー

例

すべてのチェックを実行する

# Run the full check suite
./scripts/run-all-checks.sh --output-dir ./check-results

# Run only type checks
./scripts/type-check.sh --output-dir ./check-results

# Run accessibility checks
./scripts/accessibility-check.sh --output-dir ./check-results

PR のクイックレビュー手順

1. ブランチをローカルにプルします
2. ./scripts/run-all-checks.sh --output-dir ./pr-review を実行します
3. 自動チェック結果のファイルを確認します
4. 上記の手動チェックリストに沿って確認します
5. レビューコメントを残すか、承認します

出力ファイル

結果を pre-merge-report.md に書き込みます。

# Pre-Merge Report: [PR Title]

## Status: READY TO MERGE | BLOCKING ISSUES

## Automated Checks

| Check | Status | Details |
|-------|--------|---------|
| Linting (ruff) | PASS | No issues |
| Type check (mypy) | PASS | No errors |
| Tests (pytest) | PASS | 142 passed, 0 failed |
| Coverage | PASS | 85% (threshold: 80%) |
| Frontend lint | PASS | No issues |
| Frontend types | PASS | No errors |

## Manual Checks

- [x] Code follows project patterns
- [x] Tests cover new functionality
- [x] No breaking API changes
- [ ] Documentation updated (BLOCKING)

## Blocking Issues

1. README needs update for new CLI flag

## Recommendation
Address documentation before merge.