Agent Notes
Agent Notes は、決定のコーパスを小さく、かつ権威あるものに保ちます。各ノートは、コードやドキュメントでは伝えきれない根拠のみを記録し、それ以外は記録しません。レイアウト、クラス、ファイル内フォーマットのルールは .agents/notes/README.md にあります。このスキルはワークフローを担当します。すべてのノートを意味的に判断してください。語数や経過時間は発見の補助手段であり、決して判断基準ではありません。これはガイダンスであり、チェックリストではありません。
ノートが必要かどうかを判断する
ノートを書く（または更新する）のは、永続的な決定の根拠（なぜその設計が選ばれたか、何を諦めたか、どの代替案がなぜ敗れたか、そしてそれを検証するピンは何か）のためだけにしてください。機械的な編集やローカルな編集（ローカルUIの表示変更を含む）、またはコード、APIドキュメント、README、クックブックに属する事実については、ノートを書かないでください。
- 将来的な大規模な作業の提案は
proposed/<class>/に配置します。現在の変更で下された決定はimplemented/<class>/に配置します。 - アクティブなノートがすでにその決定を扱っている場合は、重複を作成せずにそのノートを更新します。
- 決定の覆しは、古いノートを相互参照する新しいノートとして扱います。ノートを異なる決定に編集してはいけません。
ノートを書く
.agents/notes/README.mdのテーブルからクラスを選択し、ファイル名をyyyy-mm-dd-topic-title.mdとします。日付はトピックが最初に提案された日付を使用します。- README の正確なヘッダーとライフサイクルのセクション骨格を使用します。
## Alternatives consideredは必須です。真の代替案をそれぞれ記録し、なぜ敗れたかを説明します。代替案を発明してはいけません。 - 実装済みノートは、現在完了形で出荷された現実として書きます。計画、受入チェックリスト、「べき」は使用しません。動作を固定する検証と、名前付きのカバレッジギャップを記録します。
- 他のノートやドキュメントへのリンクは相対マークダウンリンクを使用します。prose-standard と trim-cot-leakage に従います。ノート自身の変更履歴セクション以外では、レビューの段取り、セッションの引用、変更のナレーションを入れないでください。
すべての新しいノートで優先関係をチェックする
ドラフトを作成する前に、アクティブなツリー（proposed/、implemented/、rejected/）を検索し、同じ決定、メカニズム、または却下された代替案をカバーするノートがないか確認します。新しいノートを書いている間に、それぞれの一致を分類します。
- 実装済みノートの完全な優先関係: 統合（新しいノートがすべての固有の根拠、代替案、結果、検証、カバレッジギャップを保持した後、古いノートは削除され、着信リンクが修復されます）するか、同じ変更でアーカイブします。
- 部分的な優先関係: 両方をアクティブに保ち、相互リンクし、現在も有効なすべての事実を更新します。
- 陳腐化した提案: 誠実な一言の理由を付けて
rejected/に移動します。 - 陳腐化した却下: それがもはや起こり得る間違いを防がなくなった場合は削除します。
既知の一致を後日の監査に先送りしないでください。
将来価値に基づいて既存のノートを分類する
監査や整理を行う際は、ライフサイクルごとに以下の結果を適用します。
- 実装済み、削除: 小さなUI調整や純粋に機械的な変更のみを説明するノート。着信リンクを修復するか削除します。ローカルなバグ修正、パフォーマンス変更、新しい機能、実質的な動作や所有権の決定は、その実装が小さかったという理由だけで削除対象になりません。このテストは、保持またはアーカイブの前に適用します。
- 実装済み、アクティブに維持: 将来の変更を導く可能性が高い、根拠、代替案、否定的な保証、耐久性のあるまたはワイヤーセマンティクス、所有権の境界、セキュリティルール、再導入条件。実装のサイズではなく決定を分類します。機械的なリネームでも、永続的な命名規則や互換性ルールを記録している場合があります。
- 実装済み、アーカイブ: 完了しており将来の作業を導く可能性が低いが、その根拠が保存に値する実質的な歴史的决定。
- 提案済み、決してアーカイブしない: ライブな提案はアクティブに保ちます。追求する価値がなくなった場合は、誠実な理由を付けて却下します。
- 却下済み、ガードレールとしてのみ保持: 敗れた提案が依然として誘惑的で意味のある間違いであり、ノートがその敗因を説明している場合にのみ、却下を保持します。それ以外の場合は削除します。
割り当てに向けてアーカイブしないでください。対象範囲内のすべてのノートを検査し、類似グループを1つの原則で分類し、真に境界線上の決定はレポート用に記録します。
キャリブレーション: 折りたたまれたサイドバーコントロールのスタイリングに関するノートは、どんなに長くても削除します。セッションがイベントソースであること、またはストレージディレクトリの単一所有者を命名するノートは、どんなに短くてもアクティブに維持します。2つのパッケージをマージしてはならない理由を記録したノートは、マージが依然として魅力的である限りガードレールとして保持します。
実装済みノートをアーカイブする
- 完全なノートを、翻訳版がある場合はそれも含めて、
implemented/<class>/からarchived/<class>/に移動します。 - 本文は編集しません。各言語ファイルの
Status: implementedの直下に、同じ日付でArchived: YYYY-MM-DDのみを挿入します。 - アクティブな散文内の着信リンクを検索します。現在の権威にリダイレクトするか、歴史的なスナップショットを意図的に引用する場合のみアーカイブパスに再ターゲットするか、リンクを削除します。アーカイブされたノートからのリンクを検証したり修復したりしてはいけません。
アーカイブ後は、ノートの編集、移動、翻訳、再フォーマット、削除を一切行ってはいけません。アーカイブされたノートは有効なリンクターゲットですが、現在の動作の権威ではありません。
検証と報告
プロファイルの commands.docs-check と git diff --check を実行し、変更されたすべての相対リンクが解決することを確認します。作成または更新されたノート、アクティブに維持されたノート、削除、アーカイブ、または却下されたノート、および選択された結果とともにすべての境界線上のケースを報告します。