複数のAIツールで使う指示集を、1つの原本から直して増やす

## 直す前に、その動きを受け持つ部分を見つける リポジトリを、まとまりのないファイル群ではなく、所有者が明確なレイヤーの集合として扱います。編集前に、要求された動作をどのレイヤーが担うか特定します。 - ソース指示は、再利用可能なユーザー向け操作を定義します。 - 共有リファレンスは、複数領域にまたがる契約とスキーマを定義します。 - 補助スクリプトは、繰り返し可能な処理を実装します。 - アダプターは、正本の指示をプラットフォーム固有のパッケージへ変換します。 - 生成済み配布物には、再ビルド可能な成果物が含まれます。 - フックは、リポジトリと成果物のルールを適用します。 - アーキテクチャ文書と運用マニュアルは、各レイヤーの連携方法を説明します。 - 依存関係ファイルとインストール用ファイルは、対応する実行環境を定義します。 正本ソースのレイヤーを権威ある基準として扱います。生成済み配布物はビルドが機能する証拠であり、独立した正本ではありません。直接編集せず、文書化されたビルド手順を通じて再生成します。 要求された動作を制御する最小の正本ファイルをたどり、それに依存して同期する必要がある文書、スキーマ、テスト、生成物をすべて特定します。 ## 原本は1つにし、AIツールごとの版は変換プログラムで作る 再利用可能な指示は、プラットフォームに依存しない単一のソース形式で管理します。対応する各環境に必要なパッケージ化と構文変換は、アダプターに任せます。 アダプターは次の処理を行えます。 - 互換性のあるソースを意味変更なしでコピーする。 - 操作ごとに1つのネイティブスキルパッケージを生成する。 - 複数の入口を持つ共有エンジンを組み立てる。 - プロンプトと補助スキルを含むプラットフォーム用パッケージを構築する。 - ソースのメタデータからディスパッチャーとルーティング表を生成する。 アダプターは元の動作と制約を必ず保持します。対象環境で異なるツールが使われる場合は、プラットフォーム固有のツール名を中立的な操作表現へ変換します。別の手書きカタログを管理するのではなく、正本の説明からルーティングメタデータを生成します。 操作を追加する時は、その正本ソースを一度だけ編集します。明示的なプラットフォーム除外は、その操作が対象プラットフォームで動作できない場合に限って使用します。影響を受けるすべてのアダプターを再ビルドし、意味のずれがないか成果物を確認します。 ## 保存するメモに、出典と確かさの印を必ず付ける 知識成果物を書き込むすべての操作は、リポジトリの正本となる書き込み契約に従わなければなりません。成果物は、目先の人間向けの読みやすさだけでなく、将来の確実な検索と推論に適するよう設計します。 各成果物には次の項目を必須とします。 - 将来のAI読者に目的を説明する短い前置き。 - 成果物の種類、日付、タグ、明示的な`AI-first`フラグなどの構造化メタデータ。 - 参照する人物、プロジェクト、アイデア、意思決定への安定した内部リンク。 - 古くなる可能性がある主張に付ける鮮度マーカー。 - 外部の主張のそばに原文のまま保持するソースURL。 - 明記された事実、強い証拠、中程度の証拠、推測を区別する信頼度ラベル。 成果物を見栄えよくするために、メタデータ、リンク、出典情報、信頼度の手掛かりを取り除いてはいけません。操作によって新しい成果物の種類を導入する場合は、その種類を生成する前に共有スキーマを拡張します。 ## 自動のチェックで確かめられる書き方の決まりを使う フォーマッターとフックが一貫して検証できる規約を使用します。 - Markdownの見出しはsentence caseで書く。 - 指示ソースに装飾目的の絵文字を入れない。 - 非ASCII記号に独自の意味がある場合を除き、組版用の代替記号ではなくASCIIの句読記号を使う。 - タグ値は小文字にし、解釈が曖昧なメタデータ文字列は引用符で囲む。 - 設定済みの言語バージョン、フォーマッター、行長制限、依存関係管理ツールに従う。 - コミットの件名は命令形にし、リポジトリの帰属表示ポリシーを適用する。 機械的なスタイルについては、正本のフォーマッターと検証フックを最終基準として扱います。これらを迂回したり、拒否される書式を手作業で維持したりしてはいけません。 規約は、自動的に強制できる程度に範囲を絞ります。機械的に確認できないルールについては、その確認に必要なレビュー証拠を文書化します。 ## 新しい作業を足す時は、説明書と一覧も同時に直す 新しい操作を追加する時は、次の順序を使用します。 1. ルーティングメタデータと完全な運用指示を備えた正本の指示ソースを作成します。 2. 実行可能なロジックが必要な場合に限り、指定されたスクリプト領域へ補助処理を追加します。 3. 成果物を作成または変更できるすべての経路から、共有の書き込み契約を参照します。 4. 新しい成果物の種類を導入する前に、共有メタデータスキーマを拡張します。 5. 運用マニュアル、機能一覧、アーキテクチャ注記、公開コマンド一覧を更新します。 6. 未リリースの変更履歴セクションに変更を記録します。 7. アダプターのビルドを実行し、影響を受けるすべてのプラットフォーム成果物を確認します。 生成されたプラットフォームツリーに操作を複製してはいけません。同期された変更では、ソース、適用されるリファレンス、テスト、文書をまとめて更新し、後の再ビルドで内容が失われたり矛盾したりすることを防ぎます。 ## 指示の動きと、版を作る流れを分けてテストする ソースの動作と生成パイプラインは別々にテストします。稼働中の知識ストアではなく、分離されたテスト用ワークスペースまたはリンクしたローカルチェックアウトを使用します。 動作を検証する時は、次を行います。 - 代表的なテストデータに対して、変更した操作を実行する。 - 生成された成果物を確認する。 - 必須メタデータ、リンク、出典情報、信頼度ラベル、その他の書き込み契約フィールドを検証する。 - 不明な事実が明示的に不明のまま保たれていることを確認する。 パイプラインを検証する時は、次を行います。 - 設定済みのパッケージ実行ツールを通じて、リポジトリのスモークテスト一式を実行する。 - アダプターの成果物の場所と生成されたルーティングを検証する。 - 補助スクリプトのインターフェースと機械可読な成果物を動作確認する。 - 意図的に成果物の配置を変える場合は、対応するアサーションを同じ変更内で更新する。 まず最小範囲の関連テストを実行し、次に影響を受けるスモークテスト一式を実行します。手動の動作確認は自動テストを補完するものであり、代わりにはなりません。 ## チェックが通ってから、許された人だけが新しい版を出す 継続的インテグレーションが成功し、機械処理向けの書き込み契約が引き続き満たされている場合に限り、リリースします。 次の管理されたリリース手順を使用します。 1. 未リリースの変更履歴項目を、日付付きのバージョン見出しの下へ移します。 2. 主となるパッケージファイルと、複製されたすべてのマニフェストまたは引用情報ファイルのバージョンを更新します。 3. すべてのバージョン宣言を比較するずれ検査を実行します。 4. 生成済み配布物を再ビルドし、影響を受けるテストを実行します。 5. タグ付けやpushの前に、公開担当の役割とブランチポリシーを確認します。 6. 承認済みの変更履歴項目からリリースノートを公開します。 共有のデフォルトブランチを保護します。コントリビューターは、定められたレビュー経路を使用します。メンテナーが直接公開できるのは、リポジトリのポリシーがその権限を明示的に認め、同じ検証ゲートを通過した場合に限ります。 ## 足りない事実を作らず、自動で作られたファイルを手で直さない 見栄えを理由にシステムの検索契約を弱めてはいけません。必須の前置きやメタデータを外したり、機械処理向け成果物を単に人間らしい表現へ書き換えたり、ソース規約で禁止された装飾要素を追加したりしてはいけません。 割合、日付、所有関係、人間関係、その他の欠けている事実を捏造してはいけません。不明な値には`TBD`またはリポジトリで定めた同等の明示的な不明マーカーを付けます。 ジェネレーターが管理する生成物は決して編集してはいけません。フックを迂回したり、許可されていないブランチから公開したり、ソースの確認だけで成功を主張したりしてはいけません。 完了を報告する前に、次を行います。 - 意図した差分全体に無関係な変更がないか確認する。 - 正本ソースと生成物が一致していることを確認する。 - 関連するフォーマッター、フック、テスト、アダプターのビルドを実行する。 - 同期対象のスキーマ、マニュアル、一覧、変更履歴項目を検証する。 - 手動検証の内容と、実行できなかった検査を記録する。 - 最終的な公開操作が、許可された役割に合致していたことを確認する。 変更した動作、検証証拠、残る制約、引き続き判断が必要な事項を報告します。