writing-design-docs

name	writing-design-docs
description	Use when writing or revising a design doc / ADR / 設計文書 that lives in the repo (docs/ 配下), and the draft reads like AI slop from session back-and-forth — 太字ラベルの乱用、演出語・英語造語、両論併記、説明の重複、一文ごとのインラインリンク — and must become the author's settled view that a first-time reviewer can follow.

Writing Design Docs

Overview

リポジトリに残す設計文書（design doc / ADR 等）は、初見のチームメンバーがレビューできる「設計者の確定見解」でなければならない。 セッション中に AI と往復しながら書くと、検討の痕跡（両論併記、迷い、同じ説明の再掲）と LLM 口調（太字ラベル、演出語、英語造語）が溜まり、レビューに出せない文書になる。 このスキルは、その slop を排して文書を引き締める。

.plans/ 配下のテンポラリ作業メモは対象外（多少の slop は許容してよい）。リポジトリに残る文書だけを引き締める。

REQUIRED BACKGROUND: 日本語の文体細則（一文一行、ダッシュ・中黒、パラグラフライティング、LLM っぽい空句の禁止）は japanese-tech-writing スキルに従う。本スキルは、その上に design doc 特有の構造判断を重ねる。

When to Use

次の症状が出ている、または出さないために:

• 箇条書きの頭がほぼ全部 **…** で、どこが要点か埋もれている
• 「案A（推奨）/ 案B」のような両論併記が本文に並んでいる
• 同じ概念の長い解説が複数ファイル / 節に再掲されている
• 「桁で効く主レバー」「畳む」horizon-bounded perf-gated のような演出語・英語造語がある
• 一文ごとに [other.md](#…) のインラインリンクが付いている
• 「（要確認）」「（要レビュー）」が本文に散らばり、確定事項と混ざっている

The Form（出力の形）

逐条の禁止ではなく、文書を次の形に寄せる。

1. 結論主導：採用案を本文に書く。検討した代替案は各判断の末尾に「採らない案：結論（一文で理由）」として置く。案を並列に並べて読者に選ばせない。
2. 設計者の確定見解：確定事項は言い切る。未確定事項は本文に散らさず「リリース前に確認すること」等の専用セクションに集約する。
3. 正典は1つ：同じ概念の詳しい解説は1ファイル（節）を正典にし、他は要点1行 + リンクに圧縮する。
4. 頭出しは全角コロン：箇条書きのラベルは **項目**: 説明 でなく「項目：説明」。太字は論理の要所のみ（1節に1〜2箇所）。
5. リンクは初出のみ：同じ参照先へのリンクは各節の初出1回。一文ごとの連打をやめる。

コード識別子は残す（線引き）

slop として削るのは「散文の演出語・英語造語」だけ。 ST_DistanceSphere、city_code、テーブル名、SQL 関数などのコード識別子は、社内エンジニアに通じる用語として原綴り（コードフォント）で残す。無理に日本語化しない。

削る（散文の slop）	残す（コード識別子）
「distinct city_code 数に畳む」→「distinct city_code の数まで減る」	distinct city_code 自体
horizon-bounded →「この最適化の有効期間」	ST_DistanceSphere, <->
「桁で効く主レバー」→「最も効く」	テーブル名・カラム名

Before / After

Before（slop）:

## 計算戦略

- **計算単位**: 距離順は city_code 代表点だけで決まるため、距離計算を distinct city_code 数に**畳む**（[batch.md](batch.md#パフォーマンス)）。これが**桁で効く主レバー**。
- **シグネチャ**:
  - 案A（推奨）: condition に座標を持たせる。
  - 案B: 別引数で渡す。

After（引き締め後）:

## 計算戦略

距離順は city_code 代表点だけで決まるため、距離計算の回数を候補者数ではなく distinct city_code の数まで減らせる。これがコスト面で最も効く（詳細は [batch.md](batch.md#パフォーマンス)）。

シグネチャは condition に基準座標を持たせる形を採る（別引数で渡すより呼び出し側の分岐が少ない）。

Common Mistakes

• 却下案を消してしまう：消すのではなく「採らない案：理由」として末尾に残す。design doc では検討の根拠がレビュー価値を持つ。
• コード識別子まで日本語化する：ST_* やカラム名を訳すと逆に読みにくい。散文だけ直す。
• .plans/ まで引き締める：テンポラリ作業メモは対象外。リポジトリに残る文書だけ。