Record Decision

目的

公開したくない判断の背景を、本人とエージェントが後から取り戻せるようにする。 記録はリポジトリの外に置き、チームの文書や公開物に混ぜない。

使うタイミング

• ユーザーが、判断を残すように頼んだとき
• ユーザーが、記録した判断の訂正・撤回を頼んだとき
• ユーザーが、過去の判断の理由を尋ねたり、以前の判断を踏まえて考えるよう頼んだりしたとき

$record-decision この判断を残して
$record-decision 読み込み API のエラー処理を決めた理由を教えて
$record-decision 前の判断を撤回したことを記録して

スキルが自動で選ばれても、保存・訂正・撤回には、それを求めるユーザーの明示的な依頼が必要となる。 会話全体の自動収集、作業日誌の作成、一般的な好みの収集には使わない。

記録の読み書き

Node.js 24、Git、flock を使う。 保存・参照・訂正・撤回は、すべて scripts/store.mjs を通す。 実行する前に、コマンドと入力形式 を確認する。

スクリプトが、Git の共通管理ディレクトリからリポジトリの識別子を求める。 保存先は $HOME/.local/state/record-decision/<識別子>/ となる。 判断ごとの内容を JSON ファイル内に保持し、読み書きする間だけロックする。 更新時は、読んだ時点の版と照合し、変わっていたら保存しない。 保存先やデータ、ロックファイルを直接作成・編集しない。

同じ共通管理ディレクトリを使う worktree は、同じ記録を参照する。 別の clone は別の記録として扱う。実行に失敗したら、別の場所に推測で保存しない。 Git のリポジトリでなければ、そのことを伝えて終える。

保存先は、この PC での継続利用を前提とする。PC 間の同期や、移動した clone の記録の探索は行わない。 別のリポジトリの記録や、ホームディレクトリ内の無関係なファイルを探索しない。

公開や混入を防ぐ条件

• スクリプトは、Git 管理下の保存先、他者にも読める専用領域、所有者の異なる記録やリンクを拒否する。 拒否されたときは理由を伝え、制約を外して実行しない。
• ホームディレクトリ、.local、state は本人または root が所有し、他者から書き込めないことを確認する。 親の 0755 は許容する。記録とロックファイルは、シンボリックリンクとハードリンクのどちらも拒否する。
• 権限や環境の制約で読み書きできない場合は、通常の承認手順に従う。 承認が得られなければ、記録の読み書きは行わない。

リポジトリ内の文書、隠しファイル、.git/、別の一時領域を代わりの保存先にしない。 .gitignore の変更、commit・push、外部サービスへの送信は行わない。

判断を保存する

1. 依頼された判断と、その判断が確定した会話を確認する。
2. list で一覧を取得し、関係する記録があれば read で読む。
3. 新規の保存・訂正・置換のどれに当たるかを確かめ、根拠のある内容だけを短くまとめる。
4. 読んだ時点の version を添え、save、correct、replace のいずれかで保存する。
5. 返された ID を read で読み直し、依頼と一致することを確かめてから報告する。

対象が会話から一意に決まるなら、保存の確認を重ねない。 対象が曖昧なら、何を残すかだけを短く聞く。 提案や未合意の選択肢を、確定した判断として保存しない。

記録する内容

決定、理由、見送った案、適用範囲、見直す条件、根拠を短く残す。 記録の ID、UTC の記録日時、状態、履歴はスクリプトに任せる。

理由、見送った案、見直す条件が確認できなければ、「記録なし」と書く。 根拠には、判断を確定できる会話の要点や、関係する commit・PR への参照を短く残す。 会話の全文や、個人情報、credentials、secrets は保存しない。 秘密情報を除くと判断の意味を保てない場合は、保存できないことを伝える。

適用範囲には、必要なら機能、ブランチ、commit を添える。 ある API の判断を、「この人は常に例外を嫌う」のような一般的な好みに広げない。

競合した場合

CONFLICT は、読んだ後に記録が変わったことを示す。 最新の記録を読み、今回残す内容と照合する。元の判断が変わっていたら、その内容を伝えてユーザーの判断を待つ。 無関係な記録だけが変わった場合は、今回の判断が変わらないことを確かめ、新しい版で保存できる。

BUSY は、別の操作が実行中であることを示す。 完了後に一覧から読み直す。古い版のまま自動で再試行し続けない。

訂正・撤回する

訂正・撤回は、対象の記録とユーザーの依頼を確かめてから行う。

• 誤記の訂正: correct を使う。変更前の値と訂正日時が履歴に残る。
• 別の判断への置換: replace を使う。新しい判断が保存され、元の記録は「置換済み」になる。 元の記録には置換先の ID が入り、新旧の記録は一度の更新で保存される。
• 撤回: retract を使う。状態が「撤回済み」になり、確認できた理由と撤回日時が履歴に残る。

更新後に読み直し、新旧の記録の対応や状態が食い違っていないか確かめる。 元の判断は削除せず、以前の理由を辿れるようにする。 ユーザーの依頼なしに、古そうな記録を訂正・撤回・置換しない。

過去の判断を参照する

1. list の名前と適用範囲から、質問に関係する記録を選ぶ。
2. read で状態と内容を読み、置換済みなら replacedBy の ID の記録も読む。
3. 現在の依頼、関係するコード・仕様と照合し、当時の前提が今も成り立つか確かめる。
4. 当時の判断と理由、今も適用できるかを短く答える。

「採用」の記録でも、現在の正しさを保証するものとして扱わない。 過去の判断を、現在の依頼やユーザーとの合意より優先しない。 判断を変える必要がありそうなら、その根拠を示す。参照だけの依頼では記録を書き換えない。

関連する記録がなければ、見つからなかったと伝える。記録がないことを、判断がなかった証拠にしない。 根拠を確かめきれない場合は、その部分を不明として扱い、理由を推測で埋めない。 参照時はディレクトリやファイルを作らない。

報告

保存・訂正・撤回では、何を記録したかと、本人用のローカル領域に保存したことを短く伝える。 参照では、当時の判断と理由、現在との違い、確認できなかったことを必要な分だけ伝える。 記録の内容を PR、Issue、共有文書に転載しない。