どこを・何で・どれだけ確かめるかの決まりのうち、どのリポジトリでも同じ部分。人が決め、エージェントが従う。
- リポジトリごとの中身(品質マップ・観点・根拠の書き方・計測の基準)は
QUALITY.mdにある。節の番号は同じで、本書の N 節の決まりで、QUALITY.mdの N 節を引く - エージェントは、変更の前に本書と
QUALITY.mdを読む - 本書の「このリポジトリの値」は、
QUALITY.mdの冒頭の表を指す(検出器の置き場所・宛先のブランチ・必須のチェック・役の名前など) - 本書には方針と表だけを置く。手順は、
QUALITY.mdの一次情報の表に挙げた文書による
人は個々の変更を細かく見るより、羅針盤を決める役を担う。 エージェントは、作業が品質マップのどの単位に当たるかを
QUALITY.mdで引き、その重みで確かめ、報告する。
リスクの高い単位ほど、検証の手段を重ね、人の確認点を増やす。 リスクの低い単位はエージェントに任せ、壊れたら作り直す。
- 単位は、リポジトリで決める(フレームワークなら名前空間、アプリなら画面・層・業務など)。表は
QUALITY.md1 節にあり、列は「単位・リスク・正の根拠・検証の手段・人が必ず見る箇所」 - リスクは、壊れたときの影響(セキュリティ・データ・後方互換性)と、仕様の複雑さで付ける(高・中〜高・中・中〜低・低)
- 表に無い単位は「中〜低」として扱う。 迷ったら、高い方に倒して報告する
- 「人が必ず見る箇所」に触れたら、報告の冒頭に書く。 人が差分のどこを見ればよいかを示すためである
- 検証の手段の具体(どのスクリプトを、どの引数で回すか)は、
QUALITY.mdの一次情報の表の文書による
テストが通ることは、正しいことの証明ではない。 同じエージェントが書いたテストとコードは、仕様の読み違いを共有しうる。
- 期待値には根拠を書く。 仕様の該当箇所(RFC の節・仕様の ID など)か、Issue の番号。書き方は 7 節と
QUALITY.md7 節- 根拠を書けない期待値は、今の振る舞いを写しただけである。そう分かるように書く(「観測」。下記)
- テスト先行で進めるリポジトリ(
TESTING.mdがある)では、根拠を付けられないケースは、仕様の決定として人に上げる(推測で補わない)
- 「検証」と「観測」を分ける
- 検証:仕様に照らして、正しいと言える値を確かめる
- 観測:仕様に幅がある、または根拠を確かめていない値を、変わったことに気付くために残す
- 観測から検証へ上げるのは、人が根拠を確かめてから
- 観測が落ちるか(合否に入れるか)は、リポジトリで決める(
QUALITY.md2 節)。 例:部品のライブラリは、振る舞いが変わること自体が利用者への影響なので、観測も落とす。 外から叩くサイトの E2E は、仕様に幅のある項目を合否に混ぜると「通った」の意味が薄まるので、落とさずに前回との差分を報告する
- 外部の基準(静的解析・適合性テスト・相互運用)があれば、それを最終的な正とする(何を使うかは
QUALITY.md2 節)
エージェントは、テストを書き換えて通すことがある。 人の注意に頼らず、仕組みでスルーできないようにする。
機械的に検出できるものに絞る。何が当たるかはリポジトリの規則(検出器の rules.psd1)で決め、表は QUALITY.md 3 節(テスト先行のリポジトリは TESTING.md 3 節)にある。
どのリポジトリでも、おおむね次が当たる。
-
テストの削除(テストの属性の行の削除)
-
テストを無効にする追加(Ignore・Skip など)
-
根拠の削除(検証から観測への格下げ)
-
検証の削除(アサーションの行の削除)
-
行の数は、ファイルごとの差し引きで数える。 書き直し・同じファイルの中での移動まで数えると、承認が形だけになる。 裏返すと、あるアサーションを消して別のアサーションを足すと数えない
-
実行のたびに変わる値(日時・スレッド ID・署名値など)の揺れは、期待値の変更に数えない。揺れだけの変更にはトレーラーは要らない
-
無効にする追加には正当な使い方がある(管理者権限が無い、DB・コンテナが無い)。足すなら理由を書いて承認を受ける
-
アサーションの緩和(比較を弱める、許容範囲を広げる)は、機械的な検出が難しい。4 節のレビューの観点で拾う
期待値の変更を含むコミットには、コミット メッセージの末尾にトレーラーで理由を書く。
fixed #NNN
Expectation-Change: <何が・なぜ変わったか(仕様の該当箇所・Issue 番号)>
- コミットするのは人なので、トレーラーを書くことが、人が差分を見て承認した記録になる
- 理由が複数あれば、行を分けて複数書く
- 理由には、根拠の Issue 番号(
#NNN)か仕様の節・ID を書く。 無ければ検出器が警告する(止めない) - 文面を提案したら、コミットの前に、突き合わせ役(サブエージェント
opentouryo-expectation-reviewer。検出器と一緒に入る)で、理由と差分を突き合わせる。 渡すのは対象(ステージした変更かコミット)とメッセージのファイルだけ。網羅・一致・根拠・方向・範囲外の観点で「合う/合わない/判断できない」が返る。 合わない点は理由を直すか人に聞き、回したらReviewed-with: opentouryo-expectation-reviewer (<モデル ID>)を書く(無ければ警告。止めない) - 文面は、人に出す前に検出器の提案の検査で確かめる:文面をリポジトリの外の一時ファイルに書き、検出器の置き場所(このリポジトリの値)で
.\CheckExpectationChange.ps1 -Proposed -MessageFile <ファイル>を動かす。作業ツリーの変更をすべてステージしたとして判定する(索引は変えない)。止まれば、直してから出す
| 段 | 仕組み | 何を塞ぐか | 有効にするのは |
|---|---|---|---|
| 1. エージェント | Claude Code の PreToolUse フック(.claude/settings.json → .claude/hooks/ExpectationGuard.ps1):期待値になりうる編集を、確認付きにする |
エージェントが黙って期待値を書き換えること | リポジトリに入れば効く |
| 2. 人のコミット | commit-msg フック(.githooks/commit-msg → CheckExpectationChange.ps1):トレーラーの無い期待値の変更を拒否する |
理由の無いコミット | 各自の手元(下記) |
| 3. PR | GitHub Actions(.github/workflows/expectation-change.yml):宛先のブランチ(このリポジトリの値)への PR のコミットを検査する(検出は段 2 と同じ CheckExpectationChange.ps1 の、ベース側の版) |
フックの未設定や --no-verify での迂回。最終的に塞ぐのはここ |
必須のチェックにするのは人(このリポジトリの値) |
- 何を期待値の変更と数えるかの実装は、本体
CheckExpectationChange.ps1と、規則rules.common.psd1・rules.psd1にある(段 1 は、編集の前に推測する簡易版) - 段 1 は止めない。 人に見せるだけで、許可すれば編集は進む。承認の記録は段 2・段 3 のトレーラーである
- 段 1 は Claude Code の機能である。ほかのエージェントでは効かないが、段 2・段 3 で塞がる
- マージ コミットは見ない。 取り込むコミットのほうで確かめているため
- 仕組み自体のファイル(
.githooks/・.claude/settings.json・.claude/hooks/・.claude/agents/・expectation-change.yml・CheckExpectationChange.ps1・rules.common.psd1・rules.psd1、ほかにrules.psd1が足したもの)の変更・削除も、トレーラーが要る。 仕組みを緩めれば、期待値をいくら変えても通るため(追加は数えない)。.claude/agents/を含むのは、役の定義を緩めればレビューも緩むためである - PR を出す前に手元で確かめるなら、検出器の置き場所で
.\CheckExpectationChange.ps1 -Range <宛先のブランチ>..HEAD -Range(段 3)は、導入より前のコミット(検出器がまだ無いコミット)を見ない。 規約が無かった時点のコミットだからである。-Commitで個別に見れば、導入前でも見る(6 節の計測に使える)- 導入の PR は、検査されない。 ベース側に検出器が無いので、PR の側の版で動く。人が差分を確かめ、必須のチェックにするのはマージの後
段 3 は、PR のマージでないコミットを 1 つずつ、そのコミットのメッセージで判定する。止まったら、上から順に選ぶ(止めたときの表示にも同じ順で出る)。
push したコミットのメッセージは書き直さない(--amend・rebase と force push)。共有のブランチでは、ほかの人・セッションの手元が壊れ、ほかの人のコミットを消すおそれがある。
- 後のコミットで承認する(履歴を書き換えない):
git commit --allow-empty -m "期待値の変更を承認する" -m "Expectation-Change-For: <止まったコミットの sha> <何が・なぜ変わったか(#NNN)>"を push する。 1 行に 1 コミット。効くのは CI だけで、手元のフックの判定は変わらない。 トレーラーの書き方の誤り(最後の段落に無い・全角の「:」・綴り・語彙に無い値)で止まったときも、これで直す。理由に、直した行を書く (例:Expectation-Change-For: 1a2b3c4d トレーラーの書き方の誤り(#NNN。直した行 Found-By: review-other-model))。誤った行は履歴に残り、集計には載らない。 CI はベース側の検出器で判定するので、宛先のブランチの写しが古い(OpenTouryoCodingAgentAssets@945878d より前)と効かない。そのときは 2 - 管理者が、その PR だけ保護を迂回してマージする(マージの画面の「Merge without waiting for requirements to be met」)。期待値を変えた理由を、PR のコメントに残す。 必須のチェックを外す・ワークフローを止める、はしない(すべての PR の保護が外れる/チェックが結果を返さず、PR がかえって止まる)
git config core.hooksPath .githooks- フックは
shで動き、powershell.exe(無ければpwsh)でCheckExpectationChange.ps1を呼ぶ - 拒否されたら、差分を確かめてトレーラーを書く。
--no-verifyで迂回しても、段 3 で止まる - 過去のコミットを確かめるには、検出器の置き場所で
.\CheckExpectationChange.ps1 -Commit <コミット>
検出器の本体は、OpenTouryoCodingAgentAssets の共通の本体の写しである(原本は同リポジトリの src/quality/ExpectationGuard/)。
| ファイル(検出器の置き場所) | 持ち主 | 中身 |
|---|---|---|
CheckExpectationChange.ps1 |
写し | 本体(段 1〜3 の判定。規則は持たない) |
rules.common.psd1 |
写し | 共通の規則(仕組みのファイル・トレーラーの検査(Found-By:・Tested-with:・Reviewed-with:。5 節)・要確認・段 1 の判定) |
判定の用例(ExpectationGuard.Tests/。置き場所はこのリポジトリの値) |
写し | 「この差分なら検出する/しない」。CI のジョブ expectation-guard-tests が回す |
rules.psd1 |
このリポジトリ | このリポジトリの規則(テストの場所・属性・無効化・根拠の削除など) |
.claude/hooks/ExpectationGuard.ps1・.githooks/commit-msg・.claude/agents/opentouryo-expectation-reviewer.mdも写しである。expectation-change.ymlは雛形から作り、このリポジトリが持つ- 写しは直さない。 直すなら原本を直し、入れ直しのコマンド(このリポジトリの値)で写し直す。
写しの先頭付近の行に原本の版があり、CI(
Verify copies)が、写しが手で直されていないかを確かめる(違えば警告。手元では.\CheckExpectationChange.ps1 -VerifyCopy) - 写し直しも「仕組みの変更」になる(印の行の版が変わるだけでも)。
Expectation-Change:の理由に、版の変化と中身が変わったかを書く - 要確認(
[Obsolete]・#pragma warning disable CS0618の追加)は止めない・トレーラーを求めない。一覧に出し、CI では足した行に注釈を付ける(範囲はrules.psd1のReviewScope)
- 期待値を変えたら、報告の冒頭に書く。 どのファイルの、どの値が、なぜ変わったか
- トレーラーの文面を提案し、コミットの前に突き合わせ役を回す(上の「承認の記録」)。コミットは人が行う(
AGENTS.md「Git 操作は行わない」) - テストを通すために期待値を変えない。 先にコードを疑う。期待値が誤っていると判断したら、その根拠(仕様の該当箇所)を示す
品質マップの単位に応じて、QUALITY.md 4 節のチェックリストで確かめる。 エージェントがレビューするときも、自分の変更を見直すときも同じである。
どの単位でも、次を確かめる。
- 期待値の変更(3 節)を含むか。含むなら、根拠があるか
- テストが、変更した分岐を実際に通しているか(テストの名前ではなく、入力と期待値で見る。測れるならカバレッジで行を見る)
- 見つかった型の横展開:同じ形が、別の箇所(別の画面・口・クラス)に残っていないか
- 検証を省く分岐(設定やパラメタで検証を飛ばせる経路)が増えていないか
- 公開の口(API・設定のキー・既定値・画面の振る舞い)の後方互換性。変えるなら、Issue と文書に書かれているか
- リスクが「高」の単位に触れる変更は、書いたセッションとは別のセッションでレビューする(文脈を引き継がない)
- さらに、書いたモデルとは別のモデルでレビューする。 同じモデルは、同じ読み違いをしやすい
- 指摘の形:重大度・箇所・内容・原典の節・再現の方法(テストにできるか、その入力)・確信度(確かめた / 推測)を必須にする。 人の検収で律速になるのは指摘の理解なので、原典と照らすだけで判断できる形にする
- 数え方:判定を経てから数える。 別モデルの指摘を、そのまま不具合と数えない
- 終了の条件:回数ではなく、別モデルのレビューで、判定後の重大度「高」の指摘が無いことで決める
- CodeQL のような、LLM とは別系統の検査も併用する。 主とレビュー役は同じ系統のモデルなので、読み違いの共有は減っても、無くなりはしない
レビュー役は、変更のレビュー役(このリポジトリの値。.claude/agents/ の役の定義)である。
主の会話の文脈を持たずに始まるので、「別のセッション」にも当たる。書き換えの道具(Edit・Write)は持たせていない。
いつ回すか:少なくとも、リスク「高」の単位に触れる変更の、fixed のコミットの前。fixing の段では任意(回す場面を広げるなら QUALITY.md・AGENTS.md に書く)。
- 基本は、
fixedの前のワーキング ツリーをレビューし、採用した指摘をそこで直す(範囲は「Issue の着手の前のコミットと、ワーキング ツリーの差分」) - コミットの後に回したなら、範囲をハッシュで指定する。 採用した指摘は、内容によって、その場で直して別のコミットにする(追加の修正)か、別の Issue にする
- 主は、呼ぶ前に、自分のレビューの指摘を書き留める(セルフレビュー。4 の突き合わせに使う)。
AGENTS.mdに「作業の見える化」があれば、呼ぶ前と報告を受けたときに、ルートのAGENT-DASHBOARD.mdを書き直す(無ければ作る) - 主は、決まった型だけを渡す(Issue 番号・範囲・単位。型は役の定義の本文)。 主の説明・設計の理由・「ここは正しい」という見立て・セルフレビューの結果は渡さない(同じ読み違いを共有しないため)
- 主は、すべての指摘に判定を付ける(採用・却下・保留と、その理由)。却下したものも報告から落とさない。 「見ていない範囲」に、差分のファイル(テストを含む)や差分に出てくる原典の節が残っていたら、そのレビューは終わっていない。 回し直すか、残ったことを報告に書く
- セルフレビューと突き合わせ、別モデルのレビューでだけ見つかった指摘を数える(6 節の計測)
- 採用した指摘を直したら、もう一度回す。終了は上の「終了の条件」による
- 結果を、完了コメントの「確かめたこと」に書く:主とレビュー役のモデル ID、指摘の数、判定の内訳、別モデルでだけ見つかった数
- 主のモデルは、各自の設定に任せる(共有の
.claude/settings.jsonでは揃えない。プロジェクトの設定は各自の設定より優先され、全員に同じモデルを強いるため)。 主もレビュー役と同じモデルなら、別モデルのレビューにならない。 そう報告し、6 節の計測には数えない - 呼んだかどうかの記録は、完了コメントと、コミットのトレーラー
Reviewed-with: <役> (<モデル ID>)(5 節)による。rules.psd1のTrailerRequirementsに組があれば、リスク「高」の単位をfixedで変えたのに無いとき、検出器が警告する(止めない。fixingでは警告しない) - 判定は検収の材料であり、検収の代わりではない。 人は判定の結果を読んで検収する
見つけた問題がセキュリティの弱点なら、公開の文書に書かない。 まず人に報告する。 チェックリストに足すのも、修正と同じコミットにする(5 節)。
見つかった問題は、次の 3 か所に戻す。
- 回帰テスト:Issue に紐付けて残す(名前の付け方はこのリポジトリの値)
- レビューの観点:
QUALITY.md4 節のチェックリストに足し、次からレビューで拾えるようにする - 品質マップ:その単位のリスク・検証の手段・人の確認点を見直す(
QUALITY.md1 節)
QUALITY.md を直すのは、問題を直したのと同じコミットにする。 先に書くと、未修正の弱点を公開することになる。
どのリポジトリにも当てはまる観点は、原本(OpenTouryoCodingAgentAssets)の本書に足すよう、人に提案する。
バグを直すコミット(fixed #NNN)には、どこで・何で見つけたかを、トレーラーで残す。 6 節の計測(バグの Issue)に使う。
fixed #NNN
Found-By: <手段> [<補足>]
<手段>は、決まった語彙から選ぶ(spec-check・review-other-model・downstreamなど)。 語彙と意味の一次情報はrules.common.psd1(検出器の置き場所)のFound-Byの規則(本書には写さない)<補足>には、派生元の Issue や見つけた作業を書く(例:Found-By: type-review (#NNN の派生))。手段が複数なら、行を分ける- トレーラーがあることが、バグの修正の印になる。 機能の追加・エンハンスには付けない
- 見つけた経緯は、推測で埋めない。 そのセッションのエージェントが文案に入れ、分からなければ人に聞く。人はコミットのときに、経緯と合っているかを見る
- 検出器が確かめる:語彙に無い値は止める(段 2・段 3)。
fixed #NNNに無ければ警告に留める(バグかどうかは機械に分からない) - 導入の前のコミットには遡って付けない(コミットは書き換えない)
そのコミットをどう確かめたか(流したテストの種類・レビューした役)を、トレーラーで残す。 Found-By: と併せて、6 節で数える。
fixed #NNN
Found-By: <手段> [<補足>]
Tested-with: <種類>[, <種類>]
Reviewed-with: <役> [(<モデル ID>)]
<種類>はunit・e2e・golden・manual・none。<役>は.claude/agents/の役の定義の名前か、人ならhuman。 語彙と意味の一次情報はrules.common.psd1の規則(本書には写さない)- 流していないテスト・回していないレビューは書かない。 記録であって証明ではない。人はコミットのときに、経緯と合っているかを見る
- 指摘の数(採用・却下・別モデルでだけ見つかった数)は長いので、完了コメントに書く(4 節)。トレーラーは「何で・誰が」だけ
- 検出器が確かめる:語彙に無い値は止める(段 2・段 3)。書き忘れは警告する(止めない):
コード(
.cs・.vb。コメント・空行だけの変更を除く)を変えたのにTested-with:が無い(流していなければTested-with: none)、 期待値の変更に突き合わせ役のReviewed-with:が無い、TrailerRequirementsの組に当たるのにReviewed-with:が無い(4 節) - トレーラーは最後の段落に並べる(本文との間に空行を 1 つ。トレーラーの間に空行を挟まない)。git はそこしか読まないので、 検出器は最後の段落に無いトレーラー・全角の「:」・名前の綴りの誤りも止め、直した行と直し方を出す
リリースごとに見る。リポジトリ固有の指標と基準の値は QUALITY.md 6 節にある。
-
期待値の変更のうち、トレーラーが付いたものの割合(3 段で塞げば 100%。漏れがあれば仕組みの穴)
-
リスクが「高」の単位で、根拠付きのテストの割合と、根拠の種類の内訳(7 節)
-
別モデルのレビューで見つかり、書いたモデルのレビューでは見つからなかった指摘の数(判定で採用したもの。数え方は 4 節。完了コメントから拾う)
-
バグの Issue の、見つけた手段の内訳(5 節の
Found-By:)。Git だけで集計できる:git log --format='%h %(trailers:key=Found-By,valueonly,separator=|)' <範囲> -
コミットの、確かめ方の内訳(5 節の
Tested-with:・Reviewed-with:。後でバグが見つかったコミットと突き合わせる):git log --format='%h %(trailers:key=Tested-with,valueonly,separator=|) %(trailers:key=Reviewed-with,valueonly,separator=|)' <範囲>
書き方(属性・引数の名前)は QUALITY.md 7 節にある。 どのリポジトリでも、次を守る。
| 根拠の種類 | 書き方の例 | 備考 |
|---|---|---|
| 仕様 | RFC 7009 §2.1、仕様の ID(EV-ORD-101・VAL-ORD-01) |
節・ID まで書く |
| 別実装 | 別実装:.NET の SHA256 と一致 |
独立した実装と突き合わせたもの |
| 設計 | 設計:<文書や XML コメントの場所> |
リポジトリ自身の文書に書いた約束。書かれていない約束は観測 |
| Issue | #NNN |
不具合の回帰 |
| リポジトリの前提 | 設定の既定値、配備の約束 | 仕様に照らせない。 変わってよいかは人が判断する |
- 節番号・ID は、原典で確かめてから書く。 誤った節は、書かないより悪い
- 根拠は、そのテストの主な期待値について書く。 付随するアサーション(引数の null の検査など)まで分けなくてよい
- 実装の XML コメントに約束が書かれていれば、それは「設計」の根拠である。 根拠を探す前に、実装の
<remarks>を読む - 付いていないテストは「未分類」。 既存のテストは、リスクが「高」の単位(1 節)から順に付ける
- 根拠を消す・変えるのは期待値の変更(3 節)。観測の印を足すだけなら当たらない
- 観測から検証へ上げるのは、人が根拠を確かめてから(2 節)
着手の前と、報告の前に確かめる(リポジトリ固有の項目は QUALITY.md 8 節)。
- 作業の対象が、品質マップ(
QUALITY.md1 節)のどの単位で、リスクはどれか - 「人が必ず見る箇所」に触れたか。触れたなら、報告の冒頭に書いたか
- 期待値の変更(3 節)を含むか。含むなら、報告の冒頭に書き、トレーラーの文面を提案したか。理由に Issue 番号か仕様の節・ID を書き、コミットの前に
opentouryo-expectation-reviewerで突き合わせたか - テストを足したなら、根拠を原典で確かめて付けたか。根拠を付けられない値は、観測にしたか(テスト先行なら、人に上げたか)(2 節・7 節)
- リスクが「高」なら、4 節の観点で見直したか(セルフレビューを書き留めたか)
- リスクが「高」なら、
fixedの前に変更のレビュー役で別モデルのレビューを回したか(4 節)。 すべての指摘に判定を付け、判定後の重大度「高」が無くなるまで回したか。結果(モデル ID・数・内訳・別モデルでだけ見つかった数)を完了コメントに書くか - 見つけた問題を、5 節の 3 か所に戻したか(セキュリティの弱点なら、まず人に報告したか)
- バグの修正(
fixed #NNN)なら、コミット メッセージの案にFound-By:を入れたか(5 節。経緯を推測で埋めていないか) - 流したテスト・回したレビューを、
Tested-with:・Reviewed-with:で書いたか。トレーラーを最後の段落に並べたか(5 節) - 文案を、人に出す前に
-Proposedで確かめたか(3 節)