開発

技術仕様書テンプレート（Markdown）

この技術仕様書テンプレートは空欄のフォームではなく、実例です。決済サービスを取り上げ、図と数式とコード例が1つの文書の中でどう並ぶかを示しています。内容は自分の設計に置き換えつつ、構成はそのまま使ってください。

このテンプレートをエディターで開く

カテゴリー: 開発
デフォルトスタイル: テクニカル

使う場面

複数の人が合意する必要のあるものを作り始める前に仕様書を書きます。エンジニアはこれを読んで設計をレビューし、プロダクトやQAの担当者はこれを読んで何がリリースされるのかを把握します。PDF版はデザインレビューやクライアントの承認、文書の見た目を数年後も変えずに残したい記録に向いています。

含まれる内容

プロジェクト名と担当者を入力する欄を含む概要と、それに続くリクエストフローのMermaidシーケンス図。
TeXの数式を含むリトライ予算の項目と、ハイライト表示されたコードブロック内のTypeScriptの例。
未解決の課題一覧の前に置かれた、改ページを挿入するための手動の区切り。

より良い文書にするヒント

フロー図は詳細より前に置きましょう。順序を先に理解したレビュアーは残りの項目を早く読み、より良い質問をしてくれます。
未解決の課題は答えが出るまで仕様書に残し、答えが出たら該当する項目に移しましょう。長い仕様書では表紙と目次を追加してください。

テンプレートのプレビュー

決済サービス仕様書

プロジェクト: プロジェクトまたはテーマ 担当者: お名前

概要

決済サービスは注文を受け取り、カードに請求し、結果を記録します。リクエストは24時間、冪等です。

フロー

sequenceDiagram
  participant App
  participant API
  participant Stripe
  App->>API: POST /charge
  API->>Stripe: create PaymentIntent
  Stripe-->>API: status
  API-->>App: receipt

リトライ予算

各クライアントは指数バックオフでリトライでき、試行 $n$ 後の待機時間は次のとおりです

w_n = \min(2^n \cdot 250\,\text{ms},\ 8\,\text{s})

例

export const charge = async (order: Order) => {
  const intent = await stripe.paymentIntents.create({ amount: order.total });
  return { id: intent.id, status: intent.status };
};

未解決の質問

下4桁を保存するか？
どの通貨を先に対応するか？

氏名や日付などの入力欄は、エディターでテンプレートを開くと置き換えられます。