決定記録
概要
決定は永続的なインフラです。メモリやチャット履歴はそうではありません。記録のコストは一度支払われるだけですが、失われた決定のコストは、誰かがコードから意図を逆解析するたびに支払われます。
記録の構造
すべての重要な決定は、固定された構造を持つ記録を生成します。これにより、誰でもどこを見ればよいかがわかります。
| セクション | 内容 |
|---|---|
| アーキテクチャ | ソリューションの形状と主要ファイル |
| データモデル | エンティティ、フィールド、リレーションシップ |
| 決定（理由付き） | 各選択とその根拠のペア — 理由は必須 |
| インターフェース | 他のコードがこれをどのように使用するか |
| 制約 | 常に真であり続けなければならないこと |
| 落とし穴 | 次の人が遭遇するわかりにくい罠 |
| 却下された代替案 | 検討されたが破棄されたもの、およびその理由 — 解決済みの問題の再議論を防ぐ |
3つの補助成果物
- すべての決定のインデックス。明示的な依存関係トラッキング（どの決定がどの決定に基づくか）と置き換えられたセクションを含む。記録の山をナビゲート可能なグラフに変える。
- 「将来の考慮事項」ドキュメント — 延期されたアイデアや既知の懸念事項。新しい作業を開始する際に参照することで、何も黙って忘れられないようにする。インシデントのアクションアイテムと、トリガー付きで延期された決定はここに置かれる。
- アーカイブ — 置き換えられた記録は削除されるのではなく、ここに移動される。履歴は保持され、上書きされない。
クイックリファレンス
- 記録の配置場所の規則:
docs/superpowers/decisions/YYYY-MM-DD-<トピック>.md。YAMLフロントマター（title、date、component、status、supersedes、dependencies）を含む。 - 「将来の考慮事項」は
docs/superpowers/future-considerations.mdに配置される。各エントリにはステータス（open/triggered/done/dropped）が付与され、該当する場合はそれを再活性化すべきトリガーも含まれる。新しい作業を開始する際に参照すること。 - フロントマターは自動生成されるインデックスの元となる — 正確に保つこと。
- 理由と却下された代替案は最も価値の高い2つのセクションである。これらがない記録は地雷である。
- 記録はパイプラインの記録段階（
designing-before-buildingを参照）で、実行後に行う。
バンドルツール
このスキルには独自のスクリプトとテンプレートが同梱されており、スキルがインストールされた任意のリポジトリで機能します。これらは SKILL.md の隣に配置されます。
recording-decisions/
scripts/doc-archive.sh 決定記録がない仕様/計画を見つける
scripts/index-rebuild.sh 記録のフロントマターからインデックスを再生成する
templates/decision-record.md
それらの場所を特定する — スキルはプロジェクト単位またはグローバルにインストールされている可能性があります。
for base in .claude/skills ~/.claude/skills; do
d="$base/recording-decisions/scripts"
[ -d "$d" ] && echo "$d" && break
done
doc-archive.sh [specs_dir] [plans_dir] [decisions_dir] [archive_dir]
一致する決定記録がない仕様を一覧表示し、テンプレートから構築された変換プロンプトを出力します。デフォルトは docs/superpowers/{specs,plans,decisions,archive} です。
index-rebuild.sh [decisions_dir] [output_file]
すべての記録のフロントマターから docs/superpowers/index.md を書き換えます — アクティブテーブル（コンポーネント、タイトル、日付、依存関係）と置き換えられたテーブル（コンポーネント、タイトル、置き換え元）を生成します。全体が再生成されるため、手動で編集しないでください。
どちらも依存関係のないbashです。このスキルを使用するプロジェクトは yq、jq、タスクランナーを必要としません。スクリプトがない場合でも、上記の手順は自己完結型であるため、直接作業を行ってください。
これがコンテキストにとって重要な理由
仕様書や計画書は意図的に冗長です。人間が推論を追跡するために書かれています。その冗長性は、Claudeがそれらを開くたびにコンテキストにチャージされます。決定記録は、前に進むために必要なもの（決定、理由、インターフェース、制約、落とし穴、却下された代替案）を約30〜50行に収め、元の仕様書は archive/ に移動され、人間が読める状態を保ちつつ、意図的に開かれるまでコストは発生しません。
使用すべきでない場合
些細で自明な変更には記録は不要です。判断基準: 後で「なぜこの方法で実装されたのか？」と誰かが尋ねるだろうか？ 「はい」の場合は記録します。
完全な根拠: 憲法第2条。engineering-constitution/references/engineering-constitution.md にバンドルされています。