core-message-writing

Core Message Writing

コアを際立たせた文章を書くために、最初に考えるべきことに振り切ったガイド。

AIは情報を足し算する方向に偏り、コアがぼやけた冗長な文章を書きがちになる。これを防ぐ。

適用範囲

• 記事・ドキュメント・PR本文・レビューコメント・コミットメッセージ・UI文言・コードコメントなど、文章を成果物として作成・推敲するときに使う。ファイルに残す作業の進捗記録も対象とし、文章の長さは問わない。
• 経緯・判断・結果を整理し、報告・記録としてひとまとまりの文章にするときはチャット上でも使う。
• 通常の会話・質疑応答や、その場の進捗通知には使わない。

このSkillが扱わないこと

• 文体は扱わない。「だ/である調」か「ですます調」か、カジュアルか落ち着いたトーンかは、対象媒体に合わせて別途決める。ここで扱うのは媒体に依存しない「コアを際立たせる」部分だけ。
• 原文をそのまま引用・転記する部分や機械処理用の構文は、文章として推敲しない。文章を推敲するときも、指定された形式や必要な情報は維持する。

根本姿勢

コアメッセージを明確に際立たせた上での、最小限の文章が最も良い。目的は文章を短くすることではなく、コアを際立たせること。その結果としての最小限であって、順序を逆にしない。

そのために、想定読者 × 読後感を決め、それを軸にすべてを判断する。AIは情報を足し算してコアをぼやかしがちなので、書き終えたら必ず見直す。

① 書く前に決める（このSkillの心臓）

書き始める前に、次の2つを言語化する。これが定まらないままだと必ずコアがぼやける。

• 想定読者：誰が読むか。その人がすでに知っていることは何か
• 読後感・とってほしいアクション：読んだ後、読者にどう感じてほしいか・何をしてほしいか

想定読者と読後感は、まず依頼と会話の文脈から判断する。その判断を毎回ユーザーに説明・確認する必要はない。短い成果物では、伝えるべきことを定め、書いた後にコアが伝わるかを見直して不要な情報を削るだけでよい。

長い文章では、さらに次も決めておくと軸がぶれにくい。

• サブメッセージ：コアを支える要点（2〜3個まで）
• 伝えないこと：あえて書かないと決めるもの（スコープ外）

決めた読後感の達成に必要な具体（コマンド・手順・実例など）は、「自明だから」で省略しない。読者が再現・納得できなくなる。

② 書いた後に、コアを際立たせる方向へ調整する

判断軸は1つ：それはコアを際立たせるか、ぼやかすか。「繰り返しは消す」「前提は省く」のような一律ルールではない。同じ要素でも、際立たせるなら残す（むしろ足す）、ぼやかすなら削る。

• 繰り返し：コアを際立たせる繰り返しは効果的に使ってよい。それ以外の繰り返し（脇道の蒸し返し、同じことの言い換え）はコアをぼやかす → 削る
• 同じ主張を言い換えて隣接で2回3回重ねない。読者が推論できる中間ステップも書かない（非自明な因果なら1回だけ書く）
• 同じ主張を別セクションで丸ごと再説明しない。締めなどで思い起こさせたいときは、再説明ではなく短い一文で想起させる
• 前提知識：コアに重要な前提は、際立たせるためにあえて入れる・強調する。コアに関わらない前提は削る
• 一般論の前置き・枕詞（「近年〜」「〜が重要な時代だ」）：ほぼ常にコアをぼやかす → 削り、本題から入る
• 回りくどい言い回し・読めば分かる逐一説明：コアに寄与しないなら削る
• 低情報な括弧での言い換え・補足：括弧の補足はデフォルトでは削る。残すのは「①想定読者がその語を知らない ②その語がコアに繋がる」の両方を満たす時だけ
• NG：読者が既に知っている語の展開・和訳。「EM（エンジニアリングマネージャー）」「デプロイ（本番への反映）」「プロファイル（認証情報の置き場）」
• 読者が直接の語を分かるなら、言い換えを括弧で重ねず最初からその語を使う（「exponential backoff」で伝わるならそう書く）
• OK（例外）：想定読者がその語の専門外で、かつコアに繋がる補足。「NVC（非暴力コミュニケーション）」。読者が知らない略語を本文で繰り返し使うときの初出定義も同様にOK
• 対象外：括弧で具体値を足すのはこの原則の対象外で、むしろコアを際立たせる足し算（「実行時間が短縮された（20分→8分）」）

際立たせる側として、「自明だから」で削ってはいけないもの：

• コアに直結する説明（各部の意味づけなど）。削ると読者が引っかかる
• つなぎ（「まず〜」「次に〜」）。先に何をするか示すと認知負荷が下がる

見出し

• 見出しは必要な時だけ使う。短い記事や単一トピックならフラットに書く
• 見出し名だけで中身が想像できるよう具体的に書く
• NG「〜の工夫」「〜について」「〜の仕組み」
• OK「commit messageが冗長すぎる問題」「サブエージェントで会話文脈から切り離す」
• 見出しだけを上から読んだとき、全体のストーリーが伝わるようにする
• 構成にメリハリをつける（重要な部分は詳しく、そうでない部分はさらっと）。全セクションを均等に書かない

最終チェックリスト

書き終えたら次を自問する。

• [ ] 決めた読後感に向かって、コアが冒頭から立っているか
• [ ] 一般論の枕詞で入っていないか
• [ ] コアをぼやかす繰り返し・脇道の前提が残っていないか（際立たせる繰り返しはOK）
• [ ] 削りすぎて、コア直結の説明やつなぎまで消していないか
• [ ] 見出しだけ読んでストーリーが伝わるか