decision-log

意思決定ログ

概要

チームやエージェントが、何を決定したか、なぜその決定に至ったか、どのような代替案を検討したか、いつ決定を見直すべきかを記録しておく必要がある場合、このスキルを使って、永続的で検索可能な意思決定記録を維持します。

このスキルは、チャット履歴や議事録では十分に解決できない、繰り返し発生する問題に対処します。

• 意思決定が長いやり取りの中に埋もれ、後から見つけにくくなります。
• 選択の背景にある理由や制約が忘れられます。
• 信頼できる記録がないため、決着したはずの議題が再び議論されます。
• 過去の経緯を残さずに、古いコンテキストを削除して方針を覆してしまいます。
• 見直しの周期が設定されていないため、期限に左右される意思決定が気づかないうちに古くなります。

このパターンは ADR 形式です。各意思決定につき 1 つの Markdown ファイルを作成し、連番を付けて、ステータス、コンテキスト、選択肢、決定、結果、見直しに関するメタデータを記録します。この形式は、Michael Nygard の Architecture Decision Record（ADR）パターンの理念に沿いつつ、プロダクト、運用、調査、チームの意思決定にも適用できるよう一般化されています。

意思決定記録は、設定可能なディレクトリに保存されます。

• すべてのコマンドで --decisions-dir DIR を指定する
• DECISIONS_DIR=/path/to/decisions を指定する
• デフォルトは、現在の作業ディレクトリを基準とした ./decisions/

クイックスタート

python scripts/decision_log.py new --title "Use SQLite for source-tracker"

このコマンドは、次の連番ファイルを作成します。例：

./decisions/ADR-001-use-sqlite-for-source-tracker.md

表示されたパスを開いて各セクションを記入し、意思決定が承認されたら ## Status を proposed から accepted に変更します。

ADR を作成するタイミング

将来の人が「なぜこうしたのか？」と尋ねるほど重要な選択をしたときは、意思決定記録を作成します。例：

• アーキテクチャ、ストレージ、API、依存関係、デプロイ、セキュリティに関する選択。
• 複数のユーザーや今後の作業に影響する、プロダクトやワークフローに関する選択。
• 実質的なコスト、制約、または除外された代替案を伴うトレードオフ。
• 日付、マイルストーン、または外部要因をきっかけに見直す必要がある意思決定。
• 過去の意思決定の撤回。

些細な選択については、ADR を作成しないでください。

• 誤字の修正、単発のリファクタリング、明白な実装の詳細。
• 明確な標準やユーザーの指示ですでに定められている選択。
• 今後の作業に影響しない、一時的な検討段階の意思決定。

ADR の形式

各意思決定記録は、次の名前の Markdown ファイルです。

ADR-NNN-short-title.md

NNN はゼロ埋めの連番です（001、002、…）。古い記録を移行する場合を除き、ファイルに手動で番号を付けないでください。番号の一貫性を保つため、CLI を使用してください。

セクションは次のとおりです。

ステータス

使用できる値：

• proposed — 作成済みですが、まだ採用されていません。
• accepted — 有効な意思決定です。
• superseded by ADR-NNN — 後の意思決定に置き換えられました。
• deprecated — 直接の置き換えを設けずに、意図的に廃止されました。

変更があったからといって、古い意思決定を削除しないでください。監査証跡を維持するため、後の意思決定に置き換えられたことを記録してください。

日付

記録を作成または承認した日付を、YYYY-MM-DD 形式で記録します。

コンテキスト

意思決定を必要とする問題の説明、背景、制約、要因、前提、事実を記録します。適切なコンテキストでは、その意思決定が明白でない理由を説明します。

検討した選択肢

重要な代替案と、それぞれのメリットとデメリットを列挙します。将来の読者が尋ねる可能性の高い、却下した選択肢も含めてください。

決定

選んだ内容と、その理由を記述します。「なぜ」は選択そのものと同じくらい重要です。選択を制約、トレードオフ、期待される結果に結び付けて説明してください。

結果

プラス、マイナス、中立の結果を記録します。これにより、記録が単なる正当化のための文書になるのを防ぎ、既知のデメリットも明らかにできます。

見直し

見直しの周期、次回の見直し日、見直しを促す条件を記録します。

• 周期：monthly、quarterly、annually、または on-trigger。
• 次回の見直し日：YYYY-MM-DD。日付ベースの周期では自動計算されます。
• トリガー：予定された見直しより前に再評価を促す条件を任意で指定します。

ワークフロー 1：作成

デフォルトの quarterly レビュー頻度で新しい決定を作成します。

python scripts/decision_log.py new --title "Use SQLite for source-tracker"

初期コンテキストを追加します。

python scripts/decision_log.py new \
  --title "Use SQLite for source-tracker" \
  --context "Single-user local index, low write volume, simple backup needs."

特定のディレクトリに作成します。

python scripts/decision_log.py new \
  --title "Use hosted object storage for exports" \
  --decisions-dir ./docs/decisions

レビュー頻度を選択します。

python scripts/decision_log.py new \
  --title "Adopt quarterly vendor review" \
  --cadence annually

完了条件：CLI が新しい ADR-NNN-short-title.md のパスを出力し、ファイルにタイトル、日付、頻度、および該当する場合は次回レビュー日が記入されていること。

ワークフロー 2：一覧表示

すべての決定を一覧表示します。

python scripts/decision_log.py list

ステータスで絞り込みます。

python scripts/decision_log.py list --status accepted
python scripts/decision_log.py list --status proposed
python scripts/decision_log.py list --status superseded
python scripts/decision_log.py list --status deprecated

トピックのテキストで絞り込みます。

python scripts/decision_log.py list --topic storage

完了条件：表に ADR 番号、日付、ステータス、タイトル、パスが表示されていること。

ワークフロー 3：後継決定への置き換え

決定が変わった場合は、まず新しい決定を作成し、その後、古い決定を後継決定に置き換えられたものとしてマークします。

python scripts/decision_log.py new --title "Move source-tracker storage to Postgres"
python scripts/decision_log.py supersede 001 --by 005

これにより、ADR-001...md が次のように更新されます。

## Status
superseded by ADR-005

さらに、置き換える ADR へのリンクが追加されます。古いコンテキストも検索可能なままです。

完了条件：list --status superseded に古い ADR が含まれ、timeline に決定の連鎖が表示されること。

ワークフロー 4：検索

決定全体のテキストを検索します。

python scripts/decision_log.py search "SQLite"
python scripts/decision_log.py search "backup"

検索結果には、一致する ADR とコンテキストの抜粋が表示されるため、すでに決着した問題を蒸し返さずに済みます。

完了条件：一致した ADR 番号、タイトル、パス、抜粋が出力されるか、一致する結果がないと CLI が明示すること。

ワークフロー 5：レビュースケジュール

次回レビュー日を迎えた決定を表示します。

python scripts/decision_log.py due-review

スケジュールされたリマインダーには、cron 対応のチェッカーを使用します。

python scripts/review_checker.py --decisions-dir ./decisions

週次 cron スケジューラーの設定例：

0 9 * * MON DECISIONS_DIR=/path/to/decisions python /path/to/scripts/review_checker.py

期限が到来した決定がない場合、チェッカーは何も出力しません。承認済みの決定のレビュー期限が到来している場合は、簡潔な概要を出力します。この概要は、既存のスケジューラーやラッパーを使ってメッセージングプラットフォームに配信できます。

完了条件：レビュー期限が到来した決定がある場合は、N decisions due for review: で始まるメッセージが出力され、期限が到来した決定がない場合はチェッカーから何も出力されないこと。

ワークフロー 6：タイムライン

後継決定への置き換えの連鎖を表示します。

python scripts/decision_log.py timeline

トピックで連鎖を絞り込みます。

python scripts/decision_log.py timeline --topic storage

出力例：

ADR-001 → ADR-005 → ADR-012

完了条件：各連鎖で最も古い決定が先に表示され、superseded by ADR-NNN リンクをたどって順に表示されること。

レビュー頻度のオプション

• monthly — すぐに古くなる可能性がある、変化の速い決定、実験、ベンダーの試用、または運用上の選択に使用します。次回レビュー日は日付の 1 か月後です。
• quarterly — アクティブな製品、アーキテクチャ、ワークフローに関する大半の決定で使用するデフォルトです。次回レビュー日は日付の 3 か月後です。
• annually — 年 1 回の検証で十分な、安定した決定に使用します。次回レビュー日は日付の 1 年後です。
• on-trigger — 日付が適切でない場合に使用します。Next review は空欄のままにし、「月間の量が 100 万レコードを超えたらレビューする」や「2 つ目のチームがこのワークフローを採用したらレビューする」など、具体的なトリガーを記述します。

月単位の計算では、対象月の最終日に合わせて日付を調整します。たとえば、1 月 31 日から 1 か月後のレビュー日は、2 月 28 日または 29 日になります。

ファイルの受け渡し

ワークフローでファイルを作成または更新した場合は、通常使用しているエディターで Markdown の記録を開き、確認、編集できるよう、ユーザーにファイルパスを伝えてください。

よくある落とし穴

1. 削除して、後継を作成しない。 削除すると履歴が失われます。古い記録に superseded by ADR-NNN と記載して、ファイルを残してください。
2. コンテキストが不足している。 制約や却下した選択肢が記載されていない決定では、 将来、同じ議論が繰り返されるのを防げません。初めて読む人にも分かるよう、背景を十分に記述してください。
3. レビュー日が記載されていない。 日付に基づく間隔が設定された承認済みの決定には、 Next review の値を設定してください。on-trigger は、具体的なトリガーがある場合にのみ使用してください。
4. 番号が付いていないファイル。 ADR-NNN-short-title.md の形式に従わないファイルは、 list、review、timeline コマンドに含まれません。
5. ステータスの不整合。 フィルターとリマインダーが機能するよう、proposed、accepted、superseded by ADR-NNN、 または deprecated を正確に使用してください。
6. 置き換えを作成する前に後継を指定する。 新しい ADR を先に作成し、古い ADR が既存の記録を参照できるようにしてください。
7. トリガーが曖昧。 「後でレビューする」はトリガーではありません。測定可能なイベント、 日付、しきい値、または依存関係の変更を使用してください。

検証チェックリスト

• 新しいファイルの名前が ADR-NNN-short-title.md で、番号が連番になっている。
• 各 ADR に Status、Date、Context、Options Considered、Decision、 Consequences、Review の各セクションがある。
• 承認済みのアクティブな決定のステータスが accepted になっている。
• 変更された決定は削除せず、後継を指定している。
• python scripts/decision_log.py list に想定した記録が表示される。
• python scripts/decision_log.py due-review で期限が到来した記録が見つかる。
• python scripts/decision_log.py timeline に後継の連鎖が表示される。
• cron スケジューラーで、意図した DECISIONS_DIR または --decisions-dir を指定して review_checker.py が実行される。
• ファイルを作成または更新した場合、そのパスをユーザーに提示する。

ファイル

• scripts/decision_log.py — 作成、一覧表示、後継の指定、検索、 レビュー期限の確認、タイムライン表示を行うメイン CLI。
• scripts/review_checker.py — cron スケジューラー向けの、対象がない場合は出力しないリマインダー確認ツール。
• templates/decision-template.md — 空の ADR テンプレート。
• references/adr-format.md — ADR の各セクションの書き方ガイド。
• references/review-cadence.md — レビュー間隔とトリガーのルール。