decision-log

决策日志

将架构和功能决策记录为轻量级 ADR 文件。退出计划模式时自动触发；在计划模式之外做出重大决策时手动触发。

设置（每个项目运行一次）

1. 创建决策日志目录

扫描仓库，查找常见的文档文件夹（docs/、doc/、documentation/）。使用第一个匹配项作为 {docs}。如果都不存在，则默认为 docs。然后：

mkdir -p {docs}/decisions

2. 在项目 Agent 指令中注册

将以下内容添加到项目的 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 等）：在 Agent 配置中添加等效的计划后指令。AGENTS.md 条目可作为跨 CLI 的备用方案。

决策记录格式

文件名：YYYY-MM-DD-{slug}.md，其中 {slug} 是简短的 kebab-case 摘要。

ID 分配

每条记录都在 frontmatter 中设置一个 id：YYYY-MM-DD-{animal}（例如，2025-03-15-falcon）。日期为记录创建日期；动物名应简短（≤8 个字符）且易于记忆。分配方式：

1. 列出决策目录中的现有 ID（grep -h '^id:' *.md）
2. 选择当天尚未使用过的动物名
3. 如果显而易见的名称已被使用，则选择另一种动物——不要追加数字

该 ID 既可作为对话中便于人类使用的引用，也可用作其他记录 references frontmatter 中的引用。

模板

---
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。
• Frontmatter 供机器使用——tldr、areas、id 和 references 可让 Agent 无需阅读正文即可扫描和遍历决策。
• 每个文件只记录一项决策——不要将无关的选择合并在一起。
• 不要捏造备选方案——只记录实际讨论或评估过的备选方案。“未评估其他方案”是有效且更推荐的回答，而不是编造选项。
• 绝不修改现有记录——如果决策发生变化，应创建一条引用旧记录的新记录。旧记录保持原样。历史记录只增不改。
• 跳过琐碎变更——拼写修正、单文件重命名和依赖项升级无需记录。

何时创建决策记录

触发条件	操作
退出计划模式（通过钩子自动触发）	根据计划创建记录
在多种方案中做出选择	创建记录说明选择理由
引入新的模式或约定	创建记录以供将来参考
撤销或替换先前的决策	创建新记录，并通过 ID 引用旧记录
实施过程中计划发生重大变化	创建新记录，并引用原计划的 ID
有人问“我们为什么要做 X？”	如果没有现有记录，则补建一条记录

做出变更之前

1. 检查决策目录中是否有与任务相关的现有记录
2. 阅读相关记录，了解背景、约束和先前的决策
3. 在新记录的 references frontmatter 字段中通过 ID 引用先前的决策