create-changelog-announcement

変更履歴のお知らせを作成する

このスキルでは、次の内容を含む完全な変更履歴のお知らせの作成方法を説明します。

1. /docs/blog/entries/ の変更履歴エントリーページ（/changelog の変更履歴インデックスは、ページネーション付きでこれらのページから自動生成されます）
2. /web/oss/src/components/SidebarBanners/data/changelog.json のサイドバーのお知らせカード
3. /docs/src/data/roadmap.ts のロードマップ更新
4. GitHub ディスカッションの終了（該当する場合）
5. ソーシャルメディアでのお知らせ（LinkedIn、Twitter、Slack）

主な担当事項

1. 変更履歴の作成ワークフロー全体

変更履歴のお知らせを作成するたびに、連携した2つの成果物を作成します。

A. 変更履歴エントリー（docs/blog/entries/[feature-slug].mdx）：

• 機能や変更についての包括的な説明

• コード例、スクリーンショット、または埋め込み動画

• 関連ドキュメントへのリンク

• ユーザーにとってのメリットとユースケース

• 2種類の異なる文章：/changelog インデックス用の短い要約と、エントリーページ用の詳細な説明です。短いバージョンは、編集して作成する1〜2段落の要約です（長いバージョンの冒頭と異なっていてもかまいません。長いバージョンの最初の数行をそのままコピーしないでください）。ファイルは次の構成にしてください。

  ---frontmatter---
  
  import Image from "@theme/IdealImage"; {/* only if you use <Image> */}
  
  <Summary>
  
  {/* Optional hero video or screenshot, shown on the index */}
  
  Curated 1-2 paragraph summary shown on the /changelog index.
  
  </Summary>
  
  {/* truncate */}
  
  {/* Repeat the hero video/screenshot here so it also shows on the page */}
  
  Full write-up (## sections, videos, code) shown on the entry's page.
  

  <Summary> はインデックス一覧でのみ（プレビューとして、「続きを読む」リンクとともに）表示されます。エントリーページでは何も表示されないため、ページには詳細な説明だけが表示され、内容が重複しません。機能にデモ動画やスクリーンショットがある場合は、インデックスに表示されるよう <Summary> 内に配置し、エントリーページにも表示されるよう、マーカーの下にある詳細な説明にも配置してください。埋め込み動画と画像は CSS で中央に配置され、幅が 680px に制限されます。そのため、既存の <iframe>／<Image> マークアップをそのまま使用してください。

B. サイドバーのお知らせ（web/oss/src/components/SidebarBanners/data/changelog.json）：

• 1文の説明
• 詳細ドキュメントへのリンク
• 日付を含む一意の ID

2. 情報の収集

エントリーを作成する前に、次の情報を集めてください。

• 機能名と説明
• バージョン番号（不明な場合は「この変更履歴エントリーの対象バージョンは何ですか？」と尋ねてください）
• リリース日（指定がなければ今日の日付にします）
• ユーザーがスクリーンショットや動画を持っているかどうか（言及があるのに提供されていない場合は尋ねてください）
• 関連ドキュメントへのリンク

明確なバージョン識別子と機能の説明がない状態では、決して作業を進めないでください。

3. 文体のガイドライン

次のガイドラインに厳密に従ってください。

• 何よりも明確さを優先：専門用語以外は、高校2年生程度が理解できる英語を使います
• 能動態を使う：「会話を追跡できるようになりました」ではなく「会話を追跡できます」
• 短い文にする：簡潔な文を基本とし、流れを良くする場合に限り長い文を使います
• 完全文にする：簡潔さによって読みやすさが明らかに向上する場合を除き、断片的な表現は避けます
• emダッシュ（—）を使わない：ピリオド、括弧（）、またはセミコロン ; を使います
• 書式設定は最小限にする：太字や箇条書きは、内容を見つけやすくする場合に限り、控えめに使います
• ユーザーを中心に書く：「追加しました」ではなく「利用できるようになりました」と書きます
• 機能よりメリットを伝える：何を構築したかではなく、ユーザーが何をできるかを説明します

例：

❌ 悪い例：「関連するトレースをグループ化できる新しいセッション追跡システムを実装しました。これにより、会話を分析しやすくなります。」

✅ 良い例：「関連するトレースをセッションにグループ化できるようになりました。これにより、会話全体を分析し、複数のターンにわたる指標を追跡できます。」

4. ID と命名規則

変更履歴エントリーファイルの命名：

• 説明的な名前を kebab-case で付けます
• 例：chat-sessions-observability.mdx、pdf-support-in-playground.mdx
• 60文字未満にします

サイドバーのお知らせ ID：

• 形式：changelog-YYYY-MM-DD-feature-slug
• 例：changelog-2026-01-09-chat-sessions
• 競合を防ぐため、一意である必要があります

バージョン形式：

• セマンティックバージョニングを使用します：v0.73.0
• エントリーのタグとして含めます（tags: [v0.73.0]）。変更履歴インデックスでは、日付の横にバージョンチップとして表示されます

5. メディアの取り扱い

ユーザーが動画やスクリーンショットに言及した場合：

YouTube 動画の場合（詳細なエントリー内）：

<div style={{display: 'flex', justifyContent: 'center', marginTop: "20px", marginBottom: "20px", flexDirection: 'column', alignItems: 'center'}}>
  <iframe
    width="100%"
    height="500"
    src="https://www.youtube.com/embed/VIDEO_ID"
    title="Feature Demo"
    frameBorder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    allowFullScreen
  ></iframe>
</div>

画像の場合（詳細なエントリー内）：

<Image
  img={require('/static/images/changelog/feature-name.png')}
  alt="Feature description"
  style={{display: 'block', margin: '20px auto', textAlign: 'center'}}
/>

不明な点がある場合は詳細を確認します：

• 「デモ動画の YouTube URL はありますか？」
• 「プレースホルダーをいくつ追加すればよいですか？」
• 「本文のどこに画像を配置すればよいですか？」

6. 機能ドキュメントとの連携

関連ドキュメントを必ず検索します：

1. /docs/docs/ に専用の機能ページがあるか確認します
2. 見つかった場合は、概要と詳細なエントリーの両方からリンクします
3. 見つからない場合は、その旨を記載して「この機能のドキュメントを作成しますか？」と確認します

ドキュメントリンクの形式：

• 相対パスを使用します：/observability/trace-with-python-sdk/track-chat-sessions
• 外部リンクでない限り、絶対 URL は使用しません

7. 品質確認チェックリスト

仕上げる前に、以下を確認します：

• バージョン番号が記載され、正しい
• エントリーとサイドバーのお知らせを作成した
• 厳選した概要を<Summary>で囲み、その後に{/* truncate */}を置き、続けて記事全文を記載した
• 可能な限り能動態を使用した
• em ダッシュが含まれていない
• 該当する場合、機能ドキュメントへのリンクを記載した
• 言及がある場合、メディアのプレースホルダーを追加した
• 執筆スタイルのガイドラインに従った
• ID とファイル名が規則に従っている
• 必須のフロントマターをすべて含めた

8. ファイルの場所

変更履歴のエントリー：

• パス：/docs/blog/entries/[feature-slug].mdx
• 例：/docs/blog/entries/chat-sessions-observability.mdx
• 変更履歴のインデックスページ（/changelog）は、これらのファイルから自動的に生成されます（date順、ページ分割あり）。別途概要ファイルを管理する必要はありません。

サイドバーのお知らせ：

• パス：/web/oss/src/components/SidebarBanners/data/changelog.json
• JSON 配列の先頭に新しいエントリーを追加します

ステップごとのワークフロー

ステップ 1：情報を集める

不足している情報があれば、ユーザーに確認します：

- What version is this for?
- Do you have a demo video or screenshots?
- What's the primary benefit users will get from this?
- Are there existing docs for this feature I should link to?

ステップ 2：関連ドキュメントを検索する

# Search for related docs
grep -r "session" docs/docs/observability --include="*.mdx" --include="*.md"

ステップ 3：詳細なエントリーを作成する

/docs/blog/entries/[feature-slug].mdxを作成します：

重要：正しいフロントマター形式を使用してください（authors フィールドは不要）：

---
title: "Feature Name"
slug: feature-name-slug
date: YYYY-MM-DD
tags: [vX.Y.Z]
description: "One-sentence description of the feature."
---

{/* NOTE: Do NOT add an H1 heading here. The frontmatter title is automatically rendered as H1 by Docusaurus. */}

<Summary>

[Curated 1-2 paragraph summary. This is the SHORT version shown on the
/changelog index. It can differ from the long write-up's opening.]

</Summary>

{/* truncate */}

## Key Capabilities

- **Capability 1**: Description
- **Capability 2**: Description
- **Capability 3**: Description

## How It Works

[Step-by-step explanation or code examples]

```python
# Code example if applicable
import agenta as ag
ag.tracing.store_session(session_id="conversation_123")

ユースケース

[この機能が役立つ実際のシナリオ]

はじめに

[ドキュメント、チュートリアル、ガイドへのリンク]

• 機能ドキュメント
• チュートリアル

次のステップ

[任意：今後予定されている内容や関連機能]

### Step 4: Write the Summary and Place the Truncate Marker

The `/changelog` index shows the `<Summary>` block (with a "Read more" link);
the entry page shows everything below `{/* truncate */}`. So:

- Put the curated short summary inside `<Summary>...</Summary>`, then the
  `{/* truncate */}` marker, then the full write-up.
- Leave blank lines inside the `<Summary>` tags so the content parses as
  Markdown (links and bold work).
- If there is a demo video or screenshot, include it inside `<Summary>` (so it
  shows on the index) and again in the write-up below the marker (so it shows
  on the entry page).
- Every entry needs content below the marker (the full write-up); that is what
  the entry page renders.

### Step 5: Add Sidebar Announcement
Add to `/web/oss/src/components/SidebarBanners/data/changelog.json`:

```json
[
    {
        "id": "changelog-2026-01-09-feature-name",
        "title": "Feature Name (Keep Under 40 Chars)",
        "description": "One-sentence benefit users get from this feature.",
        "link": "https://agenta.ai/docs/changelog/feature-slug"
    },
    // ... existing entries
]

ステップ 6：ロードマップを更新する

/docs/src/data/roadmap.tsを更新します：

機能がロードマップに掲載されていた場合：

1. inProgressFeatures配列からその機能を探します
2. shippedFeatures配列の先頭に移動します
3. PlannedFeature形式からShippedFeature形式に変換します：
   • githubUrlフィールドを削除します
   • 詳細なエントリーを指すchangelogPathフィールドを追加します
   • ISO 形式の日付（YYYY-MM-DD）を指定したshippedAtフィールドを追加します

例：

// Move from inProgressFeatures to top of shippedFeatures:
{
  id: "chat-session-view",
  title: "Chat Sessions in Observability",
  description: "Track multi-turn conversations with session grouping...",
  changelogPath: "/docs/changelog/chat-sessions-observability",
  shippedAt: "2026-01-09",
  labels: [{name: "Observability", color: "DE74FF"}],
}

ステップ 7：GitHub ディスカッションを確認する

ロードマップ項目に GitHub ディスカッションを指すgithubUrlが含まれていた場合：

1. ロードマップのエントリーからディスカッションの URL を確認します
2. ディスカッションをクローズする必要があるか確認します（不明な場合はユーザーに尋ねます）
3. gh CLI を使用する場合：gh issue close <number> --repo Agenta-AI/agenta --comment "Shipped in v0.73.0"
4. CLI を利用できない場合は、手動でクローズできるようディスカッションの URL を記録します

ステップ 8：ソーシャルメディアのお知らせを作成する

ガイドライン： .claude/skills/write-social-announcement/SKILL.mdに従います

このスキルには、よくある AI らしい文章表現を避け、自然なお知らせを書くための包括的なガイドラインが記載されています。主なポイント：

• 書き出しに変化をつけます（毎回「We just shipped」で始めない）
• AI でよく使われる語彙を避けます：「crucial」「pivotal」「showcases」「underscores」「landscape」「tapestry」
• 文末で表面的な「-ing」形の分析をしません
• 修辞疑問文を使いません（「Working with large test sets?」など）
• ありきたりな結びを避けます（「Small changes, but they add up」など）
• 具体的かつ簡潔に伝えます

LinkedIn、Twitter、Slack 用のセクションを含むSOCIAL_ANNOUNCEMENTS.mdを作成します

ステップ 9：ビルドと検証

重要：完了する前に、必ずビルドを実行してエラーがないことを確認してください。

1. ドキュメントのビルドを実行します：

cd docs && npm run build

2. ビルドに失敗した場合は、すぐにエラーを修正します：

   • よくあるエラー：authors フィールドがない - フロントマターから authors: [agenta] を削除します
   • 正しいフロントマター形式（既存のエントリーの例）：

     ---
     title: "Feature Name"
     slug: feature-name-slug
     date: YYYY-MM-DD
     tags: [vX.Y.Z]
     description: "Brief description"
     ---
     

   • 無効な MDX 構文 - 閉じられていないタグや不正な JSX がないか確認します
   • リンク切れ - 相対パスがすべて存在するか確認します

3. チェックリストを確認します：

• ビルドが正常に完了した（docs/ で npm run build を実行）
• 一貫性を確認するため、すべてのファイルを読んだ
• リンクが機能することを確認した（相対パスが正しい）
• サイドバーのお知らせの JSON 構文を確認した
• ファイル間でバージョン番号が一致していることを確認した
• 執筆スタイルがガイドラインに沿っていることを確認した
• ロードマップが正しく更新されている
• ソーシャルメディア向けのお知らせを作成した

よくあるパターンと例

例 1：新機能のお知らせ（チャットセッション）

詳細なエントリー（docs/blog/entries/chat-sessions-observability.mdx）：

---
title: "Chat Sessions in Observability"
slug: chat-sessions-observability
date: 2026-01-09
tags: [v0.73.0]
description: "Track and analyze multi-turn conversations with session grouping, cost analytics, and conversation flow visualization."
---

{/* NOTE: Do NOT add an H1 heading here. The frontmatter title is automatically rendered as H1 by Docusaurus. */}

## Overview

Chat sessions bring conversation-level observability to Agenta. You can now group related traces from multi-turn conversations together, making it easy to analyze complete user interactions rather than individual requests.

This feature is essential for debugging chatbots, AI assistants, and any application with multi-turn conversations. You get visibility into the entire conversation flow, including costs, latency, and intermediate steps.

## Key Capabilities

- **Automatic Grouping**: All traces with the same `ag.session.id` attribute are automatically grouped together
- **Session Analytics**: Track total cost, latency, and token usage per conversation
- **Session Browser**: Dedicated UI showing all sessions with first input, last output, and key metrics
- **Session Drawer**: Detailed view of all traces within a session with parent-child relationships
- **Real-time Monitoring**: Auto-refresh mode for monitoring active conversations

## How It Works

Add a session ID to your traces using either the Python SDK or OpenTelemetry:

**Python SDK:**
```python
import agenta as ag

ag.tracing.store_session(session_id="conversation_123")

OpenTelemetry：

span.setAttribute('ag.session.id', 'conversation_123')

UI はセッション ID を自動的に検出し、トレースをまとめてグループ化します。セッション ID には、UUID、複合 ID（user_123_session_456）、カスタム形式など、任意の形式を使用できます。

ユースケース

• チャットボットのデバッグ：ユーザーから問題が報告されたときに、会話の流れ全体を確認できます
• 複数ターンのエージェントを監視：エージェントが追加の質問やコンテキストをどのように処理するかを追跡できます
• 会話コストを分析：どの会話にコストがかかっているのか、その理由を把握できます
• パフォーマンスを最適化：単一のリクエストだけでなく、会話全体にわたるレイテンシの問題を特定できます

はじめに

詳しくは、ドキュメントをご覧ください：

• チャットセッションの追跡（Python SDK）
• セッションの追跡（OpenTelemetry）
• オブザーバビリティの概要

次の展開

セッションレベルの注釈、セッションの比較、自動セッション分析などの機能を追加し、セッション追跡を引き続き強化していきます。

**Sidebar Announcement**:
```json
{
    "id": "changelog-2026-01-09-chat-sessions",
    "title": "Chat Sessions in Observability",
    "description": "Track multi-turn conversations with session grouping and cost analytics.",
    "link": "https://agenta.ai/docs/changelog/chat-sessions-observability"
}

例 2：インテグレーションのお知らせ

インテグレーションについては、次の点に重点を置きます：

• 新たに何と連携できるようになったか
• セットアップがどれほど簡単か（実際に該当する場合は「コード 1 行」と記載）
• そのインテグレーションならではの主なメリット
• インテグレーションのドキュメントへのリンク

例 3：改善のお知らせ

改善については、次の点を強調します：

• 定量化できる改善（例：「10 倍高速化」「50% 削減」）
• 大幅な改善の場合は、変更前と変更後の比較
• ユーザーにとってのメリット（時間の節約、より良い使用体験）

意思決定のフレームワーク

情報が不足している場合：

• バージョン番号が不明確 → 作業を進める前にすぐ確認します
• 機能の範囲が曖昧 → 説明や例を求めます
• メディアの利用可否が不明 → プレースホルダーを追加する前にユーザーに確認します
• 分類が不明確 → 新機能、改善、バグ修正のどれに当たるか尋ねます

既存のエントリーを編集する場合：

• 事実の正確性と元の意図を必ず維持します
• 意味を変えずに、明確さと文体を改善します
• 技術的な誤りに気づいた場合は、推測せずユーザーに伝えます

出力形式

変更履歴のお知らせを作成する際は、次の内容を提示します：

1. docs/blog/entries/[slug].mdx のエントリー本文（<Summary> 内に要約をまとめ、その後に {/* truncate */} を置き、続けて全文を記載）
2. changelog.json に追加するサイドバーのお知らせの JSON
3. 関連するドキュメントを確認したことの報告
4. 必要な質問や確認事項

不明確な要件を積極的に見つけてください。 推測せず、具体的な質問をしてください。目標は、修正を加えなくてもすぐに公開できる変更履歴エントリーを作成することです。

成功のためのヒント

1. 既存のエントリーを先に読む：新しいエントリーを作成する前に、entries/ 内の最近のエントリーを2～3件読み、文体と構成を合わせます
2. 簡潔にする：ユーザーは変更履歴をざっと読みます。各文の冒頭でメリットを伝えます
3. リンクを積極的に追加する：ユーザーが詳しい情報を簡単に見つけられるようにします
4. 作成した内容を確認する：エントリーを声に出して読み、不自然な表現がないか確認します
5. 一貫性が大切です：エントリーとサイドバーのお知らせで用語が一致していることを確認します

---

忘れないでください：何千人もの開発者に新機能を紹介する、ユーザー向けドキュメントを作成しています。明確で、魅力的で、理解しやすい内容にしてください。