update-official-doc-summary

Imported from empty-can/cc-relative-info (.claude/skills/update-official-doc-summary/SKILL.md). Install upstream with npx skills add empty-can/cc-relative-info --skill update-official-doc-summary. Copyright stays with the author.

引数パース

• --site <slug>: 対象サイト。省略時は claude-code-docs(後方互換)。有効値は「サイト設定テーブル」の slug 列。値を SITE とする
• --from <commit>: 初版作成時の起点コミット。省略時は前回サマリの末尾フッタから head_commit を取得し BASE_COMMIT とする。前回サマリが無く --from も無ければエラー終了
• --automated: 無人（ヘッドレス/パイプライン）実行を示すフラグ。本フラグがあれば AUTOMATED=1、無ければ AUTOMATED=0 とする（手順 13 の Phase 3 要否判定で使用）。ラッパー run-doc-summary.ps1 が自動付与する。手動・対話起動では付けない

サイト設定テーブル

SITE(--site)で以下を決定する。<INPUT_BASE> 配下に llms.txt / llms-full.txt がある前提。

固定パス

サイト設定テーブルの選択行に基づき以下を決定する:

• SUMMARY_DIR = LLMs/official-doc-update-summary/<出力slug>/
• LATEST_DETAIL = ${SUMMARY_DIR}latest-detail.md
• LATEST_LIGHT = ${SUMMARY_DIR}latest.md
• ARCHIVES_DIR = ${SUMMARY_DIR}archives/
• TEMPLATE = .claude/skills/update-official-doc-summary/templates/<テンプレート>
• DERIVE_SCRIPT = .claude/skills/update-official-doc-summary/scripts/derive_light.py
• INPUT_LLMS_TXT = <INPUT_BASE>llms.txt
• INPUT_LLMS_FULL = <INPUT_BASE>llms-full.txt
• INPUT_DOCS_MAP = docs_map=あり のとき <INPUT_BASE>en/claude_code_docs_map.md。docs_map=なし のとき使用しない

主要処理

1. 前回サマリ参照と BASE_COMMIT 決定

Read tool で $LATEST_DETAIL を読み込む。

BASE_COMMIT の決定(引数 --from を最優先):

• 引数 --from <commit> がある場合: BASE_COMMIT = <commit>(既存ファイルの有無に関係なく優先)
• 引数 --from がない場合:
  • $LATEST_DETAIL が存在する: 末尾の HTML コメント <!-- ... head_commit: <hash> ... --> から BASE_COMMIT を抽出
  • 存在しない: 標準エラーに 初版作成には --from <commit> 指定が必要です を出力して終了

PREV_GENERATED_AT / ARCHIVE_NAME の決定(アーカイブフォルダ名で使用):

• $LATEST_DETAIL が存在する: frontmatter から 作成日 を抽出して PREV_GENERATED_AT とする(= 前回サマリの作成日 = 前回対象期間の最終日。起点日ではなく最終日を使う)。あわせて末尾フッタ generated_at_full の時刻を HHMM(4 桁・24h) として抽出し PREV_GENERATED_TIME とする
• 存在しない: PREV_GENERATED_AT は空(手順 10 の旧版アーカイブをスキップ)
• ARCHIVE_NAME の決定(アーカイブフォルダ名。手順 10 の退避先と手順 6 の {{PREV_GENERATED_AT}} の双方で使う):
  • 既定は ARCHIVE_NAME = <PREV_GENERATED_AT>
  • ただし ${ARCHIVES_DIR}<PREV_GENERATED_AT>/ が 既に存在する 場合(= 同一作成日のサマリが既にアーカイブ済み = 同日に複数回生成)は、そのまま退避すると既存アーカイブを上書き消失させるため、ARCHIVE_NAME = <PREV_GENERATED_AT>_<PREV_GENERATED_TIME>(例: 2026-06-02_1125) とする

--from 指定時に既存ファイルが存在しても、その既存ファイルは手順 10 で ${ARCHIVES_DIR}<ARCHIVE_NAME>/ へ通常通り退避される。--from は 新たな BASE_COMMIT を明示する だけで、既存サマリの扱いは変えない。

2. HEAD_COMMIT 取得と差分検出

Bash で実行:

git rev-parse HEAD

結果を HEAD_COMMIT とする。

Bash で実行:

git diff <BASE_COMMIT> <HEAD_COMMIT> -- <INPUT_BASE>

出力が空なら標準出力に 差分なし、処理停止 を出して終了 (exit 0)。 非空ならその内容を DIFF_CONTENT とする。

3. 入力ドキュメント読み込み

Read tool で以下を読む:

• $INPUT_LLMS_TXT (URL リスト・1 行説明)
• $INPUT_LLMS_FULL (全文展開) — 大ファイルなので、Grep tool で必要セクションだけ抽出する形でもよい
• $INPUT_DOCS_MAP (ページ見出しマップ) — docs_map=あり のサイトのみ。docs_map=なし のサイトでは読まない

4. ページ分類

DIFF_CONTENT を解析し、各変更ページを以下のいずれかに分類:

新着情報 (whats-new/...) はリリースノート的性質を持ち、リファレンス・ガイドの新規ページとはインパクトが異なるため、別カテゴリとして扱う。新着情報カテゴリ=なし のサイト(例: mcp)では whats-new/ 相当のページが存在しないため、{{WHATS_NEW_*}} placeholder と ## 新着情報 セクションを持たないテンプレートを使う。

5. 詳細版テンプレート読み込み

Read tool で $TEMPLATE を読み込む。

6. 詳細版生成 (英語)

テンプレートの各 placeholder を以下で埋める。出力先は一時的に変数として保持 (まだファイル書き出しはしない):

URL 併記ルール(サイト依存):

• URL言語併記=あり のサイト: en URL の /docs/en/ を /docs/ja/ に機械的置換して ja URL とし、ja/en を併記する
• URL言語併記=なし のサイト(例: mcp): 言語サブパスが無いため 単一 URL を使う(.md 除去のみ)。bullet・末尾リンクの ([日本語](url-ja) / [English](url-en)) 形式は使わず、単一リンクにする。{{WHATS_NEW_*}} placeholder はテンプレートに存在しないためスキップする

{{OVERALL_SUMMARY_BULLETS}} の選定ルール

• ハイライトと同集合: 概要は {{HIGHLIGHT_BULLETS}} で取り上げた項目のみを、同じ順序で 1 行要約する。追加候補は入れない(軽微更新・新着情報の "Other wins" 等は概要に出さず、各カテゴリのセクション本文で扱う)
• 件数: 必ずハイライトと同数(概要件数 == ハイライト件数)。これにより「概要件数 ≤ ハイライト件数」を保証する(読み手が概要とハイライトの件数差を不審に思うのを防ぐ)。derive_light.py も概要件数 > ハイライト件数 を検出するとエラー終了する
• 新着情報のみの差分で主要機能が乏しい場合: 新着情報ページ本文の "主要機能" からハイライトを構成し、概要もそのハイライトと同集合にする
• 形式: 各行を > 1. <項目> 〜 > N. <項目> の番号付き箇条書きで blockquote 内に記述。番号・順序はハイライト(1.〜N.)と一致させる

bullet フォーマット(厳守)

ライト版抽出スクリプト derive_light.py が、(#anchor) 形式の内部リンクを (./latest-detail.md#anchor) の外部リンクに自動変換する。詳細版時点では bullet 内見出しを内部リンクで書く。

ハイライトのみ番号付き箇条書き(1. 始まり、対応する h2 番号と一致させる)。他カテゴリは - の通常箇条書き。

<anchor> は対応する ## <番号と本体> 見出しから GFM 規則(小文字化・スペース→ハイフン・非英数字非ハイフン除去、Unicode 保持)で生成。h2 が番号付き(## 1. <title>)の場合、anchor も番号を含む(例: #1-claude-opus-48-リリース)。

h2 見出しの番号付け規約

固定 category 見出し(以下)は番号なし:

• ## ハイライト
• ## 新規追加されたページ
• ## 大幅に更新されたページ
• ## 軽微な更新
• ## 新着情報
• ## 関連リンク

それ以外の個別テーマ h2 は ## N. <タイトル> 形式で番号付け:

日付表記の規約

• 共通: ファイル内に登場する全ての年月日表現は 日本語表記(例: 2026年05月18日)
• 週間ダイジェスト(whats-new/2026-wXX): 2026年MM月DD日～EE日(Week N)(Week N は英語のまま、対応する日本語表現がないため例外)

各テーマセクションの末尾フォーマット({{HIGHLIGHT_DETAILS}} / {{NEW_PAGES_DETAILS}} / {{UPDATED_PAGES_DETAILS}} / {{WHATS_NEW_DETAILS}})

各 ## N. <タイトル> セクションの本文の最後に、以下の形式でページリンクを記載(「参考リンク:」の見出しは付けない、リンク行を直接置く):

- [<日本語タイトル> - Claude Code Docs (日本語)](https://code.claude.com/docs/ja/<path>)
- [<English title> - Claude Code Docs (English)](https://code.claude.com/docs/en/<path>)

• リンク先タイトルは $INPUT_LLMS_TXT の各エントリ [<Title>](<URL>): <Description> から取得した <Title> を使う。日本語タイトルは LLM が <Title> を翻訳する
• 両 URL とも .md 拡張子を付けない(.md 付き URL は raw ファイルが表示されるため、人間向けには拡張子なし URL が正しい)。$INPUT_LLMS_TXT の URL は .md 付きなので、.md を除去した上で記載する
• ja URL は en URL の /docs/en/ を /docs/ja/ に機械的置換し、かつ .md 拡張子を除去したもの

ハイライトテーマ(機能単位)では、その機能を主に解説しているページの URL を 1〜2 ページ分記載。

新着情報ページ独自情報の検出(セルフレビュー観点)

/whats-new/<page>.md の本文と、$INPUT_LLMS_FULL 内の対応ページ展開を比較し、新着情報ページにしか記載されていない内容があれば {{WHATS_NEW_DETAILS}} の該当セクションに反映する。両者に差がなければ通常通り要約する。

7. Phase 1 セルフレビュー (英語段階)

以下を順次確認し、NG があれば該当箇所を Edit tool で修正する。新規 NG が出なくなるまで反復:

• リンク実在性: 末尾参考リンクの全 URL の .md 除去前形(en パスに対応する .md 付き URL)が $INPUT_LLMS_TXT 内に実在する
• URL 拡張子: 末尾参考リンクの ja URL / en URL いずれにも .md が付いていない
• 本文整合性: ハイライト・大幅更新の記述が $INPUT_LLMS_FULL の対応ページ本文と矛盾しない
• 網羅性: DIFF_CONTENT で検出された全ページが新規 / 大幅更新 / 軽微更新 / 新着情報のいずれかに分類されている
• カテゴリ整合性: whats-new/ ページは全て新着情報カテゴリに分類されている
• 構成・展開: 概要 → 詳細の順、1 セクションが極端に短い・長いがない、用語が一貫
• h2 番号整合性: ハイライト / 新規追加 / 大幅更新 配下の個別テーマ h2 に ## N. <title> 形式で番号が付与されている。新着情報配下と固定 category 見出しには番号がない
• ハイライト bullet 番号整合性: {{HIGHLIGHT_BULLETS}} が N. 始まりの番号付き箇条書きになっていて、対応する ## N. 見出しと番号が一致
• 概要・ハイライト件数整合性: {{OVERALL_SUMMARY_BULLETS}} の項目数が {{HIGHLIGHT_BULLETS}} と一致し、各項目がハイライトの同順の項目に対応している(概要件数 ≤ ハイライト件数 の保証。超過していると derive_light.py がエラー終了する)
• 内部リンク整合性: bullet 内の (#anchor) が対応する ## N. <タイトル> の GFM アンカー(番号含む)と一致する
• 末尾参考リンクのテキスト: [<タイトル> - Claude Code Docs (日本語 or English)] 形式で空タイトルなし
• 新着情報ページ独自情報: whats-new/ ページに $INPUT_LLMS_FULL の同セクションには無い内容がある場合、それも反映済み
• メタデータ整合性: frontmatter の 対象期間 / 作成日 と末尾フッタの base_commit / head_commit / generated_at_full が正しい値
• 日付表記: 全ての年月日が日本語表記(YYYY年MM月DD日、ただし Week N は例外で英語のまま)

8. 日本語化

英語版の本文 (frontmatter と末尾フッタ HTML コメント以外) を日本語に翻訳する。Edit tool で各セクションを翻訳。

9. Phase 2 セルフレビュー (日本語化後)

• 自然な日本語: 直訳的・不自然な表現がない (必要に応じて $INPUT_LLMS_FULL を再参照して再翻訳可)
• 誤訳: 英語サマリと日本語訳の意味が一致
• 誤字・脱字: 文字レベルの誤りなし

新規 NG が出なくなるまで反復。

10. 旧版アーカイブ (前回サマリが存在する場合のみ)

ARCHIVE_NAME は手順 1 で決定済み(通常は <PREV_GENERATED_AT>、同日衝突時は <PREV_GENERATED_AT>_<PREV_GENERATED_TIME>)。Bash で実行:

mkdir -p ${ARCHIVES_DIR}<ARCHIVE_NAME>/
mv ${LATEST_LIGHT} ${ARCHIVES_DIR}<ARCHIVE_NAME>/latest.md
mv ${LATEST_DETAIL} ${ARCHIVES_DIR}<ARCHIVE_NAME>/latest-detail.md

手順 6 の {{PREV_GENERATED_AT}} placeholder(関連リンクのパス)にも同じ <ARCHIVE_NAME> を使い、アーカイブ実体とリンク先を一致させる。

11. 詳細版書き出し

Write tool で手順 6〜9 の最終結果を $LATEST_DETAIL に書き出す。手順 10 の旧版アーカイブを必ず先に済ませること（先に $LATEST_DETAIL を上書きすると旧版が失われ、アーカイブのため git show HEAD: からの復元が必要になる）。

12. ライト版生成

Bash で実行:

python ${DERIVE_SCRIPT} ${LATEST_DETAIL}

スクリプトは $LATEST_DETAIL を読み、$LATEST_LIGHT を生成する。 終了コードが非ゼロならエラー内容を標準エラーに出力して終了。

13. Phase 3 第三者レビュー (doc-summary-reviewer)

執筆 Agent 自身では気づけない確信的誤り(ハルシネーション)とフォーマット規約違反を、別 Agent で多層検出する。

実行要否の判定

AUTOMATED は冒頭「引数パース」で決定済み（--automated 引数があれば 1、無ければ 0）。ツール実行は不要。

• AUTOMATED が 1 (無人・ヘッドレス/パイプライン実行): 本 Phase は必須。スキップ不可
• AUTOMATED が 0 (手動・対話実行): 本 Phase は任意。ユーザーから明示指示がある場合のみ実行し、無ければ手順 14 へ進む

理由: ハルシネーションは執筆者が確信的に書くため Phase 1/2 セルフレビューでは捕捉できない。人が成果物を見ない無人実行時のみ機械レビューを必須化する。

レビューループ (最大 3 回)

カウンタ N=1 から開始し、以下を反復:

1. Agent tool で doc-summary-reviewer (subagent_type) を起動。プロンプトに以下を渡す:
   • SITE / INPUT_BASE / BASE_COMMIT / HEAD_COMMIT / LATEST_DETAIL / LATEST_LIGHT
   • URL_LANG: URL言語併記=あり のサイトは あり、なし のサイトは なし
2. reviewer 出力から 判定: で始まる行を探し、判定: PASS または 判定: FAIL を解釈する（reviewer は 1 行目に置く規約）
3. 判定: PASS の場合: ループを抜けて手順 14 へ
4. 判定: FAIL の場合:
   • 各 [CRITICAL] / [IMPORTANT] 指摘の修正案を Edit tool で $LATEST_DETAIL に反映する ([SUGGESTION] は任意反映)
   • Bash で python ${DERIVE_SCRIPT} ${LATEST_DETAIL} を再実行し $LATEST_LIGHT を再生成する
   • N を +1 してループ先頭へ戻る
5. N が 3 を超えても 判定: FAIL の場合 (打ち切り):
   • AUTOMATED が 1: 残存指摘を標準エラーに出力する。さらに、レビュー FAIL の生成物が commit・push されるのを決定論的に防ぐため、Bash で当該サイトの生成物を HEAD 状態へ戻す:

     git checkout -- ${SUMMARY_DIR}
     git clean -fd ${SUMMARY_DIR}
     

     これで ${SUMMARY_DIR} の追跡ファイルは HEAD に戻り、手順 10 で退避した未追跡コピーも除去されるため、ラッパーの add 対象に差分が残らず push されない (claude -p の終了コード挙動に依存せず push を抑止できる)。
   • AUTOMATED が 1 以外: 残存指摘をユーザーに提示し判断を仰ぐ (手順 14 の完了報告は行わない。生成物は破棄せず人手判断に委ねる)

14. 完了報告

以下の情報を含む完了メッセージを出力:

• 生成パス: $LATEST_LIGHT / $LATEST_DETAIL
• 旧版アーカイブ先 (該当する場合): ${ARCHIVES_DIR}<ARCHIVE_NAME>/
• 統計: ハイライト件数 / 新規追加件数 / 大幅更新件数 / 軽微更新件数 / 新着情報件数
• 期間: <BASE_COMMIT short> .. <HEAD_COMMIT short> (各 7 桁)
• Phase 3 結果: 実行した場合は 判定: PASS (N 回目で合格) / スキップした場合は Phase 3: スキップ (手動実行)