playbooks

home / skills / seika139 / dotfiles / framework_changelog

framework_changelog skill

/claude/profiles/cg-m2-mac/skills/framework_changelog

This skill helps verify that changelog entries for a framework meet Keep a Changelog standards from user perspective.

npx playbooks add skill seika139/dotfiles --skill framework_changelog

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.2 KB
---
name: "verifying-changelog-in-framework"
description: "外部公開を想定したフレームワークにある CHANGELOG.md の内容が適切かどうかを確認するスキルです。CHANGELOG.md を更新する際、またはレビューする際に利用します。"
---

# Rules for Verifying CHANGELOG.md in Framework

- フレームワークを利用するユーザー視点で、パッケージに変更が生じる場合は必ず CHANGELOG.md を更新します
  - 基本的に src/ 以下の private でないクラスやメソッドに変更があった場合は更新が必要です
  - この際、実装が破壊的変更（breaking change）を伴う場合は、SemVer における minor バージョンまたは major バージョンの更新で対応する必要があることに注意します
  - ただし、内部の不具合を修正するために生じる変更（バグフィックス）は影響度の小さい破壊的変更であれば patch バージョンの更新を許容します

## Important Formatting and Content Rules

変更に CHANGELOG.md を更新する際は、以下のフォーマットに従ってください。

- フォーマットは [Keep a Changelog](https://keepachangelog.com/ja/1.0.0/) に基づく
- CHANGELOGは全てユーザー目線で見える変更を記述する
- 実装した詳細を書くのではなく、そのサービスを利用する人（ユーザー）から見たときにどのような機能追加・変更・修正があったのかを端的に記載する
- ユーザーから本フレームワークを見たときのいわゆるインターフェイスとなる外側部分についてどんな変化が起きたかを書くこと
- 本フレームワークにどんな変化があったかではなく、ユーザーが使うときにどんな影響があるかを書くこと
- PR や Issue の番号は `[#123](github.com/your-repo/issues/123)` のようにリンク形式で記載する
- システムやコード、クラスを主語にする
- 変更点や追加内容等は端的に記載する
- バグ修正の場合はどのような事象・問題が起きていたかを記載する
- 代替手段がある場合は記載する
- クラス名は多少冗長でもFQCNで書く

Overview

This skill verifies that a framework's CHANGELOG.md is accurate, user-focused, and formatted for public release. It helps maintainers update or review changelogs so users can understand how changes affect them. The skill enforces Keep a Changelog style and Semantic Versioning guidance for visible API changes.

How this skill works

The skill inspects CHANGELOG.md entries against the codebase, focusing on publicly visible classes and methods under src/. It checks that entries are written from the user's perspective, reference PR/Issue links in the correct format, and classify changes (Added, Changed, Fixed) per Keep a Changelog. It also verifies version bump guidance for breaking and non-breaking changes and flags missing FQCNs when class names are referenced.

When to use it

  • Before releasing a new framework version to ensure the changelog reflects user-visible changes
  • During pull request review when src/ public APIs or behaviors are modified
  • When backporting bug fixes to ensure patch-level entries are appropriate
  • When auditing repository documentation for public consumption

Best practices

  • Write changelog entries from the user's perspective, describing impact rather than implementation details
  • Follow Keep a Changelog sections (Added, Changed, Fixed, Deprecated, Removed, Security)
  • Link PRs and issues with markdown links like [#123](https://github.com/your-repo/issues/123)
  • Use FQCNs for class references and prefer interface/behavior descriptions for methods
  • Bump minor/major for breaking changes; allow patch for small bugfixes that alter behavior only to fix bugs

Example use cases

  • A reviewer detects a public method signature change and uses the skill to confirm the changelog note and version bump are required
  • A maintainer prepares a release and runs the skill to ensure all src/ public API changes are recorded under appropriate headings
  • A backport of a bugfix is evaluated to decide if it can be listed as a patch-level fix in CHANGELOG.md
  • A documentation audit uses the skill to enforce user-facing phrasing and correct PR/Issue link formatting

FAQ

Should internal-only changes be listed in the changelog?

No. Only user-visible changes to non-private classes or methods should be recorded. Internal refactors that do not affect external behavior can be omitted.

How should breaking changes be handled?

Describe how users are affected and bump the minor or major version according to SemVer. Provide migration notes or alternatives when possible.