decision-log

決定ログ

アーキテクチャや機能に関する決定を、簡潔な ADR ファイルとして記録します。計画モード終了時に自動で作成されます。計画モード外での重要な決定については、手動で作成します。

セットアップ（プロジェクトごとに一度実行）

1. 決定ログのディレクトリを作成する

一般的なドキュメント用フォルダー（docs/、doc/、documentation/）をリポジトリ内で検索します。最初に見つかったものを {docs} とします。見つからない場合は、docs を使用します。その後、次を実行します。

mkdir -p {docs}/decisions

2. プロジェクトのエージェント向け指示に登録する

プロジェクトに存在する AGENTS.md、CLAUDE.md、または GEMINI.md（複数ある場合は AGENTS.md を優先）に追加します。

## Decision Log

Decision log directory: ./{docs}/decisions/

When exiting plan mode, create a decision record in the decisions directory. If a non-trivial decision is made outside plan mode (choosing between approaches, introducing a pattern, reversing a prior decision), create one too. Use the format: `YYYY-MM-DD-{slug}.md` with YAML frontmatter containing `title`, `id` (YYYY-MM-DD-animal), `date`, `areas`, `references` (IDs of related records), and `tldr`. Never modify existing records — create a new one that references the old. Keep entries concise — a decision record is a signpost, not a specification.

3. Claude Code フックをインストールする（Claude Code のみ）

プロジェクトの .claude/settings.json に追加します（必要に応じて作成します）。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/decision-log-capture.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

フックスクリプトを .claude/hooks/decision-log-capture.sh に作成します。

#!/usr/bin/env bash
# Injects a reminder to create a decision log entry after exiting plan mode.
# The agent receives this as additionalContext and writes the ADR file itself.

cat <<'HOOK_JSON'
{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "DECISION LOG: You just exited plan mode. Create a decision log entry now. Find the decisions directory from AGENTS.md/CLAUDE.md. Check existing IDs (grep '^id:' *.md) and pick an unused animal name. Write YYYY-MM-DD-{slug}.md with frontmatter: title, id (YYYY-MM-DD-animal), date, areas, references (IDs of related records or []), tldr. Four sections: Context, Decision, Alternatives Considered, Consequences. For Alternatives: only list what was actually discussed — if nothing, write 'No other approaches were evaluated'. Never modify existing records. Under 50 lines. Skip if trivial."
  }
}
HOOK_JSON

実行可能にします。chmod +x .claude/hooks/decision-log-capture.sh

その他の AI CLI（Gemini CLI、Cursor など）では、エージェント設定に同等の計画後の指示を追加します。AGENTS.md の項目は、各種 CLI で共通して使えるフォールバックです。

決定記録の形式

ファイル名：YYYY-MM-DD-{slug}.md。{slug} は短いケバブケースの要約です。

ID の割り当て

各記録には、フロントマターに id を指定します。形式は YYYY-MM-DD-{animal} です（例：2025-03-15-falcon）。日付は記録の作成日、動物名は短く（≤8 char）、覚えやすい名前にします。割り当て手順は次のとおりです。

1. 決定ディレクトリ内の既存 ID を一覧表示します（grep -h '^id:' *.md）
2. その日にまだ使われていない動物名を選びます
3. 既存の名前と重複する場合は、別の動物名を選びます。数字を付け足してはいけません

ID は、会話や他の記録の references フロントマター内で、人が読みやすい参照としても使います。

テンプレート

---
title: Short decision title
id: 2025-03-15-falcon
date: 2025-03-15
areas: [auth, database, ui]
references: []  # IDs of related prior decisions, e.g. [2025-03-10-otter, 2025-02-28-hawk]
tldr: One sentence — what changed and why.
---

## Context

What's the situation? 1-3 sentences. Reference prior decisions by ID if relevant.

## Decision

What was done? Be specific — name files, types, patterns. 2-5 sentences.

## Alternatives Considered

What else was on the table and why it was rejected? If nothing else was considered, write "No other approaches were evaluated" — do not invent alternatives after the fact.

## Consequences

What follows from this decision? Trade-offs, migration needs, things that become easier or harder. 2-4 bullet points.

ガイドライン

• 完全さより簡潔さを優先する — 決定記録は道しるべであり、設計文書ではありません。詳細が必要な場合は、コードまたは PR を確認します。
• フロントマターは機械向け — tldr、areas、id、references を使うと、エージェントは本文を読まずに決定を確認し、たどることができます。
• 1 ファイルにつき 1 つの決定 — 関係のない選択をひとまとめにしないでください。
• 代替案を捏造しない — 実際に議論または評価された代替案のみを記録します。「ほかのアプローチは評価していません」は、作り話の選択肢を挙げるよりも適切で、推奨される回答です。
• 既存の記録は決して変更しない — 決定が変わった場合は、古い記録を参照する新しい記録を作成します。古い記録はそのまま残します。履歴は追記のみです。
• 些細な変更は記録しない — 誤字の修正、単一ファイルの名前変更、依存関係のバージョン更新は記録不要です。

決定記録を作成するタイミング

トリガー	アクション
計画モードを終了する（フックによって自動実行）	計画から記録を作成する
複数のアプローチから選択する	選択の理由を記録する
新しいパターンや規約を導入する	今後の参照用に記録を作成する
以前の決定を覆す、または置き換える	古い記録を ID で参照する新しい記録を作成する
実装中に計画が大幅に変更される	元の計画の ID を参照する新しい記録を作成する
「なぜ X を実行したのか」と尋ねられる	記録がなければ、遡って作成する

変更を加える前に

1. 決定ディレクトリで、作業に関連する既存の記録を確認します
2. 関連する記録を読み、背景、制約、以前の決定を把握します
3. 新しい記録の references フロントマターで、以前の決定を ID により参照します