公開記事54本の専門用語を初出で補う｜PR差分を小さく保つ

公開記事 54 本に、103 行の追記と 98 行の削除が入りました。大半は文章の主張を変える編集ではありません。MCPやCI、pi-hermes-hibanas（このサイトの CI に使う、Raspberry Pi 上のセルフホスト GitHub Actions ランナーの名前）のような言葉へ、初出だけ短い説明を足した差分です。

2026 年 10 月 2 日に作ったdicekanbe/hibanas-net の PR #138では、初出の補足だけを 1 つの差分にしました。対象はすべてsrc/content/posts/内の Markdown です。下書き 10 本は変更していません。

私は、専門用語を消せば読みやすくなるとは考えていません。正確な名前は残し、その場で読み進めるための足場だけを置く方が実務記事に合います。

前回の販売前検査から、公開後の読みやすさへ

前回は、AI で下書きした予定表商品の時刻と改行を検査しました。今回は検査対象を配布ファイルから公開済みの記事へ移します。

時点	確認したもの	今回の変化
前回完了時	ICSのUTC時刻とCRLF改行	商品ファイルの壊れ方を販売前に止めました
今回完了後	公開記事54本の略語・内部名・製品名	初めて読む人が本文中で意味を拾えるようにしました

飛ばせる章: 略語の初出補足が必要な理由を知っている場合は、「PRの範囲を数える」から進めます。

なぜ用語集だけでは足りないのか

AI エージェントの運用記事には、MCP、CI、JSONL（JSON Lines。1 行に 1 つの JSON オブジェクトを書く形式）、SSRF（server-side request forgery。サーバーを騙して、攻撃者が選んだ URL を取得させるリクエストの種類）などの短い表記が増えます。書き手には日常語でも、検索から 1 本だけ開いた人には前提がありません。別ページの用語集へ移動させると、本文の流れが切れます。

W3C の WCAG 2.2 Technique G97 は、略語がページ内で最初に現れる場所の直前か直後へ展開形を置く方法を示しています。テスト手順も明快です。略語の初出を探し、展開形が隣にあり、意味が正しいかを確かめます。

ただし、正式名称だけで伝わるとは限りません。MCP（Model Context Protocol）だけでは役割が見えにくいため、PR #138 では「外部のツールサーバーとエージェントを接続する規格」まで添えました。略語には展開形、内部名には役割、製品名には用途を付けます。

用語

用語	今回の意味
初出	1本の記事内で、その言葉が最初に現れる場所です
展開形	CIに対するContinuous Integrationのような省略前の形です
内部名	リポジトリ名やランナー名など、運用者には通じても読者には説明が必要な名前です
diff	変更前と変更後の行を並べた差分です
PR	pull requestの略で、変更の提案とレビューをまとめる単位です
Markdown	見出しや表を記号で書けるテキスト形式です

説明を足す場所をPRで絞る

今回の流れは、記事を一括で言い換える作業ではありません。公開済みの記事だけを選び、候補の初出を直し、ファイル単位で差分を見ます。

[公開済みの記事]
        ↓
[未説明の略語・内部名を探す]
        ↓
[初出へ短い補足を追加]
        ↓
[PR #138のFiles changedで確認]
   ├─ 主張や数値まで変化 → 戻して分離
   └─ 補足だけの差分     → 品質ゲート
                              ↓
                         [人がレビュー]

GitHub の公式文書は、PR を 1 ファイルずつ確認し、確認済みのファイルをViewedにする手順を案内しています。54 本を一画面で眺めるより、ファイル単位で「説明だけか」を確かめる方が抜けを追いやすくなります。

PRの範囲を数える

最初に、PR #138 の変更量を GitHub から取得しました。ローカルの未コミット差分ではなく、レビュー対象の PR を数えます。

~/.local/bin/gh pr view 138 \
  --repo dicekanbe/hibanas-net \
  --json files,additions,deletions \
  --jq '{files:(.files|length),additions,deletions}'

実行結果です。

{"additions":103,"deletions":98,"files":54}

次に、54 件が重複せず、すべて記事の Markdown かを確認しました。

~/.local/bin/gh pr view 138 \
  --repo dicekanbe/hibanas-net \
  --json files \
  --jq '{total:(.files|length),unique:([.files[].path]|unique|length),non_post_markdown:([.files[].path|select((startswith("src/content/posts/") and endswith(".md"))|not)]|length)}'

実行結果は、総数と一意なパスがどちらも 54 件でした。記事以外は 0 件です。

{"non_post_markdown":0,"total":54,"unique":54}

件数だけでは内容を保証できません。ここでは「対象外の設定や画像が混ざっていない」ところまでを機械で確かめています。

代表差分をAPIから読む

hermes-agent-mcp-tool-filtering.mdの差分を、GitHub API から直接読みました。

~/.local/bin/gh api \
  repos/dicekanbe/hibanas-net/pulls/138/files \
  --paginate \
  --jq '.[] | select(.filename=="src/content/posts/hermes-agent-mcp-tool-filtering.md") | .patch'

出力には、次の変更が含まれていました。

-MCP サーバーを 1 台つなぐだけで、21 個のツールがエージェントへ増えました。
+MCP（Model Context Protocol。外部のツールサーバーとエージェントを接続する規格）サーバーを 1 台つなぐだけで、21 個のツールがエージェントへ増えました。

同じファイルでは、Search Console にも「Google の検索掲載データを見る無料サービス」と補いました。元の 21 個という数値、検査日、記事の結論は変えていません。

この粒度なら、読者は正式名と役割を同時に拾えます。一方で、同じ略語へ毎回説明を付けると文章が重くなります。原則は各記事の初出 1 回です。

補足を短く保つ基準

私は次の順で説明を削ります。

• その文を読むために不要な歴史や比較は入れません。
• 正式名称だけで役割が伝わらない場合は、用途を 1 句足します。
• 記事固有の内部名には、誰が何に使う名前かを示します。
• 同じページの 2 回目以降は、元の短い表記へ戻します。
• 事実や数値の更新は、読みやすさの PR から分けます。

検索向けの語を追加することより、目の前の文を止まらず読めることを優先します。Google Search Central も、読者が使う検索語の違いを想定しつつ、興味深く有用な内容を作るよう案内しています。用語の言い換えだけで中身の薄さは補えません。

よくあるエラー

症状	原因	対処
略語の正式名を足しても意味が伝わりません	展開形だけで用途を書いていません	役割を短い1句で足します
全文が括弧だらけになります	2回目以降にも同じ説明を付けています	各記事の初出だけに絞ります
読みやすさのPRで数値まで変わります	内容更新と用語補足を同時に進めています	事実更新を別PRへ分けます
ファイル数は合うのに下書きが混ざります	パスだけを見て公開状態を見ていません	frontmatterのdraftとpublication_stateも確認します
内部名の説明が長くなります	運用の全履歴を書いています	その文で必要な役割だけを書きます
PRの確認が途中で止まります	54本を一度に眺めています	GitHubのViewedを使い、1ファイルずつ進めます

一次情報

情報源	確認したこと
hibanas-net PR #138	54ファイル、103行追加、98行削除の実差分と対象記事です
W3C WCAG 2.2 Technique G97	略語の初出へ展開形を隣接させる方法と検査手順です
GitHub Docs: Reviewing proposed changes in a pull request	Files changedをファイル単位で確認し、Viewedで進捗を追う手順です
Google Search Central: SEO Starter Guide	読者の検索語を想定し、有用な内容を作る基本方針です

専門用語は、実務の精度を支える名前でもあります。消すのではなく、初出にだけ橋を架けます。今回の PR は、その橋が記事以外へはみ出していないところまで数えてから、レビューへ渡しました。