learning_timeを自動正規化する設計と実装
この記事で学べること
learning_timeの正規化をレビュー前へ移す理由- 日本語・英語の本文量から読了時間を計算するルール
- 作成時の正規化と
dev:check・prebuildの安全網を分ける設計
learning_timeは記事完成後に日英で正規化する
日英docsのlearning_time（本文量から計算する読了時間）をビルド前だけに正規化すると、内容レビューの途中で機械生成の差分が現れます。このサイトでは、正しい更新であっても、本文変更とメタデータ変更の確認が混ざりました。本文完成直後に正規化し、後続の検査はずれを戻す安全網として残します。
この記事では、「learning_timeの自動更新をいつ実行すれば、レビュー差分を混在させずに済むか」という問いに焦点を当て、期待と結果の差、確認できた条件、再発を防ぐ判断を扱います。
最後まで読むと、「learning_timeの自動更新をいつ実行すれば、レビュー差分を混在させずに済むか」という問いを、自分の状況に照らして判断するための材料を持ち帰れます。
本文完成直後にlearning_timeを正規化する
前回は、dev:checkとprebuild（本番ビルド前に正規化や検証を行う前処理）の処理順を変更しました。先にnode scripts/normalize-learning-time.mjs --writeを実行し、その後で--checkを実行します。これにより、未正規化の learning_time だけでビルド前検証が止まる問題は避けられるようになりました。
この設計だけでは、読了時間の確定が遅いままです。記事作成後のdev:checkで初めてfrontmatter（Markdown記事の先頭に置く設定情報）が変わると、本文修正と機械的な時間調整が同じレビュー差分へ現れます。
ハーネス（AIへ渡すルール、手順、検証方法をまとめた仕組み）の検証は最後の安全確認に使います。そのため、本文量から決まる値は記事作成中に確定させます。
learning_timeを日英本文の完成直後に正規化する
現在は、docs記事の作成・翻訳手順で、日本語版と英語版の本文が揃った時点で次のコマンドを実行するルールにしました。
npm run normalize-learning-timeこのnpm scriptはnode scripts/normalize-learning-time.mjs --writeを実行します。同じルールをdocsコマンド、docs-content Skill、i18n-sync Skill、content-i18nルールにも置きました。
scripts/validate-harness.mjsは、共有手順からこの処理が抜け落ちていないかを検査します。
これにより、記事作成時の流れは「日本語を書く」「英語に同期する」「本文量から learning_time を正規化する」「レビューする」「dev:check で安全網を通す」という順序になります。
learning_timeは本文量から言語別に計算する
scripts/normalize-learning-time.mjs は frontmatter と本文を読み、本文から見積もった読了時間を learning_time に書き戻します。日本語は有効文字数を約300文字/分、英語は約130語/分で計算し、最小値を5分として5分刻みに丸めます。
たとえば短い新規記事では、下書き段階の 約8分 / About 8 minutes が、本文量に合わせて 約5分 / About 5 minutes へ変わることがあります。これはレビューで直すべき文章品質の問題ではなく、本文量から決まるメタデータを標準形式へ寄せる処理です。
実践時間を含む記事では、読了時間は本文量から計算し、実践時間は既存の 実践 20分 や 20 min hands-on のような値を保持します。本文から機械的に決まる読了時間だけを自動化し、実践時間は記事設計で判断します。
dev:checkとprebuildは後続編集のずれを検出する
作成時に learning_time を正規化しても、dev:check と prebuild の自動正規化は残しています。理由は、既存記事の更新、翻訳後の加筆、レビュー中の本文変更によって、作成時の値が再び古くなる可能性があるためです。
役割分担は次のとおりです。作成時の npm run normalize-learning-time は、レビュー前に差分を小さくするための通常フローです。dev:check と prebuild の --write、--check は、作成時の実行漏れや後続編集を拾う安全網です。scripts/validate-harness.mjs は、その手順と順序が将来の変更で崩れないようにする検査です。
この三段構えにしたのは、ハーネス検証を「毎回の読了時間調整作業」にしないためです。計算できる値は作成中に確定し、最後の検証では漏れだけを検出する方が、レビューの焦点を本文・構成・根拠確認に戻せます。
まとめ：本文完成直後に正規化し、後続検査は安全網にする
learning_time は本文量から決められるため、人が固定値として管理するよりも、記事作成フローの中で自動正規化する方が安定します。一方で、本文はあとから変わるため、dev:check と prebuild の正規化は安全網として残します。
今回の修正では、docs作成・翻訳手順に npm run normalize-learning-time を明記し、そのルールを harness でも検査するようにしました。これにより、約8分 / About 8 minutes のような未正規化値がレビューやビルド直前まで残る状態を減らし、機械的に決まるメタデータは早い段階で確定できるようにしています。
最初に日英本文を確定した後で正規化コマンドを実行し、その差分を本文レビューと分けて確認します。本文量以外の基準で読了時間を決めるサイトでは、この計算方法をそのまま使えません。