退行を抑制する普遍規約¶

このページは、複数のリポジトリでコーディングエージェントを利用した際に繰り返し観察された退行と、その抑止に有効だった対策のうち、特定の言語、フレームワーク、製品、またはUI実装に依存しないものを整理します。

policy/core/ には、生成されるエージェント指示へ直接含める短い規範だけを置きます。このページは、その採用理由、適用境界、および機械的強制との関係を説明する非規範的な文書です。

採用基準¶

普遍規約へ含める項目は、原則として次の条件を満たすものに限定します。

変更対象だけを指定しても、保存すべき既存挙動、非目標、受入証拠が暗黙のままでは、エージェントが実装上の都合で範囲を拡大しやすくなります。そのため、編集前に次を識別します。

指定されていない既存挙動は、要求された変更に不可避でない限り保存対象として扱います。これは changes.define-contract と changes.minimize-scope の組合せで表現します。

既存テストを弱めないだけでなく、再現可能な不具合修正では、修正前に失敗し修正後に成功するテストを追加します。一般的なテスト数の増加より、実際に発見された反例を固定する方が、同型の退行に対する直接的な検出力を持ちます。

再現が環境依存または非決定的である場合は、再現できなかった事実を成功として扱わず、対象となる危険な条件、追加した防御、実行した代替検証を報告します。

コマンドを起動したこと、workflowが存在すること、レビューが設定されていることは、現在の変更が検証済みであることを意味しません。検証結果は、少なくとも次の状態を区別します。

必要な検証が変更surfaceを実際に覆っているかも確認します。集約コマンドや緑色のCIだけを、未包含のテスト、path filterで除外されたworkflow、または古いcommitに対する結果の代替にしてはいけません。

生成ファイル、複製された設定、コンパイル済み資産、manifest、fixture、公開文書などは、正本の変更後に陳腐化しやすい対象です。関連する変更では、リポジトリが定める生成または同期手順を使用し、欠落または差分が残っていないことを検査します。

派生物の同期は、人間やエージェントの注意だけに依存させず、可能ならgeneratorのcheck mode、再生成後のdiff、hash、schema検証、またはCIの完全一致検査で強制します。

削除、上書き、migration、deploy、publish、force updateなどの操作では、作業開始時に取得した状態が実行時にも有効とは限りません。操作直前に、少なくとも対象のidentity、scope、revision、保護状態、および競合利用を再確認します。

可能な場合はdry-run、最小scope、冪等な操作を優先します。以前の検索結果や局所的な処理結果だけから、現在の全体状態を推定して破壊的操作を許可してはいけません。

公開API、保存形式、設定形式、CLI、migration pathなどの外部契約は、明示的に許可された非互換変更でない限り保存します。また、implemented、generated、executed、verified、inferredを区別し、未検証事項を完了として報告しません。

自然言語規約は、エージェントが判断するための共通契約です。ただし、記載されているだけでは統合ゲートになりません。可能な項目は、次の順に機械化します。

agent-policy 自体は、生成された指示とlock fileの整合性を検査します。製品固有の不変条件や受入試験は、製品リポジトリのテストとCIで強制します。

次の知見は有用ですが、適用条件が技術領域に依存するため、現時点では普遍的なcore規約には含めません。

これらは、frontend、workflow、database、release、securityなどのdomain profile、または製品リポジトリ固有のpolicyとして追加する方が適切です。

恒久規約とは別に、個々のタスクでは次の情報を明示すると、core規約を具体化できます。

Outcome:
Allowed changes:
Preserved invariants:
Non-goals:
Acceptance evidence:
Destructive or externally visible actions:

この契約は恒久規約へ蓄積せず、issue、pull request、作業指示、または一時的な作業文書で管理します。