docs-changelog

ドキュメントの変更履歴の作成ガイド

対象範囲（重要）

このスキルの対象は、次の変更履歴ページのみです。

• docs/changelog/*.mdx

このスキルは GitHub Releases を対象としていません。
ユーザーがリリース PR の本文／GitHub Release のリリースノートを求めている場合は、../version-release/SKILL.md を読み込んでください。

必須の関連スキル

ドキュメントの変更履歴に関するすべてのタスクで、必ず次を読み込んでください。

• ../../../DESIGN.md（文体とコンテンツ）
• ../i18n/SKILL.md（EN/ZH のペアが関係する場合）

ファイルと命名規則

日付ベースのファイル名を使用します。

• 英語：docs/changelog/YYYY-MM-DD-topic.mdx
• 中国語：docs/changelog/YYYY-MM-DD-topic.zh-CN.mdx

EN と ZH のファイルはペアで存在し、同じリリース内容を記述する必要があります。

Frontmatter の要件

各ファイルには、次を含めてください。

---
title: <Title>
description: <1 sentence summary>
tags:
  - <Tag 1>
  - <Tag 2>
---

ルール：

1. title は意味の上で H1 のタイトルと一致させます。
2. description は簡潔で、ユーザー向けの内容にします。
3. tags は機能を表すものにし、社内チーム向けのラベルは使用しません。

コンテンツの構成（推奨）

ユーザーから別の指定がない限り、次の構成にします。

1. # <Title>
2. 冒頭の段落（2～4 文）：ユーザーに見える影響
3. 1～3 個の機能セクション（## 見出しは任意）
4. ## 改善と修正 の簡潔な箇条書き

見出しの数は抑え、箇条書きごとに見出しを設ける構成は避けてください。

執筆ルール

1. すべての主張を事実に基づかせ、実際にリリースされた変更と結びつけてください。
2. 実装の説明より先に、ユーザーにとっての価値を説明してください。
3. 箇条書きだけにせず、自然な文章を優先してください。
4. 誇張した宣伝文句や曖昧な形容詞は避けてください。
5. EN/ZH ファイル間で社内用語を一貫させてください。
6. EN/ZH でセクションの順序と対象範囲を揃えてください。

EN/ZH の同期ルール

バイリンガルの変更履歴を作成する場合：

1. 重要な事実を同じ順序で記載してください。
2. 自然な表現にローカライズし、文ごとの逐語訳は避けてください。
3. 一方のバージョンに Improvements and fixes の箇条書きがある場合、もう一方にも同等の意図を持つリストを設けてください。
4. 明示的に求められていない限り、一方の言語にだけ機能を追加しないでください。

長さの目安

• 小規模な更新：合計 3～5 個の短い段落
• 中規模な更新：4～7 個の短い段落と簡潔な修正項目
• 大規模な更新：2～4 個のセクションに分けた 6～10 個の短い段落

変更が限られている場合、内容を水増ししないでください。

作成ワークフロー

1. PR、コミット、Issue から変更の事実を集めます。
2. 社内モジュールのパスではなく、ユーザーのワークフローに沿って変更をまとめます。
3. 構成を揃えて EN と ZH のバージョンを作成します。
4. DESIGN.md（文体とコンテンツ）／i18n のガイドラインを参照し、用語を確認します。
5. 最後に、AI らしい埋め草を取り除き、文章を簡潔に整えます。

ドキュメント変更履歴のテンプレート（英語）

---
title: <Feature title>
description: <One-sentence summary for users>
tags:
  - <Tag A>
  - <Tag B>
---

# <Feature title>

<Opening paragraph: what changed for users and why it matters.>

<Optional section paragraph for key capability 1.>

<Optional section paragraph for key capability 2.>

## Improvements and fixes

- <Fix or optimization 1>
- <Fix or optimization 2>

ドキュメント変更履歴のテンプレート（中国語）

---
title: <功能标题>
description: <一句话说明>
tags:
  - <标签 A>
  - <标签 B>
---

# <功能标题>

<开场段：这次更新给用户带来的直接变化。>

<可选能力段 1。>

<可选能力段 2。>

## 体验优化与修复

- <优化或修复 1>
- <优化或修复 2>

簡易チェックリスト

• ファイルパスが docs/changelog の命名規則に準拠している
• EN と ZH の両方のバージョンが存在し、記載されている事実が一致している
• 冒頭の段落でユーザーにとっての成果を説明している
• 本文は箇条書きだけでなく、文章を中心に構成している
• Improvements and fixes セクションが簡潔かつ具体的である
• 事実にない主張や、裏付けのない対象範囲が含まれていない