# Change History

> Maintain a structured JSON history of project changes in .history/changes.json. Use this skill after making any medium-to-large changes to the codebase. This includes: new files, API changes, schema changes, dependency changes, config changes, refactors, Dockerfile changes, and significant bug fixes. Do NOT log formatting-only changes, typo fixes, or trivial single-line edits. When in doubt, log it.

- Skill: `majiayu000/change-history` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/change-history`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/change-history/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/change-history

---


# Change History

After making medium-to-large changes, update `.history/changes.json` with a new entry.

## Steps

1. Read the current `.history/changes.json` (create it if it doesn't exist)
2. Determine if the changes warrant a log entry
3. If yes, append a new entry to the `entries` array
4. Write the updated file back

## Entry Schema

Each entry must have:
- `id`: ISO timestamp + 6-char random hex suffix (e.g. `"2025-01-15T14:32:00Z-a1b2c3"`)
- `timestamp`: Current UTC time in ISO 8601
- `type`: One of `feature`, `bugfix`, `refactor`, `config`, `docs`, `test`, `infra`
- `scope`: One of `backend`, `infra`, `config`
- `summary`: One-line description (max 120 chars)
- `detail`: Multi-sentence explanation including WHY
- `files_changed`: Array of file paths
- `breaking`: Boolean
- `dependencies_added`: Array of `"package@version"` (optional)
- `dependencies_removed`: Array of `"package@version"` (optional)
- `related_entries`: Array of entry IDs (optional)
- `tags`: Freeform tags (optional)

## When to Log

**Always log:** New files, Dockerfile changes, docker-compose changes, process.py changes,
dependency changes, config changes, CI/CD pipeline changes, benchmark results.

**Never log:** Formatting-only, typo fixes, trivial edits.