Menu
ソフトウェア設計ドキュメント (Design Doc) を記述する。仕様検討後に Design Doc としてまとめる、仕様を書き下す際に漏れや観点を洗い出す、ユーザーの指示に基づいて設計する、といった用途で使う。/design-doc で起動。出力は日本語。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| 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 への依存を避けたい
書き上げたら次で自己点検する。
直前のセッション（実装・調査・変更）の内容を、ユーザーが深く理解できるまで対話的に教える教師スキル。問題・解決策・広い文脈の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>