決定ノート
ユーザーによる却下、失敗した試行、比較後に採用されなかった選択肢、延期された項目、およびスコープ外の項目を明確に区別してください。それらすべてを恒久的に不可能なものとして扱わないでください。
ノートは、未解決の提案、完全な要件、実装手順、タスクの進捗状況、またはトラブルシューティングログのためのものではありません。提案や実装計画は設計書や計画ドキュメントに残し、現在の振る舞いは所有するサブシステムのドキュメントで管理し、ソースコードと照合してください。長期的な根拠はノートに維持し、他の場所に要約してリンクしてください。
1. 決定と変更の前に検索
以下の作業を開始する前に、プロジェクトレベルの適用可能な制約、関連するサブシステムドキュメント、および関連ノートを参照してください。
- 具体的な解決策を提案する、振る舞いを確定する、または主要な設計上のトレードオフを決定する。
- 関連する実装または振る舞いテストを変更する。クロスサブシステムの作業では、関連するインターフェースと共有制約をカバーする。
- 決定記録を作成または変更する。まず同じトピックに関する既存の結論を検索する。
ユーザーが履歴について質問した場合、決定へのポインタが見つかった場合、または競合が発生した場合は、関連する記録を直接読んでください。純粋なスペルミス、書式設定、ステータス更新では、確立された制約に関係しない場合、新しい検索は必要ありません。
以下の順序で記録を特定し評価します。
- プロジェクトのエージェントエントリポイントを使用して、実際のノートの場所と適用可能なグローバル制約を見つけます。サブシステムドキュメントを使用して、現在の責務、契約、ソースコード、テスト、関連ノートを見つけます。サブシステムは複数のパッケージやリポジトリにまたがる可能性があり、1つのノートが複数のサブシステムに関連する場合があります。
- リンクをたどり、必要に応じて質問、メカニズム、ソリューション名、制約で検索します。リンク、対応するコード、または一致する名前がないことは、関連する履歴がないことを証明するものではありません。サブシステムページが存在しない場合は、利用可能な資料とタスクのトピックから関連コンテキストを見つけてください。事前に空のドキュメントを作成しないでください。
- タイトル、
Status、Scope、および結論から始めます。必要に応じて、根拠、代替案、および証拠を読みます。現在有効な記録を優先し、関連性に従って履歴をたどります。古い選択肢を再検討する場合や現在のガイダンスが不十分な場合は、アーカイブされた記録を直接検索します。問題のスコープに従って後継関係をたどります。任意のチェーンを最後までたどらないでください。 - 記録の適用可能性と現在の事実を確認します。ディレクトリが本当に存在しない場合は続行し、最初に記録が必要になったときにのみ作成します。読み取りに失敗したり、検索に一致がなかったりしても、履歴がないことを証明するものではありません。
同じタスク内では、既に検証され、まだ適用可能な結果を再利用してください。スコープ、主要な前提、または関連記録が変更された場合、または競合が発生した場合に、影響を受ける部分を再確認してください。ターンやスキルが変わったという理由だけで、すべてを再スキャンしないでください。
古い選択肢が明らかにその前提を変えた場合にのみ、積極的に再提起し、なぜ以前選択されなかったのか、どの条件が変わったのか、その影響を説明してください。ユーザーが以前の決定を明示的に変更した場合は、再度承認を求めずに新しい指示に従ってください。一般的な実装の承認は、既存の却下やスコープ制限を自動的にキャンセルするものではありません。
2. 記録を作成するかどうかの判断
新しい記録は、以下のすべての条件を満たす必要があります。
- 結論が確定している。 採用、却下、延期、またはスコープが限定されているか、長期的に保持する価値のある失敗結果と条件があること。未解決の提案や検証待ちの仮定は、設計書や計画に属します。
- 長期的な価値がある。 根拠がなければ、将来のエージェントが古い選択肢を再提起したり、意味のある失敗した試みを繰り返したり、重要な制約を誤って変更したりする可能性があること。現在の振る舞いを単に言い換えるだけではこの閾値を満たしません。
- 個別の記録が必要である。 関連する履歴が検索され、事実の更新、証拠の追加、またはスコープの明確化では情報を捉えきれないこと。真の決定の変更には、後継ルールに従った新しい記録が必要です。日付、納品数、または代替案の数によって機械的に記録を作成しないでください。
典型的な対象には、非自明なサブシステム境界、インターフェース、永続性や互換性の選択、重要な選択と代替案を選択しなかった理由、キャッシュや自動リトライを意図的に回避する理由、再提起される可能性のある重要な却下や延期、証拠に基づく長期的な失敗の結論やクロスタスクポリシーが含まれます。
通常、フォーマット、機械的なリネーム、コードやテストから理解できる通常の実装や修正、定期的な依存関係のアップグレード、一般的なトラブルシューティングの試行、ログ、TODO、進捗状況についてはノートを作成しないでください。サイズは基準ではありません。作業によって既存のノートが不正確になった場合はそれを維持し、作業によって基準を満たす新しい決定が生じた場合はそれを記録してください。
保存すべき明確な長期的価値がない場合は、テンプレートを埋めるためだけに記録を作成しないでください。ユーザーが重要な決定を保存するよう明示的に要求した場合は、適切なソースを再利用または作成し、黙って破棄しないでください。
3. 実際の結論を迅速に記録する
重要な結論が明らかになったら、完了、セッションの終了、またはコミットの承認を待たずに、迅速に記録してください。決定はユーザーから、または委任された権限内でエージェントが行う選択から生じる場合があります。記録は承認ステップを追加するものではなく、依然としてユーザーの決定を待っているトレードオフは、ノートを書くことで確定することはできません。
書く前に、フォーマットと例を読んでください。デフォルトの場所は、ターゲットプロジェクト内の .agents/notes/YYYY-MM-DD-topic.md です。既存のプロジェクトの場所を優先してください。1ファイルにつき1つの決定トピックを維持し、パスは安定させてください。ノートをステータスやサブシステムごとにディレクトリに整理しないでください。
- タイトル、
Status、Scopeを保持してください。本文は結論と根拠、トレードオフに集中させ、必要に応じて他のセクションを追加してください。本文テキストは、プロジェクトに一貫した言語がない限り、デフォルトで英語になります。代替案をでっち上げたり、固定数を要求したり、肯定的/否定的な結果ラベルを強制したりしないでください。 - 各結論のスコープと条件を明記してください。採用されたが未実装の目標を、現在の実装、移行、またはデプロイの事実として説明しないでください。設計書と計画ドキュメントは実装の進捗を所有します。
- 根拠がない場合は、提供されなかったか記録されなかったと述べてください。失敗の場合は、その条件、結果、および必要な証拠または証拠のギャップを保持してください。恒久的な不可能性を推測しないでください。後のセッションからアクセスできないチャットや一時的な出力のみに依存しないでください。
4. 更新、後継、整理
| ステータス | 意味 |
|---|---|
active | 明示的に採用され、その記述されたスコープ内でまだ適用可能。有効な却下と延期もこのステータスを使用する |
superseded | スコープ全体が1つ以上の新しい決定に置き換えられた |
retired | 何も有効ではなく、新しい決定が完全にそれを引き継ぐわけではない |
ステータスは、実装の進捗状況や候補解決策の処分を示すものではありません。事実、名前、パス、または証拠が変更されたが決定は変更されていない場合は、既存の記録を更新してください。中核となる選択または制約が明確に変更された場合は、新しい記録を作成してください。証拠が無効になった場合は再評価しますが、決定を自動的に変更しないでください。
ステータスを変更する、決定を後継する、部分的な後継を処理する、または古い選択肢を復元する前に、ステータスと後継を読んでください。古い記録と新しい記録をスコープで相互リンクし、部分的な後継後も残りの制約を保持してください。古い選択肢が再び採用された場合は、その間の決定を消去するのではなく、新しい記録を作成してください。
アーカイブ、マージ、または削除する前に、保持と整理を読んでください。デフォルトで記録を保持してください。論理的なアーカイブはパスを移動しません。マージは真の決定の変更を消去してはいけません。削除する前に、一意の情報を移行し、参照を更新してください。現在のタスクの影響を受ける記録のみを整理してください。完全なクリーンアップはスコープ内にある必要があります。
5. 納品前の確認
この作業に関連する記録と関連スコープを確認してください。新しいノートが作成されなかった場合でも、変更によって既存のノートが不正確になっていないか確認してください。
- 欠落と重複: 重要な結論と長期的な根拠は保存されましたか？会話の中だけにありますか？既存の記録で十分ですか？
- 真実と証拠: 推奨を決定として、目標を現在の状態として、失敗を恒久的な却下として、選択されなかったオプションを禁止として、延期を実装のコミットメントとして提示しないでください。未知、未提供、未検証の情報を正確に述べてください。
- ステータスとスコープ: スコープと条件は正確ですか？部分的な後継は残りの義務を保持していますか？同じスコープと条件に対して競合する有効な結論がありますか？アーカイブは現在の制約を隠していませんか？
- ドキュメントの所有権: 影響を受けるサブシステムドキュメント、設計、計画、ノートを更新してください。各ソースはその情報を所有し、他の場所はそれにリンクします。
- リンクと後継チェーン: 必要なソースは見つけられますか？結論は、自己リンク、壊れたリンク、または循環なしにスコープごとにたどれますか？整理によって、一意の根拠、証拠、および意味のある履歴参照は保持されましたか？
- 検証: プロジェクトで既に利用可能な関連チェックを実行し、その結果を確認してください。何も設定されていない場合は、手動で確認してください。依存関係、スクリプト、CI、またはフォーマット移行を自動的に追加しないでください。見つかった実際の問題を修正してください。内容をでっち上げないでください。関連するコンテンツが変更されていない場合は、成功した結果を再利用してください。
フォーマットチェックに合格することは、根拠が正しいこと、検索が完全であること、または実装が決定に従っていることを証明するものではありません。現在の事実が記録と矛盾する場合は、移行の取り決め、古くなったドキュメント、不完全な実装、および実際の競合を区別してください。検証されたエラーを修正してください。重要な判断が不明確なままの場合は、競合を説明し、決定を求めてください。新しいユーザーの指示を無効にしたり、完了を主張したりしないでください。答えに依存しない作業を続けてください。
ノートを追加、大幅に更新、後継、または整理する場合は、何が変更されたのか、なぜか、およびギャップがあれば簡単に説明し、リンクを添付してください。関連する変更がない場合に、固定の「ノートは追加されていません」というメッセージを出力しないでください。
コード、関連ドキュメント、およびノートを1つの保留中の成果物としてまとめてください。今回のラウンドの変更と確認を完了し、結果を表示した後、作業が完了したかどうか、およびローカルコミットを作成してもよいかどうかを尋ねてください。ユーザーがさらにフィードバックを提供した場合は、編集を続けてください。ノートの保存または検証は、コミット、プッシュ、または公開を許可するものではなく、ノートを早期にコミットする必要があることも意味しません。