quality-workflow

品質ワークフロー

検証ゲートの規律

義務：quality-and-verification。

• 内側のループでは、対象を絞った検証（ビルド対象を絞る、特定のテストフィルターを使用するなど）を行います。全テストスイートは、結論を出す前または最終コミット前の最終ゲートとしてのみ実行します。
• 時間のかかるゲート（pre-commit verify、全テストスイート、CI）は最終確認のためのものであり、内側のループでのデバッグには使いません。全ゲートを再実行する前に、最小限の再現手段（単一の失敗テスト、対象を絞ったビルド、単独のコマンド）で各仮説を検証します。
• 依存関係の更新や環境変更後にテストが失敗した場合は、変更のせいだと判断する前に、変更前の状態（変更前の SHA／更新前のシード）でまず再現します。

テストカバレッジの方法

• テストでは、成功、失敗、境界値、無効な入力、主要な状態遷移を網羅しなければなりません（該当する場合は、初回実行／コールドスタートと、その後の実行時の動作を含みます）。該当する場合は、代表的な並行処理、再試行、復旧のケースもテストに含めなければなりません。
• 重要な変更では、テストを選ぶ前に、エージェントは外部から確認できる変更対象の契約範囲を列挙しなければなりません。その範囲の信頼できる情報源として、変更されたドキュメント、仕様、CLI ヘルプ、API の説明、UI コントロール、ファイル形式、ユーザー向けメッセージを使用します。
• エージェントは、小規模な範囲マトリクス（範囲項目 × 状態／結果）を作成し、リスクが最も高い組み合わせを直接カバーしなければなりません。エージェントは、ハッピーパスのチェックが 1 つ通ったことを、隣接するドキュメント上のエントリポイントも動作する証拠として扱ってはなりません。
• 出力ファイルが決定論的な場合、エージェントは全内容のスナップショットテストまたはゴールデンテストを使用しなければなりません。
• エージェントは、スリープや再試行を追加するよりも、非決定論的な失敗を再現可能にすることを優先しなければなりません。エージェントは、不安定さを隠してはなりません。
• タイミング、順序、競合の問題では、エージェントは固定時間のスリープよりも、決定論的な同期（イベント、バージョン管理された状態、確認応答／ハンドシェイク）を優先しなければなりません。
• 統合境界（ネットワーク、DB、外部サービス、UI フロー）については、エージェントはその境界を検証する統合テスト、E2E テスト、または契約テストを追加しなければなりません。エージェントは、統合に関するバグの検出をユニットテストだけに頼ってはなりません。
• 重要な変更では、エージェントは小規模なテストマトリクス（シナリオ × 入力 × 状態）を作成し、リスクが最も高い組み合わせをカバーしなければなりません。意図的な未対応箇所は文書化しなければなりません。

フィードバックループと根本原因

• エージェントは、検出までの時間と修正までの時間を品質特性として扱い、手動 QA に頼るのではなく、自動化と可観測性によってフィードバックループを短縮しなければなりません。
• 不具合修正やインシデント対応では、エージェントは次の分類に基づいて簡潔な根本原因分析を行わなければなりません。
  1. 実装上のミス。
  2. 設計上の不足。
  3. 曖昧または不正確な要件。
• エージェントは、同じ変更セット内で根本原因を上流に反映しなければなりません。テスト／チェック／アラートの追加または強化、仕様と受け入れ基準の更新、該当する場合は設計ドキュメントまたは ADR の更新を行います。
• 失敗をより早い段階で検出すべきだった場合、エージェントは最も早く確実に検出できる段階（lint、typecheck、テスト、CI の必須チェック、実行時アラート、ヘルスチェック）にゲートを追加しなければなりません。この対応を省略するには、ユーザーの明示的な承認が必要です。
• エージェントは、再発を防ぐ仕組み（何が再発を検出するか）を PR の説明または issue のコメントに記録しなければなりません。具体的なフィードバックループの改善なしに「修正済み」と報告してはなりません。

検証エビデンスの手順

AC→証拠の対応付け形式

• エージェントは、AC -> evidence (tests/commands/manual steps) の明示的な対応付けを維持しなければなりません。
• エージェントは、変更によってコマンド、フラグ、エンドポイント、ビュー、状態など、ユーザーに表示されるインターフェースが追加または変更される場合、changed surface item -> direct evidence の並行した対応付けを維持することが望ましいです。
• エージェントは、冗長さを抑えるため、項目ごとの簡潔な形式（各 AC につき証拠と結果を 1 行で記載）で対応付けを提示してもかまいません。
• コード以外の変更では、エージェントは関連する検証のサブセットを実行し、フルスイートが不要な理由を説明しなければなりません。
• 必須のチェックを実行できない場合、エージェントは作業を中止し、部分的な検証で進めることについて明示的な承認を求めなければなりません。また、正確な手動検証計画を提示しなければなりません。

最終提出レスポンスの形式

• 状態を変更するすべてのタスクについて、エージェントは内部で明示的な AC -> evidence の対応付けを維持しなければなりません。
• 通常のユーザー向け最終レスポンスでは、エージェントは結果、検証内容、残存リスクを簡潔にまとめることを基本としなければなりません。
• ユーザーから求められた場合、またはより優先度の高いルールでパスごとの証拠を個別に示すことが求められる場合に限り、エージェントは Goal/Verification、AC -> evidence、または正確なコマンド一覧を詳しく提示しなければなりません。

CI とコミットフックの設定

CI とコミットフックの不変条件については、ルールモジュールの quality-and-verification と lint-format-static を参照してください。このセクションでは、設定手順を説明します。

• 許可されている場合、エージェントは必須のデフォルトブランチチェックを設定しなければなりません。それ以外の場合、エージェントはその制約を報告しなければなりません。
• エージェントは、スモークテストのみ、またはスケジュール実行のみのゲートに依存してはなりません。
• フックがインストールされていない場合、エージェントはセッション中の最初のコミットより前にインストールしなければなりません。インストールできない場合、エージェントは各コミットの前にフル検証を手動で実行しなければなりません。
• 検証スクリプトは、ロックファイルの整合性（マニフェストとロックファイルの差異検出）を確認しなければなりません。

環境上の制約

• ネットワーク、データベース、サンドボックスなどの環境制約により実行が制限される場合、エージェントは実行可能なサブセットを実行し、スキップしたテスト範囲を記録し、残りを CI でカバーしなければなりません。
• ユーザー向けツールと GUI では、エージェントは自動テストに加えて、エンドツーエンドの手動検証を実行しなければなりません。手動テストで問題が見つかった場合、エージェントはまず失敗するテストを追加し、その後で修正しなければなりません。
• CLI と API の変更では、直接的な契約チェックに、ヘルプ、使用方法、バージョン、スキーマなど、または同等の文書化されたエントリーポイントなど、変更によって提供される契約に含まれる場合は、発見可能性を高めるサーフェスを含めなければなりません。
• 必須のテストを実行することが現実的でない場合、エージェントはその不足を記録し、手動検証計画を提示し、明示的な承認を得なければなりません。

テストの実施方法

• ヒューリスティックな待機には、条件に基づくロジック、厳格な期限、診断情報、および依頼者の明示的な承認を必須としなければなりません。
• ログは診断に必要な情報を含めつつ、最小限にしなければなりません。ログにシークレットや個人データを含めてはなりません。エージェントは、最終パッチの前にデバッグ用の計測コードを削除しなければなりません。