| 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つ：同じ概念の詳しい解説は1ファイル（節）を正典にし、他は要点1行 + リンクに圧縮する。
- 頭出しは全角コロン：箇条書きのラベルは
**項目**: 説明 でなく「項目：説明」。太字は論理の要所のみ（1節に1〜2箇所）。
- リンクは初出のみ：同じ参照先へのリンクは各節の初出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/ まで引き締める：テンポラリ作業メモは対象外。リポジトリに残る文書だけ。
