ADR-0136: news 一覧の更新日時から軽微コミット(誤字修正等)をコミットメッセージ目印で除外する

• Status: Accepted (PR #1758 merge = 受理の規約により 2026-06-11 受理・代表取締役判断)
• Mode: Standard
• Kruchten Type: Executive/Property
• Scope: platform
• Implementation Status: Done (2026-06-11 実装: MINOR_COMMIT_PATTERNS + git_workflow.md 新節)
• 起案者: [email protected]
• 起案日時 (JST): 2026-06-11 16:34
• 承認日時 (JST): 2026-06-11 17:13
• Deciders: [email protected] (単独)

コンテキスト

§1.1 背景

docs サイトの「最新更新ページ (What's New)」一覧は、各ページの更新日時を git 履歴から計算して表示する。誤字修正や表記ゆれ統一のような軽微な直しでも日時が動くため、読者が「内容が変わった」と誤解してページを開き、何も変わっていないことを確認するムダな往復が起きる。一覧の目的である「意味のある最終更新を一目で知る」が損なわれている。

§1.2 現状 (As-Is)

実装が参照するコミット subject(1 行目)・非 merge ベースの実測(2026-06-11 受理前精査): style: / chore: 始まりで docs を変更したもの 17 件(2026-05-01 以降)、typo を含むもの全履歴で 1 件、「誤字」を含むもの全履歴で 0 件。起案時の「46 件・約 6%・週 12 件」はコミットメッセージ本文や merge コミットへのマッチを含む過大計上だったため本修正で訂正した。実態として、このリポジトリの誤字・表記修正は専用 subject を持たず、実質変更と同一コミットに混在している。frontmatter(ページ先頭の機械用メタデータ)だけの変更と ADR メタデータ行だけの変更は、2026-06-11 の改修(PR #1751)で本文比較により自動除外済み。

§1.3 課題

残る本文の軽微変更は、誤字修正(例: 「受け取り」→「受取」)も意味のある 1 行修正も同じ「本文 1 行の差分」であり、差分の形からは機械的に区別できない(PR #1751 実装時に確認した技術的制約)。さらに受理前精査で、chore: / style: コミットの 94.1%(17 件中 16 件)が読者に見せるべき実質変更(設計変更の記録・TODO 追加・廃止処理等)を含むことが判明し、接頭辞ベースの自動除外は誤除外を構造的に内包することが確認された。

§1.4 制約・要件

• 差分内容からの自動判定は技術的に不可能(課題の通り)。
• 非強制であること: 付け忘れても一覧に出るだけで何も壊れない。lint・コミットフックで縛らない。
• 適用範囲は news 一覧のみ。PR 単位の全変更を記録する doc_changelog には適用しない。
• 判定パターンの正典はスクリプト(scripts/generate-doc-news.mjs の MINOR_COMMIT_PATTERNS)、人間向け説明は docs/_internal/05_how-to/git_workflow.md の新節。

§1.5 目標 (To-Be)

news 一覧の更新日時を「意味のある最終更新」に揃え、軽微コミットでは日時が動かないようにする。Non-Goals: 完全な誤除外ゼロ、強制化(lint・コミットフック)。

決定

差分から判定できない以上、書き手がコミット時に申告する方式を採る。news 一覧の更新日時計算で、subject に明示マーカー [skip-news] を含むコミットを読み飛ばし、その前の「本文が意味的に変わったコミット」の日時を表示する(例: docs(adr): 参照先の表記揃え [skip-news])。

自動キーワード(typo・「誤字」・style:・chore:)は採用しない。根拠は受理前精査(2026-06-11・§5.3 盲点 #1 の前倒し実施): chore: / style: は 17 件中 16 件(94.1%)が実質変更を含み、本決定自身の連動ルール(10% 超で自動キーワードを外し明示マーカーのみへ)が発動した。typo / 「誤字」も subject での使用実績がほぼなく(全履歴で 1 件・それも実質変更との混合コミット)、自動除外の経験的支持がない。

設計上の位置づけは非強制。判定パターンの正典は scripts/generate-doc-news.mjs の MINOR_COMMIT_PATTERNS(= [skip-news] の 1 パターン)、人間向け説明は docs/_internal/05_how-to/git_workflow.md の新節。明示マーカーは付けた時点から効き、過去コミットへの遡及適用はない(過去分の軽微変更除外は PR #1751 の本文比較のみ)。除外したコミットは生成時に標準出力へログ出力し、月次で集計可能とする(盲点 #3 への対応)。

判断基準 (Decision Drivers)

3.1 評価軸

K.O. criterion: 意味のある更新が書き手の意図に反して機械的に隠される設計(誤除外を構造的に内包する自動推定)は不採用。Must 軸 #usable の score < 3 は不採用。

3.2 評価軸 × 案スコア表

(満点 = 5 × Σ係数 = 5 × 3.5 = 17.5)

受理前修正の記録 (2026-06-11): 上表は審査 run 時点の評価。受理前精査(§5.3 盲点 #1 の前倒し実施)により案 A の前提(自動キーワードが安全に軽微コミットだけを拾う)が崩れ、案 A は K.O. criterion「誤除外を構造的に内包する自動推定は不採用」に抵触することが判明した。また案 B の #usable=2 評価は「週約 12 件の手間」という過大計上(§1.2 訂正済み)に依存しており、実態(該当コミットは稀)では成立しない。よって連動ルールに従い案 B を採択する。

検討した代替案 (Alternatives Considered)

• 案 A: 併用(自動キーワード + 明示マーカー・当初採択案) — 受理前精査で chore: / style: の 94.1% が実質変更を含むことが判明し、本決定自身の連動ルール(10% 超で自動キーワード除外)が発動。typo / 「誤字」も使用実績ほぼゼロ(全履歴 1 件・混合コミット)で自動側の便益が実証できず、K.O. 基準(誤除外の構造的内包)に抵触するため不採用。
• 案 C: 自動キーワードのみ — 案 A と同じ理由で不採用。明示マーカーも持たないため軽微修正を除外する手段が一切なくなる。
• 案 D: 規約なし(現状維持) — 将来の軽微修正(誤字直し等)で日時が動くのを止める手段がないまま。明示マーカー 1 つの低コストで解決できる便益を放棄するため不採用。
• 案 E: 「表記」も自動キーワードに含める — 「表記体系の決定」のような意味のある変更まで巻き込む誤除外リスクがあり、案 A 以上に K.O. 基準に抵触するため不採用。

採用案 B(明示マーカーのみ)は、機械的な誤除外が構造的に起きず(書き手が明示したものだけ除外)、判定パターン 1 つで保守も最小になる。

影響 (Consequences)

§5.1 正の影響 (Good)

• 一覧の日時が「意味のある最終更新」に近づく。
• 機械的な誤除外が構造的に起きない(書き手が [skip-news] を明示したコミットだけが除外される)。
• 除外ログ出力により月次で誤除外の傾向を可視化できる(盲点 #3 への対応)。

§5.2 負の影響 (Bad)

• コミット subject の書き方に新しい約束が 1 つ増える(覚える負担。ただし記法は [skip-news] の 1 つのみ)。
• 判定パターンと文書の二重管理(スクリプトと git_workflow.md)が発生し、追従漏れリスクがある(盲点 #6)。
• 明示マーカーは遡及しないため、過去の軽微コミットには効かない(過去分は PR #1751 の本文比較による自動除外のみ)。なお盲点 #2(遡及適用で読者が認知していた更新日時が変わる・外部リンクとの整合性影響)は、自動キーワード不採用により遡及適用自体がなくなり解消した。

§5.3 中立・トレードオフ (Neutral / Trade-offs)

• リスク: 付け忘れによる取りこぼし(非強制の代償)。実質変更コミットへの [skip-news] 誤付与(撤退条件 #1 で監視)。
• 盲点 #1(chore: / style: の誤用リスク) — 受理前の 2026-06-11 に前倒しで精査を実施済み: subject が style: / chore: 始まりの非 merge コミット(2026-05-01 以降・docs 変更あり)17 件のうち 16 件(94.1%)が本文の実質変更を含んだ(判定 = PR #1751 と同じ本文正規化比較。内訳: 設計変更の記録・TODO 追加・廃止処理・ファイル新設・自動再生成ページ更新等)。閾値 10% を大幅に超過したため連動ルールが発動し、自動キーワードを全廃して本決定を案 B(明示マーカーのみ)に修正した。
• 盲点 #4(キーワード肥大化): 自動キーワード不採用により当面該当なし。将来自動キーワードを再導入する場合は本 ADR の改訂を要し、その際は総数上限 8 パターンを適用する。
• 盲点 #5(スコープ波及): 本 ADR の決定事項は「MINOR_COMMIT_PATTERNS の追加」と「git_workflow.md 新節の追加」の 2 点。後者は参考情報の位置づけであり、lint・PR レビュー必須化・onboarding 必修化には踏み込まない。

撤退条件 (Rollback Plan)

• #1: 誤除外(実質変更コミットへの [skip-news] 誤付与で意味のある更新が一覧から消える)の発見が月 2 件以上になったら、規約の廃止を再検討する。
• #2: 付け忘れ起因の「軽微なのに一覧に出る」報告が月 3 件以上になったら、規約の周知方法を見直すか廃止を再検討する。
• #3: 判定パターンの変更要望(自動キーワード再導入等)が四半期に 3 回以上発生したら、規約が実態に合っていないとみなし本 ADR の改訂で再評価する。
• #4: 月次の除外件数ログが前月比 20% 増を 2 ヶ月連続で記録したら、誤除外の潜在化を疑い差分サンプリング監査を実施する(盲点 #3 への対応)。

コスト試算

• 実装: 約 0.25 人日(スクリプトへの判定追加 + git_workflow.md 新節 + 検証)。類似実績 = PR #1751(同スクリプトへの判定追加)が約 0.25 人日。
• 運用: 軽微修正コミットの際に subject へ [skip-news] を一語追記する手間のみ(1 コミットあたり数秒。履歴実績では該当する単独軽微コミットは稀)。
• 実行コスト: 既存の履歴走査にコミット 1 件あたり正規表現判定 1 回が加わるのみで、生成時間(現状約 17 秒)への影響はほぼ 0。LLM・外部 API・金銭支出は 0 円。

Confirmation

• 検証手段: 受理後最初の [skip-news] 付きコミットで対象ページの一覧日時が動かないことを目視確認。以後は news 一覧再生成時のログ(軽微判定の走査件数・除外コミットの subject)と、誤除外報告の件数を記録する。git_workflow.md の新節とスクリプトの MINOR_COMMIT_PATTERNS の一致は四半期の docs 棚卸しで確認する。
• 実行頻度: 初回確認は実装後最初の [skip-news] 使用時に 1 回。誤除外件数・除外件数ログの集計は月次。文書とパターンの一致確認は四半期。
• 違反時対応: 誤除外を発見したら該当コミットを記録し、月 2 件以上で撤退条件 #1 を発動。文書とパターンの不一致は発見した側が同週内に修正 PR を出す。MINOR_COMMIT_PATTERNS 変更 PR では git_workflow.md の該当節を同一 PR で更新することを PR テンプレートのチェックリストに追記する(盲点 #6 への対応)。
• KPI: 誤除外報告 0 件/月(許容上限 1 件)。受理 1 ヶ月後の確認で誤除外 0 件なら定着とみなす。

参照 (References)

• 関連 ADR:
  • ADR-0115: AI エージェント向け知識レイヤ規約 — 補完。本規約の置き場所(正典 = スクリプト、人間向け説明 = docs/_internal の how-to)は同 ADR の層別配置に従う。
• 関連 PR/Issue:
  • PR #1657: news 一覧機能導入(ADR を経ない実装改修として導入済み)。
  • PR #1751: 軽微変更の自動除外(frontmatter / ADR メタデータ行)導入(ADR を経ない実装改修として導入済み)。本起案はその上に載る「人の書き方への期待(コミットメッセージ規約)」部分のみを決定として切り出したもの。
• 外部資料: -