changelog-review

Claude Code 变更日志审查

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用其他技能……
审查 Claude Code 版本更新中会影响插件的破坏性变更	将项目会话中的经验提炼为规则和范例
发现插件可以利用的 Claude Code 新功能	审查技能以查找可提取脚本的机会时，改用 project-skill-scripts
在弃用项破坏已安装的插件之前进行跟踪	恢复功能开发而非审查平台时，改用 project-continue

用于分析 Claude Code 变更日志并识别其对插件开发影响的专业知识。

核心目的

审查 Claude Code 版本更新，以便：

• 找出需要更新插件的破坏性变更
• 发现插件可以利用的新功能
• 在弃用项造成问题之前进行跟踪
• 确保插件遵循当前最佳实践

变更类别

高影响（需要采取行动）

类别	变更示例	操作
破坏性变更	API 变更、工具重命名	立即更新受影响的插件
安全修复	权限漏洞	检查并更新权限规则
弃用	移除功能／字段	移除已弃用的用法
钩子变更	新事件、架构变更	更新 hooks-plugin

中等影响（建议审查）

类别	变更示例	操作
新功能	新工具、frontmatter 字段	考虑增强插件
权限更新	新通配符模式	更新权限文档
SDK 变更	新回调、流式传输	更新与 SDK 相关的技能
MCP 改进	OAuth、服务配置	更新 agent-patterns-plugin

低影响（仅供参考）

类别	变更示例	操作
Bug 修复	UI 改进	在变更日志中注明
性能	启动优化	无需采取行动
IDE 功能	VS Code 更新	无需采取行动

插件影响矩阵

将变更日志类别映射到插件：

Claude Code 领域	受影响的插件
钩子	hooks-plugin、configure-plugin
技能／命令	所有包含技能／命令的插件
Agent	agents-plugin、agent-patterns-plugin
MCP 服务	agent-patterns-plugin
权限	configure-plugin、hooks-plugin
Git 操作	git-plugin
测试工具	testing-plugin
SDK 变更	agent-patterns-plugin

版本跟踪

版本状态存储在 .claude-code-version-check.json 中：

{
  "lastCheckedVersion": "2.1.7",
  "lastCheckedDate": "2026-01-14",
  "changelogUrl": "https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md",
  "reviewedChanges": [
    {
      "version": "2.1.7",
      "date": "2026-01-14",
      "relevantChanges": [],
      "actionsRequired": []
    }
  ]
}

分析流程

步骤 1：获取当前状态

# Read last checked version
cat .claude-code-version-check.json | jq -r '.lastCheckedVersion'

步骤 2：获取变更日志

使用 WebFetch 获取当前变更日志： https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md

步骤 3：识别新版本

将获取的变更日志版本与 lastCheckedVersion 进行比较。 提取自该版本以来的所有变更。

步骤 4：为变更分类

对每项变更，确定：

1. 影响级别（高／中／低）
2. 受影响的插件
3. 所需操作

步骤 5：生成报告

生成一份报告，包含：

• 发现的新版本
• 需要立即采取行动的高影响变更
• 值得审查的中等影响变更
• 插件改进建议

步骤 6：更新版本跟踪

更新 .claude-code-version-check.json，包含：

• 新的 lastCheckedVersion
• 新的 lastCheckedDate
• 已审查变更的摘要

变更检测模式

破坏性变更

查找：

• “BREAKING”或“Breaking Change”标题
• “Removed”部分
• “Migrat”关键词
• “deprecated”变为“removed”的情况

钩子系统变更

查找：

• 功能说明中提及“hook”的内容
• 新钩子事件（SessionStart、SessionEnd、SubagentStart 等）
• 钩子输入／输出的架构变更
• 权限决策更新

技能/命令变更

查找：

• 提及“技能”或“斜杠命令”
• Frontmatter 字段变更
• 发现机制更新
• “context: fork”等新字段

Agent/子 Agent 变更

查找：

• 提及“Agent”或“子 Agent”
• Task 工具变更
• Agent 配置选项
• 新的 Agent 类型

权限变更

查找：

• 提及“权限”
• 通配符模式更新
• 安全修复
• Bash 权限变更

报告格式

人类可读的审核报告模板（Summary / High-Impact / Medium-Impact / Action Items / Next Steps）请参阅 REFERENCE.md。 CI 路径会改为创建分诊问题——请参阅下文的自动化集成。

自动化集成

.github/workflows/changelog-review.yml 工作流每周运行一次审核。 它是组织可复用工作流 laurigates/.github/.github/workflows/reusable-changelog-review.yml@main （问题 #1304）的轻量调用方：计划、分派输入和仓库专属输入（分析器 路径、提交范围、规则文件章节、插件列表）位于调用方中；两作业流水线 （bash 预检查门控 → opus 分诊）位于上游。分析器脚本及其测试保留在此 仓库中，并通过 analyzer-script 输入传递给可复用工作流，因此分析逻辑 可在此处审查并进行单元测试：

bash scripts/analyze-changelog.sh --excerpt <slice> --repo-dir . \
  --tracked <ver> --latest <ver>

脚本（scripts/analyze-changelog.sh，由 scripts/tests/test-analyze-changelog.sh 测试）会输出结构化的 KEY=VALUE 内容；除了关键词计数外，它还包含弃用/移除 → 插件代码 桥接：对于弃用或 BREAKING 移除行中提及的任何工具/设置/命令，它会 在此仓库的技能/钩子/Agent/规则中执行 grep，并将仍引用这些内容的文件 列为分诊候选项。此逻辑用于处理两类遗漏：

• #1638 — 已弃用的标识符（例如 TaskOutput）仍在钩子脚本中被引用， 因为旧的关键词映射只会指向 .claude/rules/*.md。通过 deprecat|removed|renamed|unshipped 这些形式捕获。
• #1733 — BREAKING 工具移除采用动词后置且以 / 分隔的配对形式 （BREAKING: TeamCreate/TeamDelete tools removed，2.1.178）， 未被弃用语法形式捕获，导致 agent-patterns-plugin:agent-teams 技能引用已移除工具却未被标记。通过 BREAKING 行提取器捕获。

审核变更日志绝不只是更新文档。 每次运行都会将更新规则文档，以及修复 插件代码中对已移除/重命名工具/设置/环境变量的引用视为同一任务—— ACTIONABLE_DEPRECATION 候选项是跟踪问题中优先级最高的部分；被引用的 标识符已移除属于正确性缺陷（技能会指示 Claude 调用不存在的工具），而 不只是过时的文字。

工作流流程：

1. 按计划每周运行
2. 获取变更日志并比较版本（skip-if-exists 会检测偏差：未处理的开放跟踪 问题不再阻止检查更新版本）
3. 如果发现新版本：运行分析器，创建一个跟踪问题（优先级最高的是代码中 仍在引用的已弃用标识符），通过一个小型 PR 更新版本 JSON
4. 为问题添加适当的标签

Agent 式优化

上下文	命令
分析一段变更日志（结构化的 KEY=VALUE）	bash scripts/analyze-changelog.sh --excerpt <slice> --repo-dir . --tracked <ver> --latest <ver>
分诊筛选——仅代码合规候选项	… analyze-changelog.sh … | grep -E '^(ACTIONABLE_DEPRECATION|DEPRECATED_TOKENS)='
列出筛选出的候选文件	… analyze-changelog.sh … | sed -n '/^CANDIDATES:/,/^=== END/p'
仅汇总状态	… analyze-changelog.sh … | grep -E '^(STATUS|ISSUE_COUNT)='
运行分析器回归测试	bash project-plugin/skills/changelog-review/scripts/tests/test-analyze-changelog.sh

快速参考

Claude Code 相关 URL

资源	URL
更新日志	https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md
文档	https://docs.anthropic.com/en/docs/claude-code
GitHub	https://github.com/anthropics/claude-code

版本号格式

Claude Code 使用语义化版本号：MAJOR.MINOR.PATCH

• MAJOR：不兼容的变更
• MINOR：新功能
• PATCH：错误修复

Issue 标签

标签	用途
changelog-review	所有与更新日志相关的 Issue
breaking-change	需要更新的不兼容变更
enhancement	新功能机会
maintenance	常规维护