Skip to content

Latest commit

 

History

History
321 lines (238 loc) · 28.8 KB

QUALITY.common.md

File metadata and controls

321 lines (238 loc) · 28.8 KB

品質の羅針盤:共通の決まり(QUALITY.common.md)

どこを・何で・どれだけ確かめるかの決まりのうち、どのリポジトリでも同じ部分。人が決め、エージェントが従う。

  • リポジトリごとの中身(品質マップ・観点・根拠の書き方・計測の基準)は QUALITY.md にある。節の番号は同じで、本書の N 節の決まりで、QUALITY.md の N 節を引く
  • エージェントは、変更の前に本書と QUALITY.md を読む
  • 本書の「このリポジトリの値」は、QUALITY.md の冒頭の表を指す(検出器の置き場所・宛先のブランチ・必須のチェック・役の名前など)
  • 本書には方針と表だけを置く。手順は、QUALITY.md の一次情報の表に挙げた文書による

人は個々の変更を細かく見るより、羅針盤を決める役を担う。 エージェントは、作業が品質マップのどの単位に当たるかを QUALITY.md で引き、その重みで確かめ、報告する。


1. 品質マップ

リスクの高い単位ほど、検証の手段を重ね、人の確認点を増やす。 リスクの低い単位はエージェントに任せ、壊れたら作り直す。

  • 単位は、リポジトリで決める(フレームワークなら名前空間、アプリなら画面・層・業務など)。表は QUALITY.md 1 節にあり、列は「単位・リスク・正の根拠・検証の手段・人が必ず見る箇所」
  • リスクは、壊れたときの影響(セキュリティ・データ・後方互換性)と、仕様の複雑さで付ける(高・中〜高・中・中〜低・低)
  • 表に無い単位は「中〜低」として扱う。 迷ったら、高い方に倒して報告する
  • 「人が必ず見る箇所」に触れたら、報告の冒頭に書く。 人が差分のどこを見ればよいかを示すためである
  • 検証の手段の具体(どのスクリプトを、どの引数で回すか)は、QUALITY.md の一次情報の表の文書による

2. 正の定義

テストが通ることは、正しいことの証明ではない。 同じエージェントが書いたテストとコードは、仕様の読み違いを共有しうる。

  • 期待値には根拠を書く。 仕様の該当箇所(RFC の節・仕様の ID など)か、Issue の番号。書き方は 7 節と QUALITY.md 7 節
    • 根拠を書けない期待値は、今の振る舞いを写しただけである。そう分かるように書く(「観測」。下記)
    • テスト先行で進めるリポジトリ(TESTING.md がある)では、根拠を付けられないケースは、仕様の決定として人に上げる(推測で補わない)
  • 「検証」と「観測」を分ける
    • 検証:仕様に照らして、正しいと言える値を確かめる
    • 観測:仕様に幅がある、または根拠を確かめていない値を、変わったことに気付くために残す
    • 観測から検証へ上げるのは、人が根拠を確かめてから
    • 観測が落ちるか(合否に入れるか)は、リポジトリで決める(QUALITY.md 2 節)。 例:部品のライブラリは、振る舞いが変わること自体が利用者への影響なので、観測も落とす。 外から叩くサイトの E2E は、仕様に幅のある項目を合否に混ぜると「通った」の意味が薄まるので、落とさずに前回との差分を報告する
  • 外部の基準(静的解析・適合性テスト・相互運用)があれば、それを最終的な正とする(何を使うかは QUALITY.md 2 節)

3. 期待値の変更と、その承認

エージェントは、テストを書き換えて通すことがある。 人の注意に頼らず、仕組みでスルーできないようにする。

期待値の変更とは

機械的に検出できるものに絞る。何が当たるかはリポジトリの規則(検出器の 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 <ファイル> を動かす。作業ツリーの変更をすべてステージしたとして判定する(索引は変えない)。止まれば、直してから出す

3 段で塞ぐ

段 仕組み 何を塞ぐか 有効にするのは
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 の側の版で動く。人が差分を確かめ、必須のチェックにするのはマージの後

CI で止まったとき

段 3 は、PR のマージでないコミットを 1 つずつ、そのコミットのメッセージで判定する。止まったら、上から順に選ぶ(止めたときの表示にも同じ順で出る)。 push したコミットのメッセージは書き直さない(--amend・rebase と force push)。共有のブランチでは、ほかの人・セッションの手元が壊れ、ほかの人のコミットを消すおそれがある。

  1. 後のコミットで承認する(履歴を書き換えない): 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
  2. 管理者が、その PR だけ保護を迂回してマージする(マージの画面の「Merge without waiting for requirements to be met」)。期待値を変えた理由を、PR のコメントに残す。 必須のチェックを外す・ワークフローを止める、はしない(すべての PR の保護が外れる/チェックが結果を返さず、PR がかえって止まる)

段 2 を有効にする(各自の手元で 1 回)

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 操作は行わない」)
  • テストを通すために期待値を変えない。 先にコードを疑う。期待値が誤っていると判断したら、その根拠(仕様の該当箇所)を示す

4. レビューの観点

品質マップの単位に応じて、QUALITY.md 4 節のチェックリストで確かめる。 エージェントがレビューするときも、自分の変更を見直すときも同じである。 どの単位でも、次を確かめる。

  • 期待値の変更(3 節)を含むか。含むなら、根拠があるか
  • テストが、変更した分岐を実際に通しているか(テストの名前ではなく、入力と期待値で見る。測れるならカバレッジで行を見る)
  • 見つかった型の横展開:同じ形が、別の箇所(別の画面・口・クラス)に残っていないか
  • 検証を省く分岐(設定やパラメタで検証を飛ばせる経路)が増えていないか
  • 公開の口(API・設定のキー・既定値・画面の振る舞い)の後方互換性。変えるなら、Issue と文書に書かれているか

作る役と検証する役を分ける

  • リスクが「高」の単位に触れる変更は、書いたセッションとは別のセッションでレビューする(文脈を引き継がない)
  • さらに、書いたモデルとは別のモデルでレビューする。 同じモデルは、同じ読み違いをしやすい
  • 指摘の形:重大度・箇所・内容・原典の節・再現の方法(テストにできるか、その入力)・確信度(確かめた / 推測)を必須にする。 人の検収で律速になるのは指摘の理解なので、原典と照らすだけで判断できる形にする
  • 数え方:判定を経てから数える。 別モデルの指摘を、そのまま不具合と数えない
  • 終了の条件:回数ではなく、別モデルのレビューで、判定後の重大度「高」の指摘が無いことで決める
  • CodeQL のような、LLM とは別系統の検査も併用する。 主とレビュー役は同じ系統のモデルなので、読み違いの共有は減っても、無くなりはしない

サブエージェントで回す

レビュー役は、変更のレビュー役(このリポジトリの値。.claude/agents/ の役の定義)である。 主の会話の文脈を持たずに始まるので、「別のセッション」にも当たる。書き換えの道具(Edit・Write)は持たせていない。

いつ回すか:少なくとも、リスク「高」の単位に触れる変更の、fixed のコミットの前。fixing の段では任意(回す場面を広げるなら QUALITY.md・AGENTS.md に書く)。

  • 基本は、fixed の前のワーキング ツリーをレビューし、採用した指摘をそこで直す(範囲は「Issue の着手の前のコミットと、ワーキング ツリーの差分」)
  • コミットの後に回したなら、範囲をハッシュで指定する。 採用した指摘は、内容によって、その場で直して別のコミットにする(追加の修正)か、別の Issue にする
  1. 主は、呼ぶ前に、自分のレビューの指摘を書き留める(セルフレビュー。4 の突き合わせに使う)。 AGENTS.md に「作業の見える化」があれば、呼ぶ前と報告を受けたときに、ルートの AGENT-DASHBOARD.md を書き直す(無ければ作る)
  2. 主は、決まった型だけを渡す(Issue 番号・範囲・単位。型は役の定義の本文)。 主の説明・設計の理由・「ここは正しい」という見立て・セルフレビューの結果は渡さない(同じ読み違いを共有しないため)
  3. 主は、すべての指摘に判定を付ける(採用・却下・保留と、その理由)。却下したものも報告から落とさない。 「見ていない範囲」に、差分のファイル(テストを含む)や差分に出てくる原典の節が残っていたら、そのレビューは終わっていない。 回し直すか、残ったことを報告に書く
  4. セルフレビューと突き合わせ、別モデルのレビューでだけ見つかった指摘を数える(6 節の計測)
  5. 採用した指摘を直したら、もう一度回す。終了は上の「終了の条件」による
  6. 結果を、完了コメントの「確かめたこと」に書く:主とレビュー役のモデル ID、指摘の数、判定の内訳、別モデルでだけ見つかった数
  • 主のモデルは、各自の設定に任せる(共有の .claude/settings.json では揃えない。プロジェクトの設定は各自の設定より優先され、全員に同じモデルを強いるため)。 主もレビュー役と同じモデルなら、別モデルのレビューにならない。 そう報告し、6 節の計測には数えない
  • 呼んだかどうかの記録は、完了コメントと、コミットのトレーラー Reviewed-with: <役> (<モデル ID>)(5 節)による。 rules.psd1 の TrailerRequirements に組があれば、リスク「高」の単位を fixed で変えたのに無いとき、検出器が警告する(止めない。fixing では警告しない)
  • 判定は検収の材料であり、検収の代わりではない。 人は判定の結果を読んで検収する

見つけた問題がセキュリティの弱点なら、公開の文書に書かない。 まず人に報告する。 チェックリストに足すのも、修正と同じコミットにする(5 節)。


5. フィードバックの輪

見つかった問題は、次の 3 か所に戻す。

  1. 回帰テスト:Issue に紐付けて残す(名前の付け方はこのリポジトリの値)
  2. レビューの観点:QUALITY.md 4 節のチェックリストに足し、次からレビューで拾えるようにする
  3. 品質マップ:その単位のリスク・検証の手段・人の確認点を見直す(QUALITY.md 1 節)

QUALITY.md を直すのは、問題を直したのと同じコミットにする。 先に書くと、未修正の弱点を公開することになる。 どのリポジトリにも当てはまる観点は、原本(OpenTouryoCodingAgentAssets)の本書に足すよう、人に提案する。

見つけた手段を残す:Found-By:

バグを直すコミット(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 に無ければ警告に留める(バグかどうかは機械に分からない)
  • 導入の前のコミットには遡って付けない(コミットは書き換えない)

確かめ方を残す:Tested-with:・Reviewed-with:

そのコミットをどう確かめたか(流したテストの種類・レビューした役)を、トレーラーで残す。 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 はそこしか読まないので、 検出器は最後の段落に無いトレーラー・全角の「:」・名前の綴りの誤りも止め、直した行と直し方を出す

6. 計測

リリースごとに見る。リポジトリ固有の指標と基準の値は 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=|)' <範囲>
    

7. 期待値の根拠の書き方

書き方(属性・引数の名前)は 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 節)

8. エージェント向けチェックリスト

着手の前と、報告の前に確かめる(リポジトリ固有の項目は QUALITY.md 8 節)。

  • 作業の対象が、品質マップ(QUALITY.md 1 節)のどの単位で、リスクはどれか
  • 「人が必ず見る箇所」に触れたか。触れたなら、報告の冒頭に書いたか
  • 期待値の変更(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 節)