agent-setup-maintenance

エージェント設定のメンテナンス

リポジトリの共有エージェント設定を変更する際に、このスキルを使用します。

まず読むもの

• 共有設定とシムの仕組みについて、../../README.md を読みます。
• リポジトリレベルの要件について、ルートの ../../AGENTS.md を読みます。
• 共有スキルを追加または編集する場合は、../skill-creator/SKILL.md を使用し、その後このスキルに記載されたリポジトリ固有のチェックを適用します。
• 生成された出力やプロバイダーの検出動作を変更する前に、../../../scripts/agents/sync-agent-shims.mjs を確認します。
• インストール時の同期動作を変更する場合は、../../../scripts/postinstall.sh と ../../../package.json を確認します。

ワークフロー

1. 生成されたプロバイダーの出力ではなく、.agents/ 配下の正規ファイルを編集します。
2. ルートの AGENTS.md は .agents/AGENTS.md へのシンボリックリンクとして維持します。フォルダー向けの指示は AGENTS.md に直接記述し、CLAUDE.md の同等ファイルは生成しないでください。
3. .claude/、.cursor/、.codex/、.vscode/、.mcp.json などのツール固有のディレクトリは、そのツールに真に固有の機能が必要な場合を除き、生成される検出用の場所として扱います。
4. ルートの AGENTS.md は簡潔に保ちます。詳細なワークフローや条件付きのワークフローは、共有スキルまたはパッケージの AGENTS.md ファイルに移します。
5. 開発者からのフィードバックを学習のループとして扱います。タスクを通じて、長期的に役立つリポジトリの規約、繰り返し発生する落とし穴、再利用可能なワークフロー、または検証パターンが明らかになった場合は、最も関連性の高い AGENTS.md または共有スキルを更新します。
6. 共有スキルを追加または変更する場合は、SKILL.md をエントリーポイントとして維持し、ルートの AGENTS.md にスキルごとのリンクを追加しないでください。
7. 共有設定の動作を大きく変更する場合は、同じ PR で README.md とコントリビューター向けのドキュメントも更新します。

Docker／インストール時の制約

• pnpm install は、リポジトリのソースツリー全体が存在しない可能性のある環境で実行されます。
• Docker ビルドでは、Turbo のプルーニングされたインストールステージで、イメージに scripts/ と .agents/ がまだ存在しないうちに、ルートの postinstall が実行されることがあります。
• プルーニングされたそのような環境でも、インストール時のエージェント設定ロジックが堅牢に動作するようにします。リポジトリが所有する必要なファイルが存在しない場合は、エラーを出さずにスキップします。

必須の検証

共有エージェント設定を変更した後、次を実行します。

• pnpm run agents:sync
• pnpm run agents:check
• 同期動作を変更した場合は node --test scripts/agents/sync-agent-shims.test.mjs

関連する場合は、追加の検証も実行します。

• インストール時の動作を変更した場合は pnpm run postinstall
• 変更したスクリプトを対象とするテスト

設計ルール

• プロバイダー固有のファイルを重複させるのではなく、リポジトリが所有する唯一の信頼できる情報源を優先します。
• 可能な限り、共有設定をツールに依存しないものに保ちます。
• 固定の検出パスや、共有設定モデルでは表現できない機能をプロバイダーが必要とする場合に限り、プロバイダー固有のファイルをソース管理下に置きます。