markdown-writinglisted

# Markdown Writing Skill 読み手は**その場の会話・コードベース・検討過程を知らない第三者**（社外・レビュアー・将来の担当者）である、という前提で書く。 適用対象: 仕様書 / 設計書 / README / OpenAPI 説明 / PR タイトル・本文 / コミットメッセージ / 調査レポート / 実装プラン / レビューコメント。 ## 重要ルール ### 1. 説明文に内部識別子・略語を持ち込まない **テーブル名・カラム名・クラス名などの内部識別子や、その場で作った略語を、説明文の主語・目的語に使わない。** 「何のために」「何をやったか」を説明する文でこれらを使うと、読み手が識別子の意味を知っている前提になり、**書いた側は説明した気になり、読み手には何も伝わらない**。 | | 例 | |---|---| | ❌ Bad | `user_subscriptions` の `plan_id` を更新し、us と sp を再生成する | | ✅ Good | 利用者の契約プランを変更し、請求明細を作り直す | | ❌ Bad | lcr がないと provisional に fallback する | | ✅ Good | 計算結果の控えが無い場合は、現在のマスタ値を参照する | **識別子を書いてよい場所**（むしろ書くべき）: - コードブロック・差分・スキーマ定義・SQL - 「どこを直したか」の指し示し（`app/Services/Foo.php:120` / 変更ファイル一覧） - 調査レポートのエビデンスブロック（クエリと実行結果） - 用語���導入する目的で、業務用語に括弧書きで添える場合 **やること**: - 説明は業務用語・日本語で書き、識別子は必要なら括弧で添える（例: 「請求明細（`billing_details`）」） - 同じ文書で識別子を繰り返し使うなら、冒頭に**用語の対応表**を置き、本文は業務用語で通す - 略語は初出で正式名称を��記する。会話中に作ったローカル略称は文書に持ち込まない - プロジェクトに用語集（`terminology` skill、`docs/` の用語定義、UI ラベルの翻訳ファイル等）があれば、そこの表記に合わせる ### 2. 検討過程の痕跡を残さない 作成者とその場の相談相手（AI との対話含む）だけに通じるラベルや言い回しは、第三者には意味不明なので本文に書かない。 - 検討時の選択肢ラベル（「案A / 案B」「Option A」「パターン1」などの符丁） - 「今回の相談で」「壁打ちの結果」「先ほど決めた」など会話由来の指示語 - 不採用にした代替案との比較を、比較のためだけに残すこと **やること**: 決まった内容を、ラベルなしで断定形で書く。「なぜそうするか」は理由として本質的なものだけを一般的な言葉で残す。 ### 3. 変更履歴を本文に残さない 指摘を受けて直した場合でも、**修正の経緯そのもの**を本文に含めない。 - 「以前は X だったが、指摘を受けて Y に変更した」式の記述 - 「〜という誤りがあったため修正」「レビュー対応で追加」などの由来説明 - 不採用になった案の書きかけ **やること**: 現時点で正しい確定情報だけを書く。変更理由・経緯はコミットメッセージ / PR 説明 / レビュー返信に置く（git 履歴に残るので本文で二重に持たない）。 - **stale 化防止**