mcpField
A
agent-changelog

agent-changelog

github.com/petekpAgent 工作流1052 次安装21 周前更新
代码仓库

关于 agent-changelog

Agent Changelog 是一项生成 `AGENT_CHANGELOG.md` 的技能，帮助编码 Agent 理解项目决策与演进。它汇总 Git 历史、文档和代码线索，并检查过时或相互矛盾的信息。

主要功能

  1. 01收集 Git、文档和代码线索
  2. 02记录架构变更与决策
  3. 03追踪弃用方案和迁移
  4. 04交叉检查过时文档信息
  5. 05编写并更新 `AGENT_CHANGELOG.md`

适用场景

  1. 01让编码 Agent 熟悉陌生代码库
  2. 02回顾重大迁移后的项目变化
  3. 03查找与当前代码冲突的文档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/petekp/agent-skills --skill agent-changelog

安装后在 Claude Code 中输入/agent-changelog确认已加载。

详细介绍

Agent 变更日志

按时间顺序记录关键决策、架构变更和项目演进，优化编码 Agent 的上下文构建。

输出

写入项目根目录中的 AGENT_CHANGELOG.md。此文件可帮助 Agent：

  • 了解关键决策及其原因
  • 识别已弃用、应避免的模式或方法
  • 掌握项目从过去到现在的发展轨迹及可能的未来方向
  • 发现与当前实际情况相矛盾的过时文档

工作流

1. 收集来源

并行从以下来源收集信息：

Git 历史：

git log --oneline --since="6 months ago" | head -100
git log --all --oneline --grep="BREAKING" --grep="deprecate" --grep="remove" --grep="migrate" -i
git tag -l --sort=-creatordate | head -20

文档：

  • .claude/plans/ - 实施计划和决策
  • CLAUDE.md - 项目说明
  • README.md - 项目概览
  • docs/ 或类似的文档目录
  • CHANGELOG.md（如果存在，传统变更日志）

代码线索：

  • @deprecated 注解
  • 带日期的 TODO、FIXME、HACK 注释
  • 迁移文件、升级脚本
2. 确定关键事件

提取对 Agent 理解项目有帮助的事件：

始终包括：

  • 架构决策（新增或移除的模式）
  • 破坏性变更和迁移
  • 已弃用的功能或方法
  • 主要依赖项变更
  • 目录结构变更
  • API 变更（内部或外部）

重要时包括：

  • 会改变 Agent 工作方式的新功能
  • 揭示错误假设的 Bug 修复
  • 会影响方法建议的性能变更

跳过：

  • 次要 Bug 修复
  • 外观调整
  • 常规依赖项更新
  • 单项功能新增（除非涉及架构）
3. 交叉核对矛盾

针对每个重要事件，检查现有文档是否与其矛盾：

Event: "Migrated from Redux to Zustand" (commit abc123, 2024-03)

Check: Does any documentation still reference Redux patterns?
- README.md mentions Redux? → Flag as STALE
- CLAUDE.md suggests Redux approach? → Flag as STALE
- Old tutorials in docs/? → Flag as STALE

在“发现的过时信息”部分记录矛盾。

4. 编写变更日志

按以下结构组织输出文件：

# Agent Changelog

> This file helps coding agents understand project evolution, key decisions,
> and deprecated patterns. Updated: [DATE]

## Current State Summary

[2-3 sentences on where the project is NOW - the authoritative current architecture]

## Stale Information Detected

[List any documentation that contradicts current reality - agents should ignore these until fixed]

| Location | States | Reality | Since |
|----------|--------|---------|-------|
| docs/auth.md | "Uses JWT tokens" | Migrated to sessions | 2024-06 |

## Timeline

### [YEAR-MONTH] - [Brief Title]

**What changed:** [Factual description]

**Why:** [Decision rationale if known from plans/commits]

**Agent impact:** [How this affects how agents should work in the codebase]

**Deprecated:** [What approaches/patterns should agents avoid]

---

[Repeat for each significant event, reverse chronological]

## Deprecated Patterns

[Consolidated list of things agents should NOT do, with what to do instead]

| Don't | Do Instead | Deprecated Since |
|-------|------------|------------------|
| Use `OldService` | Use `NewService` | 2024-08 |

## Trajectory

[Brief note on where the project appears to be heading based on recent changes and plans]
5. 验证和更新

写入后：

  • 如果已有 AGENT_CHANGELOG.md，先阅读并合并内容，不要重复
  • 根据 Git 历史核实日期
  • 确保“发现的过时信息”部分包含可执行的内容

主动运行时机

在以下情况下，建议运行此技能：

  • 主要重构或迁移刚刚完成
  • .claude/plans/ 中的计划最近已执行
  • 短时间内发生了多项架构决策
  • 发现文档似乎与代码的实际情况相矛盾
  • 长时间间隔后开始处理某个代码库
  • 开始熟悉不熟悉的代码库

指南

  • 准确性优先于完整性——错误的历史记录比不完整更糟
  • 在可能的情况下说明原因（提交消息、计划文档）
  • 明确指出 Agent 应避免什么，不要只描述发生了什么变化
  • 保持条目简洁——这是参考资料，不是讲故事
  • 为所有内容注明日期，帮助 Agent 判断信息是否仍然适用

评论

支持 Markdown