petekp/agent-changelog

Agent Changelog

Compile a chronological record of key decisions, architectural changes, and project evolution optimized for coding agent context-building.

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

Workflow

1. Gather Sources

Collect information from these sources in parallel:

Git history:

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

2. Identify Key Events

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)

3. Cross-Reference for Contradictions

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.

4. Write the Changelog

Structure the output file:

# 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. Validate and Update

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

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

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