writing-guidelines

執筆ガイドライン

忙しく、あなたの作業を見ていない読者に向けて書きます。気の利いた表現より読みやすさを、網羅性より明確さを優先します。

ルール

• 結論から始めます。 最初の文で、何が起きたのか、あるいはそれが何なのかを答えます。「要点だけ教えて」と言われたとき、読者が知りたい答えを示します。補足はその後に続けます。
• 余分な表現を削ります。 「ほんの」「単に」「基本的に」「するために」「注意が必要です」を削除します。削除しても文の意味が変わらないなら、その文を削除します。
• 抽象的な表現より具体的な表現を使います。 ファイル名、数値、コマンドを明記します。「高速化」より「ビルド時間を40秒から9秒に短縮」のほうが具体的です。
• 能動態を使い、1文につき1つの内容にします。 3つの要点を含む長文より、1つずつ要点を伝える短文のほうがすばやく読めます。
• 用語を統一します。 プロジェクト独自の語彙を使い、同じものには毎回同じ言葉を使います。共通言語としての CONTEXT.md がある場合は、その名称に合わせます（domain-modeling を参照）。
• 読みやすさを優先し、ぶっきらぼうな文にしません。 短いことと明確であることは別です。読者に不要な情報を削って短くします。文章を断片や矢印の連鎖（A -> B -> fails）、独自の略語に圧縮しないでください。

エラーメッセージとUI文言

• 何が起きたのか、次に何をすべきかを伝えます。Error: config missing よりも、Config not found at ./app.config.ts. Create it or pass --config <path>. のほうが適切です。
• 行き止まりを作りません。失敗を伝えるときは、次の手順も示します。
• プロダクトの語調に合わせ、感嘆符や余分に熱のこもった表現は避けます。

AIが書いたように見える表現を取り除く

• ダッシュ（エムダッシュとエヌダッシュ）は使わず、前後にスペースを入れたハイフンか句点を使います。これは機械が書いた文章を見分ける最も確実な特徴です。
• 空疎な書き出し：「めまぐるしく変化する現代社会では」「注目すべき点は」。
• ためらい表現の重ね合わせ：「おそらく、ひょっとすると、もしかしたら」。
• 二項対立を使った強調：「Xではありません。Yです。」という修辞的な表現。
• 1文で済む内容を、過剰に構造化した箇条書きにしないでください。

出力

編集するときは、簡潔に整えた文章を提示します。求められた場合は、変更点ごとに1行の説明を添えます。元の文章を褒めて編集内容を水増ししないでください。