release-changelog-harness

リリースと変更履歴のハーネス

リリースを分かりやすくしましょう。バージョンを上げるたびに、その意図を構造化して記録し、メンテナーの頭の中や GitHub Releases のテキスト欄だけでなく、Git でエージェントと人間が読めるようにします。

このスキルが扱うのはメタハーネスの文化（どのツールを使い、どのゲートを設け、どのドキュメントに記載するか）です。各パッケージマネージャーの完全なチュートリアルではありません。

専門家による多角的な視点 — アイデアを批評する

専門家の視点	「どこでも JS Changesets を使う」ことへの評価
JS モノレポのメンテナー	強力なデフォルトです。5 つの package.json ファイルを手作業で編集するより、.changeset/*.md と changeset version を使うほうが優れています。
Dart／Flutter のパブリッシャー	そのままでは適合性が低いです。pub ではタグと CHANGELOG.md を使い、モノレポでは npm Changesets ではなく、Melos の version／changelog を使うことがよくあります。
Rust／Go のリリース担当者	release-plz、cargo-release、git-cliff を使いましょう。Changesets を無理に使うと、なじみのないワークフローが加わります。
エージェント運用者	ノートが、エージェントが読んで PR を作成できる、Git 内の小さな構造化ファイルに記録されている場合に効果を発揮します。Slack に文章だけで残す場合とは異なります。
複数リポジトリの管理者（~/mcp）	関連リポジトリ全体で共通の可読性の取り決めを設け、エコシステムごとに異なるジェネレーターを使ってもかまいません。
スキル管理憲章	いつ、どのゲートを設け、どのドキュメントに記載するかを説明します。上流ドキュメントへのリンクを掲載し、200 行の設定を SKILL.md に貼り付けないでください。

改善した方針（こちらを使ってください）：

まずリリース可読性の取り決めを採用し、次にエコシステムに適したジェネレーターを選びます（Changesets は JS ワークスペースに適した優れたジェネレーターの 1 つですが、万能のツールではありません）。

詳しい議論とアンチパターンについては、mixture-of-experts.md を参照してください。

リリース可読性の取り決め（規範）

ツールを選ぶ前に、リポジトリが以下を守ることに合意してください。

1. Git 内のノート — 変更履歴または changeset ファイルをバージョン管理します。Web UI にリリースノートだけを残すことは避けます。
2. 投稿者による構造化された入力 — 投稿者は決められた形式（例：.changeset/foo.md、Conventional Commits のスコープ、または ADR のノート）で変更の意図を記録します。「思い出したときにバージョンを上げる」ではありません。
3. 機械的な公開手順 — DX_FAQ にコマンドの手順を 1 つ記載します。「リリース可能かどうか」の正式な判断基準は CI です。
4. エージェントが読める出力 — リリース後は、CHANGELOG.md（またはパッケージごとの変更履歴）に実際にリリースされた内容を反映します。エージェントが「vX で何が変わったのか」に回答できるようにします。
5. 選定理由の記録 — ツールチェーンの選択が自明でない場合は、簡潔な ADR または DESIGN_FAQ の Q&A に理由を記録します。
6. インストールに関する信頼性とリリース内容の一致 — 最新の GitHub Release、リリースアセット、チェックサム、パッケージのバージョン、インストール手順の内容を一致させます。古いバージョンを固定したインストール例は、リリース内容とのずれを招きます。

エコシステム別のルーター（デフォルトのパターン）

リポジトリ内のシグナル	デフォルトのツール	備考
pnpm-workspace.yaml / npm workspaces	@changesets/cli	JS モノレポの業界標準です。GitHub Action と組み合わせます。
単一の Node パッケージ、高いリリース頻度	release-please または Changesets	release-please は conventional commits から PR を作成します。Changesets は人間／エージェントが意図を明示するファイルを使います。
Dart モノレポ（melos.yaml）	Melos の version + changelog	DX_FAQ の pub publish 順序に合わせます。
単一の Dart パッケージ	CHANGELOG.md + git tag + dart pub publish	エントリーはエージェントが編集可能な Markdown にします。
Rust ワークスペース	release-plz または cargo-release + git-cliff	バージョン PR を作成する自動化を優先します。
バイナリを含む製品ハーネス	release-please + tag CI + install.sh	2 つ目のバージョン情報源を追加しないでください。 binary-release-contract.md に従います。
メタ + CLI バイナリ（Skill Steward）	Changesets + 単一の Release ワークフロー + install.sh	バージョン PR によって、まず git の正本を更新します。次に Release ワークフローでタグ付け、アセットのビルド、GitHub Release の作成／更新を行い、ADR 0014 に従って latest／install の信頼性を検証します。

全体の一覧：ecosystem-tooling.md。バイナリ／インストール：binary-release-contract.md。

このスキルを使用する場面

• 「JS コミュニティのように Changesets を使うべきです」
• リリースプロセスが不明瞭、バージョンがずれている、またはエージェントが何をリリースしたか判断できない
• リリース CI、バージョンポリシー、またはモノレポの公開ワークフローを追加する
• changelog ツールがリポジトリのアーキタイプに合っているか監査する（repo-quality-system-lifecycle）

ワークフロー

1. リポジトリを分類する

repo-quality-system-lifecycle のアーキタイプ（アプリ、ライブラリ、CLI／ツール、プラグイン、ハーネス、メタ／ガバナンス）を使用します。メタリポジトリとハーネスリポジトリには明瞭さが必要です。アプリリポジトリには明瞭さに加えて、ランタイム互換性に関する注記も必要です。

2. ジェネレーターを選択する（自明でない場合は ADR を作成）

質問	はいの場合 →
公開可能な JS パッケージが複数ありますか？	Changesets（デフォルト）
単一パッケージで、コミットメッセージを起点にリリースしますか？	release-please
メンテナーが PR ごとに明示的なリリースノートを作成しますか？	Changesets
pub または Cargo が主要ですか？	上記のエコシステム表。Changesets ではありません

妥当な選択肢が複数ある場合は、docs/decisions/NNNN-release-changelog-tooling.md に選択を記録します。

3. ハーネスの各所を接続する

対象	対応
DX_FAQ	メモリーパレスのブロックに、changeset の追加、バージョン設定、公開、タグの検証を追加します
CI	changesets／changelog ポリシーに違反した場合は公開／タグ付けをブロックします。バイナリでは、単一のリリース担当者を使用するか、明示的な workflow_run／PAT の引き継ぎを使用します
AGENTS.md	ドキュメントルーターに 1 行追加します。Changesets の詳しい説明は不要です
CONTRIBUTING	「ユーザーに影響するすべての PR で changeset または CHANGELOG エントリーを追加する」

4. 最小限の Changesets 構成（JS モノレポとプライベートパッケージ）

コントリビューターが追加する内容：

---
"package-name": patch
---

Short imperative summary agents can quote in release notes.

プライベートパッケージと公開タグ

デフォルトでは、Changesets は package.json で "private": true と指定されたパッケージを無視します。プライベートなルートパッケージまたはプライベートなワークスペースモジュールのバージョン更新を許可するには、.changeset/config.json を更新して次を含めます。

  "privatePackages": {
    "version": true,
    "tag": false
  }

カスタムのリリーススクリプトが公開用の vX.Y.Z タグを管理する場合は、"tag": false を使用します。Changesets 自体にパッケージ別のタグを作成させる場合に限り、"tag": true を使用します。

メンテナーのフロー：

pnpm changeset          # or npx @changesets/cli
pnpm changeset version
pnpm install            # if lockfile must update
git commit -am "chore: version packages"

公開方法はプロジェクトごとに異なります（changeset publish、GitHub Action、または npm provenance）。正確なコマンドはここではなく、DX_FAQ に記載してください。

Changesets による自動リリースでは、次を優先します。

merge feature PR with changeset
→ CI opens/updates Version PR
→ merge Version PR
→ same Release workflow creates vX.Y.Z, builds artifacts, creates/updates GitHub Release, verifies latest release state

GITHUB_TOKEN でタグをプッシュする場合、アセットのビルドに別の on: push: tags ワークフローを依存させないでください。このトークンでは、GitHub が再帰的なワークフローのトリガーを抑制します。

5. 配布方法を選ぶ

配布単位	パターン
実行可能な MCP/CLI	GitHub Releases のバイナリ＋チェックサム＋install.sh — binary-release-contract.md
スキルのみ	npx skills add owner/repo — 利用者向けのリポジトリー tarball はありません
ライブラリー	エコシステム表に従って pub.dev / npm / crates.io

Skill Steward： npx skills でスキルを配布します。steward_cli は GitHub Releases と install.sh で AOT コンパイル済みバイナリを配布します（ADR 0014）。

6. わかりやすさを確認する

• エージェントが GitHub API を使わずに、Git から「未リリースの変更」を確認できます
• バージョン更新にノートがない場合、CI が失敗します
• DX_FAQ に、コピーしてすぐに実行できるコマンドが記載されています
• バージョン情報の参照元が重複していません（例：手動更新＋ボットによる更新）
• バイナリがある場合：タグのアセットがバージョンの SSOT と一致し、最新の GitHub Release がパッケージのバージョンを示しています。install.sh はデフォルトで最新バージョンを使い、バージョンを固定した例にはプレースホルダーまたは生成されたチェックを使用しています

アンチパターン

アンチパターン	問題点
Rust のみのリポジトリーで Changesets を使う	文化に合わず、コントリビューターに無視されます
GitHub Releases にのみ変更履歴を記載する	リポジトリー内のエージェントが見落とします
AGENTS.md に 1,000 行のリリース文書を記載する	タスクのコンテキストを圧迫します。DX_FAQ / ADR に記載すべき内容です
「リリース時に AI が CHANGELOG を書くから」と Changesets を省略する	再現性がなく、PR 作成時にレビューできません
利用者向けの説明文なしでバージョンを更新する	ユーザーやエージェントがアップグレードのリスクを評価できません
Git に変更履歴がないままバイナリをリリースする	ユーザーにはバージョンが見えますが、エージェントには意図がわかりません
GITHUB_TOKEN によるタグのプッシュ後に、タグをトリガーとするバイナリ用ワークフローを別途実行する	GitHub は再帰的なワークフローのトリガーを抑制するため、最新のリリースやアセットが気づかれないまま古い状態になることがあります
実在する古いバージョンを固定したインストール例を記載する	README/DX と GitHub Releases/install.sh の内容が食い違います
サーバー製品のエンドユーザー向けインストールに git clone を使う	install.sh と Release アセット（バイナリリリースパターン）を使用してください

関連スキル

スキル	用途
repo-quality-system-lifecycle	リポジトリーの類型、機械的なゲート、エビデンスの所在
mcp-harness-repo-maintainer	型付きアクション、プローブ、ベンチマーク、CLI/MCP の同等性
repository-governance-lifecycle	ADR、DESIGN_FAQ/DX_FAQ の更新、計画の整合性
skill-source-citations	長期的に参照できるリリースツールの情報源

インストール

npx skills add arenukvern/skill_steward --skill release-changelog-harness

情報源

references/sources.md