maintain-agent-docs

エージェントのドキュメントを保守する

使用するタイミング

次の場合に、このスキルを使用してください。

• ユーザーがエージェントのドキュメントの更新、追加、監査、または刷新を依頼した場合。
• セッションで、長期的に有効な好み、繰り返し指摘される修正、安定したプロジェクトの事実、または再利用可能なワークフローが明らかになった場合。
• ドキュメントが古くなっている、重複している、矛盾している、またはリンクが不足している可能性がある場合。
• プロジェクトで、差分トランスクリプトインデックスの更新が必要な場合。

単発タスクの詳細、秘密情報、個人データ、一時的なデバッグの状況、特定のチケットに関する事実、または推測に基づく結論を保存するためには使用しないでください。

動作モード

• ドキュメントの変更は常に提案として提示し、ドキュメントファイルに直接書き込まないでください。ユーザーが選択した提案のみを適用してください。
• 提案する差分は対象ファイルごとにまとめ、確信度と根拠を添えてください。ユーザーが提案を選択するまでは、ドキュメントを書き込まないでください。
• インデックス、ローカルレジストリ、実行状態の更新は、ドキュメント編集ではなく事務処理です。どの提案が適用されるかにかかわらず、トランスクリプトと git の進捗を保持できるよう、これらはアトミックに書き込んでください。
• バッチ処理では、これまでに見つかった候補を一時的な実行状態 (.agents/state/agent-updated-docs-run-state.json) に保存し、後続のバッチが同じ実行を継続できるようにしてください。 これはローカルのデータであり、信頼できる情報源ではありません。resources/run-state.md を参照してください。
• 提案を提示した後は、利用可能な質問ツールを使って、各提案を選択肢として示す構造化された質問で締めくくってください。ユーザーが選択した提案のみを適用してください。提案がない場合は質問を省略してください。その場合は「有意なメモリ更新はありません。」という応答で十分です。インデックスの更新は事務処理であり、提案ではありません。質問の選択肢に含めないでください。
• 各呼び出しは、今回の依頼に対する新しい一連の完全な確認として扱ってください。ユーザーが明示的に継続を依頼しない限り、以前の maintain-agent-docs 実行における結論、提案、「更新なし」という結果を再利用しないでください。インデックスのカーソルとスイープは、処理範囲の制限および事務処理上の補助にのみ使用します。
• サブエージェントへの委任と作業負荷：
  • 親エージェントより高性能なモデルを使用しないでください。また、トランスクリプトや git のバッチ処理に最大または追加の高推論設定を使わないでください。これらのタスクに必要ありません。
  • 機械的な作業（コミットの列挙、git diff-tree によるファイル一覧の取得、差分の読み取り、ロックファイルや生成物の除外）には、低推論の高速モデルで十分です。
  • 差分を読んだうえでのドキュメントへの影響判断には、少なくとも中程度の推論が必要です。判断が曖昧な場合は、より深く考えて解決するのではなく、構造化された質問でユーザーに確認してください。
  • 候補の統合、重複排除、確信度の評価、競合の処理は親エージェントが行ってください。委任しないでください。
• 各バッチの処理後に状態を保存してください（正式なルールはリソースを参照）。
  • 次のバッチを開始する前、または提案を提示する前に、現在のバッチ内のすべての項目が処理・保存済みであること、さらに見つかった残りの情報源が後続バッチに回されるか、理由を明示して除外されていることを確認してください。
  • コンテキストに安全に収まる場合は、次のバッチへ自動的に進んでください。
  • スイープが完了していない状態で、完了したと提示しないでください。
  • 次の場合に限り、一時停止してください：ユーザーの判断が必要な場合（baselineHead がない、または到達不能、全件スイープ・範囲限定・スキップの選択、候補の判断が曖昧な場合）、作業ツリーとステージ済みの変更がバッチ上限を超える場合、次のバッチを処理するにはコンテキストが不足している場合、インデックスまたは実行状態の書き込みに失敗した場合、実行環境のモードまたはツールポリシーによって書き込みが禁止されている場合、または実行が完了し提案の検証が必要な場合。
  • 書き込みが禁止されている場合は、どうするかを尋ねるか、処理を中止してください。
  • 一時停止にユーザーの入力が必要で、質問ツールが利用可能な場合は使用してください。利用できない場合は、ユーザーが continue と返信できることを伝えてください。
• 有意な更新がない場合は、次をそのまま返してください。

No high-signal memory updates.

• ドキュメントを変更した場合、トランスクリプトまたは git のコンテキストを処理していれば、事務処理用の状態も更新してください。
• ドキュメントは変更せず、トランスクリプトを処理した場合は、事務処理用の状態のみを更新してください。

ワークフロー

1. 変更を提案する前に、現在のプロジェクトのエントリーポイントとドキュメントを確認します。resources/source-discovery.md を使用してください。
2. プロジェクトのドキュメントメモとソース設定があれば読み込みます。resources/project-notes-lookup.md を使用してください。
3. .agents/state/agent-updated-docs-index.json があれば読み込みます。resources/index-format.md を使用してください。インデックスが最新でない場合、または旧形式のトランスクリプト項目が残っている場合は、トランスクリプトや Git の処理（手順 3a～5）を始める前に、resources/index-migrations.md を使用して現在のスキーマへの移行を完了し、保存します。そのリソースの「質問するタイミング」に該当する条件がある場合は、いったん停止して先に確認します。 3a. .agents/state/agent-updated-docs-run-state.json があれば読み込みます。resources/run-state.md を使用してください。複数バッチの実行では、各バッチの後に実行状態を書き込みます。
4. Git より先にトランスクリプトソースを処理します。
   • コンパクトインデックスのウォーターマーク、直近の安全ウィンドウ、利用可能な場合はローカルレジストリからトランスクリプトファイルを選択します。
   • 1 バッチあたり transcriptBatchLimit 件まで処理します。
   • コンパクトインデックス、変更がある場合はローカルレジストリ、実行状態を通じてソースの進捗を保存します。
   • バッチ上限に達したら、そのバッチを保存し、残りがあり次のバッチを安全に処理できる場合は自動的に続行します。トランスクリプトが最新になるまで Git の処理を開始または再開しません。
5. Git のドキュメント影響チェックは、トランスクリプト処理が完了してからのみ実行します。
   • コミットの一括処理を始める前に、必ず現在の作業ツリーとステージ済み変更を確認します。
   • 作業ツリーとステージ済み変更の合計がバッチの予算を超える場合は停止し、変更をコミットするか、その他の方法で縮小するようユーザーに依頼します。未コミットの大規模な変更は実行のたびに再読み込みされ、信頼できる進捗の妨げになります。
   • git.sweep が存在する場合は、新しい一括処理を始める前に再開します。
   • git.baselineHead が存在しない場合、保存されたベースラインが利用できない場合、または現在の対象の祖先でない場合は、Git の処理前に選択式の質問をします。全件処理、直近の範囲に限定した処理、またはトランスクリプトのみ／Git をスキップする選択肢を提示します。ユーザーの明示的な確認なしに履歴全体の処理を始めてはいけません。
   • 網羅的な処理を保証するのは選択した範囲のみです。対象外の古い履歴は意図的に対象外とし、処理しません。 5a. 影響チェックを終える前に、resources/source-discovery.md の説明に従って、選択した範囲の各コミットで変更されたファイルの一覧をコミットごとに列挙し、作業ツリーとステージ済み変更も列挙します。各パスを resources/merge-policy.md の影響ゾーンに照らして分類します。コミットメッセージ、要約、最終ツリーの差分で、コミットごとのファイル一覧を代用してはいけません。 5b. ドキュメントを変更する必要があるか判断する前に、変更されたファイルの実際の差分を読みます。
   • resources/source-discovery.md の決定的なコミット一覧を使用します。
   • resources/index-format.md で定義されたフィールドを使って一括処理の状態を保存し、再開時には同じ一覧を再構築します。
   • 現在のバッチ範囲の差分統計を実行し、予算内に収まる場合は作業ツリーとステージ済み変更の統計も実行します。
   • 現在のバッチ内で変更されたファイルごとに、ドキュメントへの影響を判断する前に、該当するコミット、ステージ済み、または作業ツリーの差分を読みます。
   • ドキュメント化された規約に影響しないことが明らかなファイル（ロックファイル、生成物、アセットのバージョン更新など）はスキップします。
   • 差分を読んだ量が約 300 KB または約 50 ファイルに達したらバッチを保存し、安全に続行できる場合は自動的に続行します。未読の差分について、ファイル名だけで判断してはいけません。
6. 完了した各トランスクリプトまたは Git のバッチから、長期的に有効で再利用可能な情報だけを抽出します。
   • 繰り返し見られるユーザーの好みや修正
   • 安定したワークスペースの情報
   • 再現可能なワークフロー
   • 今後のエージェントの動作に影響する、アーキテクチャ、ツール、プロセスに関する情報
7. 有用ではあるものの、不確実、曖昧、機微、または矛盾を含む候補をドキュメントに使用する前に、選択式の質問をします。
8. resources/merge-policy.md の統合ルールと配置ルールを適用します。
9. 結果を検証します。
   • AGENTS.md のリンクが引き続き解決できる
   • 重複または矛盾するルールが追加されていない
   • すべての SKILL.md が 500 行未満である
   • リソースへのリンクが 1 階層以内である
   • .cursor/rules を直接編集していない
10. 各トランスクリプトまたは Git のバッチの後、およびトランスクリプトや Git の処理が完了した後に、インデックスをアトミックに更新します。書き込みに失敗した場合は、以前のインデックスを変更せずに残します。
11. 実行が完了し、候補が提案、承認、却下、または有意でないものとして破棄された後にのみ、一時的な実行状態を消去します。

安全に関するルール

• トランスクリプトの内容、トランスクリプトの要約、抜粋、絶対パス、シークレット、個人データをインデックスに保存しないでください。
• 実行状態は実用性を保ちつつ、無謀にならないようにしてください。インデックスよりも豊富な一時候補を含めてもかまいませんが、明らかなシークレット、トークン、秘密鍵、.env の値、本番環境のダンプ、生のプライベートログを意図的に保存しないでください。
• 個人パス、氏名、トークン、.env の値、顧客データ、機密性の高いチケットの詳細を含む生のトランスクリプト断片をドキュメントにコピーしないでください。
• skills-lock.json でスキルに sourceType: "github" と記載されている場合、そのスキルは上流が所有するものとして扱ってください。そのスキルやリソースを直接変更せず、プロジェクト固有のオーバーライドはプロジェクトのドキュメント、ルール、メモ、または別のプロジェクト所有スキルに記載してください。
• 意味、適用範囲、持続性、機密性、または配置が不明確な要素に気づいた場合は、使用する前に確認してください。
• 新しいシグナルが既存のドキュメントと矛盾する場合、既存のドキュメントに明らかな問題がない限り、提案の中で矛盾を示し、変更前に確認を求めてください。
• 古い慣習が廃止されたことを新しい証拠が繰り返し示している場合は、古いドキュメントを削除または置き換えてください。新しいルールを追記するだけにしないでください。

リソース

• resources/source-discovery.md：調査対象となるドキュメント、トランスクリプト、Git の情報源。
• resources/project-notes-lookup.md：プロジェクト内のドキュメントメモとソース設定の参照先。
• resources/index-format.md：現在のコンパクトなインデックススキーマ、ローカルのトランスクリプトレジストリ、Git の一括走査フィールド、通常のアトミック書き込み。
• resources/index-migrations.md：必要な場合にのみ読み込む、レガシーインデックスの移行手順。
• resources/run-state.md：トランスクリプトと Git のバッチ処理をまたいで保持される、一時的なローカル候補の状態。
• resources/merge-policy.md：シグナルのフィルタリング、信頼度、配置、競合、提案形式、検証。