選択したコード変更を根拠付きのリリースノートに変換する

コミットメッセージの要約ではなく、根拠を示せる記述を作成する

選択したコード変更から根拠あるリリースノートを作成するには、差分を自ら読み、影響を受ける対象ごとに変更を整理し、変更ごとに参照元を添えて明確に1文を書き、実際に検証された記録を添付して、証拠に裏付けられていない文をすべて削除します。差分を表示しながらCueで説明をディクテーションし、確認済みのテキストからドラフト作成を依頼することも可能です。このテキストのみを扱う演習では、リポジトリへのアクセス、テスト、タグ付け、公開などの権限は付与されません。これはタスクの境界設定であり、Cueや接続されたAgentにそれらの機能が欠けていることを意味するものではありません。

コミットメッセージは作成者の意図を要約したものであり、レビュー後に不完全になったり陳腐化したりすることがあります。リリースノートは、コードを見られない人々に対する期待値へとそれらの主張を変換するものです。単一の情報源をユーザー体験全体の証明として扱うのではなく、対象を差分、テスト、デプロイ記録と照合してください。

3つの方法が利用可能ですが、これらは段階的な手順ではなく代替の選択肢です：

1. 普段お使いのツールに直接ディクテーションする。ノートを作成している編集可能なフィールド（下書き用ノートやドラフトファイル）にフォーカスを合わせ、Cue Dictationで説明を口述します。挿入されたテキストを確認し、自身で送信します。Cueはテキストを入力しているだけであり、ドキュメントの管理元は受信用アプリです。
2. Cue内で外部Agentを選択する。Agentセレクターを備えたCueバージョンでは、ClaudeやCodexがローカルAgentの選択肢として表示されます。リストにClaude、Codex、Geminiなどの項目が表示されていること自体は、有効な接続、ログイン、利用可能なモデル、あるいはリポジトリへのアクセス権があることの証明にはなりません。Agentにデータを渡す前に、アクセス権限を確認してください。
3. サポート対象のモデルでCue Agentを使用する。Agent列でCueを選択し、利用可能なモデルを選択します。これにより文章を作成するモデルは切り替わりますが、ターミナル、リポジトリのチェックアウト、公開権限が付与されるわけではありません。

変更セットが長い場合は、差分を開いた状態で行う音声ウォークスルーをCueの録音・文字起こし機能で保持できます。その文字起こしは加工前の未検証データとして扱い、確定した記録としては扱わないでください。照合作業については録音からコンテキストへのワークフローで説明しています。

変更セット、検証記録、公開先を準備する

このワークフローは、担当者がリリース文の責任を持つことを前提としています。開始する前に、4つの要素を揃えてください。以下の実践演習にはこれら4つがすべて含まれているため、リポジトリがなくても進めることができます。

• 正確な変更セット。説明対象となるコミット範囲、タグ、またはプルリクエストと、それぞれのコミット識別子。「先週の作業」は変更セットではありません。境界を特定できなければ、どの変更をリリースノートに含めるべきか判断できません。
• 差分そのもの。前後の文脈が理解できる十分なコード行を含む変更箇所。コミットの件名行だけでは、コードが何を行うかの根拠にはなりません。
• 検証された内容の記録。どのテストが存在して合格したか、どのプラットフォームで実行されたか、何がカバーされていないか、そして実際に取得された測定値。何も測定されていない場合はそれが記録であり、推測ではなく「記載なし」としてノートに反映されるべきです。
• 公開先とそのルール。ノートの公開場所、承認者、チーム内に情報解禁（エンバーゴ）やセキュリティ情報開示のプロセスがあるかどうか。パッチがユーザーに届く前に詳細を記載してはならない修正もあります。

Cueを使用する場合は、インストールされているバージョンの機能を用い、Dictationのマイクと入力権限を確認してください。書きかけの文が誤って公開されないよう、下書き用のノートから始めてください。デフォルトのショートカットはプラットフォームによって異なり変更も可能です。ガイドに記載されているキーよりも、お使いの環境の設定が優先されます。Dictationのチュートリアルで設定と挿入の確認について解説しています。

ここでの承認管理は、一般的な執筆作業以上に重要です。非公開の差分は外部Agentと共有できない場合があり、リリースノートは組織の行動基準を外部に確約するものになり得ます。共有は必要最小限にとどめ、組織のデータ取り扱い規則に従い、機密情報を入力する前にCueのプライバシーポリシーを確認してください。

実践演習: 架空のノートアプリのリリース 1.4.0

以下はすべて「Example Notes」という架空のアプリ向けの実践教材です。コミットとテスト記録はこの演習のために作成された架空のものであり、コードも不完全な抜粋です。Cue製品自体の挙動、記録されたCueの実行結果、または測定された成果ではありません。リポジトリやAgentアカウントがなくても、手動で情報源を確認できます。4つの情報源を白紙のノートにコピーしてください。この演習では、利用者はsrc/index.mjsから再エクスポートされた関数をインポートするものとし、その他の互換用エクスポートは提供されていないと想定します。

コード、識別子、検証対象の記述を完全に一致させるため、4つの情報源ブロックはすべての言語版で英語のまま維持されています。解説と回答例は個別に翻訳されています。この不完全な差分をプログラムとして実行しないでください。

C-01 — 選択された変更セット（架空の5つのコミット）:

a1b2c3d  feat(export): include the note title in the exported file name
e4f5a6b  refactor(export): extract buildExportName from the export handler
9c0d1e2  fix(export): stop trimming the final page when a note ends with an empty block
7f8a9b0  chore(deps): update markdown-render 2.3.1 -> 2.4.0
3d4e5f6  feat(sync): add background sync retry behind the disabled syncRetry flag

C-02 — これらのコミットの差分（結合して表示）:

--- a/src/export-name.mjs
+++ b/src/export-name.mjs
@@
-export function exportName(note) {
-  return `note-${note.id}.pdf`;
-}
+const MAX_TITLE = 40;
+
+export function buildExportName(note) {
+  const title = (note.title || '').trim().slice(0, MAX_TITLE);
+  const safe = title.replace(/[^\p{L}\p{N} _-]/gu, '').trim();
+  return safe ? `${safe}.pdf` : `note-${note.id}.pdf`;
+}

--- a/src/index.mjs
+++ b/src/index.mjs
@@
-export { exportName } from './export-name.mjs';
+export { buildExportName } from './export-name.mjs';

--- a/src/export-pages.mjs
+++ b/src/export-pages.mjs
@@
 export function exportPages(blocks) {
-  return paginate(blocks.filter(block => block.text.length > 0));
+  return paginate(blocks);
 }

--- a/package.json
+++ b/package.json
@@
-    "markdown-render": "2.3.1"
+    "markdown-render": "2.4.0"

--- a/src/sync.mjs
+++ b/src/sync.mjs
@@
 export function scheduleSync(config, queue) {
+  if (config.syncRetry) return scheduleWithRetry(queue, { attempts: 3 });
   return scheduleOnce(queue);
 }

C-03 — このリリースで実際に検証された記録:

Unit tests for export-name.mjs: 6 cases pass. Covered: usable title, empty title,
title of only punctuation, title over 40 characters, missing title property,
non-Latin title.
export-pages.mjs: no test covers this file, before or after the change.
Manual export: run on macOS only. Not run on Windows.
markdown-render 2.4.0: upstream release notes were not read. Reason for the bump
is recorded only as "routine update".
config/defaults.json: syncRetry is false. Not changed in this release.
Performance: no measurement was taken before or after these changes.
Crash reports: none were linked to any commit in this change set.

C-04 — チームメンバーが作成したリリース文ドラフト（検証対象）:

1. Exports are now named after your note.
2. Fixed a crash that caused the last page to disappear.
3. Export is about twice as fast.
4. Background sync retry is now available.
5. Internal refactor only, no API changes.
6. Updated markdown-render for security.

上記の差分は可読性のために1つのブロックとして表示されています。これだけでは各行がどのコミットで導入されたかは確定できません。回答例の作成にはC-02とファイルパスを引用し、C-01の件名は検証すべき主張としてのみ扱ってください。実際の業務では、コミット識別子を文章に紐付ける前に、各コミット独自の差分を確認してください。

C-04を読む前にC-02を確認してください。記述ごとに異なる修正が必要です。コードの挙動、テストカバレッジ、利用可否はそれぞれ別の問題です。リネームされた関数は、このサンプルの公開エントリポイントから再エクスポートされています。filterの呼び出しを削除するとすべてのブロックがpaginateに渡されますが、その実装は含まれていないため、最終的なPDFのレイアウトもクラッシュの修正も証明されていません。デフォルトで無効なフラグは、別の場所で有効化できるかどうかを教えてくれません。また、JavaScriptのslice(0, 40)はUTF-16コードユニットをカウントするため、必ずしも視覚上の40文字とは限りません。

ウォークスルーを記録し、範囲を限定したドラフトを依頼する

1. 差分と白紙の下書きノートを並べて開きます。公開ツールのリリース説明欄から直接書き始めないでください。
2. ノートのテキストフィールドにフォーカスを合わせ、Cueの設定に表示されているショートカットでDictationを開始し、話す前に録音状態を確認します。音声キャプチャが利用できない場合は、代わりにウォークスルーを入力してください。この演習は音声に依存するものではありません。より長時間の録音を行う場合は、まずリンク先の録音からコンテキストへのガイドにある設定と確認手順に従ってください。
3. 変更点を1つずつ声に出して説明します。それぞれについて、コードが現在どう動作するか、誰に影響があるか、自分自身で何を確認したかを話します。何も確認していない場合は「未検証」と発言してください。このフレーズは後から復元するよりも、その場で残しておく方が確実です。
4. ディクテーションを停止し、処理を待ってから、挿入されたテキストを読みます。コミット識別子、ファイルパス、バージョン番号、フラグ名などは口述せず、情報源から直接貼り付けてください。音声は説明には適していますが、9c0d1e2のような文字列の入力には適していません。
5. 作成したメモの横に情報源を揃えます。修正したテキストがすでに明確であれば、Agentは使わずに自身で編集してください。構成や表現の支援が必要な場合は、Cue Agentまたは接続された外部Agentを開き、C-01からC-04を明示的に貼り付けます。リポジトリウィンドウを開いているだけでは、Agentにコンテキストが渡されたことにはなりません。
6. ドラフト作成リクエストを送信します。裏付けのない文が洗練された文章の中に紛れ込まないよう、リリースノート、根拠テーブル、主張の検証を3つの独立したブロックとして出力するよう依頼します。
7. 検証チェックリストを用いて、C-02およびC-03と照らし合わせてドラフトを自ら確認します。その後、承認されたテキストをリリース管理ツールにコピーし、編集中のバージョンと対象を確認した上で、自身で公開してください。Agentにタグ付け、プッシュ、デプロイ、またはノートの投稿を依頼してはなりません。

リリースノート作成プロンプトをコピーする

ブラケット内の項目を確認済みの情報源に置き換えるか、練習用としてC-01からC-04を貼り付けてください。実際の業務ではプレースホルダーを残さないでください。

タスク: 提供された情報源のみからリリースノートのドラフトを作成してください。外部への公開は行わないでください。
リリース: [バージョンおよびプラットフォーム]
情報源:
C-01 コミット一覧、C-02 差分、C-03 検証記録、
C-04 他者によって書かれたドラフト文。

以下の3つの独立したブロックを出力してください。

ブロックA. リリースノート（以下のカテゴリで分類）:
- 利用者向けの変更点
- このパッケージをインポートしている利用者向け（公開インターフェースが変更された場合のみ）
- 内部および依存関係の変更
- デフォルトで無効、または提供状況が未検証の項目
- 未測定の項目
平易な言葉で変更ごとに1文で記述してください。コードやインターフェースの記述には C-02 とファイルパスを、確認・測定・既定の設定の記述には C-03 を引用してください。結合された差分では個々の行とコミットの対応関係は特定できません。C-01の件名から推測して紐付けないでください。フォールバック、切り捨て、デフォルト値、未テストのファイルなど、情報源に示されている条件や制限を明記してください。

ブロックB. 根拠テーブル: 記述内容、該当するコード行またはC-03の記載項目、および未検証の事項。ソースコードに裏付けられた挙動と、実際にテストされた挙動を区別してください。テストが存在しないことは「未検証」を意味し、直ちに虚偽であることを意味するわけではありません。抜粋から確定できない結果は「未検証」として残す必要があります。

ブロックC. C-04の各記述の検証: 「裏付けあり」「不完全」「裏付けなし」「矛盾」のいずれかとその理由、および可能な場合は証拠上許容される表現。完全に削除すべき記述は別途リストアップしてください。

ルール:
提供された情報源のみを使用してください。原因、クラッシュ、ユーザー数、パフォーマンスの変化、セキュリティへの影響、顧客からの苦情などを推測しないでください。
コミットメッセージは主張に過ぎず、証拠ではありません。差分と矛盾する場合は、差分に従い矛盾を指摘してください。
デフォルトで無効であることは、完全に利用不可であることを証明するものではありません。記録されたデフォルト値を報告し、オプトイン手段、ロールアウト状態、一般的なユーザーへの提供状況を推測しないでください。
C-03に記録されていないテストについて言及しないでください。
ドラフト作成のみを行ってください。タグ付け、リリース、公開、プッシュ、デプロイ、ファイルの編集は行わないでください。

出力例

以下の3つのブロックは、この演習のために作成された例示です。Cueの実際の実行記録でも、製品の出力サンプルでもなく、Agentが返す結果を保証するものでもありません。ご自身の結果と見比べて確認してください。

リリースノートの例:

Example Notes 1.4.0 (架空の演習リリース)

利用者向けの変更点
- エクスポートファイル名は、トリムされたタイトルの先頭40個のUTF-16コードユニットを使用し、使用不可の文字を削除します。文字が残らない場合は note-{id}.pdf になります。提供されたテスト記録には6件の合格ケースが記載されていますが、テストコード自体は提供されていません。(C-02: src/export-name.mjs; C-03)
- 空テキストのブロックを除外することなく、すべてのブロックがpaginateに渡されるようになりました。最終的なPDFのレイアウトおよびクラッシュ修正の有無は未検証です（paginateの実装は提供されておらず、C-03にはこのファイルのテスト記録がありません）。(C-02: src/export-pages.mjs; C-03)

このパッケージをインポートしている利用者向け
- パッケージのインデックスにおいて、エクスポート関数 exportName が buildExportName に変更されました。この演習における公開エントリポイントの前提に基づくと、exportName のインポートは更新が必要です。(C-02: src/index.mjs)

内部および依存関係の変更
- markdown-render が 2.3.1 から 2.4.0 に更新されました。アップストリームのリリースノートは確認されていないため、その影響やセキュリティ上の重要性は確定していません。(C-02: package.json; C-03)

デフォルトで無効
- 再試行処理の分岐が存在しますが、提供されたデフォルト設定では syncRetry は false のままです。オプトインの可否やデプロイ状況は不明です。(C-02: src/sync.mjs; C-03)

未測定の項目
- このリリースにおいてパフォーマンス測定は実施されていません。(C-03)
- この変更セットのいずれのコミットにもクラッシュレポートは紐付けられていません。(C-03)
- エクスポートの手動確認はmacOSのみで実施されました。(C-03)

根拠テーブルの例（ブロックB）:

主張の検証例（C-04のチェックリスト）:

記述5は特に注意して確認すべき点です。「内部的（Internal）」とは対象読者に対する表現であり、単一のファイルに対する表現ではありません。モジュール内でのリネームは内部的なものですが、パッケージのインデックスにおける同様のリネームは、それをインポートするすべての人にとって破壊的変更となります。

すべての記述を差分と照合する

この確認作業は自身で行ってください。手元にドラフトを置き、もう一方にC-02とC-03を並べます。ノートを作成したのと同じAgentに、その記述が正確かどうかの確認を依頼してはなりません。

最後に「逆読み」で確認を終えます。C-01とC-04を伏せ、差分とC-03だけを読んで、自分ならゼロからどう書くかを考えます。残っている主張にはすべて情報源が必要です。根拠のない記述がどこから来たのかを勝手に推測しないでください。その後、誰かが export-pages.mjs のテストを追加するなどして記録が更新された場合は、記述内容とその根拠をセットで更新してください。

この方法が適さないケース

• この演習はテキストのみ、ドラフト作成のみを対象としています。確認済みの情報源を明示的に指定してください。この演習のためにファイルの変更、テスト、ネットワークリクエスト、タグ付け、公開などを許可してはなりません。実際のツールの利用可否はインストールされているバージョン、選択したAgent、接続環境、権限に依存し、この記事によって保証されるものではありません。
• 規模が大きいリリースやスカッシュされたリリースは、1回のパスでは対応しきれません。この方法は全体を通読できる規模の変更セットに適しています。数百件のコミットがある場合は事前の選別が必要であり、無関係な変更を束ねたスカッシュコミットは参照先として不十分です。代わりにファイルや範囲を指定し、その旨を明記してください。
• 非公開のコードは自社環境の外に出せない場合があります。許可なく雇用主やクライアントの差分をAgentに貼り付けないでください。判断に迷う場合は、下書きノートから直接ドラフトを作成し、Agentの手順を省略してください。
• セキュリティ修正には独自のプロセスが存在します。パッチがユーザーに行き渡る前に脆弱性の詳細を説明することはリスクを生む可能性があります。組織の開示ルールは、ここでのいかなる表現の提案よりも優先されます。
• 「コードの取り込み」と「機能の提供」は同一ではありません。フラグ、段階的ロールアウト、サーバー側の制御、ストアの審査などが、マージされたコミットとユーザーの間に介在します。差分だけではそのどれが適用されているかはわかりません。
• リリースノートは品質を保証するものではありません。変更内容を説明するものであり、リリースが正確であること、安全であること、完全であることを証明するものではありません。
• 言語が異なれば、別のレビューが必要です。翻訳されたリリースノートは新たな記述の集合です。英語版を確認したとしても、翻訳版を確認したことにはなりません。

ドラフトや記録に誤りがある場合の対処法

Cueの音声キャプチャや挿入に関する問題については、ご利用のプラットフォーム、Cueのバージョン、モード、および機密情報を伏せた実例を添えて「Cueサポートに問い合わせる」をご利用ください。非公開のリポジトリ、認証情報、未公開のセキュリティ詳細などは送信しないでください。

この演習から生じる疑問点

これを練習するのにリポジトリは必要ですか？ 不要です。C-01からC-04ですべて完結しています。この演習はテキストのみで構成されており、実製品の実コードは含まれていないため、任意のAgentに安全に貼り付けることができます。

Cueが代わりに差分を取得してくれますか？ そうであると思い込まないでください。インストールされているバージョンと選択したAgentが実際にアクセスできる範囲を確認し、依存する前に検証してください。このワークフローでは差分をテキストとして提供するため、自分自身で差分を読む習慣を維持できます。

内部的なリファクタリングはリリースノートに記載すべきですか？ 通常は別のセクションに記載するか、記載しません。基準は変更が小さいかどうかではなく、パッケージをインポートしている人を含め、チーム外の誰かがそれを観測できるかどうかです。

「ユーザーから見える変更はありません」と書くのは安全ですか？ 公開インターフェース、出力形式、エラーメッセージ、デフォルト値、依存関係を確認した後でのみ安全です。演習の記述5は、まさにこの確認で不合格となります。

情報源と関連ワークフロー

このチュートリアルでは、これらのガイド向けに文書化されたCueのDictationおよびAgentの境界について説明しています。Git、CI、パッケージレジストリ、リリースツールとの統合を保証するものではありません。架空の演習よりも、インストールされている環境の操作設定と組織のリリースプロセスが優先されます。

• Cue Dictationチュートリアル: フォーカスされたフィールド、録音状態、およびテキスト挿入のトラブルシューティング。
• Cue Voice Agentチュートリアル: 明示的なコンテキストの指定と範囲を限定した依頼。
• コーディングAgentとCueの併用: ツールへのディクテーション、外部Agentの選択、モデルを用いたCue Agentの利用の違い。
• Codexによるコード変更のレビュー: その変更が正しいかどうかを判断するワークフロー（本ワークフローはすでに承認された変更を説明するもの）。
• Claude Codeによる軽微なバグ修正: リリースノートの対象となる前に、限定的な変更を実装およびテストする。
• 音声による週次ステータス更新の作成: 同僚向けの進捗報告（読者が異なり、各行をコミットに紐付ける必要はありません）。
• 正確な専門用語のディクテーション: 識別子、バージョン、エラー文字列を正確に維持する。
• Cueのプライバシーポリシー: 非公開のコードや記録を提供する前にご確認ください。