資料の扱いと確認範囲
資料の確認規約
1. introduction/index.md から目的に合う資料を選ぶ。機械的な探索が必要な場合だけ、introduction/manifest.json の routes を補助的に使う。
2. 選んだ introduction 資料は、公開可能な事実と設計意図をあらかじめ整理した説明の基盤として用いる。そこに示された要点、想定問答、制約を使って説明を組み立てる。
3. 実装保証、安全性の網羅性、性能、特定配布物の内容など、強い客観的主張が必要な場合は、示されたソース、設定、テスト、検査結果または配布物を追加確認する。
4. 回答では 確認済み事実、方針、既知の制約、推論、未確認 を区別する。資料が不足するときは推測で埋めない。
5. コード変更では、対象ファイル、呼び出し元、関連テストを確認してから変更する。存在を確認していないパス、クラス、関数を前提にしない。
文書構造の役割
| 層 | 役割 | 読み方 |
|---|---|---|
introduction/index.md | 背景・設計・確認資料の入口 | 目的に合う資料を選ぶ |
introduction/manifest.json | 機械的な参照を補助する経路表 | 通常の読者は index のリンクを使う |
introduction/project_context.xml | 重要制約と確認観点を整理した構造化補助情報 | 必要な場合だけ参照し、強い主張には示された根拠を追加確認する |
introduction/core/*.md | 背景、設計、利用判断、技術参照の補足資料 | 目的に合う資料を読み、必要な場合だけ根拠へたどる |
docs/ja/・docs/en/、ソース、テスト、設定 | 一次資料 | 客観的な結論の根拠にする |
introduction は、読者が毎回ゼロから解釈しなくてよいように整理した資料群である。公開可能な範囲で、プロジェクトが伝えたい文脈、質問の切り分け、説明時に隠してはいけない制約を先に整理する。ただし、この層は利用者の質問や確認を置き換えず、未確認の実装保証を作り出さない。
この層は、人もAIも解釈しやすいよう、見出し、表、JSON、XML、YAMLなどの構造を使う。一般的な利用者向け操作手順は docs/ja/ と docs/en/ を正本とする。
文字コード・構造化・画像の規約
- 公開するテキストは UTF-8（BOM の有無は可）で保存し、置換文字
U+FFFDを含めない。JSON と XML は構文として妥当でなければならない。 - 本文は、短い見出し、表、JSON/XML/YAML のような追いやすい構造を用いる。ただし構造化表現は内容の正確性を保証しない。
- コード索引に書くパスはリポジトリに実在し、シンボル名はそのパスで確認したものだけにする。古くなった索引は削除または「未検証」と明示する。
- 画像は人間向け説明を補助する場合にだけ用い、代替テキストを付ける。AIの根拠は画像だけに置かず、本文または一次資料で同じ事実を示す。
公開前の必須確認
GitHub Pagesの文書ポータルは次の順で生成・検査する。site/github/output/public/ はローカルおよびCIで生成する公開成果物であり、Gitでは追跡せず、手で編集しない。Cloudflareの紹介ページは公開文書を複製せず、紹介ページ用に選別した静的ファイルだけを公開する。
python site/github/scripts/build_public_site.py --replace --documentation-portal
python site/github/scripts/validate_public_site.py --site site/github/output/public検査は、公開対象の限定、UTF-8復号、JSON/XML構文、ローカルのMarkdown/HTMLリンク・画像参照、manifestの経路、開発者専用資料の除外を確認する。意味内容や実装との一致は、変更者が一次資料を確認して判断する。サイトの更新は release や publish.ps1 -Mode Submit から切り離された手動作業であり、必要なときに上記の生成・検査を明示実行する。