From 5b0f36b59fb01c6b82708d4c438cec2521bf4c77 Mon Sep 17 00:00:00 2001 From: ootakazuhiko Date: Mon, 25 May 2026 07:15:07 +0900 Subject: [PATCH] docs: add external reference audit playbook --- docs/appendices/appendix-b/index.md | 36 +++++++++++++++++++++++++++++ docs/appendices/appendix-c/index.md | 5 ++++ src/appendices/appendix-b/index.md | 36 +++++++++++++++++++++++++++++ src/appendices/appendix-c/index.md | 5 ++++ 4 files changed, 82 insertions(+) diff --git a/docs/appendices/appendix-b/index.md b/docs/appendices/appendix-b/index.md index 3c26096..e9c15bf 100644 --- a/docs/appendices/appendix-b/index.md +++ b/docs/appendices/appendix-b/index.md @@ -121,6 +121,42 @@ rollout review など、商用運用で繰り返す作業の標準手順を整 - 公式仕様と本文の用語が一致しないが、どちらが現行か分からない - 旧章との整合が崩れ、読者の導線が壊れる +## 外部リンク棚卸し / 公式情報鮮度確認 + +GitHub AgentOps では、Copilot、GitHub Actions、MCP、OpenAI Codex などの公式情報が短期間で変わります。 +リンク切れの有無だけでなく、本文が参照している plan、preview 状態、quota、課金、権限、API 名称が +現在の公式情報と矛盾していないかを確認します。 + +推奨手順： + +1. 対象範囲を決める + - 全文棚卸し、特定章、リリース前確認、四半期レビューのどれかを Issue に明記する + - 料金、preview、quota、Actions minutes、security boundary など、変化しやすい項目を優先する +2. 外部リンク検査を実行する + - 基本コマンドは `npm run check-external-links` + - DNS や社内 proxy の制限で到達できない host は、恒久対応ではなく一時的な検査除外として記録する +3. 一次情報と本文の対応を確認する + - GitHub Docs、OpenAI Developers、公式 repository など、一次情報を優先する + - blog、community 記事、個人記事を根拠にする場合は、本文の主根拠にしない +4. source と生成物を同期する + - 原稿は `src/` を編集し、`npm run build` で `docs/` を更新する + - top page や README の導線を変更した場合は、公開 smoke の確認対象に含める +5. PR evidence を残す + - 実行日、検査コマンド、確認した代表リンク、未対応リンク、再確認が必要な項目を PR 本文に記録する + +停止条件： + +- 公式情報の現行名称や提供状態が確認できない +- 料金、quota、preview 状態など、誤ると読者の意思決定に影響する情報の根拠が取れない +- 一時的なネットワーク障害と恒久的なリンク切れを切り分けられない + +完了 evidence： + +- `npm run check-external-links` の結果 +- 参照元章と代表リンクの確認日 +- `npm test` と公開 Pages smoke の結果 +- 次回棚卸しで再確認すべき変化しやすい項目 + ## 安全なリファクタ - 関連 Skill: `skills/refactor-safe/SKILL.md` diff --git a/docs/appendices/appendix-c/index.md b/docs/appendices/appendix-c/index.md index d2315c3..a2eb9b2 100644 --- a/docs/appendices/appendix-c/index.md +++ b/docs/appendices/appendix-c/index.md @@ -252,15 +252,20 @@ permissions: - link-check / build が落ち、公開が止まる - source を直さず生成 docs だけ編集し、次 build で差分が消える - Companion のパス移動で本文の固定パスが壊れる +- 公式 Docs の URL は到達するが、本文の plan、preview 状態、quota、課金、権限名が古くなっている ### 対処（最小） - ローカルで品質ゲートを実行し、再現手順を PR に残す - source と generated docs の責任を分け、生成物は build で更新する - Companion の移動・改名は移行期間を設け、旧パスから案内する +- `npm run check-external-links` で外部リンクの HTTP 到達性を確認する +- 料金、preview、quota、API 名称、権限名は到達性とは別に一次情報で鮮度を確認する +- 一時的な DNS / proxy 制約で除外した host は、PR evidence に除外理由と再確認期限を残す - 公開後は代表ページを smoke test し、主要 marker が表示されることを確認する 再発防止：docs PR では `npm test`、公開 site smoke、固定パス確認を PR template に含めます。 +外部仕様に依存する章では、公式情報の確認日と次回棚卸し対象を PR 本文に記録します。 ## 最終確認チェックリスト diff --git a/src/appendices/appendix-b/index.md b/src/appendices/appendix-b/index.md index 2d97442..ace90ff 100644 --- a/src/appendices/appendix-b/index.md +++ b/src/appendices/appendix-b/index.md @@ -116,6 +116,42 @@ rollout review など、商用運用で繰り返す作業の標準手順を整 - 公式仕様と本文の用語が一致しないが、どちらが現行か分からない - 旧章との整合が崩れ、読者の導線が壊れる +## 外部リンク棚卸し / 公式情報鮮度確認 + +GitHub AgentOps では、Copilot、GitHub Actions、MCP、OpenAI Codex などの公式情報が短期間で変わります。 +リンク切れの有無だけでなく、本文が参照している plan、preview 状態、quota、課金、権限、API 名称が +現在の公式情報と矛盾していないかを確認します。 + +推奨手順： + +1. 対象範囲を決める + - 全文棚卸し、特定章、リリース前確認、四半期レビューのどれかを Issue に明記する + - 料金、preview、quota、Actions minutes、security boundary など、変化しやすい項目を優先する +2. 外部リンク検査を実行する + - 基本コマンドは `npm run check-external-links` + - DNS や社内 proxy の制限で到達できない host は、恒久対応ではなく一時的な検査除外として記録する +3. 一次情報と本文の対応を確認する + - GitHub Docs、OpenAI Developers、公式 repository など、一次情報を優先する + - blog、community 記事、個人記事を根拠にする場合は、本文の主根拠にしない +4. source と生成物を同期する + - 原稿は `src/` を編集し、`npm run build` で `docs/` を更新する + - top page や README の導線を変更した場合は、公開 smoke の確認対象に含める +5. PR evidence を残す + - 実行日、検査コマンド、確認した代表リンク、未対応リンク、再確認が必要な項目を PR 本文に記録する + +停止条件： + +- 公式情報の現行名称や提供状態が確認できない +- 料金、quota、preview 状態など、誤ると読者の意思決定に影響する情報の根拠が取れない +- 一時的なネットワーク障害と恒久的なリンク切れを切り分けられない + +完了 evidence： + +- `npm run check-external-links` の結果 +- 参照元章と代表リンクの確認日 +- `npm test` と公開 Pages smoke の結果 +- 次回棚卸しで再確認すべき変化しやすい項目 + ## 安全なリファクタ - 関連 Skill: `skills/refactor-safe/SKILL.md` diff --git a/src/appendices/appendix-c/index.md b/src/appendices/appendix-c/index.md index d210ac5..56272d4 100644 --- a/src/appendices/appendix-c/index.md +++ b/src/appendices/appendix-c/index.md @@ -247,15 +247,20 @@ permissions: - link-check / build が落ち、公開が止まる - source を直さず生成 docs だけ編集し、次 build で差分が消える - Companion のパス移動で本文の固定パスが壊れる +- 公式 Docs の URL は到達するが、本文の plan、preview 状態、quota、課金、権限名が古くなっている ### 対処（最小） - ローカルで品質ゲートを実行し、再現手順を PR に残す - source と generated docs の責任を分け、生成物は build で更新する - Companion の移動・改名は移行期間を設け、旧パスから案内する +- `npm run check-external-links` で外部リンクの HTTP 到達性を確認する +- 料金、preview、quota、API 名称、権限名は到達性とは別に一次情報で鮮度を確認する +- 一時的な DNS / proxy 制約で除外した host は、PR evidence に除外理由と再確認期限を残す - 公開後は代表ページを smoke test し、主要 marker が表示されることを確認する 再発防止：docs PR では `npm test`、公開 site smoke、固定パス確認を PR template に含めます。 +外部仕様に依存する章では、公式情報の確認日と次回棚卸し対象を PR 本文に記録します。 ## 最終確認チェックリスト