documentation-governance

ドキュメントガバナンス

ミッション

プロジェクトとともに進化できる、発見しやすく、レビュー可能で、検証可能なドキュメントシステムを維持します。Markdown と Git をデフォルトのソース形式および履歴管理の仕組みとし、VitePress は表示レイヤーとして位置付けます。それ自体を唯一の正式な保存先にはしません。

確認済みのデフォルトポリシー

• ガバナンスの範囲：一貫性のある標準を確立し、妥当な理由があればディレクトリの再構成を認めます。
• サイトの提供：ローカルプレビューとオフライン／静的な成果物を提供します。
• コードとの同期：差分を検出し、更新を提案して、結果を検証します。意味上の変更にはレビューが必要です。
• ファイルの変更：大規模な変更や破壊的な変更の前に確認を得ます。
• 自動化：依頼に応じて手動で実行します。別途依頼がない限り、Git フック、CI/CD、スケジュールされたジョブ、クラウド公開、外部サービスは追加しません。
• リポジトリに標準で備わっているツールと依存関係を優先します。必要性を説明し、重要な変更について許可を得ずに、パッケージをインストールしたり、パッケージマニフェストを変更したりしません。

中核となる不変条件

1. 編集前に調査します。利用可能な場合は、リポジトリのルート、既存のドキュメント、プロジェクトの指示、パッケージスクリプト、VitePress の設定、Git の作業ツリーの状態を確認します。
2. 情報の種類ごとに権威の所在を明確にします。実行時のコードは現在の動作を示す根拠ですが、意図された製品の動作を自動的に規定するものではありません。要件と実装に矛盾がある場合は、独断で判断せず報告します。
3. 大規模な移行の前に計画します。現在のパス → 提案するパス、理由、影響を受ける参照、リスク、ロールバック方法を提示します。ファイルの削除、上書き、大量移動、多数のファイル名変更、既存のサイト設定の置き換えを行う前に承認を求めます。
4. ユーザーの作業を保護します。無関係な変更を上書きしません。作業ツリーに変更がある場合は、既存の変更とこのタスクで加えた変更を区別します。変更のリセット、クリーンアップ、破棄は行いません。
5. 最小限でレビューしやすい編集を行います。対象を絞った修正で済む場合、広範な書き換えは避けます。有用な履歴とコンテンツを保持します。
6. 事実と推論を分けます。不確かな主張には needs-review と記すか、監査レポートに記載します。
7. 変更後に検証します。影響を受けるリンク／アセット、メタデータ、ナビゲーション、および利用可能であればサイトのビルドを確認します。実行しなかったチェックとその理由を報告します。
8. 公開を黙って行いません。build は publish ではありません。オフライン用のパッケージ作成はデプロイではありません。明示的な許可がない限り、アップロードや公開は行いません。
9. VitePress がなくても、このスキルを有用に保ちます。棚卸し、マッピング、差分分析、基本的な検証は、VitePress に依存せず実行できるようにします。

タスクの振り分け

依頼を満たす最小範囲のワークフローを選びます。実行前に、workflows/ 内の対応するファイルを読みます。

• 初回導入または標準的なセットアップ → workflows/onboarding.md
• 既存の内容を把握する → workflows/inventory.md
• ファイルを再構成または移行する → workflows/migration.md
• コード／仕様／ドキュメントを比較する、または変更を同期する → workflows/code-sync.md
• VitePress をセットアップ、プレビュー、ビルド、またはパッケージ化する → workflows/site-delivery.md
• 品質レビューまたは定期監査 → workflows/audit.md
• ユーザーがレポートのみを求めている場合 → 依頼がない限りファイルを変更しません。

実行プロトコル

A. コンテキストを確認する

• リポジトリのルートとプロジェクトの種類を特定します。
• 適用されるプロジェクトのガイダンス（例：AGENTS.md、CONTRIBUTING.md、既存のドキュメント規約）を読みます。
• 関連ファイルとパッケージスクリプトを調べます。ツールがインストール済みだと決めつけません。
• 既存の VitePress 設定とドキュメントソースのディレクトリを確認します。
• Git が利用可能であれば、Git の状態を確認します。見た目がクリーンなディレクトリを、未追跡ファイルがない証拠とみなしません。

B. 要求されたアクションを分類する

• 読み取り専用： インベントリ作成、レポート作成、リンクスキャン、ドリフト分析。
• 低リスクで元に戻せる変更： 不足しているインデックスの追加、明らかに壊れているローカルリンクの修正、合意した場所への新しいレポートファイルの作成。
• 大規模な変更： 一括移動・名前変更、ドキュメントの削除または置き換え、権限ルールの変更、ナビゲーションの再構成、サイト設定の置き換え、依存関係のインストール、パッケージスクリプトの変更、大量の派生コンテンツの生成、アセットを除外または書き換えるパッケージ化。

読み取り専用の作業を進めてください。依頼で修正が明確に求められている場合は、低リスクの編集を行ってもかまいません。大規模な変更は事前に確認し、簡潔な計画を提示してください。

C. 適用して検証する

• 選択したワークフローと参照資料に従ってください。
• 重要なパスの変更を移行マップに記録してください。
• 関連するチェックだけを実行し、機械的なチェックには決定論的なスクリプトを優先してください。
• チェックを実行できない場合は、成功したかのように示さず、その制約を明記してください。
• 変更したファイル、実行したチェックとその結果、未解決の判断事項、次のアクションを要約してください。

ドキュメントモデル

明確さを保てる最小限の概念を使用してください。

• 正規ソース： 特定の主張や成果物に関する信頼できる情報源。
• 派生コンテンツ： 正規ソースから生成されたコンテンツ。生成元と再生成方法を明記してください。
• 補足説明： 人が保守する説明、根拠、例、チュートリアル。
• ステータス： draft、active、needs-review、deprecated、archived。
• オーナー： 判明している場合は、役割、チーム、担当者を記載してください。オーナーを作り上げてはいけません。
• レビューの契機： レビューのきっかけとなるコードパス、スキーマ、機能、バージョン、イベント。

すべての既存ドキュメントに、直ちにフロントマターを必須としないでください。まず新規または積極的に保守されているドキュメントに導入し、その後、既存ドキュメントを段階的に移行してください。

プロジェクト設定

必要に応じて、templates/docs-governance.example.yml を基に .governance/docs.yml を作成してください。これはプロジェクト固有の設定として扱い、必須のグローバルスキーマとはしないでください。生成されたインベントリやレポートは正規ドキュメントと分けて保管し、明示的なルールがない限り、生成物を信頼できる情報源として扱わないでください。

ツールのルール

• スクリプトはデフォルトで安全に動作し、可能な限り標準ライブラリを使用し、ヘルプを提供し、検証失敗時にはゼロ以外の終了コードを返し、名前とドキュメントで明示されていない限りソースファイルを変更しないでください。
• インベントリと監査の出力先は、ユーザーが承認したレポートの保存場所にしてください。デフォルトの候補として artifacts/documentation-governance/ を提案するのは、プロジェクトの規約と競合しないことを確認した後に限ります。
• ローカルまたはオフラインのドキュメントではローカルリンクを使用してください。明確に宣言されていない限り、オフラインで提供する成果物にリモートアセットや実行時の取得処理を含めないでください。
• 機能をテストし、その制約を説明していない限り、PDF 出力、単一ファイルへのバンドル、完全な可搬性を実現できると主張しないでください。

完了の定義

タスクは、依頼された成果が提供され、回答で以下を報告した場合にのみ完了です。

1. 変更内容（または読み取り専用であること）。
2. 重要なファイルと判断事項。
3. 実施した検証と実際の結果。
4. 未解決の競合やリスク、および未実施のチェック。
5. 該当する場合は、ローカルでのプレビュー、ビルド、パッケージ化の方法。

パッケージ構成については README.md を、詳細なルールについては references/ を参照してください。