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. 指す対象が文脈で変わる語に、この文書での意味を与える **読み手が語自体は知っているが、指す対象が文脈によって変わる語**を、言い換えも定義もせずに使わない。 ルール 1 が「読み手が知らない語を使わない」ことを求めるのに対し、こちらは**読み手が別の意味で知っている語**を扱う。知らない語ではないため読み飛ばされ、**読み手は分かったつもりで先へ進み、別の対象を思い浮かべたまま作業する**。 | 対応 | 使う場面 | |---|---| | 一意な語へ言い換える | **既定。** 文書の主題を表す語がこれに当たる場合 | | 初出で定義する | 言い換えると不自然になる場合、業界で定着した呼び方がある場合 | **言い換えを既定とする理由。** 定義は読み飛ばされる。読み手が知っている語であるほど、定義を読まずに自分の解釈で読み進める。語そのものを一意にすれば、読み飛ばしても誤解が生じない。 | | 例 | |---|---| | ❌ Bad | スタックを 3 つ並列で起動する | | ✅ Good | テスト環境を 3 つ並列で起動する | | ❌ Bad | 環境ごとにモデルを切り替え