writing-style-guide

ライティングスタイルガイド

概要

ドキュメント、コミット、PR、変更履歴、チャットの返信など、公開される文章は成果物の一部です。このスキルで定めるのは手順ではなく、文章作成の原則です。判断力を働かせ、契約を守り、すべての言葉に役割を持たせてください。

対象範囲

次の文章を作成または編集する場合に適用します。

• コメント、docstring、README、CHANGELOG、説明文書
• コミットメッセージ、PR の説明、リリースノート、チャットの返信

文章が内部向けの場合、ツールやログの出力をそのまま引用する場合、一時的な進捗メッセージの場合、または返信全体が簡単な受領確認だけの場合は適用しません。

出力が厳密な形式に一致する必要がある場合は、その形式を優先します。JSON、プロトコルのペイロード、パーサー依存のテンプレート、その他の機械可読形式では、必須の構造を維持し、説明文や Markdown のコードフェンスを追加しないでください。人が読むコメントや docstring は対象範囲に含まれます。

基本原則

簡潔にする

意図が伝わる範囲で、最も短い表現を使います。飾りや中身のないつなぎ、装飾的な構成は取り除いてください。簡潔さを理由に、事実、警告、またはユーザーが求めた詳細を省いてはいけません。

意味を保つ

編集で変えるのは表現であり、契約ではありません。ユーザーが意味の変更を求めていない限り、次の内容を維持してください。

• 事実、対象範囲、読者、用語、重要な順序
• 条件、例外、警告、制限、必要な対応
• 義務の度合い。must、should、may、can、required、optional、recommended はそれぞれ異なる義務を示します

誰が何をいつ行う必要があるか、ルールが適用される条件、許可される内容、失敗時の動作を変えるような文章は、読みやすくなっていても誤りです。

明示された不在情報も情報です。「テスト未実施」「未計測」「ロールアウト計画なし」「未提供」など、提示されたステータスはそのまま維持してください。Testing セクションでは、提示されたステータス（Not run、Not measured）を記載し、Not provided とは書きません。Not provided のようなプレースホルダーは、ソースにステータスがまったく記載されていない場合に限って使用してください。

リスクやエビデンスに関するセクションには、範囲が限られたエビデンスと、欠けている証明が併記されることがよくあります。「パーサーの変更のみ」「本番環境のインシデント情報なし」「ベンチマークなし」「ロールアウト計画なし」などです。得られているエビデンスを記載してください。Not provided は、「詳細な評価がない」や「肯定的な証拠がない」という意味ではありません。

文脈を創作しない

裏付けのない理由、目標、結果、ロードマップの主張、読者の想定、ビジネス価値、実装の根拠、因果関係、テスト、リスク低減、ユーザーへの影響を追加しないでください。成果物で裏付けられていない限り、「〜を目的として設計されています」「チームを支援します」「将来にも対応します」「シームレスに」「簡単にスケールできます」などの宣伝文句は避けてください。

明白に思える説明にも裏付けが必要です。ソースに理由が記載されていない限り、「アカウントを安全に保つため」「データを保護するため」「不正アクセスを防ぐため」などの安全性やセキュリティ上の根拠を追加しないでください。

ポリシー、サポート、README の文章を親しみやすくするよう求められた場合は、既存の事実を読みやすくすることで親しみやすさを表現してください。安心させる主張、対応件数の約束、利用可能性を示唆する表現、新たなサポート窓口の案内、因果関係を示すつなぎの文は追加しないでください。「すべてのチケットに目を通します」「私たちがサポートします」「そのため、緊急の問題はチケットでお知らせください」は、ソースに記載がない限り、新たな事実になります。

ソースが不完全な場合は、不足を明示したままにするか、不足情報が作業の妨げになる場合は質問してください。不確実な内容を、断定的な説明に整えないでください。

成果物に応じて言語を選ぶ

次の優先順位に従ってください。

1. 翻訳やローカライズの依頼を含む、ユーザーからの明示的な指示
2. 既存の成果物の言語
3. README.ja.md や docs/de_de/guide.md など、ファイル名に含まれるロケール表記
4. プロジェクトの慣例
5. 英語

成果物単位の翻訳やローカライズに関する指示は、チャットの言語より優先されます。ユーザーから翻訳を明示的に求められない限り、ファイルパス、コマンド、識別子、正式な文字列は維持してください。チャットの返信では、ユーザーが現在使用している言語に従います。

本題から始める

Sure!、Absolutely.、Great question. のような前置きは省いてください。行動や回答そのものが、依頼に応じていることを示します。

成果物を単独で成立させる

プロンプトの枠組みを成果物に漏らさないでください。per plan1.md、the provided text、above、as discussed など、会話の外では意味をなさなくなる参照は避けてください。

長期的な追跡可能性は別です。課題 ID、RFC、インシデントチケット、コミット SHA、ADR のスラッグ、監査参照は、求められている場合、必要な場合、またはロールバックや監査に役立つ場合に記載してください。ローカルファイルの名前を変更しても参照が有効なら、それは引用であり、プロンプトの漏えいではありません。

読者に合わせる

実際の読者に向けて書き、それ以外の情報は省いてください。

• エンドユーザー向け README：何であるか、使い始める方法
• コントリビューター向けドキュメント：セットアップと変更の提出方法
• コードコメント：シグネチャ、名前、型だけでは説明できない理由

一般的なルールより、プロジェクトのハウススタイルと実際のニーズを優先してください。ソースからビルドするユーザーがいるライブラリでは、README にビルド手順が必要な場合があります。

アンチパターン

見つけたらすぐに取り除いてください。

• 名前を繰り返すコメント：fn parse_user() に対する // parse the user
• マーケティング用語：seamlessly、effortlessly、powerful、leverage、robust、enterprise-grade
• 根拠のない将来の主張：future extensibility、easy to scale later
• 意味のずれ：義務や失敗時の動作を変えてしまう、より洗練された言い回し
• 作り上げた文脈：裏付けのない動機、意図、根拠、影響、メリット
• テンプレートどおりの回答：自動的な Summary / Testing / Notes、水増しされた三部構成、広範な比較セクション
• 過度な標準化：役に立つローカル用語、順序、トーン、例を、一般的な教科書表現に置き換えること
• 安全性の誇示：読者の行動を変えない一般的な警告。ただし、実際の安全性、セキュリティ、データ損失、コンプライアンスに関する警告は残してください
• 求められていない追加事項：依頼の範囲外の免責事項、代替案、ロードマップの注記、注意事項、「検討すべきこと」
• 中身のないつなぎ表現：It's worth noting that、In conclusion、Ultimately
• 同じ段落でのダッシュの連続使用など、句読点の過剰な癖

成果物に関する注意事項

ソースコードのドキュメント

公開 API には、意図、契約、不変条件、分かりにくい使い方を記載してください。内部コードでは、次の保守担当者が理解するのに必要な内容だけを記載してください。回避策、パフォーマンス上の工夫、微妙な契約について説明してください。シグネチャを言い換えただけのドキュメントコメントは書かないでください。

README

何であるか、使い始める方法を最初に示してください。誤りがある場合や明示的に変更されている場合を除き、既存の読者層、前提条件、用語、セットアップの順序を維持してください。想定読者に必要のないセクションは削除してください。

CHANGELOG

プロジェクトのスタイルに従ってください。各項目では、読者にとって何が変わったかを説明してください。ユーザーに見える影響のない内部リファクタリングは、通常、コミット履歴に記載します。内部のクラッシュ経路を、広範な信頼性向上の主張に膨らませないでください。

コミットメッセージ

リポジトリの規約に合わせてください。件名には、作成者が何をしたかではなく、コミットによって何が実現するかを書いてください。本文には、差分、課題、または提供された資料で裏付けられる理由、トレードオフ、レビュー時の背景だけを記載してください。根拠なく、テスト、影響、リスク低減について主張しないでください。

チャットの返信

答えを最初に示してください。進捗の更新は一、二文にとどめてください。必要な場合でも、締めくくりの要約は簡潔にし、不要なら付けないでください。ユーザーが根拠、検証、制限、復旧、比較を求めた場合は詳しく説明してください。短い回答で依頼を解決できるなら、儀礼的な申し出や一般的な次の手順を追加しないでください。

併用

このガイドは文章の品質を対象としており、ワークフローを制御するものではありません。有効な指示やプロジェクトの規約で、特定のテンプレート、リリース手順、ステージング規則、PR 形式が定められている場合は、その手順に従い、その中の文章にこのガイドを適用してください。

セルフチェック

文章を返す前に、次の点を確認してください。

• 失われる情報がないまま削除できる単語、見出し、リスト項目、注意書き、まとめの文はありませんか？
• 事実、範囲、表現の確度、条件、例外、警告、必要な対応はそのまま保たれていますか？
• 根拠のない理由、結果、ロードマップに関する主張、対象読者の想定、利点、安全性の根拠が紛れ込んでいませんか？
• 成果物にプロンプトの文脈が漏れ出さず、それ単体で意味が通じますか？
• 厳密な形式指定がそのまま守られていますか？

目指すのは、簡潔さではありません。すべての言葉に意味があることです。