配布用AGENTS.mdの共通ルールを、利用先リポジトリのルートにある AGENTS.md へ手動で導入します。新規導入ではコピーし、既存ファイルがある場合は必要な本文を組み込みます。更新も手動で行います。
配布用AGENTS.mdには、コミット・ブランチ・PR・Issueの規約と、ドキュメントの配置・記述などの共通ルールを含めています。利用先に、このツールキットの docs/ や templates/ をコピーする必要はありません。APM、導入スクリプト、自動同期は使いません。
Skillsの導入は、従来どおり Skillsの導入方法に従います。
配布元の templates/AGENTS.md を取得し、利用先の既存の指示を確認できる状態にします。作業場所は、このツールキットではなく、ルールを導入するリポジトリです。配置先を確認し、利用先の変更手順に従って作業します。
共通ルール本文の編集元は、このツールキットの templates/AGENTS.md です。このツールキット自身は、ルートの AGENTS.md から参照しています。利用先には本文を配置し、配布元へのアクセスを作業時の前提にしません。
配布用AGENTS.mdの冒頭には、このリポジトリのMITライセンス全文をコメントで含めています。コピーする場合も既存ファイルへ組み込む場合も、このコメントを一緒に残します。
取得元、取得日、取得した版のコミットまたはタグを、利用先のAGENTS.mdのコメントなどに記録します。導入先で調整した内容も記録し、更新時に比較できるようにします。
- 利用先のAGENTS.md、README、既存の規約文書を読み、重複する指示と矛盾する指示を確認します。下位ディレクトリにも指示ファイルがある場合は、その内容も確認します。
- ファイルの置き場所ではなく、適用範囲で分類します。全プロジェクトで守る規約は共通ルール、起動・テスト手順や固有の制約はプロジェクトのルールです。
- 矛盾がある場合は、採用する方針を決めます。例えば既存の取り込み先が
main以外なら、共通ルール本文中の取り込み先などを利用先の方針に合わせて修正し、その調整を記録します。矛盾した指示を並べたままにしません。
- 配布元の
templates/AGENTS.mdを、利用先リポジトリのルートへAGENTS.mdという名前でコピーします。 - 「このプロジェクトのルール」節の案内文を、そのプロジェクトの起動・テスト手順、固有の制約、設計・仕様・利用方法の参照先に置き換えます。
- 既存のREADMEや
docs/にある規約本文との重複・矛盾を整理します。 - 後述の確認を済ませ、利用先の変更手順で取り込みます。
- 既存のファイル全体を置き換えず、プロジェクト固有の指示を残して共通ルール本文と冒頭のライセンスコメントを組み込みます。
- 「共通ルール」と「このプロジェクトのルール」の節に整理します。配布用ファイルの先頭見出しや空の案内節まで重ねて追加する必要はありません。
- 同じ指示をまとめ、矛盾する指示は導入前に決めた方針に合わせます。必要な起動・テスト手順や制約を削除しないよう、編集前後を比較します。
- 既存のREADMEや
docs/に同じ共通ルール本文がある場合は、利用先のAGENTS.mdへの参照に置き換えます。設計・仕様・利用方法はdocs/に残します。 - ドキュメントの配置変更が必要な場合は、文書を整理して参照リンクも更新します。
- 後述の確認を済ませ、利用先の変更手順で取り込みます。
以下はこのガイド用に作成した例です。npm run dev と npm test は例示であり、実際のプロジェクトの手順を残します。
編集前のAGENTS.mdに、次の指示があったとします。
# エージェント向け指示
- 起動には npm run dev を使います。
- 変更後は npm test を実行します。
- 利用方法は docs/usage.md に記載します。組み込み後は、次の形に整理します。共通ルール部分のコメントは説明用であり、実際には配布用AGENTS.mdの本文を入れます。
# エージェント向け指示
## 共通ルール
<!-- templates/AGENTS.mdの「共通ルール」節の本文をここに組み込みます。 -->
## このプロジェクトのルール
- 起動には npm run dev を使います。
- 変更後は npm test を実行します。
- 利用方法は docs/usage.md に記載します。利用先の docs/usage.md は残します。共通ルールの取り込み元を示すコメントは記録であり、そのパスを作業時に読む指示にはしません。
- 利用先のAGENTS.mdだけで、必要な共通ルールを読めることを確認します。配布元のローカルパスや、未配置の文書への必須参照が残っていないことも確認します。
- 共通ルールに、コミット・PRの規約だけでなく、ドキュメントの配置・記述ルールが含まれていることを確認します。
- 起動・テスト手順や固有の制約が、編集前と同じ内容で残っていることを確認します。共通ルールとの重複・矛盾が残っていないことも確認します。
- AGENTS.md、README、関連文書の参照リンクが有効なことを確認します。
- 利用するエージェントに、読み込んだ指示ファイルと、従う共通ルール・プロジェクト固有の指示を確認します。必要な内容が認識されることを確認してから作業を依頼します。
- 差分を確認し、利用先の変更手順に従って取り込みます。
- 配布元の
templates/AGENTS.mdと、利用先のAGENTS.mdの「共通ルール」部分を比較します。 - 必要な変更だけを手動で反映し、以前の導入時に調整した指示と、プロジェクト固有の指示を保持します。共通ルールを再度末尾へ追加しません。
- 取得した版と導入先の調整の記録を更新し、「導入後の確認」を再実施します。
導入先の変更を配布元へ戻すことは必須にしません。採用したい変更だけをリポジトリ所有者が選び、配布元の通常のPR手順で反映します。配布元を更新しても、各導入先へ自動で反映されることはありません。