Issue #142 P1: Pages公開導線の整理 + AI利用ポリシー (#145)

* feat: Pages導線とAI利用ポリシーを追加（Issue #142 P1）

* fix: Docs-as-Code章のブランチ切替をswitchに統一

* fix: AI利用ポリシーの表記を初心者向けに調整

Author: ootakazuhiko

AI_USAGE_POLICY.md

@@ -0,0 +1,50 @@
+# AI利用ポリシー（テンプレ）
+
+この文書は、生成AI（例：Copilot、ChatGPT など）を活用して Issue / Pull Request / ドキュメントを作成・更新する際の、最小限の運用ルールです。
+
+## 目的
+
+- AI 支援を使っても、品質と安全性（誤情報・誤設定・機密漏えいの防止）を維持する。
+- 「誰が何を確認したか」を Pull Request に残し、検証責任を曖昧にしない。
+
+## 適用範囲
+
+- このリポジトリへの Issue 作成、Pull Request 作成、ドキュメント更新
+
+## 基本原則
+
+- **最終責任は人間が持つ**：AI の出力は提案であり、正しさは保証されない。
+- **検証可能性を優先する**：再現手順・確認方法・根拠を残す。
+- **最小変更・段階導入**：大きな修正は分割し、レビュー可能な単位にする。
+
+## 禁止事項（Must Not）
+
+- **機密情報・個人情報を入力しない**
+  - 例：トークン、パスワード、秘密鍵、顧客情報、社内限定資料
+- **根拠が確認できない内容を断定しない**
+  - 不明な場合は「要確認」と明示し、確認観点を Issue に残す。
+- **ライセンス不明な文章・画像・コードを持ち込まない**
+  - 参照元と利用条件が確認できない場合は採用しない。
+
+## 推奨運用（Should）
+
+### Pull Request の作成時
+
+- `.github/PULL_REQUEST_TEMPLATE.md` の「AI支援の開示（任意）」を埋める。
+  - AI 支援を使った場合は **「どこに使ったか」** と **「人間が確認した観点」** を明記する。
+
+### AI 生成の典型的な誤り（チェックリスト）
+
+AI 支援を使った変更は、少なくとも次を確認してください。
+
+- [ ] **リンク**：リンク先が存在し、意図したページに到達する
+- [ ] **事実関係**：用語定義・前提・仕様が本文と矛盾しない
+- [ ] **手順/コマンド**：手順が省略されていない（前提条件・注意事項を含む）
+- [ ] **設定値**：パス・ファイル名・キー名が実在し、表記揺れがない
+- [ ] **セキュリティ**：機密情報を含まない／危険な手順が推奨されていない
+- [ ] **読者前提**：初心者がつまずきやすい箇所に補足がある
+
+## 参考
+
+- PRテンプレ：`.github/PULL_REQUEST_TEMPLATE.md`
+- docs品質ゲート：`.github/workflows/docs-quality-gate.yml`

docs/src/chapter-docs-as-code/index.md

@@ -148,7 +148,7 @@ Issue と Pull Request の基本操作は、以下の章も参照してくださ
 
 ```bash
 mkdir -p docs/templates
-git checkout -b docs/add-templates
+git switch -c docs/add-templates
 git add docs/
 git commit -m "docs: add templates"
 git push -u origin docs/add-templates
@@ -158,6 +158,21 @@ git push -u origin docs/add-templates
 
 ---
 
+## 品質ゲートとAI支援（任意）
+
+文書は、リンク切れや表記ゆれが増えると「読めるが信用できない状態」になりやすいです。最低限の自動チェック（品質ゲート）を入れておくと、運用の安定性が上がります。
+
+- docs品質ゲート（例）：`.github/workflows/docs-quality-gate.yml`
+- ローカル実行（例）：`npm run docs:quality-gate`
+
+また、AI 支援を使う場合は、機密情報の取り扱いと検証観点をルール化しておくと、事故を減らせます。
+
+- AI利用ポリシー（テンプレ）：https://github.com/{{ site.repository }}/blob/main/AI_USAGE_POLICY.md
+
+関連する章：
+
+- GitHub Actions：{{ '/src/chapter-github-actions/' | relative_url }}
+
 ## まとめ
 
 - Docs-as-Code は「文書を Pull Request でレビューして保守する」ための運用です。

docs/src/chapter-github-actions/index.md

@@ -403,6 +403,42 @@ jobs:
       uses: actions/deploy-pages@v4
 ```
 
+### Pages公開を「文書運用」の導線にする（運用設計）
+
+GitHub Pages は、静的サイトを公開する機能です。文書運用（Docs-as-Code）と組み合わせると、次の導線が作れます。
+
+- Issue で「何を変えるか」を決める
+- Pull Request で文書を改訂し、レビューで合意する
+- マージをトリガに、Pages へ自動デプロイして「公開版」を更新する
+
+#### 公開範囲のモデル（例）
+
+Pages を使う前に、**何を公開対象にするか**（公開/非公開の境界）を決めてください。
+
+- **public docs**：外部公開してよい利用者向け文書（例：手順書、仕様の公開版）
+- **private docs**：組織/チーム内だけに共有する文書（例：社内向けナレッジ、限定公開の手順）
+- **internal docs**：運用手順・Runbook など、公開運用に載せない文書（例：障害対応、秘密情報を前提にする手順）
+- **mixed**：public と internal が混在する場合は、ディレクトリを分けて「公開対象だけをビルドする」設計にする
+
+※ internal docs には、機密情報（トークン/鍵/社内URLなど）を書かない運用が前提です。必要な場合は、別の保管場所（社内Wikiなど）を検討してください。
+
+#### ディレクトリ構成とビルド出力の注意
+
+Pages は、次の 2 パターンで運用されることが多いです。
+
+- **Deploy from a branch**：`main` ブランチの `/docs` を公開する（最小構成）
+- **GitHub Actions で build → deploy**：ビルド成果物を Pages にアップロードする（柔軟だが設定は増える）
+
+GitHub Actions で build → deploy する場合は、ビルド成果物のパス（例：`./dist`）を指定します。これはプロジェクト構成によって異なります。
+
+- Jekyll の場合：`_site/` が出力先になることが多い（要確認）
+- Node/Vite などの場合：`dist/` が出力先になることが多い（要確認）
+
+このリポジトリの Docs-as-Code 例（推奨構成・テンプレ）は、次の章と `examples/` を参照してください。
+
+- Docs-as-Code：{{ '/src/chapter-docs-as-code/' | relative_url }}
+- 実習サンプル（examples）：{{ '/examples/' | relative_url }}
+
 ### 環境変数とシークレットの管理
 
 **シークレットの設定手順：**

docs/src/chapter-pull-requests/index.md

@@ -224,6 +224,10 @@ Pull Requestの作成からマージまでの一連の流れを理解し、効
 
 ※ AI支援を使う場合は、「AI支援の開示（任意）」を追加しておくと、後から検証責任の所在が曖昧になりにくくなります。
 
+AI 支援の運用ルール（機密入力の禁止、確認観点など）は、次のポリシーを参照してください。
+
+- AI利用ポリシー（テンプレ）：https://github.com/{{ site.repository }}/blob/main/AI_USAGE_POLICY.md
+
 ### CODEOWNERSでレビュー担当を自動で割り当てる（発展）
 
 チームで運用する場合、「誰がレビュー責任を持つか」を仕組みで決めておくと、レビューが詰まりにくくなります。その代表例が **CODEOWNERS** です。

docs/src/chapter-troubleshooting/index.md

@@ -222,6 +222,17 @@ git push --force origin main
 
 ![ネットワーク接続問題]({{ '/assets/images/diagrams/chapter10/03_network_connection_issues.svg' | relative_url }})
 
+**文書公開運用（Docs-as-Code + Pages）でのよくあるミス**
+
+- 公開対象（public docs / internal docs）の境界が曖昧で、意図しない情報まで公開してしまう
+- ビルド出力ディレクトリ（`_site` / `dist` など）がプロジェクト構成と合っていない
+- `baseurl` の設定がリポジトリ名と一致しておらず、リンクが 404 になる
+
+公開運用の考え方は、次の章も参照してください。
+
+- Docs-as-Code：{{ '/src/chapter-docs-as-code/' | relative_url }}
+- GitHub Actions（Pagesデプロイ）：{{ '/src/chapter-github-actions/' | relative_url }}
+
 **404エラーの診断と解決**
 
 **よくある原因と解決方法：**
@@ -232,7 +243,7 @@ git push --force origin main
 1. Repository → Settings → Pages
 2. Source: Deploy from a branch
 3. Branch: main (または gh-pages)
-4. Folder: / (root) または /docs
+4. Folder: /docs（docs/ でサイトを管理する場合）または / (root)
 ```
 
 **2. ファイル構造の確認**