AkiGarage/readme-release-sync

READMEリリース同期

このスキルは、READMEのコピー、リリースノート、チェンジログ、製品スクリーンショット/GIF、またはバイリンガル製品ドキュメントに触れるタスクがあるときに使用してください。

目的は、メンテナのレビュー負担を軽減することです。レビュアーが古い名前、スクリーンショット、機能説明、または英語/日本語の不一致を見つける前に、ドキュメントが実際の製品状態と一致しているようにします。

基本ルール

既存のドキュメントだけに基づいて製品向けドキュメントを編集しないでください。最初に現在のソース・オブ・トゥルース（真実の情報源）を特定します。これには、アプリケーションコード、UI文字列、スクリーンショット/GIF、リリースブランチ、バージョンファイル、パッケージメタデータ、またはユーザーが提供した最新のスクリーンショット/ビデオが含まれます。

ワークフロー

1. ターゲット状態を確定する

   • リポジトリファイルまたは明示的なユーザー指示から、製品/アプリ名、ブランチ、バージョン、バイナリ名、およびプラットフォーム範囲を確認します。
   • 説明されている機能の関連する実装またはUI文字列を調査します。
   • コードまたはブランチのコンテキストが明らかに矛盾しない限り、ユーザーが提供した最新のスクリーンショット/ビデオを権威ある視覚的証拠として扱います。

2. ドキュメントとメディアを一緒に更新する

   • UIが変更された場合は、古いスクリーンショット/GIFを置き換えます。
   • すべての画像参照が存在し、意図したファイルを指していることを確認します。
   • スクリーンショットが現在の製品名、メニューラベル、バージョン、またはUI状態と視覚的に矛盾していないことを確認します。
   • 削除された動作を説明する古いメディア参照は削除します。
   • プライベートリポジトリから供給されるパブリックリリースの場合、スクラブ（機密情報削除）されたスナップショットがパブリックリポジトリにコピーされた後、release/vX.Y.Z ブランチでパブリックリポジトリのパブリックREADMEファイルを更新します。プライベートリポジトリのREADMEを最終的なパブリックのソース・オブ・トゥルースとして依存しないでください。
   • パブリックの CHANGELOG、リリースドラフトノート、インストールドキュメント、およびパブリック開発ログを、同じリリース向けドキュメントセットの一部として扱います。これらはREADMEと同じ製品名、バージョン、アセット名、プライバシーに関する記述、およびユーザー向け表現を使用する必要があります。

3. バイリンガルドキュメントの同等性を維持する

   • 英語と日本語のセクションを主張ごとに比較します。
   • 両方の言語で同じ製品事実、機能の順序、注意事項、およびセットアップ要件を維持します。
   • 重要な動作を一方の言語だけで説明したままにしないでください。

4. 読みやすいパブリックREADMEコピーを作成する

   • 最初に読むセクションはスキャンしやすくします。短い段落、段落ごとに1つのアイデア、および読みやすさを向上させる空白行を使用します。
   • 製品が何をするのか、ユーザーが何を見たり実行したりできるのかを最初に述べます。実装の仕組みは、セットアップ、安全性、またはトラブルシューティングに関係する場合にのみ後で説明します。
   • 詰め込まれた機能文よりも、明確な動作行を優先します。良い形式は、1文の概要とそれに続く2〜4行の簡潔な機能説明です。
   • UI動作については、可視結果を説明します。ドラッグして移動、端またはコーナーからリサイズ、ダブルクリックでリセットなど。ユーザーが必要としない限り、ヒット領域、カーソル矩形、スケーリング内部、または正確なデフォルトパーセンテージなどの内部フレームワークの詳細は避けます。
   • 詳細情報は本当に役立つ場所に保持しますが、パブリックREADMEにメンテナ専用の実装説明を記載しないでください。
   • リリースノートとチェンジログエントリにも同じ可読性ルールを適用します。ユーザーが認識できる修正、インストール手順、またはトラブルシューティングパスに影響を与えない限り、正確なデフォルトパーセンテージ、ヒット領域表現、カーソル矩形の仕組み、またはビルドシステムの詳細などの内部精度は避けます。

5. 日本語読みやすくする

   • 自然な場合は通常の日本語UI用語を優先します。タブ、詳細パネル、マウスオーバー、最小表示、フローティングタブ。
   • コマンド、パス、パッケージ名、アプリ名、URL、コード識別子などの技術的なリテラルは英語のままにします。
   • 冗長な機能リストと繰り返しの段落を削除し、メインの機能セットを一般的な日本語読者がすぐにスキャンできるようにします。

6. 古い製品のずれをスキャンする

   • 古い製品名、古いアプリ名、古いバイナリ名、古いリポジトリ名。
   • 過去のチェンジログエントリ以外の古いバージョン番号。
   • 廃止されたUIラベル、削除されたプラットフォームに関するメモ、および古い動作のスクリーンショット。
   • インストールされたCLIまたはパッケージのみが必要な場合に、依存関係が実行中である必要があると暗に示す記述。

7. クローズ前に検証する

   • 利用可能な場合は、関連するドキュメントのlint/checkコマンドを実行します。
   • 古い名前/バージョン/ラベルをスキャンするために、範囲を限定した rg スキャンを実行します。
   • READMEファイル、チェンジログ、リリースノート、およびリリースに含まれるパブリックドキュメント全体に対して、古い/プライベート/内部すぎる表現のスキャンを実行します（トップレベルのREADMEだけでなく）。
   • READMEの画像リンクが存在することを確認します。
   • リリースPRの場合、メンテナにブランチ/PRのGitHubレンダリング済みREADME URLを提供し、明示的な視覚承認を待ちます。これはユーザーが実際に目にするGitHub表示と一致する必要があります。ローカルプレビュー、生のMarkdown、静的スクリーンショット、または自動チェックは補助的な証拠としてのみ使用します。
   • パブリックリポジトリの git diff を調査して、READMEの主張、バージョンメタデータ、リリースアセット名、およびコピーされた実装変更が一致していることを確認します。
   • パブリックリリースの場合、タグまたはGitHub Releaseの作成前に、release/vX.Y.Z ブランチ -> PR -> CI -> マージ のフローを優先します。直接の main へのプッシュは、メンテナが明示的にPRゲートをスキップするように依頼した場合のみ使用します。
   • コードが変更された場合は、関連するテストまたはビルドを実行します。
   • 編集したファイルだけでなく、ソース・オブ・トゥルースのチェックのサマリーを報告します。

出力チェックリスト

終了前に、以下を報告します。

• 確認した製品名/バージョン/ブランチ;
• 確認したメディア参照;
• 確認した日本語/英語のパリティ;
• GitHubレンダリング済みREADMEの視覚承認を受けたか、または明示的にまだ保留中;
• 古い表現のスキャン結果;
• テスト/ビルド/ドキュメントチェックを実行したか、または実行しなかった理由。