株式会社BALEEN STUDIO
🎨

Design Docの書き方ガイド

D.YAMAGUCHI
に公開
プロジェクトマネジメント
設計
ドキュメンテーション
api設計
designdoc
idea

Context and scope

Context

ドキュメントを書くにあたって、背景となる情報を記述する。

（例）
個人開発のときは、ドキュメントをほとんど書いてこなかった。
それは、書き方がその日の気分によって異なったり、ガイドラインやテンプレートをその時の気分で作成しておきながら、イレギュラーな項目が登場し、使わなくなってしまったりするため、小さな単位の個人開発・プロジェクトではそれらの行為が無価値であると思っていたからだ。

しかし、チーム開発や、AIを使った開発をする上で、単純なプログラミングのコード情報・コメントだけでなく、なぜそのコードを採用したのか、このサービスにはどのような機能があるのか、この機能はどのように使われているのか、また使われていないのか。など、メンテナンスや新規実装にあたって、 必要な文脈（コンテキスト・背景情報） が、頭の中にのみある情報をテキストに書き出す必要が出てきた。
そこで、マイクロサービスのような機能を実装する場合については、全く新しいテンプレートを用意するのではなく、design-docs-at-googleの各項目に合わせたDesign Docを採用する ことにした。

出典
Desing Doc - https://www.industrialempathy.com/posts/design-docs-at-google/

Scope

ドキュメントの対象、対象となるサービスのバージョンを記述する。

（例）
このドキュメントでは、以下の項目を対象とする。

  • Design Docの各項目のテンプレート的な表示の仕方
  • Design Docの各項目の書き方例

対象のバージョン

  • service/A v1.0.0
  • service/B v1.0.0

Goals and non-goals

Goals

Goals は、ドキュメントで理解してほしいポイントを書く。

(例)

  • テンプレートっぽく書けるようにする。
  • わかりやすいがある程度抽象化されてた例を使って説明する。

Non-goals

Non-goals は、ドキュメントのポイントとして受け取ることができるかもしれないが、曲解や誤解されそうな、注意してほしいポイントを書く。

(例)

  • 実際に使用するAPIを作成すること。
  • このDesign Docだけが完璧なものと主張すること。
  • 細かい書き方を記載すること。

The actual design

System-context-diagram

サービスのデータフローや、関連サービスとのデータフローをmermaidなどで記述する。

（例）

APIs

どのAPIの設計とそのAPIでやりとりされるときに発生するリソースを書く。

（例）

  • Aリソース
    • Aリソースは、◯◯の情報が入ったリソース
    • fields
      • name: Aのリソース名(A/xxx)
      • display_name: Aの表示名
  • GetA
  • Bリソース
    • Bリソースは、△△の情報が入ったリソース。Aのリソースを親とする。
    • Fields
      • name: Bのリソース名　(A/xxx/B/xxx)
  • DeleteB
    • Request
      • name: Bのリソース名
      • allow_missing: 削除時に存在しないことを許容するかどうか。
    • 出典

Data storage

どのデータがどこに保存されているかを記載しておく。

DBのデータスキーマ等もここに書いている。

（例）

  • Aリソースの各fields → DB Aのtable Tに保管している
  • Bリソースのenum fields → プログラム上にハードコーディングしている

Code and pseudo-code

protoファイルやopenapiのyamlなど、API単位のプロトコード、モックを書く。
githubの実装フォルダのリンクなど、実装している部分を置いても良い。

Degree of constraint

設計の自由度や、制約によって設計選定の幅が狭められた要素を記述する。
また、ここまでのセクションの要点整理としても使えるはず。

（例）

  • A APIは、□□ライブラリのバージョンx.xx.xに限定する。それ以降のバージョンは非互換の変更対象となり、大規模なメンテナンスをしないと動かない。

Alternatives considered

検討した事項について、代替案があるものは、記載しておく。

（例）
BのDeleteを実行したときに、Aのリソース削除したい。

  • 採用案
    • BのDeleteを実行したときは、Aのリソースを削除しない。
  • 代替案
    • BのDeleteを実行したときは、Aのリソースを削除する。
  • 採用理由
    • Aのリソースが削除されてしまうと、Bのリソースだけではない他の子リソースはにも影響してしまう。

Cross-cutting concerns

横断的な関心事項は、その機能だけが持たない、共通の機能やセキュリティについて記述する。

（例）
セキュリティについて、A API、 B API のアクセスレベルを 2 とした。
GetAの結果は、キャッシュルールのもと、キャッシュされる。

Reference

リファレンスは、全体的なページに対する出典・参照を記述する。
ただし、各項目内で限定される文章は、ここに書くよりも、各章節で個別に出典を書くほうが読みやすいドキュメントになる。

Design Docs at Google - https://www.industrialempathy.com/posts/design-docs-at-google/

Changelog

変更履歴は「機能/仕様変更のみ」を対象とし、表記ゆれや例示修正などは含めない。

自動生成された設計書や、APIの仕様が不安定で変わりやすい場合、この文書はメンテナンスが必要になる。メンテナンスする場合は、読まなくて良い箇所や、横断的に修正する箇所が多くなってしまうが、その負荷を削るには、ドキュメントのスコープを修正してより小さなドキュメントにするか、AIなどでChangelogと合わせて加筆させたりするのが良いかもしれない。

  • 2025-07-29 初稿

附録

template用

## Context and scope

### Context

### Scope

## Goals and non-goals

### Goals

### Non-goals

## The actual design

### System-context-diagram

### APIs

### Data storage

### Code and pseudo-code

### Degree of constraint

## Alternatives considered

## Cross-cutting concerns

## Reference

## Changelog

-
株式会社BALEEN STUDIO
株式会社BALEEN STUDIO

社内・パートナーにAzure MVP受賞経験者 多数！ gRPC × API Firstで最新技術を活用した開発を推進中！

Discussion