Back to Details

agent-changelog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Changelog

Agent 变更日志

Compile a chronological record of key decisions, architectural changes, and project evolution optimized for coding agent context-building.
编译一份按时间顺序排列的关键决策、架构变更和项目演进记录，专为编码Agent构建上下文而优化。

Output

输出

Write to 
AGENT_CHANGELOG.md
in the project root. This file helps agents:
  • Understand key decisions and their rationale
  • Identify deprecated patterns/approaches to avoid
  • Grasp the trajectory from past to present to likely future
  • Detect stale documentation that contradicts current reality
写入项目根目录下的
AGENT_CHANGELOG.md
文件中。该文件可帮助Agent：
  • 理解关键决策及其背后的理由
  • 识别需要避免的废弃模式/方法
  • 掌握从过去到现在再到未来可能发展的轨迹
  • 检测与当前实际情况不符的过时文档

Workflow

工作流程

1. Gather Sources

1. 收集来源

Collect information from these sources in parallel:
Git history:
bash
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
Documentation:
  • .claude/plans/
    - implementation plans and decisions
  • CLAUDE.md
    - project instructions
  • README.md
    - project overview
  • docs/
    or similar documentation directories
  • CHANGELOG.md
    if exists (traditional changelog)
Code signals:
  • @deprecated
    annotations
  • TODO
    , 
    FIXME
    , 
    HACK
    comments with dates
  • Migration files, upgrade scripts
并行从以下来源收集信息：
Git历史记录：
bash
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. Identify Key Events

2. 识别关键事件

Extract events that matter for agent understanding:
Always include:
  • Architectural decisions (new patterns, removed patterns)
  • Breaking changes and migrations
  • Deprecated features/approaches
  • Major dependency changes
  • Directory structure changes
  • API changes (internal or external)
Include if significant:
  • New features that change how agents should work
  • Bug fixes that reveal incorrect assumptions
  • Performance changes that affect approach recommendations
Skip:
  • Minor bug fixes
  • Cosmetic changes
  • Routine dependency updates
  • Individual feature additions (unless architectural)
提取对Agent理解有重要意义的事件：
务必包含：
  • 架构决策（新增模式、移除模式）
  • 破坏性变更与迁移
  • 废弃的功能/方法
  • 重大依赖变更
  • 目录结构变更
  • API变更（内部或外部）
若重要则包含：
  • 会改变Agent工作方式的新功能
  • 能揭示错误假设的Bug修复
  • 会影响方法建议的性能变更
可忽略：
  • 小Bug修复
  • 外观变更
  • 常规依赖更新
  • 单个功能新增（除非涉及架构）

3. Cross-Reference for Contradictions

3. 交叉引用以查找矛盾

For each significant event, check if existing documentation contradicts it:
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
Track contradictions in a "Stale Information Detected" section.
针对每个重大事件，检查现有文档是否与之矛盾：
事件：「从Redux迁移到Zustand」（提交记录abc123，2024-03）

检查：是否有文档仍在引用Redux模式？
- README.md提到Redux？→ 标记为过时
- CLAUDE.md建议使用Redux方法？→ 标记为过时
- docs/中的旧教程？→ 标记为过时
在「检测到的过时信息」部分记录矛盾内容。

4. Write the Changelog

4. 编写变更日志

Structure the output file:
markdown
undefined
按以下结构编写输出文件：
markdown
undefined

Agent Changelog

Agent 变更日志

This file helps coding agents understand project evolution, key decisions, and deprecated patterns. Updated: [DATE]
本文件帮助编码Agent理解项目演进、关键决策及废弃模式。更新时间：[日期]

Current State Summary

当前状态摘要

[2-3 sentences on where the project is NOW - the authoritative current architecture]
[2-3句话说明项目当前的权威架构]

Stale Information Detected

检测到的过时信息

[List any documentation that contradicts current reality - agents should ignore these until fixed]
LocationStatesRealitySince
docs/auth.md"Uses JWT tokens"Migrated to sessions2024-06
[列出所有与当前实际情况不符的文档——Agent在问题修复前应忽略这些内容]
位置文档描述实际情况变更时间
docs/auth.md「使用JWT令牌」已迁移到会话机制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]
变更内容： [事实描述]
原因： [若从计划/提交记录中可查，说明决策理由]
对Agent的影响： [这会如何改变Agent在代码库中的工作方式]
废弃内容： [Agent应避免的方法/模式]
[按倒序时间重复记录每个重大事件]

Deprecated Patterns

废弃模式

[Consolidated list of things agents should NOT do, with what to do instead]
Don'tDo InsteadDeprecated Since
Use 
OldService
Use 
NewService
2024-08
[汇总Agent不应采用的方法，及替代方案]
禁止操作替代方案废弃时间
使用
OldService
使用
NewService
2024-08

Trajectory

发展轨迹

[Brief note on where the project appears to be heading based on recent changes and plans]
undefined
[根据近期变更和计划，简要说明项目未来的发展方向]
undefined

5. Validate and Update

5. 验证与更新

After writing:
  • Read existing 
    AGENT_CHANGELOG.md
    if present and merge, don't duplicate
  • Verify dates against git history
  • Ensure "Stale Information Detected" section is actionable
编写完成后：
  • 若已存在
    AGENT_CHANGELOG.md
    ，则进行合并，避免重复
  • 对照Git历史记录验证日期
  • 确保「检测到的过时信息」部分具备可操作性

When to Proactively Run

何时主动运行

Suggest running this skill when:
  • A major refactor or migration just completed
  • Plans in 
    .claude/plans/
    were recently executed
  • Multiple architectural decisions happened in quick succession
  • Detected documentation that seems to contradict code reality
  • Starting work on a codebase after a long gap
  • Onboarding to an unfamiliar codebase
建议在以下场景运行此技能：
  • 重大重构或迁移刚完成
  • .claude/plans/
    中的计划刚执行完毕
  • 短时间内发生多项架构决策
  • 检测到文档与代码实际情况不符
  • 长时间未接触某代码库后重新开始工作
  • 加入不熟悉的代码库进行入职学习

Guidelines

指南

  • Prioritize accuracy over completeness—wrong history is worse than incomplete
  • Include rationale when available (commit messages, plan docs)
  • Be specific about what agents should avoid, not just what changed
  • Keep entries concise—this is reference material, not storytelling
  • Date everything to help agents judge relevance
  • 优先保证准确性而非完整性——错误的历史比不完整的历史危害更大
  • 若有相关依据（提交信息、计划文档），请包含决策理由
  • 明确说明Agent应避免的内容，而非仅说明变更内容
  • 保持条目简洁——这是参考资料，而非故事叙述
  • 所有内容都标注日期，帮助Agent判断相关性