AIのスキル文書を1か所で管理し、AIが探しやすい形で書く

## もとのスキル文書だけを直し、ほかは生成ツールで作り直す スキル文書の正本を特定し、生成された連携物、マニフェスト、プラットフォーム別の展開物は派生物として扱う。正本とその参照を編集してから、リポジトリの生成ツールで派生物を再生成する。 CI管理下の生成物を手作業で編集してはならない。メモリ内または一時領域で再生成し、コミット済みの派生物が正本からずれていれば失敗するチェックモードを継続的インテグレーションに用意する。 同じスキルを複数のプラットフォームへ配布する場合は、分岐した別版を保守せず、内容を共有する。内容、メタデータ、バージョン値をどのファイルが管理するか記録し、貢献者が競合する正本を作らないようにする。 インストール方法とエンドユーザー向けの使い方は、貢献者向け指示の外に置く。貢献者向け文書では、製品ガイドを重複させず、保守、検証、テスト、リリースの動作を説明する。 ## 選ぶための情報は入口の文書に、詳しい手順は参照ファイルに置く メインのスキル文書を検索の入口とし、詳細な参照資料は必要な時だけ読み込む。情報は次の場所に配置する。 - 判断フレームワークと使用頻度の高いパターンは入口文書に置く。 - 詳細ガイド、テンプレート、拡張例は参照ファイルに置く。 - 基準シナリオと判断理由の記録はテスト文書に置く。 - インストール方法と使い方はユーザー向け文書に置く。 - 貢献者向けの工程詳細は貢献ガイドに置く。 入口文書と隣接する参照資料は、安定した相対リンクで接続する。下位のサブセクションを再構成する場合も、ルーティング表が使用する最上位の参照アンカーは維持する。 配置判断には1つの基準を使う。どの経路を選ぶか決める項目は入口の近くに残し、選択済みの経路を深く実行する方法を説明する項目は参照資料へ移す。 ## 判断表を先に置き、短く言い切る指示で書く ガイドを最初から最後まで読む人ではなく、意図を分類し、分岐を選び、実行するエージェントに合わせて最適化する。 複数の方法が有効な場合は、手順書より前にコンパクトな判断表を置く。各セクションは次の順序にする。 1. 判断表 2. 既定の手順 3. 代替案 4. 簡潔な規則と注意点 命令形を使い、箇条書き1項目につき1つの事実だけを書く。「検討するとよい」「注意する」「心に留める」などの助言用の前置きは、直接的な行動へ変える。分かりにくい区別には、短い肯定規則と否定規則を優先する。 すべての表、例、コードブロックは、既述ではない事実を追加しなければならない。手順だけで指示が伝わる場合は、変更前後の差分、重複する理由説明、教材的な余談、網羅性だけを目的とする例を省く。 理由説明は冒頭の1文以内にする。サブセクションごとにトークン量の目標を設定し、超過したセクションは、判断基準、必須の行動、制約、例外を省かずに分割または圧縮する。 ## 変更の後に、文書の形を自動で確かめ、AIの動きを試す 成果物に応じた検証を行う。文書中心のスキルではコンパイルが不要な場合もあるが、自動の構造検査と手動の動作テストは必要になる。 必須のfrontmatter項目、命名規則、行数またはトークン量の上限、内部リンク、生成物の同期、リポジトリ固有のlint規則を自動検査する。緩やかなサイズ目標は警告として扱い、厳格な完全性制約は失敗として扱う。 内容を変更する場合は、次の順序で進める。 1. 正本のスキルまたは参照資料を編集する。 2. ローカルで構造検証を実行する。 3. ホスト環境でスキルを再読み込みする。 4. 変更した分岐を通る現実的なユーザー問い合わせを実行する。 5. 基準シナリオと動作を比較し、回帰がないか確認する。 プルリクエストには、影響を受けるシナリオの変更前後の証拠を必須とする。情報アーキテクチャを実質的に変更する場合は、検索時の構造、圧縮、欠けている判断分岐に焦点を当てた独立レビューを受ける。 ## プルリクエストのチェックを必須にし、バージョン番号は自動リリースで付ける メインブランチを保護し、プルリクエスト、検証チェック、有効なConventional Commits形式のタイトルを必須とする。変更をsquash mergeし、プルリクエストのタイトルがリリースコミットになる場合は、そのタイトルがバージョン決定に使われるため、タイトルも検証する。 Conventional Commitsの変更種別をバージョン更新へ対応付け、メジャー変更を示す明示的な信号も用意する。リリースワークフローは、変更履歴、正本のバージョンメタデータ、プラットフォームのマニフェスト、生成物を1回のリリース変更で更新する。 同期対象のバージョン番号を手作業で編集してはならない。バージョンの正本を1つだけ設け、タグを作成する前にリリースパイプラインから各所へ反映する。 マージ前に次を確認する。 - 生成物が正本と一致している。 - 分岐を含む手順書より前に判断表がある。 - 重複する前置きと例が省かれている。 - ルーティング対象のアンカーが安定している。 - 変更した基準シナリオに証拠がある。 - 必須の検証とタイトルチェックが通っている。