菜单
ソフトウェア設計ドキュメント (Design Doc) を記述する。仕様検討後に Design Doc としてまとめる、仕様を書き下す際に漏れや観点を洗い出す、ユーザーの指示に基づいて設計する、といった用途で使う。/design-doc で起動。出力は日本語。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
直前のセッション（実装・調査・変更）の内容を、ユーザーが深く理解できるまで対話的に教える教師スキル。問題・解決策・広い文脈の3点を Socratic に掘り下げ、チェックリストとクイズ（AskUserQuestion）で理解を検証する。コードは書けたが中身を理解しきれていないとき、ペアプロ/レビュー後の理解定着、学習目的で「教えて」「解説して理解させて」と言われたときに使う。
git の変更を分析し、conventional commit 形式でコミットを作成する。
GitHub PullRequest のレビューコメントを分析し修正する。/fix-review で起動。
Transform work logs and debugging notes into well-structured GitHub Issues or PRs. <example> user: Create an Issue from my investigation findings assistant: I'll use github-issue-pr-writer to draft the Issue description </example>
| name | design-doc |
| description | ソフトウェア設計ドキュメント (Design Doc) を記述する。仕様検討後に Design Doc としてまとめる、仕様を書き下す際に漏れや観点を洗い出す、ユーザーの指示に基づいて設計する、といった用途で使う。/design-doc で起動。出力は日本語。 |
| reference | https://refactoringenglish.com/excerpts/write-an-effective-design-doc/ |
ドキュメント本文は日本語で書く。セクション見出しは英語名 (Objective, Background, ...) を主とし、必要に応じて日本語を併記する。
設計判断を Design Doc に書くか、未決定事項を質問するか提案で済ませるか、どのセクションを設けるか。すべて 「その判断を間違えたらどれだけ痛いか?」 で決める。
代償が小さい判断を AI が決め打ちで埋めたが後で見直したいものは、Open Issues に残す。
AskUserQuestion でまとめて質問し、各選択肢に「なぜこの判断が重いか」を添える。cost が低い箇所は AI が提案して埋めるユーザーに明確な仕様がある部分はそれに忠実に従い、勝手に変えない。仕様が薄い部分だけ AI が cost of being wrong に基づいて補う。両者は 1 つの Design Doc 内に混在してよい。
非対話のセッション (自動化や、質問に答えが返らない状況) では質問を諦め、cost が高い項目も妥当な値を仮置きして埋める。仮置きした項目は Open Issues に「要確認」として残し、何を仮定したかを明記する。
依頼が「漏れの洗い出し」なら、下記セクション群をチェックリストとして使い、欠けている観点 (特に cost が高い未決定事項) を指摘する。Design Doc 全体を書かず観点提示だけでよい。
すべての Design Doc にすべてのセクションが要るわけではない。 骨格はほぼ常に書く。内容次第セクションは cost of being wrong で取捨し、シナリオもセキュリティも対象次第で省く (内部ライブラリにユーザーシナリオは不要、外部入力のないバッチにセキュリティ節は過剰)。該当しないセクションは省く (空欄や N/A で埋めない)。
省略は基本サイレントでよい (省いたセクションを文書内で列挙しない)。例外として、読み手が「なぜ無いのか」を当然疑う主要セクション (典型は Scenarios や Security) を意図的に省くときだけ、Background か Non-Goals に一行だけ省略理由を添えてよい。省略専用の節は作らない。
文書冒頭の H1 として、短く・特徴的で・印象に残るプロジェクト名を置く。良い名前の条件は、声に出しやすい (short)・どのプロジェクトか分かる (distinctive)・概念を表す (evocative)。
Project Flying Silver Horse (冗長で意味をなさない)RecencyBank (目的を表し、口頭で言いやすい)固有名なので「見出しは英語名を主」ルールの対象外。
Title 直下に key-value で置く。
- Author: 名前 (連絡先)
- Status: Draft / Design-complete, ready for implementation / ...
- Created: YYYY-MM-DD
- URL: 正式な参照先 (発行後に記入)
プロジェクトの目的を一文で。どんな立場のステークホルダーにも分かる平易な言葉で、1 ページ目に置く。
例: Trogdor Web サーバと Postgres データベースの間にキャッシュ層を追加し、アプリケーションのパフォーマンスを改善する。
なぜこのプロジェクトをやるのか、何の問題を解くのか、過去に試みがあったか。判断の基準として効く文脈を書く。
書く分量の目安は 「読む前に同僚に口頭で説明するとしたら何を伝えるか」。それが 1 ページ目に載っているべき内容。
可能なら数字と観測で裏付ける。「遅い」より「レスポンスが 100ms から 600ms に悪化した」「ページロード時間の 80% が DB 参照」「参照の 95% が全体の 3% の行に集中」のように具体で書くと、後段の判断の根拠になる。
実装ではなくインパクトで書く。プロジェクトがユーザー・チーム・会社にどう利益をもたらすかを述べる。各項目は動詞始まりにする (最小化する、共有できるようにする、維持する)。
例:
- 家族の写真や動画を親族や親しい友人と共有できるようにする。
- 複雑さを最小化し、PC に不慣れな親族でも安心して使えるようにする。
- 全データを非公開に保ち、許可されたユーザーだけがアクセスできるようにする。
スコープ外を明示し、読み手が「これも入っている」と誤解しそうな項目を否定形で打ち消す。簡潔な理由を添えてよい。
例:
- 商用の写真共有アプリは作らない。
- 過去アップロードの URL リンクは保持しない。
- 複数の家族が同一サーバを共有することは許可しない。
完成後のシステムが現実でどう動くかを、読み手に絵として見せる。利用者の操作や外部とのやり取りがある対象で書く。番号付きの手順が有効。
例:
- 親が Web アプリを開く。
- メインページで最も目を引く UI 要素 (CTA) が「アップロード」ボタンで、親はそれをクリックする。
- ...
データフローやコンポーネント関係を図示する。後から編集できるツールを使う (Excalidraw, draw.io, Google Drawings、またはコードで書ける Mermaid / D2 / Graphviz)。ホワイトボードの写真は編集できず一生そのままになるので避ける。図のソース (描画ファイルやコード) へのリンクを必ず添え、チームが再現・改訂できるようにする。
人や他システムとの接点 (UI、API / CLI のセマンティクス、ファイル形式) を示す。内部実装の全詳細ではなく、表に見える契約面を重視する。UI は精密なモックより、簡単なスケッチや振る舞いの説明でよい。
テスト計画や機能仕様など、関連文書へのリンク。
新メンバーや外部読者向けに、馴染みのない用語を定義する。
後から変えにくい判断ほど cost が高いので、ここに厚く書く。
予算・インフラ・依存による主要な制約。
言語、ハードウェア、永続ストレージ、サードパーティ。実装後に変えるのが難しい判断は何かを深く考え、そこに絞る。簡単に差し替えられるものは軽く扱う。
「速い」「高性能」「モバイルで快適」といった曖昧な目標を、測定可能で客観的な数値にする。稼働率・レイテンシ・規模を、括弧で文脈を添えて書く。
例:
- 目標: 99% の可用性 (two nines)。
- ビューポート内のサムネイルは、1 Gbps 接続のデスクトップで 400ms 以内に表示する。
作業を、利害関係者にとって意味のある成果物が出るマイルストーンに分ける。誤解を早く見つけられる順序を優先する (例: ダミーデータでも UI を先に見せれば、認識のズレを実装前に検出できる)。各マイルストーンに「実装するもの / まだ実装しないもの」を添えてよい。
リスクが小さい対象ではまるごと省く。
考慮した脅威、攻撃面 (悪意あるデータを処理しうる箇所)、信頼境界を書く。脅威が起こりにくい・無関係と思っても、そう判断した根拠を残す。各脅威は脅威タイトル → Scenario: (状況と影響) → Mitigations: (緩和策の箇条書き) の形式で書く。
例:
未認証の攻撃者が S3 バケット内の写真を発見する
Scenario: バケットが公開設定だと、URL を推測した第三者が写真を閲覧できる。 Mitigations:
- バケットを非公開にし、署名付き URL でのみアクセスさせる。
- ...
機微データの扱い、保持期間、アクセス制御、暗号化。解決策より先に「何が問題か」に焦点を当てる。
規制 (金融・医療等) の順守、OSS のライセンス選定。
SLO をどう測定し、違反をどう検知するかを書く。少なくとも「サービスが落ちたらどう気づくか」「性能が 100 倍悪化したらどう気づくか」「何のイベントでアラート (page) するか」に答える。
例: 95 パーセンタイルのレイテンシが 3s 以上で page。2 分平均の CPU が 90% 以上で page。
記録する重要イベント、ログレベル、保持期間、アクセス制御、機微データの除外。
未解決の設計上の問題を、問題文 → 検討した選択肢 → 直近の次の一手の形で書く。「設計の欠陥」「複数案で迷っている」「情報待ち」が対象。
レビューで誤解された点は脇の会話で済ませず文書本文に取り込む。欄外の議論が 2〜3 往復しても決着しなければ、ここに移す。
決着した Open Issue を、決定を要約して移す。議論の全体を後世のために残す。
例: Decision: Sendamatic を使う。合わなければ Amazon SES。 Criteria: (評価基準のリスト) Candidates (魅力度の降順): (ランク付けした候補)
却下した案、特に有力だった案や深く調べた案を pro/con で書く。網羅は不要で数行で十分。検討に値しなかった案は Definitely not: でまとめてよい。
例:
Google Photos
- Pros: 写真が収まれば無料
- Cons: Google への依存を避けたい
書き上げたら次で自己点検する。