変更は、デモで動作したから、手動テストで期待どおりの結果になったから、あるいはコードがメインブランチに到達したからといって完了ではありません。これらの兆候は実装の一部を確認できるかもしれませんが、その変更が本番環境で安全であり、理解可能で、運用可能であることは証明しません。
PHPプロジェクトにおける完了の定義では、特定の変更を受け入れ可能とする証拠を定める必要があります。ビジネス上の振る舞いだけでなく、既存データ、非同期タスク、連携、権限、可観測性、ロールバックも対象にしなければなりません。これにより、プロダクトが運用で維持できないものを受け入れたり、技術チームが影響の修復が困難な変更をデプロイしたりすることを防げます。
受け入れ、実装、運用を混同しない
しばしば単一の「完了」にまとめられる、次の3つの状態を分けることが重要です。
- 受け入れ済みのスコープ: 合意したビジネスルールが、関連するシナリオで期待どおりに振る舞うことを確認済みです。
- 実装完了: 必要なコード、テスト、設定、スキーマ変更が準備・レビュー済みです。
- 運用可能な変更: システムを未知の状態に残すことなく、デプロイ、監視、サポートし、必要に応じて制限またはロールバックできます。
既存のPHPアプリケーションでは、これらの状態間の隔たりが大きいことがあります。コントローラーの新しいバリデーションはデモでは通過しても、同じAPIを使う自動化を止める可能性があります。マイグレーションはエラーなく実行できても、インポート処理がまだ以前のセマンティクスで解釈する値を変換してしまうことがあります。インターフェースに追加した権限が、内部ルートやコンソールコマンドには適用されない場合もあります。
この定義を一律の儀式にしてはなりません。リスクに応じたものにすべきです。孤立した視覚的な調整に必要な証拠は、請求、権限、個人データ、外部に影響するフローの変更より少なくなります。
影響に応じた基準マトリクスを構築する
開発前に、変更を影響範囲ごとに分類します。複雑なスコアを割り当てる必要はありません。どの側面が変わるか、どの失敗が許容できないかを特定すれば十分です。各側面により、追加の基準と証拠が有効になります。
ビジネスと振る舞い
検証可能な例とともに、ルール、例外、境界状態を定義します。不完全なデータ、繰り返しリクエスト、並行実行、予測可能なエラーに対して何が起こるべきかを含めてください。あるルールが別のルールに置き換わる場合は、いつから適用されるか、以前のルールに基づいて作成されたレコードをどう扱うかを明記します。
データとスキーマ
マイグレーション、新しいフィールド、情報の再計算、インポートがある場合は、影響を受ける件数、アプリケーションとスキーマのバージョン間における一時的な互換性、実行後の検証を定めます。マイグレーションの完了はデータの正しさと同義ではありません。件数、無効な値、重複、想定外のnull、関連する関係の保持を確認する必要があります。
連携と非同期処理
キュー、cron、webhook、メール、ファイルストレージ、外部APIには、それぞれ固有の基準が必要です。入出力契約、リトライ、冪等性、タイムアウト、部分レスポンスの扱い、エラーの行き先を文書化します。PHPでは、コンソールコマンドやworkerがWebリクエストとは異なるサービスや認証情報を使用する可能性があります。テストでは、その現実的な実行をカバーしなければなりません。
権限、セキュリティ、プライバシー
各リソースを誰が閲覧、作成、承認、変更、エクスポートできるかを示します。認可は、ボタンの表示可否だけでなくサーバー側で検証する必要があります。個人データまたは運用上の秘密情報が関与する場合は、ログの最小化、アクセス制限、エラー、トレース、通知に表示される情報のレビューを含めてください。
運用とデプロイ
デプロイ後の障害をどのように検知するかを決めます。コンテキストを含むログ、既存のメトリクス、適用可能なアラート、または具体的な手動確認を用います。デプロイとreleaseを区別してください。前者はアーティファクトと設定を導入し、後者はユーザーやプロセスに振る舞いを公開します。可能な場合、設定、段階的な有効化、またはビジネス条件によって、完全なロールバックと混同せずに公開範囲を制限できます。
変更に添えるべき証拠
完了リストは、「検証済み」や「文書化済み」といった曖昧な表現ではなく、観測可能な証明を求める場合に有用です。証拠は変更を受け入れる人がレビューでき、インシデント時にも役立つ必要があります。
- 自動テスト: 分離されたルールのユニットテスト、永続化・認可・サービスの統合テスト、実際にフローをカバーできる箇所に限ったエンドツーエンドテスト。
- 受け入れ確認: 拒否ケースを含め、入力、結果、ロールを特定して実行したビジネスシナリオ。
- マイグレーション結果: 実行計画、事前・事後検証、想定件数、異常の明示的な扱い。
- 連携契約: フィールド、エラーコード、認証、制限、リトライ、および既存コンシューマーとの互換性の変更。
- 運用検証: デプロイ後にフローが機能していることを確認できるログ、メトリクス、クエリと、それをレビューすべき担当者。
- サポートガイド: 既知の症状、探すべき識別子、安全な対応、エスカレーション。短くアクセスしやすいものでなければならず、プレッシャー下で役に立たない一般的な文書ではいけません。
すべての証拠を独立した文書にする必要はありません。正確で見つけやすく、変更とともに維持されるなら、テスト一式、デプロイノート、検証クエリで十分な場合があります。
最小基準と強化基準
データ、外部インターフェース、権限を変更しない低リスクの変更では、通常、受け入れ済みのスコープ、コードレビュー、関連テスト、特定された設定、デプロイ後の確認が最小限に含まれます。この場合でも、何を正しい振る舞いと見なすかを明確にする必要があります。
次の条件のいずれかに該当する場合は、強化された統制を追加してください。
- 永続データを作成、変換、削除する。
- 経済的、契約上、またはコンプライアンス上の影響を持つルールを変更する。
- ロール、権限、認証、または情報の公開範囲を変更する。
- 課金、メール送信、webhook送信など、外部システムに対する処理を実行する。
- 繰り返し実行される可能性があるworker、キュー、スケジュールタスク、プロセスに影響する。
- デプロイにアプリケーション、データベース、インフラ、またはプロバイダー間の調整が必要である。
これらの場合、バージョン間の互換性、順序付けられたデプロイ計画、データ検証、予測可能な障害のテスト、可観測性、意思決定の責任者、封じ込め計画を含めてください。有用な問いは「テストはあるか」ではなく、「この変更固有のリスクを低減する証拠は何か」です。
ロールバック: 何も起きなかったふりではなく、制御を取り戻す
現実的なロールバックは、発生した影響に左右されます。コードのロールバックは簡単かもしれませんが、破壊的なマイグレーション、送信済みメール、外部APIが受理した更新をロールバックすることは容易ではありません。そのため、基準では将来の実行を元に戻すこと、すでに発生した影響を補償すること、データを修正することを区別する必要があります。
release前に、対応を強いるしきい値、誰が判断できるか、どのアクションが安全かを定義します。設定フラグにより新しい実行を停止できます。キューを一時停止すれば、さらなる影響を防げます。補償的な修正では、すでに処理済みのレコードを変更する前に人によるレビューが必要になることがあります。安全な自動ロールバックがない場合は、そのことを明記し、明確な制限を持つ復旧手順を準備してください。
有効なロールバック計画は、不可逆な影響、それらを封じ込める方法、封じ込めが機能したと判断するために必要な証拠を特定します。
例: PHPバックオフィスでの新しい承認
バックオフィスに、特定の申請は実行に進む前に特定のロールが承認しなければならないというルールを導入する場合を考えます。デモでは、ボタンが表示され、状態が「承認済み」に変わることを示せます。しかし、それでは不十分です。
完了の定義では、状態モデルを明確にする必要があります。どの申請に承認が必要か、既存の申請をどう扱うか、承認を取り消せるか、2人が同時に操作できるかです。ドメインサービス、コントローラー、APIルート、コンソールコマンドが同じ認可を適用することを検証しなければなりません。また、古いクエリを使用するworkerが、承認なしに保留中の申請を実行しないことも確認する必要があります。
状態フィールドを追加する場合、マイグレーションには履歴レコードを分類するルールと、件数の事後確認が必要です。監査ログでは、不要な機微情報を含めないようにしつつ、該当する場合はアクター、時点、遷移、理由を保持すべきです。運用チームは、承認待ちで滞留した申請を検知する方法と、不整合な遷移が現れた場合に処理を停止する方法を把握する必要があります。ロールバックでは新規申請に対する要件を無効化できるかもしれませんが、明示的な判断なしに、すでに記録された承認を削除すべきではありません。
デリバリーサイクルに基準を組み込む
完了の定義を、タスクを閉じるためのリストとして最後に作成してはなりません。リファインメント中に、プロダクトと技術チームはルール、依存関係、影響を受けるデータ、運用上の結果を特定します。開発前に、受け入れシナリオと必要な証拠に合意します。実装中は、それらの証拠がテスト、マイグレーション、計装、最小限の文書化を導きます。デプロイ前には、実行順序、責任者、封じ込めが引き続き有効であることを確認します。
3つのアンチパターンを避けてください。リスクを無視する汎用的なリスト、変更がデプロイ準備済みになってから見つかる基準、そしてサポートに実行可能なシグナルを提供しない長大な文書です。PHPプロジェクトにおける優れた完了の定義は、デフォルトで官僚主義を増やすものではありません。デモが終わった後に変更を安全に運用できるために真でなければならないことを明示します。
