保守ドキュメントは何をしますか？

1. 責任範囲と現在のスコープを明確にする

このスキルを使用して、記録を作成するか再利用するか、コンテンツを整理するか、説明を検証するか、ギャップを明らかにするか、ソース間の関係、ステータス、およびナビゲーションを維持するかを決定します。これにはエンジニアリング判断が必要です。現在のメカニズムを説明するときは実際のパスを調査し、単に会話を整形したり、テンプレートを埋めて誤った確実性を生み出したりしないでください。

現在のタスクを実行するエージェントは、技術的な選択、トレードオフ、タスク分割、実装、デバッグ、および検証を処理します。出力を保持する必要がある場合は、これらの共有ルールを使用します。サブシステムドキュメントへの対象を絞った調査と更新は有効なタスクであり、最初に別の設計プロセスを開始する必要はありません。
to-docs を使用して、人間が後でレビュー、編集、および参照できる読みやすい設計成果物を作成します。人間が読める設計は完全なソースになり得ます。このスキルは、保存時点からのドキュメントの所有権と一貫性をガイドします。最初にエンジニアリング記録を要求したり、スキル間で循環呼び出しを作成したりしないでください。
grilling を使用して現在のトピックを深く明確にします。grill-me がその明示的なエントリポイントです。決定を再開したり、各イテレーションに承認ゲートを追加したりせずに、確立されたコンテンツから続行します。
decision-notes を使用して、長期的な決定を見つけ、記録し、置き換え、整理します。このスキルはその結論を参照します。個別のインタビュープロセスや決定ライフサイクルを確立するものではありません。トリガー条件が適用される場合、直接リンクがなくても検索します。
必要に応じて handoff を使用して、セッションやエージェント間の引き継ぎを準備または検証します。このスキルは引き続きエンジニアリング資料とステータスを維持します。タスクを実行する人が変わったという理由だけで完全な重複を作成したり、スキル間で循環呼び出しを作成したりしないでください。
通常の読み取り、即時の質問、および既存の資料に影響を与えない小さな変更は、単独で完全な保守プロセスをトリガーしません。それでもタスクに必要な資料は読み取ってください。ドキュメントのみのリクエストは、製品動作の変更、無関係なチェックの実行、またはコードのコミットを行う権限を拡大しません。既存のエンジニアリングタスクの承認は引き続き有効です。

環境で実際に利用可能な名前を使用します。スキルを呼び出せない場合は、代わりにプロジェクトの設定されたガイダンスを読みます。利用できないスキルを呼び出したと主張しないでください。コラボレーションは循環ロードや重複検索を引き起こしてはなりません。

2. ソースを特定し、記録を再利用するか作成するかを決定する

プロジェクトの実際のエージェントエントリポイントから開始して、制約、要件、受入基準、関連するサブシステム、変更記録、およびメモを見つけます。現在の作業の範囲を検証します。既存のプロジェクトの場合は、既存の場所と名前を優先します。移行を要求しないでください。サブシステム間の作業の場合は、関連するインターフェースと共有制約をカバーします。

同じタスクですでに読み取られ検証されたコンテキストは、それがまだ適用される場合は再利用します。スコープ、重要な前提、またはソースが変更された場合、または競合が現れた場合は、影響を受ける領域を再確認します。ターンやスキルが変わったという理由だけで、リポジトリ全体を再スキャンしたり、インタビューを再開したりしないでください。

場所、名前、ファイル分割、またはナビゲーションを選択するときは、Organization and Sources を読んでください。

最初に、同じ変更にまだ適用される既存のドキュメントを探します。類似したトピックは、必ずしも同じ変更を意味するわけではありません。既存の作業を続行するには、元の記録を見つけて現在の状態を検証し、自動的に完全な引き継ぎドキュメントを作成しないようにします。
ターゲット設計、移行計画、依存関係、または調査・検証すべき質問を、後で実装、受入、またはセッション間の継続のために保持する必要がある場合は、記録を作成または更新します。これは調査とソリューションの比較中にも適用されます。
現在のターンで完了した小さく明確な変更は、会話だけで伝達できますが、その場合でも、確立されたルールで必要とされる既存のドキュメントとメモは維持します。ユーザーが明示的に何かを保存するように要求した場合は、適切な既存のソースを優先して記録します。
行数、ファイル数、会話ターン数、またはコミット数に基づいて機械的に記録を作成しないでください。空のページやドキュメントライブラリ全体を事前に作成したり、ドキュメントを書くたびに毎回尋ねたりしないでください。

3. 目的に応じて資料を検証および維持する

現在の作業	必要に応じて読む	情報の所有権
人間が読める設計とエンジニアリング資料の間の所有権と整合性を検証する	Organization and Sources	人間が読める設計は、目標、シナリオ、動作の完全なソースを保持する。エンジニアリング資料はそれらを参照し補足する
現在のサブシステムを説明する、またはドキュメントと実装の間の差異を修正する	Subsystem Documentation	現在の責任、メカニズム、契約、およびソースコード、テスト、メモへのナビゲーション
変更の目標、設計、タスク、継続コンテキストを記録する	Change Designs and Plans	現在の目標、既存の状態からのギャップ、未解決の質問、実装、および検証計画
ステータスを更新する。記録を完了、一時停止、キャンセル、再開、または終了する	Status and Closeout	全体的な進捗、タスク結果、実際の検証、残りの作業の処分

各事実は一箇所に維持し、他の場所ではそれを要約してリンクします。docs/designs/<topic>.md は、完全な人間が読める設計ソースになり得ます。エンジニアリングの詳細、依存関係、検証、進捗は、必要な場合にのみ .agents/changes/ に追加します。設計を複製しないでください。既存のソースの概要を完全なコピーに変えたり、インデックスに2番目のステータスや進捗記録を作成したり、メモソースの外部で長期的な根拠を維持したりしないでください。

エンジニアリング変更のエントリポイント、README、計画、および全体的なステータスルールは、エンジニアリング変更記録を必要とする作業にのみ適用されます。人間が読める設計に課されるものではありません。設計の確定または未解決のコンテンツは、エンジニアリングの進捗ではありません。必須の設計ステートマシンを導入したり、すべての設計に付随するエンジニアリングディレクトリを作成したりしないでください。

確定した結論、未解決の推奨事項、前提、調査項目を、ソースコードの検証、既存のテストカバレッジ、および実際の実行時検証から区別します。リンクは、それがサポートするメカニズム、カバーされる動作、または決定トピックを説明する必要があります。テストが存在することは、それが正常に実行されたことを意味しません。目標を採用することは、それが実装されたこと、または移行や互換性の義務が自動的に削除されたことを意味しません。

ドキュメントと実装が一致しない場合、関連するソースコード、テスト、要件、該当するメモ、および実装ステータスを確認します。ドキュメントが古くなっているか、実装が意図された動作から逸脱しているか、移行が不完全かを判断します。検証されたドキュメントエラーを修正します。実装エラーは既存の承認範囲内で対処します。欠陥を通常の契約として説明したり、古いドキュメントを使用して新しいユーザー指示を無効にしたりしないでください。主要な動作やトレードオフが不明確なままの場合は、その競合を説明し、その決定に依存しない作業を続けながらユーザーに判断を仰ぎます。

4. 実質的な変更に合わせて資料を同期する

サブシステムの責任、境界、主要パス、インターフェース、状態、障害動作、互換性動作、または必要なナビゲーションが変更された場合、プロジェクトが完了するのを待たずに、検証された変更と並行して関連ドキュメントを更新します。内部リファクタリング後も正確な説明は機械的に書き換えませんが、壊れたリンクは修正します。
目標、スコープ、主要な選択、または前提が明確に変更された場合は、設計を更新します。未解決のコンテンツは引き続き未解決としてラベル付けします。タスクの結果、依存関係、ブロッカー、または次のステップが実行や継続に影響を与える形で変更された場合は、計画を更新します。影響を受けるステップを実行する前に、重要なスケジュール変更を同期します。すべてのツール操作を記録しないでください。
既存の承認範囲内で調整を自律的に処理します。ドキュメントの更新は承認要件を追加せず、必要なユーザー決定を置き換えることはできません。承認を超える動作、スコープ、または主要なトレードオフの変更については、ユーザーに決定を仰ぎます。確定した事項を再確認しないでください。
配信、一時停止、または引き継ぎの前に、継続的な保持を必要とする関連資料が、次のエージェントが現在の状態、目標からのギャップ、残りの作業、および次のステップを特定できるようにします。これらの瞬間まで待って最初の記録を作成しないでください。

現在のタスクに関連するスコープのみを処理します。現在の事実はサブシステムドキュメントに、長期的な決定は decision-notes に保持し、他の場所はそれらを参照するようにします。

5. 確認と配信

このタスクで合意されたスコープを確認します。リポジトリ全体の監査に変えないでください。

カバレッジと所有権: 永続化する必要があるコンテンツを保持します。重複した散文、空のプレースホルダー、または一時的な会話にのみ残された継続コンテキストなしで、適切なソースを再利用します。
正確性: 現在の状態、目標、確定および未解決のポイント、証拠を明確にします。ステージの進捗、コード変更、成功した検証、および必要な手動受入を混同しないでください。
ステータスと継続: エンジニアリング変更記録が存在する場合、その全体的なステータスは変更エントリポイントでのみ維持し、実際の進捗に従ってタスクをマークします。関連するブロッカー、ギャップ、次のステップ、および残りの作業を検索可能にし、必要な結論と証拠をクローズアウト記録に保持します。
リンクと一貫性: 関連する要件と受入基準、設計、計画、サブシステム、およびメモが正確に接続されていることを確認し、リンクが機能するようにします。資料や記録を再編成しても、固有の情報が失われないようにします。
検証範囲: タスクとプロジェクトに基づいて、該当する既存のチェックを実行し、結果をレビューします。専用ツールが存在しない場合は手動レビューを実行します。ドキュメントを完了するためだけに、無関係なチェック、完全なテストスイート、または新しいツールチェーンを課さないでください。コンテンツが変更されていない場合は検証済みの結果を再利用し、未検証または制約のある領域を正確に説明します。

現在のドキュメントタスクを完了するということは、合意された情報が正確であり、ソースが検索可能であり、未知の点と検証ギャップが開示され、資料が継続をサポートすることを意味します。設計が十分であること、実装が正しいこと、または機能が完了していることを証明するものではありません。全体的な変更の完了は、Status and Closeout を使用して個別に検証します。

今回のラウンドからの変更、チェック、および必要なギャップを簡潔な説明と実際のファイルへのリンクとともに配信します。継続的なメンテナンスを必要とする結果はリポジトリに配置します。関連するコード、ドキュメント、およびメモを保留中の成果物としてまとめておきます。ドキュメントを保存しても、コミット、プッシュ、PR、またはリリースは許可されません。プロジェクトの既存のコミット確認ルールに従い、ドキュメントが保存されたという理由だけで early commit しないでください。

保守ドキュメント