Skip to content

[Docs] 通常運用スコープの比例性原則を独立文書化#183

Merged
BlueEventHorizon merged 2 commits into
developfrom
docs/scope-proportionality-principle
Jul 7, 2026
Merged

[Docs] 通常運用スコープの比例性原則を独立文書化#183
BlueEventHorizon merged 2 commits into
developfrom
docs/scope-proportionality-principle

Conversation

@BlueEventHorizon

Copy link
Copy Markdown
Owner

概要

背景

以前のレビューで、evaluator が「プロセスクラッシュを前提にした1箇所のみのアトミック化提案」のような、カタストロフィックな異常事態への過剰な防御実装を fix 推奨してしまう問題が見つかった。この判断基準(3点チェック)は review_priorities_spec.md §3.4 に追記されていたが、以下の構造的欠陥があった:

  1. review_priorities_spec.md 自体が reviewer/evaluator の必須読み込みリスト(ssot_refs[])に含まれておらず、実際に読まれる保証がなかった
  2. 3点チェックの2番目「通常運用フロー(commit前のdiff確認等の既存の安全網)で顕在化するか」という文言が、「レビューで見つかった=顕在化済みでskipでよい」という自己論駁的な誤読を許し、通常のレビュー修正(要件・設計・ルール違反、実行時リスク等)まで過剰に skip される可能性があった(Issue [Improve] scope_proportionality_spec の 3点チェックが通常のレビュー修正まで skip に倒しうる #182

やったこと

1コミット目: 原則の独立文書化と構造的な必須参照化

  • plugins/forge/docs/scope_proportionality_spec.md を新規作成し、比例性の原則を集約
  • review_priorities_spec.md §3.4 を全文複製から参照形式に変更(重複していた §3.4 番号衝突も §3.5〜§3.7 に修正)
  • review/SKILL.md Phase 3 の ssot_refs[] 固定注入(P3)に追加し、レビュー種別を問わず reviewer/evaluator が必ず読む構造にした(受動的な文書内参照だけでは読まれる保証がないため)
  • impl-issue/SKILL.md Phase 8 に、実装スコープ判断時の動的検索の参照ポインタを追加(パス直書きせず /forge:query-forge-rules 経由)

2コミット目: Issue #182 対応(3点チェックの誤読防止)

  • 3点チェックの適用対象を、以下3類型に明示的に限定した:
    1. カタストロフィックな外部要因への防御
    2. 発生経路を具体化できない投機的な防御実装
    3. 設計・要件・プロジェクトルールに根拠のない品質改善の即時修正化
  • 3類型に該当しない指摘(明示された要件・設計・ルール違反、具体的な実行時リスク、データ損失・セキュリティ・破壊的操作等)は本原則の対象外であり、skip の根拠にできないことを明記
  • 3点チェック2番目の文言を「レビュー対象コードとは独立した既存の安全網」であることを明示する形に修正し、「レビューで見つかったこと」自体が根拠にならないと明記
  • 判定に迷う場合は「該当しない(=通常通り fix 対象)」とし、false positive(過剰 skip)を避ける方針を追加

やらないこと(このプルリクエストのスコープ外とすること)

  • docs/rules/(プロジェクト自身の開発ルール)への配置は行わない。本原則は forge/anvil を使う全下流プロジェクトに適用されるべきものであり、配布物である plugins/forge/docs/ に置く必要がある

レビュー観点

レビューレベル

  • Lv0: まったく見ないでAcceptする
  • Lv1: ぱっとみて違和感がないかチェックしてAcceptする
  • Lv2: 仕様レベルまで理解して、仕様通りに動くかある程度検証してAcceptする
  • Lv3: 実際に環境で動作確認したうえでAcceptする

備考

Closes #182

全1292テスト green(ToC鮮度契約テスト含む)。

BlueEventHorizon and others added 2 commits July 7, 2026 11:28
- plugins/forge/docs/scope_proportionality_spec.md を新規作成
  (カタストロフィックな異常事態 [OSクラッシュ・ファイルシステム破損等] への
  防御はスコープ外と明示し、fix判定の3点チェックを一般化して集約)
- review_priorities_spec.md §3.4 を全文複製から参照形式に変更
  (重複していた §3.4 番号衝突も §3.5〜§3.7 に修正)
- review/SKILL.md Phase 3 の ssot_refs[] 固定注入(P3)に追加し、
  レビュー種別を問わず reviewer/evaluator が必ず読む構造的な参照にする
  (受動的な文書内参照だけでは読まれる保証がないため)
- impl-issue/SKILL.md Phase 8 に、実装スコープ判断時の動的検索の
  参照ポインタを追加(パス直書きせず /forge:query-forge-rules 経由)
- forge ToC を再生成・同梱ファイルへ反映

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- scope_proportionality_spec.md: 3点チェックの適用対象を3類型
  (カタストロフィックな外部要因防御/投機的防御実装/根拠なき品質改善の
  即時修正化) に明示的に限定し、3類型に該当しない指摘(要件・設計・
  ルール違反、具体的な実行時リスク、データ損失・セキュリティ等)は
  対象外と明記
- 3点チェック2番目の「通常運用フローで顕在化するか」が
  「レビューで見つかった=顕在化済みでskip可」と誤読される
  自己論駁的な文言だったため、「レビュー対象コードとは独立した
  既存の安全網」であることを明示し、「レビューで見つかったこと」
  自体が根拠にならないと明記
- review_priorities_spec.md §3.4 も同様に、全fix判定ではなく
  3類型該当時のみ適用されると明確化
- 判定に迷う場合は「該当しない(=通常通りfix対象)」とし、
  false positive(過剰skip)を避ける方針を追加

Closes #182

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@BlueEventHorizon BlueEventHorizon self-assigned this Jul 7, 2026
@BlueEventHorizon
BlueEventHorizon marked this pull request as ready for review July 7, 2026 03:38
@BlueEventHorizon
BlueEventHorizon merged commit 9465932 into develop Jul 7, 2026
1 check passed
@BlueEventHorizon
BlueEventHorizon deleted the docs/scope-proportionality-principle branch July 7, 2026 03:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant