messaging-framework

メッセージングフレームワーク

コミット、PR の説明、ブランチ名、技術ドキュメントを書く際の基本原則です。

2 つの目標

目標	目的
情報を伝える	作業の内容を読者が理解し、覚えられるようにします
価値を訴える	レビューにかける労力に見合う価値があることを示します

課題を軸にしたパターン

実際の課題のみを軸にメッセージを構成します。

• 確認された問題
• その後に生じる影響

解決策の説明が中心となる PR 本文は書かないでください。レビュアーは差分を確認します。変更内容からすでに分かることを繰り返すためだけに、テスト計画のセクションを追加しないでください。

課題には、エラー、ワークフローの重複、コストのかかるプロセス、分かりにくい挙動など、実際に経験したことと、その結果を記述してください。

悪い例	良い例
「共通インターフェイスがない」	「ローカル開発のオーケストレーションが環境ごとに重複していたため、コピー間で不整合が生じていた」
「エラーのコンテキストが失われた」	「バックエンドの失敗が誤った結果にマッピングされ、技術的なエラーがドメイン上の結果に見えていた」

文の構成

次の形式を優先してください。

• 「[Verb] メカニズムによってメリットを実現する」
• 「メリットを実現するためにメカニズムを[Verb]する」

例：

• 「設定とログの整形を自動化してローカル開発を高速化する」
• 「アセット同期の競合状態を修正してデータ損失を防ぐ」

成果物ごとの形式

成果物	形式	長さ
ブランチ名	TICKET/short-description	短く
コミットの件名	TICKET: type(scope): verb benefit by mechanism	100 文字以内
コミットの本文	課題のみ	中程度
PR タイトル	コミットの件名と同じ	短く
PR の説明	課題と 1 行のアプローチ	中程度

アンチパターン

• 「機能を追加する」
• 「バグを修正する」
• 「コードをリファクタリングする」
• 「依存関係を更新する」
• PR 本文での解決策のチェックリスト
• 確認された問題ではなく、汎用的な抽象化を示すこと